@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/calls/__tests__/relay-setup-router.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Tests for the inbound admission-floor enforcement in `routeSetup`.
+ *
+ * `routeSetup` is pure routing logic but reads several module-level singletons
+ * (config, trust resolver, pending verification session, invite store). These
+ * are mocked so the table below can drive trust class, member status, pending
+ * challenge, and active invites independently of any DB.
+ *
+ * The floor verdict is exercised through the REAL `enforceAdmissionPolicy`
+ * floor tables (`TRUST_CLASS_RANK` × `ADMISSION_FLOOR`), with the exempt-channel
+ * short-circuit bypassed in the mock so the tests assert the true floor
+ * semantics independent of any channel's exempt status (`phone` is now
+ * enforced).
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import {
+  ADMISSION_FLOOR,
+  type AdmissionPolicy,
+} from "@vellumai/gateway-client";
+
+import type {
+  ChannelPolicy,
+  ChannelStatus,
+} from "../../contacts/types.js";
+import type {
+  ActorTrustContext,
+  TrustClass,
+} from "../../runtime/actor-trust-resolver.js";
+import { TRUST_CLASS_RANK } from "../../runtime/actor-trust-resolver.js";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({ calls: { verification: { enabled: false } } }),
+}));
+
+// Controllable resolved trust context.
+let nextTrust: ActorTrustContext;
+mock.module("../../runtime/actor-trust-resolver.js", () => ({
+  resolveActorTrust: () => nextTrust,
+  // Re-export the real rank table; the floor mock below consumes it.
+  TRUST_CLASS_RANK,
+}));
+
+// Controllable pending verification challenge.
+let pendingChallenge: unknown = null;
+mock.module("../../runtime/channel-verification-service.js", () => ({
+  getPendingSession: () => pendingChallenge,
+}));
+
+// Controllable active voice invites.
+let activeInvites: Array<{
+  friendName: string | null;
+  guardianName: string | null;
+  expiresAt?: number;
+}> = [];
+mock.module("../../memory/invite-store.js", () => ({
+  findActiveVoiceInvites: () => activeInvites,
+}));
+
+// Real floor semantics, exemption bypassed (see file header).
+mock.module(
+  "../../runtime/routes/inbound-stages/admission-policy.js",
+  () => ({
+    enforceAdmissionPolicy: (input: {
+      trustClass: TrustClass;
+      memberStatus: ChannelStatus | undefined;
+      policy: AdmissionPolicy;
+    }) => {
+      if (input.memberStatus === "blocked" || input.memberStatus === "revoked") {
+        return {
+          admitted: false,
+          reason:
+            input.memberStatus === "blocked"
+              ? "member_blocked"
+              : "member_revoked",
+          shouldChallenge: false,
+          effectivePolicy: input.policy,
+        };
+      }
+      const rank = TRUST_CLASS_RANK[input.trustClass];
+      const floor = ADMISSION_FLOOR[input.policy];
+      if (rank >= floor) return { admitted: true };
+      return {
+        admitted: false,
+        reason: `admission_policy_${input.policy}`,
+        shouldChallenge: false,
+        effectivePolicy: input.policy,
+      };
+    },
+  }),
+);
+
+const { routeSetup } = await import("../relay-setup-router.js");
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function makeTrust(
+  trustClass: TrustClass,
+  channel?: { status: ChannelStatus; policy?: ChannelPolicy; role?: string },
+): ActorTrustContext {
+  const memberRecord = channel
+    ? {
+        contact: {
+          displayName: "Test Caller",
+          role: channel.role ?? "trusted_contact",
+        } as never,
+        channel: {
+          id: "ch_1",
+          status: channel.status,
+          policy: channel.policy ?? "allow",
+        } as never,
+      }
+    : null;
+  return {
+    canonicalSenderId: "+15551234567",
+    guardianBindingMatch: null,
+    memberRecord,
+    trustClass,
+    actorMetadata: {
+      identifier: "+15551234567",
+      displayName: undefined,
+      senderDisplayName: undefined,
+      memberDisplayName: undefined,
+      username: undefined,
+      channel: "phone",
+      trustStatus: trustClass,
+    },
+  } as ActorTrustContext;
+}
+
+function route(admissionPolicy?: AdmissionPolicy | null) {
+  return routeSetup({
+    callSessionId: "cs_1",
+    session: null, // inbound
+    from: "+15551234567",
+    to: "+15559999999",
+    admissionPolicy,
+  });
+}
+
+beforeEach(() => {
+  pendingChallenge = null;
+  activeInvites = [];
+});
+
+// ---------------------------------------------------------------------------
+// Floor table: trustClass × policy → admit/deny
+// ---------------------------------------------------------------------------
+
+describe("routeSetup — admission floor table", () => {
+  // For "known" classes (trusted_contact, guardian) the resolver yields a
+  // member channel; unknown/unverified flow through the unknown ACL branch.
+  function setTrust(trustClass: TrustClass) {
+    if (trustClass === "guardian") {
+      nextTrust = makeTrust("guardian", {
+        status: "active",
+        role: "guardian",
+      });
+    } else if (trustClass === "trusted_contact") {
+      nextTrust = makeTrust("trusted_contact", { status: "active" });
+    } else if (trustClass === "unverified_contact") {
+      nextTrust = makeTrust("unverified_contact", { status: "unverified" });
+    } else {
+      nextTrust = makeTrust("unknown");
+    }
+  }
+
+  const cases: Array<{
+    policy: AdmissionPolicy;
+    admits: TrustClass[];
+    denies: TrustClass[];
+  }> = [
+    {
+      policy: "strangers",
+      admits: ["unknown", "unverified_contact", "trusted_contact", "guardian"],
+      denies: [],
+    },
+    {
+      policy: "any_contact",
+      admits: ["unverified_contact", "trusted_contact", "guardian"],
+      denies: ["unknown"],
+    },
+    {
+      policy: "trusted_contacts",
+      admits: ["trusted_contact", "guardian"],
+      denies: ["unknown", "unverified_contact"],
+    },
+    {
+      policy: "guardian_only",
+      admits: ["guardian"],
+      denies: ["unknown", "unverified_contact", "trusted_contact"],
+    },
+    {
+      policy: "no_one",
+      admits: [],
+      denies: ["unknown", "unverified_contact", "trusted_contact", "guardian"],
+    },
+  ];
+
+  for (const { policy, admits, denies } of cases) {
+    for (const trustClass of denies) {
+      test(`${policy} denies ${trustClass}`, () => {
+        setTrust(trustClass);
+        const { outcome } = route(policy);
+        expect(outcome.action).toBe("deny");
+        if (outcome.action === "deny") {
+          expect(outcome.logReason).toBe(
+            `Inbound voice admission floor: ${policy}`,
+          );
+        }
+      });
+    }
+    for (const trustClass of admits) {
+      test(`${policy} admits ${trustClass}`, () => {
+        setTrust(trustClass);
+        const { outcome } = route(policy);
+        expect(outcome.action).not.toBe("deny");
+      });
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Blocked / revoked always deny
+// ---------------------------------------------------------------------------
+
+describe("routeSetup — blocked / revoked", () => {
+  test("blocked caller is denied (pre-floor ACL check)", () => {
+    nextTrust = makeTrust("unknown", { status: "blocked" });
+    const { outcome } = route("strangers");
+    expect(outcome.action).toBe("deny");
+  });
+
+  test("revoked member is denied under permissive floor", () => {
+    // Revoked → resolver classifies as unknown; the floor mock denies on
+    // memberStatus regardless of the permissive policy.
+    nextTrust = makeTrust("unknown", { status: "revoked" });
+    const { outcome } = route("strangers");
+    expect(outcome.action).toBe("deny");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// admissionPolicy null/undefined → current behavior unchanged
+// ---------------------------------------------------------------------------
+
+describe("routeSetup — no policy preserves current behavior", () => {
+  test("unknown caller → name_capture", () => {
+    nextTrust = makeTrust("unknown");
+    expect(route(null).outcome.action).toBe("name_capture");
+    expect(route(undefined).outcome.action).toBe("name_capture");
+  });
+
+  test("unverified known caller → unverified_caller", () => {
+    nextTrust = makeTrust("unverified_contact", { status: "unverified" });
+    expect(route(null).outcome.action).toBe("unverified_caller");
+  });
+
+  test("trusted contact → normal_call", () => {
+    nextTrust = makeTrust("trusted_contact", { status: "active" });
+    expect(route(null).outcome.action).toBe("normal_call");
+  });
+
+  test("guardian → normal_call", () => {
+    nextTrust = makeTrust("guardian", { status: "active", role: "guardian" });
+    expect(route(null).outcome.action).toBe("normal_call");
+  });
+
+  test("member policy deny still denies", () => {
+    nextTrust = makeTrust("trusted_contact", {
+      status: "active",
+      policy: "deny",
+    });
+    expect(route(null).outcome.action).toBe("deny");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Active permissive floor admits straight to a normal call
+// ---------------------------------------------------------------------------
+// When a policy is ACTIVELY set and admits the caller, the floor is the access
+// decision: unknown/unverified callers bypass name_capture / unverified_caller
+// and connect directly. With a null policy the legacy identity flows persist.
+
+describe("routeSetup — permissive floor admits to normal_call", () => {
+  test("any_contact admits an unverified_contact to normal_call (not unverified_caller)", () => {
+    nextTrust = makeTrust("unverified_contact", { status: "unverified" });
+    const { outcome } = route("any_contact");
+    expect(outcome.action).toBe("normal_call");
+  });
+
+  test("strangers admits an unknown caller to normal_call (not name_capture)", () => {
+    nextTrust = makeTrust("unknown");
+    const { outcome } = route("strangers");
+    expect(outcome.action).toBe("normal_call");
+  });
+
+  test("strangers admits an unverified_contact to normal_call", () => {
+    nextTrust = makeTrust("unverified_contact", { status: "unverified" });
+    const { outcome } = route("strangers");
+    expect(outcome.action).toBe("normal_call");
+  });
+
+  test("null policy preserves legacy name_capture for unknown caller", () => {
+    nextTrust = makeTrust("unknown");
+    expect(route(null).outcome.action).toBe("name_capture");
+  });
+
+  test("null policy preserves legacy unverified_caller for unverified caller", () => {
+    nextTrust = makeTrust("unverified_contact", { status: "unverified" });
+    expect(route(null).outcome.action).toBe("unverified_caller");
+  });
+
+  test("trusted_contacts (default) still denies unknown and unverified", () => {
+    nextTrust = makeTrust("unknown");
+    expect(route("trusted_contacts").outcome.action).toBe("deny");
+    nextTrust = makeTrust("unverified_contact", { status: "unverified" });
+    expect(route("trusted_contacts").outcome.action).toBe("deny");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Invites & pending challenges bypass the floor
+// ---------------------------------------------------------------------------
+
+describe("routeSetup — floor bypasses", () => {
+  test("active voice invite bypasses the floor (no_one policy)", () => {
+    nextTrust = makeTrust("unknown");
+    activeInvites = [{ friendName: "Friend", guardianName: "Guardian" }];
+    const { outcome } = route("no_one");
+    expect(outcome.action).toBe("invite_redemption");
+  });
+
+  test("pending verification challenge bypasses the floor (no_one policy)", () => {
+    // A pending challenge for a known member routes to verification regardless
+    // of the floor.
+    nextTrust = makeTrust("trusted_contact", { status: "active" });
+    pendingChallenge = { id: "vs_1" };
+    const { outcome } = route("no_one");
+    expect(outcome.action).toBe("verification");
+  });
+});

package/src/calls/call-pointer-messages.ts

@@ -78,7 +78,8 @@ export function resetPointerMessageProcessor(): void {
  * Resolve whether the audience for a pointer message is trusted.
  *
  * Trusted when:
- * - recent message provenance trust class is 'guardian' or 'trusted_contact'
+ * - recent message provenance trust class is 'guardian', 'trusted_contact',
+ *   or 'unverified_contact'
  * - conversation origin channel is 'vellum' (desktop app)
  *
  * Untrusted by default when insufficient evidence.
@@ -86,11 +87,16 @@ export function resetPointerMessageProcessor(): void {
 function resolvePointerAudienceTrust(conversationId: string): boolean {
   try {
     // Check provenance trust class on recent messages first — this catches
-    // trusted contacts who initiate calls from gateway channels (e.g. WhatsApp)
-    // where the conversation itself isn't desktop-origin.
+    // identity-known non-guardian contacts (trusted and unverified) who
+    // initiate calls from gateway channels (e.g. WhatsApp) where the
+    // conversation itself isn't desktop-origin.
     const provenance =
       getConversationRecentProvenanceTrustClass(conversationId);
-    if (provenance === "guardian" || provenance === "trusted_contact")
+    if (
+      provenance === "guardian" ||
+      provenance === "trusted_contact" ||
+      provenance === "unverified_contact"
+    )
       return true;
 
     const originChannel = getConversationOriginChannel(conversationId);

package/src/calls/channel-admission-reader.ts

@@ -0,0 +1,104 @@
+/**
+ * Gateway-backed channel admission policy reader.
+ *
+ * Reads a channel's resolved admission floor from the gateway via the
+ * `get_channel_admission_policy` IPC route. Admission must never break call
+ * setup, so this reader FAILS OPEN: any transport failure, malformed shape,
+ * or thrown error resolves to `null` (= admit, no enforcement). A policy is
+ * only returned when the gateway responds with `{ policy: <valid policy> }`.
+ *
+ * Caches per channelType with a short TTL, mirroring the conversation
+ * threshold cache in `../permissions/gateway-threshold-reader.ts`. Only the
+ * result of a SUCCESSFUL gateway round-trip is cached (a valid policy, or an
+ * explicit `{ policy: null }` "no enforcement" answer); a transport failure /
+ * throw / malformed shape fails open to `null` WITHOUT caching, so a recovered
+ * gateway is re-consulted on the next call setup rather than skipping the
+ * admission floor for the rest of the TTL.
+ */
+
+import {
+  type AdmissionPolicy,
+  isAdmissionPolicy,
+} from "@vellumai/gateway-client";
+
+import type { ChannelId } from "../channels/types.js";
+import { ipcCall } from "../ipc/gateway-client.js";
+
+const CACHE_TTL_MS = 5_000;
+
+// Short IPC timeout so admission fails open PROMPTLY: a gateway that accepts
+// the socket but stalls must never delay a live call handshake. 1s is generous
+// under normal conditions yet far below ipcCall's 5s default.
+const ADMISSION_IPC_TIMEOUT_MS = 1_000;
+
+const cache = new Map<
+  ChannelId,
+  { policy: AdmissionPolicy | null; timestamp: number }
+>();
+
+/** Test-only: clear the policy cache. */
+export function _clearCacheForTesting(): void {
+  cache.clear();
+}
+
+/**
+ * Outcome of a single gateway fetch. Only a SUCCESSFUL round-trip (a valid
+ * policy, or an explicit `{ policy: null }` "no enforcement" answer) is
+ * cacheable. A transport failure, thrown error, or malformed shape is NOT
+ * cached so a recovered gateway is re-consulted on the next call setup.
+ */
+type FetchResult =
+  | { ok: true; policy: AdmissionPolicy | null }
+  | { ok: false };
+
+async function fetchAdmissionPolicy(
+  channelType: ChannelId,
+): Promise<FetchResult> {
+  try {
+    // ipcCall() returns undefined on transport failure (socket not found,
+    // timeout, parse error). That, a throw, or a malformed shape is a FAILURE:
+    // fail open without caching so the next setup re-attempts the IPC.
+    const result = (await ipcCall(
+      "get_channel_admission_policy",
+      { channelType },
+      ADMISSION_IPC_TIMEOUT_MS,
+    )) as { policy?: unknown } | null | undefined;
+
+    if (result === undefined) return { ok: false };
+    if (result && isAdmissionPolicy(result.policy)) {
+      return { ok: true, policy: result.policy };
+    }
+    // Explicit "no enforcement" — the gateway successfully answered. Cacheable.
+    if (result && result.policy === null) return { ok: true, policy: null };
+    // Anything else (missing/invalid policy field) is a malformed shape.
+    return { ok: false };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Resolve a channel's admission policy from the gateway, or `null` on any
+ * failure / absence. `null` means admit with no enforcement.
+ *
+ * Always fails open to `null` on failure, but only caches the result of a
+ * SUCCESSFUL gateway round-trip — a transient hiccup must not skip the
+ * admission floor for the rest of the TTL.
+ */
+export async function getChannelAdmissionPolicy(
+  channelType: ChannelId,
+): Promise<AdmissionPolicy | null> {
+  const cached = cache.get(channelType);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+    return cached.policy;
+  }
+
+  const result = await fetchAdmissionPolicy(channelType);
+  if (!result.ok) {
+    // Fail open WITHOUT caching so a recovered gateway is re-consulted next time.
+    return null;
+  }
+
+  cache.set(channelType, { policy: result.policy, timestamp: Date.now() });
+  return result.policy;
+}

package/src/calls/guardian-dispatch.ts

@@ -9,14 +9,15 @@
 
 import { findGuardianForChannel } from "../contacts/contact-store.js";
 import {
-  createCanonicalGuardianDelivery,
   createCanonicalGuardianRequest,
   listCanonicalGuardianDeliveries,
   listCanonicalGuardianRequests,
-  updateCanonicalGuardianDelivery,
 } from "../memory/canonical-guardian-store.js";
+import {
+  recordApprovalCardDelivery,
+  recordGuardianRequestDeliveries,
+} from "../notifications/canonical-delivery-recorder.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
-import type { NotificationDeliveryResult } from "../notifications/types.js";
 import { getLogger } from "../util/logger.js";
 import { getUserConsultationTimeoutMs } from "./call-constants.js";
 import type { CallPendingQuestion } from "./types.js";
@@ -39,17 +40,6 @@ export interface GuardianDispatchParams {
   inputDigest?: string;
 }
 
-function applyDeliveryStatus(
-  deliveryId: string,
-  result: NotificationDeliveryResult,
-): void {
-  if (result.status === "sent") {
-    updateCanonicalGuardianDelivery(deliveryId, { status: "sent" });
-    return;
-  }
-  updateCanonicalGuardianDelivery(deliveryId, { status: "failed" });
-}
-
 /**
  * Dispatch a guardian action request to all configured channels.
  * Fire-and-forget: errors are logged but do not propagate.
@@ -179,7 +169,7 @@ async function dispatchGuardianQuestionInner(
 
     // Route through the canonical notification pipeline. The paired vellum
     // conversation from this pipeline is the canonical guardian conversation.
-    let vellumDeliveryId: string | null = null;
+    let vellumDeliveryId: string | undefined;
     const requestCode =
       request.requestCode ?? request.id.slice(0, 6).toUpperCase();
     const signalResult = await emitNotificationSignal({
@@ -208,44 +198,26 @@ async function dispatchGuardianQuestionInner(
       onConversationCreated: (info) => {
         if (info.sourceEventName !== "guardian.question" || vellumDeliveryId)
           return;
-        const delivery = createCanonicalGuardianDelivery({
+        vellumDeliveryId = recordApprovalCardDelivery({
           requestId: request.id,
-          destinationChannel: "vellum",
-          destinationConversationId: info.conversationId,
-        });
-        vellumDeliveryId = delivery.id;
+          channel: "vellum",
+          conversationId: info.conversationId,
+        })?.id;
       },
     });
 
-    for (const result of signalResult.deliveryResults) {
-      if (result.channel === "vellum") {
-        if (!vellumDeliveryId) {
-          const delivery = createCanonicalGuardianDelivery({
-            requestId: request.id,
-            destinationChannel: "vellum",
-            destinationConversationId: result.conversationId,
-          });
-          vellumDeliveryId = delivery.id;
-        }
-        applyDeliveryStatus(vellumDeliveryId, result);
-        continue;
-      }
-
-      const delivery = createCanonicalGuardianDelivery({
-        requestId: request.id,
-        destinationChannel: result.channel,
-        destinationChatId:
-          result.destination.length > 0 ? result.destination : undefined,
-      });
-      applyDeliveryStatus(delivery.id, result);
-    }
+    vellumDeliveryId = recordGuardianRequestDeliveries({
+      requestId: request.id,
+      deliveryResults: signalResult.deliveryResults,
+      vellumDeliveryId,
+    });
 
     if (!vellumDeliveryId) {
-      const fallback = createCanonicalGuardianDelivery({
+      recordApprovalCardDelivery({
         requestId: request.id,
-        destinationChannel: "vellum",
+        channel: "vellum",
+        status: "failed",
       });
-      updateCanonicalGuardianDelivery(fallback.id, { status: "failed" });
       log.warn(
         { requestId: request.id, reason: signalResult.reason },
         "Notification pipeline did not produce a vellum delivery result",