M5: Cutover decision authorization + remove isTrusted

assistant/src/approvals/guardian-decision-primitive.ts

@@ -18,7 +18,8 @@
  *   9. Kind-specific resolver dispatch via the resolver registry
  *
  * Security invariants enforced here:
- *   - Decision application is identity-bound to expected guardian identity
+ *   - Decision authorization is purely principal-based:
+ *     actor.guardianPrincipalId must match request.guardianPrincipalId
  *   - Decisions are first-response-wins (CAS-like stale protection)
  *   - `approve_always` is rejected/downgraded for guardian-on-behalf requests
  *   - Scoped grant minting only on explicit approve for requests with tool metadata
@@ -35,6 +36,7 @@ import {
   type GuardianApprovalRequest,
   updateApprovalDecision,
 } from '../memory/channel-guardian-store.js';
+import { getActiveBinding } from '../memory/guardian-bindings.js';
 import { DAEMON_INTERNAL_ASSISTANT_ID } from '../runtime/assistant-scope.js';
 import type {
   ApprovalAction,
@@ -273,6 +275,39 @@ export function mintCanonicalRequestGrant(params: {
   return { minted: false };
 }
 
+// ---------------------------------------------------------------------------
+// Cross-channel principal authorization helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether an actor's guardian principal is authorized to act on a
+ * request that was bound to a (possibly different) guardian principal.
+ *
+ * Authorization passes when:
+ *   1. The actor's principal directly matches the request's principal, OR
+ *   2. The actor's principal matches the assistant's canonical (vellum)
+ *      principal — this covers the cross-channel case where a request was
+ *      created with a channel binding's principal (e.g. Telegram) but the
+ *      guardian responds from vellum/desktop.
+ *
+ * Returns `true` when the actor is authorized, `false` otherwise.
+ */
+export function isAuthorizedGuardianPrincipal(
+  actorPrincipalId: string,
+  requestPrincipalId: string,
+): boolean {
+  if (actorPrincipalId === requestPrincipalId) {
+    return true;
+  }
+
+  // Cross-channel fallback: check if the actor matches the assistant's
+  // canonical (vellum) principal.
+  const vellumBinding = getActiveBinding(DAEMON_INTERNAL_ASSISTANT_ID, 'vellum');
+  const canonicalPrincipal = vellumBinding?.guardianPrincipalId;
+
+  return !!canonicalPrincipal && actorPrincipalId === canonicalPrincipal;
+}
+
 // ---------------------------------------------------------------------------
 // Canonical guardian decision primitive
 // ---------------------------------------------------------------------------
@@ -349,44 +384,58 @@ export async function applyCanonicalGuardianDecision(
     return { applied: false, reason: 'invalid_action', detail: `invalid action: ${action}` };
   }
 
-  // 2c. Validate identity: actor must match guardian_external_user_id
-  // unless the actor is trusted (desktop).
-  //
-  // Channel tool-approval requests must always be identity-bound. Treat
-  // missing guardianExternalUserId as unauthorized (fail-closed) so a
-  // non-guardian actor can never approve an unbound request.
-  if (
-    !actorContext.isTrusted &&
-    request.kind === 'tool_approval' &&
-    !request.guardianExternalUserId
-  ) {
+  // 2c. Principal-based authorization: actor.guardianPrincipalId must match
+  // request.guardianPrincipalId for any applied decision. This is the single
+  // authorization gate — there is no trusted bypass.
+
+  if (!request.guardianPrincipalId) {
     log.warn(
       {
-        event: 'canonical_decision_missing_guardian_binding',
+        event: 'canonical_decision_missing_request_principal',
         requestId,
         kind: request.kind,
         sourceType: request.sourceType,
       },
-      'Canonical tool approval missing guardian binding; rejecting decision',
+      'Canonical request missing guardianPrincipalId; rejecting decision',
     );
-    return { applied: false, reason: 'identity_mismatch', detail: 'missing guardian binding' };
+    return { applied: false, reason: 'identity_mismatch', detail: 'request missing guardianPrincipalId' };
   }
 
-  if (
-    request.guardianExternalUserId &&
-    !actorContext.isTrusted &&
-    actorContext.externalUserId !== request.guardianExternalUserId
-  ) {
+  if (!actorContext.guardianPrincipalId) {
     log.warn(
       {
-        event: 'canonical_decision_identity_mismatch',
+        event: 'canonical_decision_missing_actor_principal',
+        requestId,
+        actorChannel: actorContext.channel,
+      },
+      'Actor missing guardianPrincipalId; rejecting decision',
+    );
+    return { applied: false, reason: 'identity_mismatch', detail: 'actor missing guardianPrincipalId' };
+  }
+
+  if (!isAuthorizedGuardianPrincipal(actorContext.guardianPrincipalId, request.guardianPrincipalId)) {
+    log.warn(
+      {
+        event: 'canonical_decision_principal_mismatch',
+        requestId,
+        expectedPrincipal: request.guardianPrincipalId,
+        actualPrincipal: actorContext.guardianPrincipalId,
+      },
+      'Actor principal does not match request principal or canonical principal',
+    );
+    return { applied: false, reason: 'identity_mismatch', detail: 'principal mismatch' };
+  }
+
+  if (actorContext.guardianPrincipalId !== request.guardianPrincipalId) {
+    log.info(
+      {
+        event: 'canonical_decision_cross_channel_principal_match',
         requestId,
-        expectedGuardian: request.guardianExternalUserId,
-        actualActor: actorContext.externalUserId,
+        requestPrincipal: request.guardianPrincipalId,
+        actorPrincipal: actorContext.guardianPrincipalId,
       },
-      'Actor identity does not match expected guardian',
+      'Actor principal matches canonical vellum principal (cross-channel authorization)',
     );
-    return { applied: false, reason: 'identity_mismatch' };
   }
 
   // 2d. Check expiry

assistant/src/approvals/guardian-request-resolvers.ts

@@ -43,8 +43,8 @@ export interface ActorContext {
   externalUserId: string | undefined;
   /** Channel the decision arrived on. */
   channel: string;
-  /** Whether the actor is a trusted/desktop context. */
-  isTrusted: boolean;
+  /** Principal ID for authorization — must match the request's guardianPrincipalId. */
+  guardianPrincipalId: string | undefined;
 }
 
 /** The decision being applied. */
@@ -374,7 +374,9 @@ const accessRequestResolver: GuardianRequestResolver = {
       return {
         ok: true,
         applied: true,
-        ...(ctx.actor.isTrusted ? { guardianReplyText: `Access denied for ${requesterLabel}.` } : {}),
+        // Desktop actors (vellum channel) receive inline reply text; channel
+        // actors get replies delivered via the channel delivery context.
+        ...(ctx.actor.channel === 'vellum' ? { guardianReplyText: `Access denied for ${requesterLabel}.` } : {}),
       };
     }
 
@@ -528,7 +530,9 @@ const accessRequestResolver: GuardianRequestResolver = {
     return {
       ok: true,
       applied: true,
-      ...(ctx.actor.isTrusted ? { guardianReplyText: verificationReplyText } : {}),
+      // Desktop actors (vellum channel) receive inline reply text; channel
+      // actors get replies delivered via the channel delivery context.
+      ...(ctx.actor.channel === 'vellum' ? { guardianReplyText: verificationReplyText } : {}),
     };
   },
 };

assistant/src/daemon/handlers/guardian-actions.ts

@@ -3,6 +3,7 @@ import {
 } from '../../approvals/guardian-decision-primitive.js';
 import { getCanonicalGuardianRequest } from '../../memory/canonical-guardian-store.js';
 import type { ApprovalAction } from '../../runtime/channel-approval-types.js';
+import { resolveLocalIpcGuardianContext } from '../../runtime/local-actor-identity.js';
 import { listGuardianDecisionPrompts } from '../../runtime/routes/guardian-action-routes.js';
 import type { GuardianActionDecision, GuardianActionsPendingRequest } from '../ipc-protocol.js';
 import { defineHandlers, log } from './shared.js';
@@ -45,13 +46,15 @@ export const guardianActionsHandlers = defineHandlers({
       }
     }
 
+    // Resolve the local IPC actor's principal via the vellum guardian binding.
+    const localGuardianCtx = resolveLocalIpcGuardianContext('vellum');
     const canonicalResult = await applyCanonicalGuardianDecision({
       requestId: msg.requestId,
       action: msg.action as ApprovalAction,
       actorContext: {
-        externalUserId: undefined,
+        externalUserId: localGuardianCtx.guardianExternalUserId,
         channel: 'vellum',
-        isTrusted: true,
+        guardianPrincipalId: localGuardianCtx.guardianPrincipalId ?? undefined,
       },
       userText: undefined,
     });

assistant/src/daemon/handlers/sessions.ts

@@ -600,13 +600,16 @@ export async function handleUserMessage(
         ]));
 
         if (pendingRequestIdsForConversation.length > 0) {
+          // Resolve the local IPC actor's principal via the vellum guardian binding
+          // for principal-based authorization in the canonical decision primitive.
+          const localCtx = resolveLocalIpcGuardianContext(ipcChannel);
           const routerResult = await routeGuardianReply({
             messageText: messageText.trim(),
             channel: ipcChannel,
             actor: {
-              externalUserId: undefined,
+              externalUserId: localCtx.guardianExternalUserId,
               channel: ipcChannel,
-              isTrusted: true,
+              guardianPrincipalId: localCtx.guardianPrincipalId ?? undefined,
             },
             conversationId: msg.sessionId,
             pendingRequestIds: pendingRequestIdsForConversation,

assistant/src/daemon/session-process.ts

@@ -383,9 +383,9 @@ export async function processMessage(
       messageText: trimmedContent,
       channel: 'vellum',
       actor: {
-        externalUserId: undefined,
+        externalUserId: session.guardianContext?.guardianExternalUserId,
         channel: 'vellum',
-        isTrusted: true,
+        guardianPrincipalId: session.guardianContext?.guardianPrincipalId ?? undefined,
       },
       conversationId: session.conversationId,
       pendingRequestIds: canonicalPendingRequestIdsForConversation,

assistant/src/memory/canonical-guardian-store.ts

@@ -271,6 +271,7 @@ export function getCanonicalGuardianRequestByCode(code: string): CanonicalGuardi
 export interface ListCanonicalGuardianRequestsFilters {
   status?: CanonicalRequestStatus;
   guardianExternalUserId?: string;
+  guardianPrincipalId?: string;
   requesterExternalUserId?: string;
   conversationId?: string;
   sourceType?: string;
@@ -289,6 +290,9 @@ export function listCanonicalGuardianRequests(filters?: ListCanonicalGuardianReq
   if (filters?.guardianExternalUserId) {
     conditions.push(eq(canonicalGuardianRequests.guardianExternalUserId, filters.guardianExternalUserId));
   }
+  if (filters?.guardianPrincipalId) {
+    conditions.push(eq(canonicalGuardianRequests.guardianPrincipalId, filters.guardianPrincipalId));
+  }
   if (filters?.conversationId) {
     conditions.push(eq(canonicalGuardianRequests.conversationId, filters.conversationId));
   }

assistant/src/runtime/guardian-reply-router.ts

@@ -20,6 +20,7 @@
 import {
   applyCanonicalGuardianDecision,
   type CanonicalDecisionResult,
+  isAuthorizedGuardianPrincipal,
 } from '../approvals/guardian-decision-primitive.js';
 import type { ActorContext, ChannelDeliveryContext } from '../approvals/guardian-request-resolvers.js';
 import {
@@ -195,19 +196,26 @@ function findPendingCanonicalRequests(
     });
   }
 
-  // For desktop/trusted actors without an externalUserId, query by
-  // conversationId so the NL path can discover pending requests.
+  // Actors without an externalUserId: scope by conversationId so the NL
+  // path can discover pending requests bound to this conversation.
+  // Include guardianPrincipalId filter when available so the guardian only
+  // sees requests they are authorized to act on.
   if (conversationId) {
     return listCanonicalGuardianRequests({
       status: 'pending',
       conversationId,
+      ...(actor.guardianPrincipalId ? { guardianPrincipalId: actor.guardianPrincipalId } : {}),
     });
   }
 
-  // Trusted actors without a conversationId: return all pending requests
-  // so desktop sessions can always discover pending guardian work.
-  if (actor.isTrusted) {
-    return listCanonicalGuardianRequests({ status: 'pending' });
+  // Actors with a guardianPrincipalId but no externalUserId or
+  // conversationId: query by principal so desktop sessions can still
+  // discover pending guardian work via their bound principal.
+  if (actor.guardianPrincipalId) {
+    return listCanonicalGuardianRequests({
+      status: 'pending',
+      guardianPrincipalId: actor.guardianPrincipalId,
+    });
   }
 
   return [];
@@ -299,22 +307,24 @@ export async function routeGuardianReply(
       // silently defaulting to approve_once.
       if (!codeResult.remainingText || codeResult.remainingText.trim().length === 0) {
         // Identity check: only expose request details to the assigned guardian
-        // or trusted (desktop) actors. Mirrors the identity check in
-        // applyCanonicalGuardianDecision to prevent leaking request details
-        // (toolName, questionText) to unauthorized senders.
+        // principal. Uses the shared cross-channel principal helper (same logic
+        // as applyCanonicalGuardianDecision) to prevent leaking request details
+        // (toolName, questionText) to unauthorized senders while allowing
+        // cross-channel lookups (e.g. desktop guardian entering a code for a
+        // Telegram-originated request).
         if (
-          request.guardianExternalUserId &&
-          !actor.isTrusted &&
-          actor.externalUserId !== request.guardianExternalUserId
+          request.guardianPrincipalId &&
+          actor.guardianPrincipalId &&
+          !isAuthorizedGuardianPrincipal(actor.guardianPrincipalId, request.guardianPrincipalId)
         ) {
           log.warn(
             {
-              event: 'router_code_only_identity_mismatch',
+              event: 'router_code_only_principal_mismatch',
               requestId: request.id,
-              expectedGuardian: request.guardianExternalUserId,
-              actualActor: actor.externalUserId,
+              expectedPrincipal: request.guardianPrincipalId,
+              actualPrincipal: actor.guardianPrincipalId,
             },
-            'Code-only clarification blocked: actor identity does not match expected guardian',
+            'Code-only clarification blocked: actor principal does not match request or canonical principal',
           );
           return {
             decisionApplied: false,

assistant/src/runtime/routes/conversation-routes.ts

@@ -87,6 +87,8 @@ async function tryConsumeCanonicalGuardianReply(params: {
   approvalConversationGenerator?: ApprovalConversationGenerator;
   /** Verified actor identity from actor-token middleware. */
   verifiedActorExternalUserId?: string;
+  /** Verified actor principal ID for principal-based authorization. */
+  verifiedActorPrincipalId?: string;
 }): Promise<{ consumed: boolean; messageId?: string }> {
   const {
     conversationId,
@@ -98,6 +100,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
     onEvent,
     approvalConversationGenerator,
     verifiedActorExternalUserId,
+    verifiedActorPrincipalId,
   } = params;
   const trimmedContent = content.trim();
 
@@ -114,12 +117,7 @@ async function tryConsumeCanonicalGuardianReply(params: {
     actor: {
       externalUserId: verifiedActorExternalUserId,
       channel: sourceChannel,
-      // When a verified identity is available, disable the trusted bypass so
-      // that the identity-match checks in applyCanonicalGuardianDecision
-      // actually run. Only fall back to isTrusted when no verified identity
-      // was resolved (defensive — shouldn't happen for vellum since
-      // verification runs upstream).
-      isTrusted: !verifiedActorExternalUserId,
+      guardianPrincipalId: verifiedActorPrincipalId,
     },
     conversationId,
     pendingRequestIds,
@@ -523,12 +521,15 @@ export async function handleSendMessage(
       ? smDeps.resolveAttachments(attachmentIds)
       : [];
 
-    // Resolve the verified actor's external user ID for inline approval
-    // routing. Uses the guardianExternalUserId from the verified context
-    // (actor-token or local-fallback) rather than hardcoding undefined.
+    // Resolve the verified actor's external user ID and principal for inline
+    // approval routing. Uses the guardianExternalUserId and guardianPrincipalId
+    // from the verified context (actor-token or local-fallback).
     const verifiedActorExternalUserId = actorVerification?.ok
       ? actorVerification.guardianContext.guardianExternalUserId
-      : undefined;
+      : session.guardianContext?.guardianExternalUserId;
+    const verifiedActorPrincipalId = actorVerification?.ok
+      ? actorVerification.guardianContext.guardianPrincipalId ?? undefined
+      : session.guardianContext?.guardianPrincipalId ?? undefined;
 
     // Try to consume the message as a canonical guardian approval/rejection reply.
     // On failure, degrade to the existing queue/auto-deny path rather than
@@ -544,6 +545,7 @@ export async function handleSendMessage(
         onEvent,
         approvalConversationGenerator: deps.approvalConversationGenerator,
         verifiedActorExternalUserId,
+        verifiedActorPrincipalId,
       });
       if (inlineReplyResult.consumed) {
         return Response.json(