@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

package/src/runtime/routes/__tests__/global-search-routes.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Unit tests for the global-search contacts ordering source.
+ *
+ * Recency ordering for contacts surfaces `contacts.updatedAt`, never the
+ * channel-derived `lastInteraction` column. Daemon-native contact search
+ * carries no gateway-relayed ContactRead, so `updatedAt` is the deterministic
+ * ordering key.
+ */
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import type { ContactWithChannels } from "../../../contacts/types.js";
+
+let searchContactsResult: ContactWithChannels[] = [];
+
+const searchContactsMock = mock(() => searchContactsResult);
+
+const actualContactStore = await import("../../../contacts/contact-store.js");
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  ...actualContactStore,
+  searchContacts: searchContactsMock,
+}));
+
+const { ROUTES } = await import("../global-search-routes.js");
+
+const handler = ROUTES.find((r) => r.operationId === "search_global")!.handler;
+
+function makeContact(
+  overrides: Partial<ContactWithChannels>,
+): ContactWithChannels {
+  return {
+    id: "ct_1",
+    displayName: "Alice",
+    notes: null,
+    role: "contact",
+    lastInteraction: null,
+    interactionCount: 0,
+    createdAt: 1,
+    updatedAt: 1,
+    contactType: "human",
+    userFile: null,
+    channels: [],
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  searchContactsResult = [];
+  searchContactsMock.mockClear();
+});
+
+describe("global-search contacts recency source", () => {
+  test("surfaces contacts.updatedAt as lastInteraction, not the channel column", async () => {
+    searchContactsResult = [
+      makeContact({
+        id: "ct_1",
+        displayName: "Alice",
+        updatedAt: 5000,
+        lastInteraction: 9999,
+      }),
+    ];
+
+    const result = (await handler({
+      queryParams: { q: "ali", categories: "contacts" },
+    })) as { results: { contacts: { id: string; lastInteraction: number }[] } };
+
+    expect(result.results.contacts).toHaveLength(1);
+    expect(result.results.contacts[0].lastInteraction).toBe(5000);
+  });
+
+  test("preserves searchContacts ordering deterministically", async () => {
+    searchContactsResult = [
+      makeContact({ id: "ct_a", displayName: "A", updatedAt: 300 }),
+      makeContact({ id: "ct_b", displayName: "B", updatedAt: 200 }),
+      makeContact({ id: "ct_c", displayName: "C", updatedAt: 100 }),
+    ];
+
+    const result = (await handler({
+      queryParams: { q: "x", categories: "contacts" },
+    })) as { results: { contacts: { id: string; lastInteraction: number }[] } };
+
+    expect(result.results.contacts.map((c) => c.id)).toEqual([
+      "ct_a",
+      "ct_b",
+      "ct_c",
+    ]);
+    expect(result.results.contacts.map((c) => c.lastInteraction)).toEqual([
+      300, 200, 100,
+    ]);
+  });
+});

package/src/runtime/routes/__tests__/http-adapter-actor-header.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Regression tests for actor/principal header sanitization in the HTTP
+ * adapter.
+ *
+ * The HTTP adapter must derive the actor identity headers
+ * (`x-vellum-actor-principal-id`, `x-vellum-principal-type`) exclusively from
+ * the verified AuthContext, never from caller-supplied request headers. A
+ * caller whose token carries no actorPrincipalId (svc_gateway / svc_daemon /
+ * local principals) must not be able to spoof another principal — e.g. the
+ * guardian — by setting the header explicitly. This protects principal-gated
+ * handlers (surface action `apr:*` guardian decisions, guardian actions, host
+ * proxies) from approval-token bypass via a forged actor principal.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { resolveScopeProfile } from "../../auth/scopes.js";
+import type { AuthContext } from "../../auth/types.js";
+import { routeDefinitionsToHTTPRoutes } from "../http-adapter.js";
+import type { RouteDefinition } from "../types.js";
+
+// Echo route: returns the identity headers the handler actually observed.
+const ECHO_ROUTE: RouteDefinition = {
+  operationId: "echo_identity_headers",
+  endpoint: "test/echo-identity",
+  method: "POST",
+  policy: null,
+  handler: ({ headers }) => ({
+    actorPrincipalId: headers?.["x-vellum-actor-principal-id"] ?? null,
+    principalType: headers?.["x-vellum-principal-type"] ?? null,
+  }),
+};
+
+function buildAuthContext(overrides: Partial<AuthContext>): AuthContext {
+  return {
+    subject: "svc:gateway:self",
+    principalType: "svc_gateway",
+    assistantId: "self",
+    scopeProfile: "gateway_service_v1",
+    scopes: resolveScopeProfile("gateway_service_v1"),
+    policyEpoch: 0,
+    ...overrides,
+  };
+}
+
+async function invokeEcho(params: {
+  spoofedPrincipalId?: string;
+  spoofedPrincipalType?: string;
+  authContext: AuthContext;
+}): Promise<{ actorPrincipalId: string | null; principalType: string | null }> {
+  const [httpRoute] = routeDefinitionsToHTTPRoutes([ECHO_ROUTE]);
+
+  const reqHeaders: Record<string, string> = {
+    "content-type": "application/json",
+  };
+  if (params.spoofedPrincipalId !== undefined) {
+    reqHeaders["x-vellum-actor-principal-id"] = params.spoofedPrincipalId;
+  }
+  if (params.spoofedPrincipalType !== undefined) {
+    reqHeaders["x-vellum-principal-type"] = params.spoofedPrincipalType;
+  }
+
+  const req = new Request("http://daemon.local/v1/test/echo-identity", {
+    method: "POST",
+    headers: reqHeaders,
+    body: JSON.stringify({}),
+  });
+
+  const response = await httpRoute.handler({
+    req,
+    url: new URL(req.url),
+    // The echo handler doesn't touch `server`; a stub is fine.
+    server: undefined as never,
+    authContext: params.authContext,
+    params: {},
+  });
+
+  return (await response.json()) as {
+    actorPrincipalId: string | null;
+    principalType: string | null;
+  };
+}
+
+describe("http-adapter actor/principal header sanitization", () => {
+  test("drops a spoofed actor-principal header when the context has no actorPrincipalId", async () => {
+    // A service token (svc_gateway) has no actorPrincipalId. The forged header
+    // must be stripped, not passed through to the handler.
+    const result = await invokeEcho({
+      spoofedPrincipalId: "guardian-principal-victim",
+      authContext: buildAuthContext({ actorPrincipalId: undefined }),
+    });
+
+    expect(result.actorPrincipalId).toBeNull();
+    // principalType is always re-derived from the verified context.
+    expect(result.principalType).toBe("svc_gateway");
+  });
+
+  test("overrides a spoofed actor-principal header with the verified context value", async () => {
+    const result = await invokeEcho({
+      spoofedPrincipalId: "guardian-principal-victim",
+      spoofedPrincipalType: "actor",
+      authContext: buildAuthContext({
+        subject: "actor:self:real-actor",
+        principalType: "actor",
+        scopeProfile: "actor_client_v1",
+        scopes: resolveScopeProfile("actor_client_v1"),
+        actorPrincipalId: "real-actor",
+      }),
+    });
+
+    expect(result.actorPrincipalId).toBe("real-actor");
+    expect(result.principalType).toBe("actor");
+  });
+
+  test("passes through the genuine actor identity when no spoof is present", async () => {
+    const result = await invokeEcho({
+      authContext: buildAuthContext({
+        subject: "actor:self:real-actor",
+        principalType: "actor",
+        scopeProfile: "actor_client_v1",
+        scopes: resolveScopeProfile("actor_client_v1"),
+        actorPrincipalId: "real-actor",
+      }),
+    });
+
+    expect(result.actorPrincipalId).toBe("real-actor");
+    expect(result.principalType).toBe("actor");
+  });
+});

package/src/runtime/routes/__tests__/surface-action-routes.test.ts

@@ -25,6 +25,7 @@ interface StubConversation {
   handleSurfaceActionThrows?: Error;
   handleSurfaceUndoCalled?: boolean;
   handleSurfaceUndoThrows?: Error;
+  trustContext?: { trustClass: string; sourceChannel: string };
   surfaceActionCalls: Array<{
     surfaceId: string;
     actionId: string;
@@ -43,6 +44,48 @@ const findBySurfaceCalls: string[] = [];
 const getOrCreateCalls: string[] = [];
 const rawGetCalls: Array<{ sql: string; params: unknown[] }> = [];
 
+// Gateway guardian-delivery list (shared by the route's dev-bypass lookup and
+// the local-principal-trust mapper): null = unreachable, [] = no guardian.
+let mockGuardianList: Array<Record<string, unknown>> | null = [];
+let httpAuthDisabled = false;
+
+// Stub for the shared reset-drift helper. The route under test only consumes
+// its result (a guardian TrustContext or null); the gate itself is covered in
+// runtime/__tests__/guardian-vellum-migration.test.ts. Tests set
+// `mockReResolve` per case and read `reResolveCalls` to assert routing.
+const reResolveCalls: string[] = [];
+let mockReResolve: { trustClass: string; sourceChannel: string } | null = null;
+
+mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: (_input?: { channelTypes?: string[] }) =>
+    Promise.resolve(mockGuardianList),
+  peekCachedGuardianDelivery: () => mockGuardianList ?? undefined,
+  guardianForChannel: (
+    list: Array<Record<string, unknown>>,
+    channelType: string,
+  ) => list.find((g) => g.channelType === channelType && g.status === "active"),
+}));
+
+// Member ACL rides on memberRecord via the member-verdict cache; no local
+// contact here.
+mock.module("../../../contacts/contact-store.js", () => ({
+  findContactByAddress: () => null,
+}));
+
+mock.module("../../../config/env.js", () => ({
+  isHttpAuthDisabled: () => httpAuthDisabled,
+}));
+
+mock.module("../../guardian-vellum-migration.js", () => ({
+  reResolveTrustOnResetDrift: async (
+    incomingPrincipalId: string,
+    _sourceChannel: string,
+  ) => {
+    reResolveCalls.push(incomingPrincipalId);
+    return mockReResolve;
+  },
+}));
+
 mock.module("../../../daemon/conversation-registry.js", () => ({
   findConversation: (id: string) => {
     findConvCalls.push(id);
@@ -122,6 +165,9 @@ function makeStub(id: string): StubConversation {
       stub.handleSurfaceUndoCalled = true;
       if (stub.handleSurfaceUndoThrows) throw stub.handleSurfaceUndoThrows;
     },
+    setTrustContext: (ctx: { trustClass: string; sourceChannel: string }) => {
+      stub.trustContext = ctx;
+    },
   });
   return stub;
 }
@@ -139,6 +185,10 @@ beforeEach(() => {
   findBySurfaceCalls.length = 0;
   getOrCreateCalls.length = 0;
   rawGetCalls.length = 0;
+  mockGuardianList = [];
+  httpAuthDisabled = false;
+  reResolveCalls.length = 0;
+  mockReResolve = null;
 });
 
 // ---------------------------------------------------------------------------
@@ -337,6 +387,30 @@ describe("triggerSurfaceAction handler", () => {
     ]);
   });
 
+  test("resolves dev-bypass to the guardian principal before threading the turn", async () => {
+    httpAuthDisabled = true;
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-dev-thread");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-dt", actionId: "act-dt" },
+      headers: { "x-vellum-actor-principal-id": "dev-bypass" },
+    });
+
+    // dev-bypass is translated so the surface turn matches the SSE host-proxy
+    // client's registered guardian principal (CU/app-control same-actor check).
+    expect(live.surfaceActionCalls).toEqual([
+      {
+        surfaceId: "surf-dt",
+        actionId: "act-dt",
+        data: undefined,
+        sourceActorPrincipalId: GUARDIAN_PRINCIPAL,
+      },
+    ]);
+  });
+
   test("propagates accepted=false rejection as BadRequestError", async () => {
     const live = makeStub("conv-reject");
     live.handleSurfaceActionResult = {
@@ -362,6 +436,120 @@ describe("triggerSurfaceAction handler", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Trust context resolution
+// ---------------------------------------------------------------------------
+
+const GUARDIAN_PRINCIPAL = "principal-guardian";
+// Daemon-minted vellum-principal-* ids: the DB-reset drift signature. The
+// gateway rebinds to a fresh id while the client still holds a JWT for the old.
+const VELLUM_PRINCIPAL_OLD = "vellum-principal-old";
+const VELLUM_PRINCIPAL_NEW = "vellum-principal-new";
+
+function guardianDelivery(principalId: string): Record<string, unknown> {
+  return {
+    channelType: "vellum",
+    contactId: "contact-1",
+    principalId,
+    address: "guardian-address",
+    externalChatId: "guardian-chat",
+    status: "active",
+  };
+}
+
+// A guardian TrustContext the stubbed helper hands back on a recovered drift.
+function guardianCtx(): { trustClass: string; sourceChannel: string } {
+  return { trustClass: "guardian", sourceChannel: "vellum" };
+}
+
+describe("triggerSurfaceAction trust context", () => {
+  test("guardian principal → guardian from the gateway binding, helper not called", async () => {
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-guardian");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-g", actionId: "act-g" },
+      headers: { "x-vellum-actor-principal-id": GUARDIAN_PRINCIPAL },
+    });
+
+    expect(live.trustContext?.trustClass).toBe("guardian");
+    expect(live.trustContext?.sourceChannel).toBe("vellum");
+    // First-pass resolve already granted guardian, so the drift helper is skipped.
+    expect(reResolveCalls).toEqual([]);
+  });
+
+  test("unknown principal: helper consulted, null result stays unknown (fail closed)", async () => {
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    mockReResolve = null;
+    const live = makeStub("conv-unknown");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-u", actionId: "act-u" },
+      headers: { "x-vellum-actor-principal-id": VELLUM_PRINCIPAL_OLD },
+    });
+
+    expect(reResolveCalls).toEqual([VELLUM_PRINCIPAL_OLD]);
+    expect(live.trustContext?.trustClass).toBe("unknown");
+  });
+
+  test("reset drift: helper returns guardian → route adopts it", async () => {
+    mockGuardianList = [guardianDelivery(VELLUM_PRINCIPAL_NEW)];
+    mockReResolve = guardianCtx();
+    const live = makeStub("conv-drift");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-d", actionId: "act-d" },
+      headers: { "x-vellum-actor-principal-id": VELLUM_PRINCIPAL_OLD },
+    });
+
+    expect(reResolveCalls).toEqual([VELLUM_PRINCIPAL_OLD]);
+    expect(live.trustContext?.trustClass).toBe("guardian");
+  });
+
+  test("dev-bypass resolves the real guardian principal from the gateway, helper not called", async () => {
+    httpAuthDisabled = true;
+    mockGuardianList = [guardianDelivery(GUARDIAN_PRINCIPAL)];
+    const live = makeStub("conv-dev");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-dev", actionId: "act-dev" },
+      headers: { "x-vellum-actor-principal-id": "dev-bypass" },
+    });
+
+    // The synthetic dev-bypass principal is translated to the real guardian,
+    // yielding a guardian trust context without consulting the drift helper.
+    expect(live.trustContext?.trustClass).toBe("guardian");
+    expect(reResolveCalls).toEqual([]);
+  });
+
+  test("dev-bypass with an empty gateway: helper null result → unknown (fail closed)", async () => {
+    httpAuthDisabled = true;
+    // The gateway has no active binding, so dev-bypass cannot translate to a
+    // real guardian; the first-pass resolve is unknown and the helper, returning
+    // null, leaves trust unknown.
+    mockGuardianList = [];
+    mockReResolve = null;
+    const live = makeStub("conv-dev-fallback");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: { surfaceId: "surf-devf", actionId: "act-devf" },
+      headers: { "x-vellum-actor-principal-id": "dev-bypass" },
+    });
+
+    expect(live.trustContext?.trustClass).toBe("unknown");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // undoSurfaceAction
 // ---------------------------------------------------------------------------

package/src/runtime/routes/browser-routes.ts

@@ -92,7 +92,7 @@ async function handleBrowserExecute({
   // register with (dev-bypass otherwise mismatches).
   const headerActor =
     headers["x-vellum-actor-principal-id"]?.trim() || undefined;
-  const sourceActorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+  const sourceActorPrincipalId = await resolveActorPrincipalIdForLocalGuardian(
     conversation?.getTurnActorPrincipalId() ?? headerActor,
   );
 

package/src/runtime/routes/canonical-guardian-expiry-sweep.ts

@@ -8,13 +8,16 @@
  * requester.
  *
  * This sweep operates on the unified canonical domain
- * (`canonical_guardian_requests`) and does not auto-deny pending interactions
- * or deliver channel notices — the canonical request status transition is the
- * single source of truth, and consumers (resolvers, clients polling prompts)
- * observe the expired status directly.
+ * (`canonical_guardian_requests`). On expiry it transitions the request status
+ * (the single source of truth), withdraws the approval cards on every surface,
+ * notifies the requester that their request expired, and releases any in-memory
+ * pending interaction. Requester notices are delivered straight to the
+ * requester's channel — not the guardian-facing notification pipeline — and the
+ * guardian stays passive, since the withdrawn card already reflects expiry.
  */
 
 import { withdrawGuardianRequestCards } from "../../approvals/guardian-card-withdrawal.js";
+import { notifyExpiredGuardianRequest } from "../../approvals/guardian-expiry-notifier.js";
 import {
   listCanonicalGuardianRequests,
   resolveCanonicalGuardianRequest,
@@ -39,7 +42,7 @@ let sweepInProgress = false;
  * concurrent decision that wins the race is never overwritten by the
  * sweep.  Returns the count of requests transitioned to expired.
  */
-async function sweepExpiredCanonicalGuardianRequests(): Promise<number> {
+export async function sweepExpiredCanonicalGuardianRequests(): Promise<number> {
   const pending = listCanonicalGuardianRequests({ status: "pending" });
   const now = Date.now();
   let expiredCount = 0;
@@ -76,6 +79,11 @@ async function sweepExpiredCanonicalGuardianRequests(): Promise<number> {
         request: resolved,
         status: "expired",
       });
+
+      // Notify the requester their request expired and release any in-memory
+      // pending interaction. Best-effort and non-throwing, like the card
+      // withdrawal above.
+      await notifyExpiredGuardianRequest(resolved);
     }
   }
 

package/src/runtime/routes/channel-verification-routes.ts

@@ -179,7 +179,7 @@ export async function handleCreateVerificationSession({
   }
 
   // Inbound challenge path
-  const result = createInboundChallenge(channel, rebind, conversationId);
+  const result = await createInboundChallenge(channel, rebind, conversationId);
   if (!result.success) {
     throw new BadRequestError(
       (result as { message?: string }).message ??
@@ -192,12 +192,12 @@ export async function handleCreateVerificationSession({
 /**
  * GET /v1/channel-verification-sessions/status
  */
-function handleGetVerificationStatus({
+async function handleGetVerificationStatus({
   queryParams = {},
   body = {},
 }: RouteHandlerArgs) {
   const channel = (queryParams.channel ?? (body as Record<string, unknown>).channel) as ChannelId | undefined;
-  return getVerificationStatus(channel);
+  return await getVerificationStatus(channel);
 }
 
 /**