@vellumai/assistant 0.9.0-dev.202606181324.0804a69 → 0.9.0-dev.202606181513.fd39213

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/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/media-stream-server.ts

@@ -50,6 +50,7 @@ import {
   recordCallEvent,
   updateCallSession,
 } from "./call-store.js";
+import { getChannelAdmissionPolicy } from "./channel-admission-reader.js";
 import { finalizeCall } from "./finalize-call.js";
 import { MediaStreamOutput } from "./media-stream-output.js";
 import { parseMediaStreamFrame } from "./media-stream-parser.js";
@@ -90,6 +91,18 @@ export class MediaStreamCallSession {
   private streamSid: string | null = null;
   private callSid: string | null = null;
   private disposed = false;
+  // True from the synchronous start of handleStart until setup routing
+  // completes. Resolving the admission floor yields the event loop, so
+  // transcripts/barge-in arriving in this window are ignored — a denied or
+  // not-yet-authorized caller's speech is never persisted before the floor
+  // and trust ACL are applied. The controller-existence checks below also
+  // gate persistence, but this guard makes the intent explicit and covers
+  // the brief async window before the controller is created.
+  private setupRouting = false;
+  // Resolves when the async setup routing kicked off by the `start` frame
+  // settles. Exposed via whenSetupSettled() for deterministic test awaiting,
+  // since handleStart now yields on the admission-policy read.
+  private setupSettled: Promise<void> = Promise.resolve();
 
   // ── Operational diagnostics counters ──────────────────────────────
   /** Number of barge-in attempts that were accepted (assistant was speaking). */
@@ -141,6 +154,14 @@ export class MediaStreamCallSession {
     return this.controller;
   }
 
+  /**
+   * Resolves once the async setup routing started by the `start` frame has
+   * settled. Test-only convenience — production code does not await this.
+   */
+  whenSetupSettled(): Promise<void> {
+    return this.setupSettled;
+  }
+
   /**
    * Feed a raw WebSocket message into the session.
    *
@@ -154,7 +175,16 @@ export class MediaStreamCallSession {
     // Intercept `start` to bootstrap the session before forwarding.
     const parseResult = parseMediaStreamFrame(raw);
     if (parseResult.ok && parseResult.event.event === "start") {
-      this.handleStart(parseResult.event);
+      // handleStart resolves the admission floor asynchronously; the
+      // setupRouting guard set synchronously at its top ensures inbound
+      // frames forwarded below are ignored until routing completes.
+      this.setupSettled = this.handleStart(parseResult.event).catch((err) => {
+        log.error(
+          { err, callSessionId: this.callSessionId },
+          "Media-stream setup routing failed",
+        );
+        this.setupRouting = false;
+      });
     }
 
     // Always forward to the STT session (it handles all event types).
@@ -296,7 +326,12 @@ export class MediaStreamCallSession {
 
   // ── Internal: media-stream event handlers ─────────────────────────
 
-  private handleStart(event: MediaStreamStartEvent): void {
+  private async handleStart(event: MediaStreamStartEvent): Promise<void> {
+    // Enter the setup-pending window synchronously, before any await. The
+    // admission-policy read below yields the event loop, so frames forwarded
+    // to the STT session can produce transcripts/barge-in before routing
+    // completes — those are dropped while setupRouting is true.
+    this.setupRouting = true;
     this.streamSid = event.streamSid;
     this.callSid = event.start.callSid;
 
@@ -337,12 +372,32 @@ export class MediaStreamCallSession {
     const from = session?.fromNumber ?? "";
     const to = session?.toNumber ?? "";
 
+    // Resolve the phone channel's inbound admission floor so the trust floor
+    // (e.g. guardian_only) is enforced on this transport too — not just the
+    // gateway webhook's no_one kill switch. The reader fails open to `null`
+    // by contract, so a transport hiccup admits the caller.
+    const admissionPolicy = await getChannelAdmissionPolicy("phone");
+
+    // The admission-policy read above yields the event loop; if Twilio closed
+    // the WebSocket meanwhile, the close handler will have called destroy().
+    // Abort setup so we don't create a controller or speak on a disposed
+    // session.
+    if (this.disposed) {
+      log.info(
+        { callSessionId: this.callSessionId },
+        "Media-stream session disposed during admission read — aborting setup",
+      );
+      this.setupRouting = false;
+      return;
+    }
+
     const { outcome, resolved } = routeSetup({
       callSessionId: this.callSessionId,
       session: session ?? null,
       from,
       to,
       customParameters: event.start.customParameters,
+      admissionPolicy,
     });
 
     log.info(
@@ -377,6 +432,10 @@ export class MediaStreamCallSession {
         );
         registerCallController(this.callSessionId, this.controller);
 
+        // Routing/ACL cleared — leave the setup-pending window so subsequent
+        // transcripts and barge-in are handled normally.
+        this.setupRouting = false;
+
         // Fire the initial greeting.
         this.controller.startInitialGreeting().catch((err) => {
           log.error(
@@ -525,6 +584,18 @@ export class MediaStreamCallSession {
 
   private handleTranscriptFinal(text: string, _durationMs: number): void {
     if (!text.trim()) return;
+
+    // Drop transcripts arriving while setup routing is still pending so a
+    // not-yet-authorized / floor-denied caller's speech is never persisted
+    // before the admission floor and trust ACL are applied.
+    if (this.setupRouting) {
+      log.debug(
+        { callSessionId: this.callSessionId },
+        "Transcript received during setup routing — dropping",
+      );
+      return;
+    }
+
     this.transcriptFinalsProduced++;
 
     if (!this.controller) {
@@ -560,6 +631,17 @@ export class MediaStreamCallSession {
   }
 
   private handleDtmf(digit: string): void {
+    // Drop DTMF arriving while setup routing is still pending so a
+    // not-yet-authorized / floor-denied caller's digit is never persisted
+    // before the admission floor and trust ACL are applied.
+    if (this.setupRouting) {
+      log.debug(
+        { callSessionId: this.callSessionId, digit },
+        "DTMF received during setup routing — dropping",
+      );
+      return;
+    }
+
     log.info(
       { callSessionId: this.callSessionId, digit },
       "DTMF digit received on media-stream",