@vellumai/assistant 0.4.9 → 0.4.11

package/src/mcp/mcp-oauth-provider.ts

@@ -0,0 +1,347 @@
+/**
+ * OAuthClientProvider implementation for MCP servers.
+ *
+ * Uses secure-keys (OS keychain / encrypted file store) for persistent
+ * credential storage and a loopback HTTP server for the browser callback.
+ */
+
+import { createServer, type Server } from 'node:http';
+
+import type { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+
+import {
+  deleteSecureKeyAsync,
+  getSecureKeyAsync,
+  setSecureKeyAsync,
+} from '../security/secure-keys.js';
+import { getLogger } from '../util/logger.js';
+import { isLinux, isMacOS } from '../util/platform.js';
+
+const log = getLogger('mcp-oauth');
+
+const CALLBACK_PATH = '/oauth/callback';
+const CALLBACK_TIMEOUT_MS = 2 * 60 * 1000; // 2 minutes
+
+// Keychain key helpers
+function tokensKey(serverId: string): string { return `mcp:${serverId}:tokens`; }
+function clientInfoKey(serverId: string): string { return `mcp:${serverId}:client_info`; }
+function discoveryKey(serverId: string): string { return `mcp:${serverId}:discovery`; }
+
+export interface McpOAuthCallbackResult {
+  /** Resolves with the authorization code when the callback is received. */
+  codePromise: Promise<string>;
+}
+
+export class McpOAuthProvider implements OAuthClientProvider {
+  private readonly serverId: string;
+  private readonly serverUrl: string;
+  private readonly interactive: boolean;
+  private _codeVerifier: string | undefined;
+  private _redirectUrl: string | undefined;
+  private _codePromise: Promise<string> | null = null;
+  private callbackServer: Server | null = null;
+  private callbackTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * @param interactive When true (e.g. `mcp auth` CLI), opens browser for OAuth.
+   *                    When false (daemon), logs a message instead.
+   */
+  constructor(serverId: string, serverUrl: string, interactive = false) {
+    this.serverId = serverId;
+    this.serverUrl = serverUrl;
+    this.interactive = interactive;
+  }
+
+  // --- redirectUrl ---
+
+  get redirectUrl(): string | undefined {
+    return this._redirectUrl;
+  }
+
+  // --- clientMetadata ---
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      client_name: 'Vellum Assistant',
+      redirect_uris: this._redirectUrl ? [this._redirectUrl] : [],
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+    };
+  }
+
+  // --- Tokens ---
+
+  async tokens(): Promise<OAuthTokens | undefined> {
+    const raw = await getSecureKeyAsync(tokensKey(this.serverId));
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as OAuthTokens;
+    } catch {
+      log.warn({ serverId: this.serverId }, 'Failed to parse stored OAuth tokens');
+      return undefined;
+    }
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    await setSecureKeyAsync(tokensKey(this.serverId), JSON.stringify(tokens));
+    log.info({ serverId: this.serverId }, 'OAuth tokens saved');
+  }
+
+  // --- Client Information ---
+
+  async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    const raw = await getSecureKeyAsync(clientInfoKey(this.serverId));
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as OAuthClientInformationMixed;
+    } catch {
+      log.warn({ serverId: this.serverId }, 'Failed to parse stored client information');
+      return undefined;
+    }
+  }
+
+  async saveClientInformation(info: OAuthClientInformationMixed): Promise<void> {
+    await setSecureKeyAsync(clientInfoKey(this.serverId), JSON.stringify(info));
+    log.info({ serverId: this.serverId }, 'OAuth client information saved');
+  }
+
+  // --- Code Verifier (in-memory, ephemeral) ---
+
+  async saveCodeVerifier(verifier: string): Promise<void> {
+    this._codeVerifier = verifier;
+  }
+
+  async codeVerifier(): Promise<string> {
+    if (!this._codeVerifier) {
+      throw new Error('No code verifier available — OAuth flow not started');
+    }
+    return this._codeVerifier;
+  }
+
+  // --- Discovery State ---
+
+  async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
+    const raw = await getSecureKeyAsync(discoveryKey(this.serverId));
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as OAuthDiscoveryState;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async saveDiscoveryState(state: OAuthDiscoveryState): Promise<void> {
+    await setSecureKeyAsync(discoveryKey(this.serverId), JSON.stringify(state));
+  }
+
+  // --- Redirect to Authorization ---
+
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    const url = authorizationUrl.toString();
+
+    if (!this.interactive) {
+      // Daemon mode — don't open browser, just log guidance
+      log.info({ serverId: this.serverId }, 'OAuth required but running in non-interactive mode');
+      return;
+    }
+
+    log.info({ serverId: this.serverId }, 'Opening browser for OAuth authorization');
+    console.log(`[MCP] Opening browser for OAuth authorization of "${this.serverId}"...`);
+
+    try {
+      const { execFile } = await import('node:child_process');
+      const onError = (err: Error | null) => {
+        if (err) {
+          log.warn({ err }, 'Failed to open browser');
+          console.log(`[MCP] Please open this URL in your browser:\n${url}`);
+        }
+      };
+      if (isMacOS()) {
+        execFile('open', [url], onError);
+      } else if (isLinux()) {
+        execFile('xdg-open', [url], onError);
+      } else {
+        log.warn('Unsupported platform for browser open — please visit the URL manually');
+        console.log(`[MCP] Please open this URL in your browser:\n${url}`);
+      }
+    } catch (err) {
+      log.warn({ err }, 'Failed to open browser');
+      console.log(`[MCP] Please open this URL in your browser:\n${url}`);
+    }
+  }
+
+  // --- Invalidate Credentials ---
+
+  async invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void> {
+    log.info({ serverId: this.serverId, scope }, 'Invalidating OAuth credentials');
+
+    if (scope === 'all' || scope === 'tokens') {
+      await deleteSecureKeyAsync(tokensKey(this.serverId));
+    }
+    if (scope === 'all' || scope === 'client') {
+      await deleteSecureKeyAsync(clientInfoKey(this.serverId));
+    }
+    if (scope === 'all' || scope === 'verifier') {
+      this._codeVerifier = undefined;
+    }
+    if (scope === 'all' || scope === 'discovery') {
+      await deleteSecureKeyAsync(discoveryKey(this.serverId));
+    }
+  }
+
+  // --- Callback Server ---
+
+  /**
+   * Start a loopback HTTP server to receive the OAuth callback.
+   * Returns a promise that resolves with the authorization code.
+   */
+  startCallbackServer(): Promise<McpOAuthCallbackResult> {
+    return new Promise((resolveSetup, rejectSetup) => {
+      let settled = false;
+      let listening = false;
+      let codeResolve: (code: string) => void;
+      let codeReject: (err: Error) => void;
+
+      const codePromise = new Promise<string>((resolve, reject) => {
+        codeResolve = resolve;
+        codeReject = reject;
+      });
+      this._codePromise = codePromise;
+
+      const server = createServer((req, res) => {
+        if (settled) {
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end(renderPage('Authorization already completed', false));
+          return;
+        }
+
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname !== CALLBACK_PATH) {
+          res.writeHead(404, { 'Content-Type': 'text/plain' });
+          res.end('Not found');
+          return;
+        }
+
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+
+        settled = true;
+
+        if (error) {
+          const errorDesc = url.searchParams.get('error_description') ?? error;
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end(renderPage(`Authorization failed: ${errorDesc}`, false));
+          cleanup();
+          codeReject(new Error(`MCP OAuth authorization denied: ${error}`));
+          return;
+        }
+
+        if (!code) {
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end(renderPage('Missing authorization code', false));
+          cleanup();
+          codeReject(new Error('MCP OAuth callback missing authorization code'));
+          return;
+        }
+
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(renderPage('Authorization successful! You can close this tab.', true));
+        cleanup();
+        codeResolve(code);
+      });
+
+      this.callbackServer = server;
+
+      const timeout = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          cleanup();
+          codeReject(new Error('MCP OAuth callback timed out'));
+        }
+      }, CALLBACK_TIMEOUT_MS);
+      if (typeof timeout === 'object' && 'unref' in timeout) timeout.unref();
+      this.callbackTimeout = timeout;
+
+      const cleanup = () => {
+        if (this.callbackTimeout) {
+          clearTimeout(this.callbackTimeout);
+          this.callbackTimeout = null;
+        }
+        if (this.callbackServer) {
+          this.callbackServer.close();
+          this.callbackServer = null;
+        }
+      };
+
+      server.listen(0, '127.0.0.1', () => {
+        const addr = server.address() as { port: number };
+        this._redirectUrl = `http://127.0.0.1:${addr.port}${CALLBACK_PATH}`;
+        listening = true;
+        log.info({ serverId: this.serverId, redirectUrl: this._redirectUrl }, 'OAuth callback server started');
+        resolveSetup({ codePromise });
+      });
+
+      server.on('error', (err) => {
+        const message = `MCP OAuth callback server error: ${err.message}`;
+        if (!listening) {
+          settled = true;
+          cleanup();
+          rejectSetup(new Error(message));
+        } else if (!settled) {
+          settled = true;
+          cleanup();
+          codeReject(new Error(message));
+        }
+      });
+    });
+  }
+
+  /** Returns the code promise from the running callback server. */
+  waitForCode(): Promise<string> {
+    if (!this._codePromise) {
+      throw new Error('Callback server not started — call startCallbackServer() first');
+    }
+    return this._codePromise;
+  }
+
+  /** Stop the callback server if it's still running. */
+  stopCallbackServer(): void {
+    if (this.callbackTimeout) {
+      clearTimeout(this.callbackTimeout);
+      this.callbackTimeout = null;
+    }
+    if (this.callbackServer) {
+      this.callbackServer.close();
+      this.callbackServer = null;
+    }
+  }
+}
+
+// --- Static helpers ---
+
+/**
+ * Delete all OAuth credentials for a given MCP server.
+ * Used by `mcp remove` for cleanup.
+ */
+export async function deleteMcpOAuthCredentials(serverId: string): Promise<void> {
+  await Promise.all([
+    deleteSecureKeyAsync(tokensKey(serverId)),
+    deleteSecureKeyAsync(clientInfoKey(serverId)),
+    deleteSecureKeyAsync(discoveryKey(serverId)),
+  ]);
+  log.info({ serverId }, 'OAuth credentials deleted');
+}
+
+// --- HTML rendering ---
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function renderPage(message: string, success: boolean): string {
+  const title = success ? 'Authorization Successful' : 'Authorization Failed';
+  const color = success ? '#4CAF50' : '#f44336';
+  return `<!DOCTYPE html><html><head><title>${escapeHtml(title)}</title><style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#f5f5f5}div{text-align:center;padding:2rem;background:white;border-radius:8px;box-shadow:0 2px 4px rgba(0,0,0,0.1)}h1{color:${color}}</style></head><body><div><h1>${escapeHtml(title)}</h1><p>${escapeHtml(message)}</p></div></body></html>`;
+}

package/src/memory/channel-delivery-store.ts

@@ -33,6 +33,7 @@ export {
   getDeadLetterEvents,
   getRetryableEvents,
   markProcessed,
+  markRetryableFailure,
   recordProcessingFailure,
   replayDeadLetters,
 } from './delivery-status.js';

package/src/memory/db-init.ts

@@ -33,6 +33,7 @@ import {
   migrateGuardianBootstrapToken,
   migrateGuardianDeliveryConversationIndex,
   migrateGuardianPrincipalIdColumns,
+  migrateGuardianPrincipalIdNotNull,
   migrateGuardianVerificationPurpose,
   migrateGuardianVerificationSessions,
   migrateMessagesFtsBackfill,
@@ -185,5 +186,8 @@ export function initializeDb(): void {
   // 30. Backfill guardianPrincipalId for existing bindings and requests, expire unresolvable pending requests
   migrateBackfillGuardianPrincipalId(database);
 
+  // 31. Enforce NOT NULL on channel_guardian_bindings.guardian_principal_id
+  migrateGuardianPrincipalIdNotNull(database);
+
   validateMigrationState(database);
 }

package/src/memory/delivery-status.ts

@@ -107,6 +107,49 @@ export function recordProcessingFailure(eventId: string, err: unknown): void {
   }
 }
 
+/**
+ * Mark an event as failed with a specific error message, bypassing error
+ * classification. Use this when the failure reason is known and the event
+ * should remain retryable (up to max attempts).
+ */
+export function markRetryableFailure(eventId: string, errorMessage: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  const row = db
+    .select({ attempts: channelInboundEvents.processingAttempts })
+    .from(channelInboundEvents)
+    .where(eq(channelInboundEvents.id, eventId))
+    .get();
+
+  const attempts = (row?.attempts ?? 0) + 1;
+
+  if (attempts >= RETRY_MAX_ATTEMPTS) {
+    db.update(channelInboundEvents)
+      .set({
+        processingStatus: 'dead_letter',
+        processingAttempts: attempts,
+        lastProcessingError: errorMessage,
+        retryAfter: null,
+        updatedAt: now,
+      })
+      .where(eq(channelInboundEvents.id, eventId))
+      .run();
+  } else {
+    const delay = retryDelayForAttempt(attempts);
+    db.update(channelInboundEvents)
+      .set({
+        processingStatus: 'failed',
+        processingAttempts: attempts,
+        lastProcessingError: errorMessage,
+        retryAfter: now + delay,
+        updatedAt: now,
+      })
+      .where(eq(channelInboundEvents.id, eventId))
+      .run();
+  }
+}
+
 /** Fetch events eligible for automatic retry (failed + past their backoff). */
 export function getRetryableEvents(limit = 20): Array<{
   id: string;

package/src/memory/guardian-bindings.ts

@@ -23,7 +23,7 @@ export interface GuardianBinding {
   channel: string;
   guardianExternalUserId: string;
   guardianDeliveryChatId: string;
-  guardianPrincipalId: string | null;
+  guardianPrincipalId: string;
   status: BindingStatus;
   verifiedAt: number;
   verifiedVia: string;
@@ -62,7 +62,7 @@ export function createBinding(params: {
   channel: string;
   guardianExternalUserId: string;
   guardianDeliveryChatId: string;
-  guardianPrincipalId?: string | null;
+  guardianPrincipalId: string;
   verifiedVia?: string;
   metadataJson?: string | null;
 }): GuardianBinding {
@@ -76,7 +76,7 @@ export function createBinding(params: {
     channel: params.channel,
     guardianExternalUserId: params.guardianExternalUserId,
     guardianDeliveryChatId: params.guardianDeliveryChatId,
-    guardianPrincipalId: params.guardianPrincipalId ?? null,
+    guardianPrincipalId: params.guardianPrincipalId,
     status: 'active' as const,
     verifiedAt: now,
     verifiedVia: params.verifiedVia ?? 'challenge',

package/src/memory/migrations/127-guardian-principal-id-not-null.ts

@@ -0,0 +1,108 @@
+import { type DrizzleDb, getSqliteFrom } from '../db-connection.js';
+import { withCrashRecovery } from './validate-migration-state.js';
+
+/**
+ * Enforce NOT NULL on channel_guardian_bindings.guardian_principal_id.
+ *
+ * Migration 125 added the column as nullable, and migration 126 backfilled
+ * existing rows. This migration:
+ *
+ * 1. Backfills any remaining null guardian_principal_id rows with
+ *    guardian_external_user_id as a sensible default (same fallback
+ *    strategy used by migration 126).
+ * 2. Rebuilds the table to add a NOT NULL constraint on the column
+ *    (SQLite does not support ALTER COLUMN).
+ *
+ * Idempotent: checks the DDL before rebuilding; skips if the column
+ * already has NOT NULL.
+ */
+export function migrateGuardianPrincipalIdNotNull(database: DrizzleDb): void {
+  withCrashRecovery(database, 'migration_guardian_principal_id_not_null_v1', () => {
+    const raw = getSqliteFrom(database);
+
+    // Guard: table must exist
+    const tableExists = raw.query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'channel_guardian_bindings'`,
+    ).get();
+    if (!tableExists) return;
+
+    // Guard: column must exist (added by migration 125)
+    const colExists = raw.query(
+      `SELECT 1 FROM pragma_table_info('channel_guardian_bindings') WHERE name = 'guardian_principal_id'`,
+    ).get();
+    if (!colExists) return;
+
+    // Check if the column already has NOT NULL (idempotency)
+    const colInfo = raw.query(
+      `SELECT "notnull" FROM pragma_table_info('channel_guardian_bindings') WHERE name = 'guardian_principal_id'`,
+    ).get() as { notnull: number } | null;
+    if (colInfo && colInfo.notnull === 1) return;
+
+    raw.exec('PRAGMA foreign_keys = OFF');
+    try {
+      raw.exec('BEGIN');
+
+      // Backfill any remaining null rows before adding the constraint
+      raw.exec(/*sql*/ `
+        UPDATE channel_guardian_bindings
+        SET guardian_principal_id = guardian_external_user_id,
+            updated_at = ${Date.now()}
+        WHERE guardian_principal_id IS NULL
+          AND guardian_external_user_id IS NOT NULL
+      `);
+
+      // For any rows where even guardian_external_user_id is null (shouldn't
+      // happen but defensive), use 'unknown' as a placeholder
+      raw.exec(/*sql*/ `
+        UPDATE channel_guardian_bindings
+        SET guardian_principal_id = 'unknown',
+            updated_at = ${Date.now()}
+        WHERE guardian_principal_id IS NULL
+      `);
+
+      // Rebuild the table with NOT NULL on guardian_principal_id
+      raw.exec(/*sql*/ `
+        CREATE TABLE channel_guardian_bindings_new (
+          id TEXT PRIMARY KEY,
+          assistant_id TEXT NOT NULL,
+          channel TEXT NOT NULL,
+          guardian_external_user_id TEXT NOT NULL,
+          guardian_delivery_chat_id TEXT NOT NULL,
+          guardian_principal_id TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'active',
+          verified_at INTEGER NOT NULL,
+          verified_via TEXT NOT NULL DEFAULT 'challenge',
+          metadata_json TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )
+      `);
+
+      raw.exec(/*sql*/ `
+        INSERT INTO channel_guardian_bindings_new
+        SELECT id, assistant_id, channel, guardian_external_user_id,
+               guardian_delivery_chat_id, guardian_principal_id,
+               status, verified_at, verified_via, metadata_json,
+               created_at, updated_at
+        FROM channel_guardian_bindings
+      `);
+
+      raw.exec(/*sql*/ `DROP TABLE channel_guardian_bindings`);
+      raw.exec(/*sql*/ `ALTER TABLE channel_guardian_bindings_new RENAME TO channel_guardian_bindings`);
+
+      // Recreate the unique index for active bindings
+      raw.exec(/*sql*/ `
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_guardian_bindings_active
+        ON channel_guardian_bindings(assistant_id, channel)
+        WHERE status = 'active'
+      `);
+
+      raw.exec('COMMIT');
+    } catch (e) {
+      try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+      throw e;
+    } finally {
+      raw.exec('PRAGMA foreign_keys = ON');
+    }
+  });
+}

package/src/memory/migrations/index.ts

@@ -68,6 +68,7 @@ export { migrateCanonicalGuardianDeliveriesDestinationIndex } from './123-canoni
 export { migrateVoiceInviteDisplayMetadata } from './124-voice-invite-display-metadata.js';
 export { migrateGuardianPrincipalIdColumns } from './125-guardian-principal-id-columns.js';
 export { migrateBackfillGuardianPrincipalId } from './126-backfill-guardian-principal-id.js';
+export { migrateGuardianPrincipalIdNotNull } from './127-guardian-principal-id-not-null.js';
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/migrations/registry.ts

@@ -100,6 +100,12 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     version: 15,
     description: 'Backfill guardianPrincipalId for existing channel_guardian_bindings and canonical_guardian_requests rows, expire unresolvable pending requests',
   },
+  {
+    key: 'migration_guardian_principal_id_not_null_v1',
+    version: 16,
+    dependsOn: ['migration_backfill_guardian_principal_id_v3'],
+    description: 'Enforce NOT NULL on channel_guardian_bindings.guardian_principal_id after backfill',
+  },
 ];
 
 export interface MigrationValidationResult {

package/src/memory/schema.ts

@@ -637,7 +637,7 @@ export const channelGuardianBindings = sqliteTable('channel_guardian_bindings',
   channel: text('channel').notNull(),
   guardianExternalUserId: text('guardian_external_user_id').notNull(),
   guardianDeliveryChatId: text('guardian_delivery_chat_id').notNull(),
-  guardianPrincipalId: text('guardian_principal_id'),
+  guardianPrincipalId: text('guardian_principal_id').notNull(),
   status: text('status').notNull().default('active'),
   verifiedAt: integer('verified_at').notNull(),
   verifiedVia: text('verified_via').notNull().default('challenge'),

package/src/runtime/actor-trust-resolver.ts

@@ -20,6 +20,8 @@ import { canonicalizeInboundIdentity } from '../util/canonicalize-identity.js';
 import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
 import { getGuardianBinding } from './channel-guardian-service.js';
 
+export type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -35,8 +37,8 @@ export interface ActorTrustContext {
     guardianExternalUserId: string;
     guardianDeliveryChatId: string | null;
   } | null;
-  /** Canonical principal ID from the guardian binding. Nullable for backward compatibility — M5 will make this required. */
-  guardianPrincipalId?: string | null;
+  /** Canonical principal ID from the guardian binding. */
+  guardianPrincipalId?: string;
   /** Ingress member record, if any, for this sender. */
   memberRecord: IngressMember | null;
   /** Trust classification. */
@@ -184,7 +186,7 @@ export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustCont
   return {
     canonicalSenderId,
     guardianBindingMatch,
-    guardianPrincipalId: binding?.guardianPrincipalId ?? undefined,
+    guardianPrincipalId: binding?.guardianPrincipalId,
     memberRecord,
     trustClass,
     actorMetadata: {
@@ -203,17 +205,24 @@ export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustCont
 /**
  * Convert an ActorTrustContext into the runtime trust context shape used by
  * sessions/tooling.
+ *
+ * This is the single canonical conversion from resolved trust to runtime
+ * context. The guardianExternalUserId is canonicalized to handle phone-
+ * channel formatting variance (e.g. stored binding vs E.164).
  */
 export function toGuardianRuntimeContextFromTrust(
   ctx: ActorTrustContext,
   conversationExternalId: string,
 ): GuardianRuntimeContext {
+  const canonicalGuardianExternalUserId = ctx.guardianBindingMatch?.guardianExternalUserId
+    ? canonicalizeInboundIdentity(ctx.actorMetadata.channel, ctx.guardianBindingMatch.guardianExternalUserId) ?? undefined
+    : undefined;
   return {
     sourceChannel: ctx.actorMetadata.channel,
     trustClass: ctx.trustClass,
     guardianChatId: ctx.guardianBindingMatch?.guardianDeliveryChatId ??
       (ctx.trustClass === 'guardian' ? conversationExternalId : undefined),
-    guardianExternalUserId: ctx.guardianBindingMatch?.guardianExternalUserId,
+    guardianExternalUserId: canonicalGuardianExternalUserId,
     guardianPrincipalId: ctx.guardianPrincipalId,
     requesterIdentifier: ctx.actorMetadata.identifier,
     requesterDisplayName: ctx.actorMetadata.displayName,