@vellumai/assistant 0.3.26 → 0.3.28

package/src/runtime/access-request-helper.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared access-request creation and notification helper.
+ *
+ * Encapsulates the "create/dedupe canonical access request + emit notification"
+ * logic so both text-channel and voice-channel ingress paths use identical
+ * guardian notification flows.
+ */
+
+import type { ChannelId } from '../channels/types.js';
+import {
+  createCanonicalGuardianRequest,
+  listCanonicalGuardianRequests,
+} from '../memory/canonical-guardian-store.js';
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
+import { getLogger } from '../util/logger.js';
+import { getGuardianBinding } from './channel-guardian-service.js';
+import { GUARDIAN_APPROVAL_TTL_MS } from './routes/channel-route-shared.js';
+
+const log = getLogger('access-request-helper');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface AccessRequestParams {
+  canonicalAssistantId: string;
+  sourceChannel: ChannelId;
+  externalChatId: string;
+  senderExternalUserId?: string;
+  senderName?: string;
+  senderUsername?: string;
+}
+
+export type AccessRequestResult =
+  | { notified: true; created: boolean; requestId: string }
+  | { notified: false; reason: 'no_sender_id' | 'no_guardian_binding' };
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Create/dedupe a canonical access request and emit a notification signal
+ * so the guardian can approve or deny the unknown sender.
+ *
+ * Returns a result indicating whether the guardian was notified and whether
+ * a new request was created or an existing one was deduped.
+ *
+ * This is intentionally synchronous with respect to the canonical store writes
+ * and fire-and-forget for the notification signal emission.
+ */
+export function notifyGuardianOfAccessRequest(
+  params: AccessRequestParams,
+): AccessRequestResult {
+  const {
+    canonicalAssistantId,
+    sourceChannel,
+    externalChatId,
+    senderExternalUserId,
+    senderName,
+    senderUsername,
+  } = params;
+
+  if (!senderExternalUserId) {
+    return { notified: false, reason: 'no_sender_id' };
+  }
+
+  const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
+  if (!binding) {
+    log.debug({ sourceChannel, canonicalAssistantId }, 'No guardian binding for access request notification');
+    return { notified: false, reason: 'no_guardian_binding' };
+  }
+
+  // Deduplicate: skip creation if there is already a pending canonical request
+  // for the same requester on this channel. Still return notified: true with
+  // the existing request ID so callers know the guardian was already notified.
+  const existingCanonical = listCanonicalGuardianRequests({
+    status: 'pending',
+    requesterExternalUserId: senderExternalUserId,
+    sourceChannel,
+    kind: 'access_request',
+  });
+  if (existingCanonical.length > 0) {
+    log.debug(
+      { sourceChannel, senderExternalUserId, existingId: existingCanonical[0].id },
+      'Skipping duplicate access request notification',
+    );
+    return { notified: true, created: false, requestId: existingCanonical[0].id };
+  }
+
+  const senderIdentifier = senderName || senderUsername || senderExternalUserId;
+  const requestId = `access-req-${canonicalAssistantId}-${sourceChannel}-${senderExternalUserId}-${Date.now()}`;
+
+  const canonicalRequest = createCanonicalGuardianRequest({
+    id: requestId,
+    kind: 'access_request',
+    sourceType: 'channel',
+    sourceChannel,
+    conversationId: `access-req-${sourceChannel}-${senderExternalUserId}`,
+    requesterExternalUserId: senderExternalUserId,
+    requesterChatId: externalChatId,
+    guardianExternalUserId: binding.guardianExternalUserId,
+    toolName: 'ingress_access_request',
+    questionText: `${senderIdentifier} is requesting access to the assistant`,
+    expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
+  });
+
+  void emitNotificationSignal({
+    sourceEventName: 'ingress.access_request',
+    sourceChannel,
+    sourceSessionId: `access-req-${sourceChannel}-${senderExternalUserId}`,
+    assistantId: canonicalAssistantId,
+    attentionHints: {
+      requiresAction: true,
+      urgency: 'high',
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    contextPayload: {
+      requestId,
+      sourceChannel,
+      externalChatId,
+      senderExternalUserId,
+      senderName: senderName ?? null,
+      senderUsername: senderUsername ?? null,
+      senderIdentifier,
+    },
+    dedupeKey: `access-request:${canonicalRequest.id}`,
+  });
+
+  log.info(
+    { sourceChannel, senderExternalUserId, senderIdentifier },
+    'Guardian notified of access request',
+  );
+
+  return { notified: true, created: true, requestId: canonicalRequest.id };
+}

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

@@ -0,0 +1,225 @@
+/**
+ * Unified inbound actor trust resolver.
+ *
+ * Produces a single trust-resolved actor context from raw inbound identity
+ * fields. Normalizes sender identity via channel-agnostic canonicalization,
+ * then resolves trust classification by checking guardian bindings and
+ * ingress member records.
+ *
+ * Trust classifications:
+ * - `guardian`: sender matches the active guardian binding for this channel.
+ * - `trusted_contact`: sender is an active ingress member (not the guardian).
+ * - `unknown`: sender has no member record or no identity could be established.
+ *
+ * The legacy `ActorRole` enum (`guardian` / `non-guardian` / `unverified_channel`)
+ * is still required by existing policy gates. The `toLegacyActorRole()` mapper
+ * converts the new trust classification to the legacy enum.
+ */
+
+import type { ChannelId } from '../channels/types.js';
+import type { IngressMember } from '../memory/ingress-member-store.js';
+import { findMember } from '../memory/ingress-member-store.js';
+import { canonicalizeInboundIdentity } from '../util/canonicalize-identity.js';
+import { normalizeAssistantId } from '../util/platform.js';
+import { getGuardianBinding } from './channel-guardian-service.js';
+import type { ActorRole, DenialReason, GuardianContext } from './guardian-context-resolver.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type TrustClass = 'guardian' | 'trusted_contact' | 'unknown';
+
+export interface ActorTrustContext {
+  /** Canonical (normalized) sender identity. Null when identity could not be established. */
+  canonicalSenderId: string | null;
+  /** Guardian binding match, if any, for this (assistantId, channel). */
+  guardianBindingMatch: {
+    guardianExternalUserId: string;
+    guardianDeliveryChatId: string | null;
+  } | null;
+  /** Ingress member record, if any, for this sender. */
+  memberRecord: IngressMember | null;
+  /** Trust classification. */
+  trustClass: TrustClass;
+  /** Assistant-facing metadata for downstream consumption. */
+  actorMetadata: {
+    identifier: string | undefined;
+    displayName: string | undefined;
+    username: string | undefined;
+    channel: ChannelId;
+    trustStatus: TrustClass;
+  };
+  /** Legacy denial reason for backward-compatible unverified_channel paths. */
+  denialReason?: DenialReason;
+}
+
+export interface ResolveActorTrustInput {
+  assistantId: string;
+  sourceChannel: ChannelId;
+  externalChatId: string;
+  senderExternalUserId?: string;
+  senderUsername?: string;
+  senderDisplayName?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the inbound actor's trust context from raw identity fields.
+ *
+ * 1. Canonicalize the sender identity (E.164 for phone channels, trimmed ID otherwise).
+ * 2. Look up the guardian binding for (assistantId, channel).
+ * 3. Compare canonical sender identity to the guardian binding.
+ * 4. Look up the ingress member record using the canonical identity.
+ * 5. Classify: guardian > trusted_contact (active member) > unknown.
+ */
+export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustContext {
+  const assistantId = normalizeAssistantId(input.assistantId);
+
+  const rawUserId = typeof input.senderExternalUserId === 'string' && input.senderExternalUserId.trim().length > 0
+    ? input.senderExternalUserId.trim()
+    : undefined;
+
+  const senderUsername = typeof input.senderUsername === 'string' && input.senderUsername.trim().length > 0
+    ? input.senderUsername.trim()
+    : undefined;
+
+  const senderDisplayName = typeof input.senderDisplayName === 'string' && input.senderDisplayName.trim().length > 0
+    ? input.senderDisplayName.trim()
+    : undefined;
+
+  // Canonical identity: normalize phone-like channels to E.164.
+  const canonicalSenderId = rawUserId
+    ? canonicalizeInboundIdentity(input.sourceChannel, rawUserId)
+    : null;
+
+  const identifier = senderUsername ? `@${senderUsername}` : canonicalSenderId ?? undefined;
+
+  // No identity at all => unknown
+  if (!canonicalSenderId) {
+    return {
+      canonicalSenderId: null,
+      guardianBindingMatch: null,
+      memberRecord: null,
+      trustClass: 'unknown',
+      actorMetadata: {
+        identifier,
+        displayName: senderDisplayName,
+        username: senderUsername,
+        channel: input.sourceChannel,
+        trustStatus: 'unknown',
+      },
+      denialReason: 'no_identity',
+    };
+  }
+
+  // Guardian binding lookup
+  const binding = getGuardianBinding(assistantId, input.sourceChannel);
+  const guardianBindingMatch = binding
+    ? { guardianExternalUserId: binding.guardianExternalUserId, guardianDeliveryChatId: binding.guardianDeliveryChatId }
+    : null;
+
+  // Check if sender IS the guardian. Compare canonical sender against the
+  // binding's guardian identity (also canonicalize for phone channels to
+  // handle formatting variance in the stored binding).
+  let isGuardian = false;
+  if (binding) {
+    const canonicalGuardianId = canonicalizeInboundIdentity(input.sourceChannel, binding.guardianExternalUserId);
+    isGuardian = canonicalGuardianId === canonicalSenderId;
+  }
+
+  // Ingress member lookup using canonical identity.
+  const memberRecord = findMember({
+    assistantId,
+    sourceChannel: input.sourceChannel,
+    externalUserId: canonicalSenderId,
+    externalChatId: input.externalChatId,
+  });
+
+  // Trust classification
+  let trustClass: TrustClass;
+  if (isGuardian) {
+    trustClass = 'guardian';
+  } else if (memberRecord && memberRecord.status === 'active') {
+    trustClass = 'trusted_contact';
+  } else {
+    trustClass = 'unknown';
+  }
+
+  // Denial reason for legacy compatibility
+  let denialReason: DenialReason | undefined;
+  if (!isGuardian && !binding) {
+    denialReason = 'no_binding';
+  }
+
+  return {
+    canonicalSenderId,
+    guardianBindingMatch,
+    memberRecord,
+    trustClass,
+    actorMetadata: {
+      identifier,
+      displayName: senderDisplayName,
+      username: senderUsername,
+      channel: input.sourceChannel,
+      trustStatus: trustClass,
+    },
+    denialReason,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Legacy compatibility mapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Map the new trust classification to the legacy ActorRole enum used by
+ * existing policy gates. This preserves backward compatibility while the
+ * codebase migrates to the unified trust model.
+ *
+ * Mapping:
+ * - guardian => 'guardian'
+ * - trusted_contact => 'non-guardian' (existing gates treat active members as non-guardian)
+ * - unknown (no_identity) => 'unverified_channel'
+ * - unknown (no_binding) => 'unverified_channel'
+ * - unknown (with binding, not guardian) => 'non-guardian'
+ */
+export function toLegacyActorRole(ctx: ActorTrustContext): ActorRole {
+  if (ctx.trustClass === 'guardian') return 'guardian';
+  if (ctx.trustClass === 'trusted_contact') return 'non-guardian';
+
+  // unknown: distinguish between unverified_channel and non-guardian
+  if (ctx.denialReason === 'no_identity' || ctx.denialReason === 'no_binding') {
+    return 'unverified_channel';
+  }
+
+  // Has a binding, has identity, but not guardian and not a member => non-guardian
+  if (ctx.guardianBindingMatch && ctx.canonicalSenderId) {
+    return 'non-guardian';
+  }
+
+  return 'unverified_channel';
+}
+
+/**
+ * Convert an ActorTrustContext into the legacy GuardianContext shape that
+ * existing route-level code expects. This is a bridge for incremental
+ * migration — new code should consume ActorTrustContext directly.
+ */
+export function toGuardianContextCompat(ctx: ActorTrustContext, externalChatId: string): GuardianContext {
+  const actorRole = toLegacyActorRole(ctx);
+
+  return {
+    actorRole,
+    guardianChatId: ctx.guardianBindingMatch?.guardianDeliveryChatId ??
+      (actorRole === 'guardian' ? externalChatId : undefined),
+    guardianExternalUserId: ctx.guardianBindingMatch?.guardianExternalUserId,
+    requesterIdentifier: ctx.actorMetadata.identifier,
+    requesterExternalUserId: ctx.canonicalSenderId ?? undefined,
+    requesterChatId: externalChatId,
+    denialReason: ctx.denialReason,
+  };
+}

package/src/runtime/channel-guardian-service.ts

@@ -231,11 +231,19 @@ export function validateAndConsumeChallenge(
       }
     }
 
-    // For Telegram: verify actorChatId matches expectedChatId
-    // AND/OR actorExternalUserId matches expectedExternalUserId
+    // For chat-based channels (Telegram, Slack, etc.): when both
+    // expectedExternalUserId and expectedChatId are set, require the
+    // externalUserId match — chatId alone is insufficient because chat IDs
+    // can be shared (e.g. Slack channel IDs, Telegram group chat IDs) and
+    // would let any participant in the same chat satisfy identity binding.
+    // Fall back to chatId-only match only when expectedExternalUserId is
+    // not available (legacy sessions or channels without user-level identity).
     if (challenge.expectedChatId != null) {
-      if (actorChatId === challenge.expectedChatId ||
-          actorExternalUserId === challenge.expectedExternalUserId) {
+      if (challenge.expectedExternalUserId != null) {
+        if (actorExternalUserId === challenge.expectedExternalUserId) {
+          identityMatch = true;
+        }
+      } else if (actorChatId === challenge.expectedChatId) {
         identityMatch = true;
       }
     }

package/src/runtime/guardian-context-resolver.ts

@@ -4,9 +4,13 @@
  * This module centralizes how we classify an inbound actor as
  * guardian/non-guardian/unverified so every channel path uses the same
  * source-of-truth logic.
+ *
+ * Guardian binding comparisons now use canonicalized identities (E.164 for
+ * phone-like channels) to eliminate formatting-variance mismatches.
  */
 import type { ChannelId } from '../channels/types.js';
 import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import { canonicalizeInboundIdentity } from '../util/canonicalize-identity.js';
 import { normalizeAssistantId } from '../util/platform.js';
 import { getGuardianBinding } from './channel-guardian-service.js';
 
@@ -41,18 +45,32 @@ export interface ResolveGuardianContextInput {
  * - active binding exists but sender differs -> non-guardian
  * - no sender identity -> unverified_channel (no_identity)
  * - no binding -> unverified_channel (no_binding)
+ *
+ * Identity comparison is normalization-safe: both the sender ID and the
+ * guardian binding ID are canonicalized for the source channel before
+ * comparison, so formatting differences (e.g. `+1 (555) 123-4567` vs
+ * `+15551234567`) do not cause false non-guardian classifications.
  */
 export function resolveGuardianContext(input: ResolveGuardianContextInput): GuardianContext {
   const assistantId = normalizeAssistantId(input.assistantId);
-  const senderExternalUserId = typeof input.senderExternalUserId === 'string' && input.senderExternalUserId.trim().length > 0
+  const rawUserId = typeof input.senderExternalUserId === 'string' && input.senderExternalUserId.trim().length > 0
     ? input.senderExternalUserId.trim()
     : undefined;
   const senderUsername = typeof input.senderUsername === 'string' && input.senderUsername.trim().length > 0
     ? input.senderUsername.trim()
     : undefined;
-  const requesterIdentifier = senderUsername ? `@${senderUsername}` : senderExternalUserId;
 
-  if (!senderExternalUserId) {
+  // Canonicalize sender identity for normalization-safe comparisons.
+  // canonicalizeInboundIdentity returns string | null; coerce to
+  // string | undefined so assignments to optional (string | undefined)
+  // fields in GuardianContext don't produce a type mismatch.
+  const canonicalSenderId = rawUserId
+    ? (canonicalizeInboundIdentity(input.sourceChannel, rawUserId) ?? undefined)
+    : undefined;
+
+  const requesterIdentifier = senderUsername ? `@${senderUsername}` : canonicalSenderId;
+
+  if (!canonicalSenderId) {
     return {
       actorRole: 'unverified_channel',
       denialReason: 'no_identity',
@@ -68,18 +86,25 @@ export function resolveGuardianContext(input: ResolveGuardianContextInput): Guar
       actorRole: 'unverified_channel',
       denialReason: 'no_binding',
       requesterIdentifier,
-      requesterExternalUserId: senderExternalUserId,
+      requesterExternalUserId: canonicalSenderId,
       requesterChatId: input.externalChatId,
     };
   }
 
-  if (binding.guardianExternalUserId === senderExternalUserId) {
+  // Canonicalize the stored guardian identity for the same channel so
+  // phone-format variance in the binding record doesn't cause mismatches.
+  const canonicalGuardianId = canonicalizeInboundIdentity(
+    input.sourceChannel,
+    binding.guardianExternalUserId,
+  ) ?? undefined;
+
+  if (canonicalGuardianId === canonicalSenderId) {
     return {
       actorRole: 'guardian',
       guardianChatId: binding.guardianDeliveryChatId || input.externalChatId,
       guardianExternalUserId: binding.guardianExternalUserId,
       requesterIdentifier,
-      requesterExternalUserId: senderExternalUserId,
+      requesterExternalUserId: canonicalSenderId,
       requesterChatId: input.externalChatId,
     };
   }
@@ -89,7 +114,7 @@ export function resolveGuardianContext(input: ResolveGuardianContextInput): Guar
     guardianChatId: binding.guardianDeliveryChatId,
     guardianExternalUserId: binding.guardianExternalUserId,
     requesterIdentifier,
-    requesterExternalUserId: senderExternalUserId,
+    requesterExternalUserId: canonicalSenderId,
     requesterChatId: input.externalChatId,
   };
 }

package/src/runtime/guardian-decision-types.ts

@@ -22,6 +22,12 @@ export interface GuardianDecisionPrompt {
   expiresAt: number;
   conversationId: string;
   callSessionId: string | null;
+  /**
+   * Canonical request kind (e.g. 'tool_approval', 'pending_question').
+   * Present when the prompt originates from the canonical guardian request
+   * store. Absent for legacy-only prompts.
+   */
+  kind?: string;
 }
 
 export interface GuardianDecisionAction {