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

package/src/runtime/__tests__/guardian-vellum-migration.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Unit tests for the narrow reset-drift trust-recovery helper
+ * `reResolveTrustOnResetDrift`.
+ *
+ * The real helper runs against mocked leaf deps: the gateway guardian read
+ * (`getGuardianDelivery`/`guardianForChannel`) supplies the authoritative
+ * principal, the local-mirror heal target is resolved via
+ * `findContactByAddress` (keyed on the gateway guardian's channel address) and
+ * written via `updateContactPrincipalAndChannel` (the real
+ * `healGuardianBindingDrift` drives this), and the local trust resolver
+ * (`resolveTrustContext`) closes the loop. Heal invocations are observed via
+ * the contact-store write mock.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+let mockGuardianList: Array<Record<string, unknown>> | null = [];
+
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: async () => mockGuardianList,
+  guardianForChannel: (
+    list: Array<Record<string, unknown>>,
+    channelType: string,
+  ) => list.find((g) => g.channelType === channelType && g.status === "active"),
+}));
+
+// Local mirror the real heal repairs. `findContactByAddress` returns the local
+// contact (with its vellum channel) the heal writes to;
+// `updateContactPrincipalAndChannel` records heal writes.
+let mockLocalContact: {
+  id: string;
+  channels: Array<{ id: string; type: string }>;
+} | null = null;
+const healWrites: Array<{ principalId: string }> = [];
+
+mock.module("../../contacts/contact-store.js", () => ({
+  findContactByAddress: () => mockLocalContact,
+  updateContactPrincipalAndChannel: (
+    _contactId: string,
+    _channelId: string,
+    principalId: string,
+  ) => {
+    healWrites.push({ principalId });
+    return true;
+  },
+}));
+
+// The local trust resolver returns guardian for the actor; the gate threads
+// sourceChannel via the real withSourceChannel wrapper.
+mock.module("../../runtime/trust-context-resolver.js", () => ({
+  resolveTrustContext: (input: { actorExternalId?: string }) => ({
+    trustClass: "guardian",
+    sourceChannel: "vellum",
+    resolvedActor: input.actorExternalId,
+  }),
+  withSourceChannel: (sourceChannel: unknown, ctx: Record<string, unknown>) => ({
+    ...ctx,
+    sourceChannel,
+  }),
+}));
+
+const { reResolveTrustOnResetDrift } = await import(
+  "../guardian-vellum-migration.js"
+);
+
+function gatewayGuardian(principalId: string): Record<string, unknown> {
+  return {
+    channelType: "vellum",
+    contactId: "guardian-contact",
+    principalId,
+    address: principalId,
+    status: "active",
+  };
+}
+
+function localGuardian() {
+  return {
+    id: "contact-1",
+    channels: [{ id: "channel-1", type: "vellum" }],
+  };
+}
+
+describe("reResolveTrustOnResetDrift", () => {
+  beforeEach(() => {
+    mockGuardianList = [];
+    mockLocalContact = null;
+    healWrites.length = 0;
+  });
+
+  test("reset drift: heals and returns the re-resolved guardian ctx", async () => {
+    // Gateway principal diverges from the incoming JWT; heal repairs the local
+    // mirror toward the incoming actor.
+    mockGuardianList = [gatewayGuardian("vellum-principal-new")];
+    mockLocalContact = localGuardian();
+
+    const ctx = await reResolveTrustOnResetDrift(
+      "vellum-principal-old",
+      "vellum",
+    );
+
+    expect(ctx?.trustClass).toBe("guardian");
+    expect(healWrites).toEqual([{ principalId: "vellum-principal-old" }]);
+  });
+
+  test("no local mirror to repair still returns the guardian ctx", async () => {
+    // The gate passes and the re-resolve yields guardian even when there is no
+    // local mirror row for heal to write.
+    mockGuardianList = [gatewayGuardian("vellum-principal-new")];
+    mockLocalContact = null;
+
+    const ctx = await reResolveTrustOnResetDrift(
+      "vellum-principal-old",
+      "vellum",
+    );
+
+    expect(ctx?.trustClass).toBe("guardian");
+    expect(healWrites).toEqual([]);
+  });
+
+  test("gateway unreachable (null): returns null, heal not called", async () => {
+    mockGuardianList = null;
+    mockLocalContact = localGuardian();
+
+    const ctx = await reResolveTrustOnResetDrift(
+      "vellum-principal-old",
+      "vellum",
+    );
+
+    expect(ctx).toBeNull();
+    expect(healWrites).toEqual([]);
+  });
+
+  test("empty/revoked gateway (no active guardian): returns null, heal not called", async () => {
+    mockGuardianList = [];
+    mockLocalContact = localGuardian();
+
+    const ctx = await reResolveTrustOnResetDrift(
+      "vellum-principal-old",
+      "vellum",
+    );
+
+    expect(ctx).toBeNull();
+    expect(healWrites).toEqual([]);
+  });
+
+  test("gateway guardian is a real (non vellum-principal-*) id: returns null", async () => {
+    mockGuardianList = [gatewayGuardian("user@example.com")];
+    mockLocalContact = localGuardian();
+
+    const ctx = await reResolveTrustOnResetDrift(
+      "vellum-principal-old",
+      "vellum",
+    );
+
+    expect(ctx).toBeNull();
+    expect(healWrites).toEqual([]);
+  });
+
+  test("incoming principal is not vellum-principal-*: returns null", async () => {
+    mockGuardianList = [gatewayGuardian("vellum-principal-new")];
+    mockLocalContact = localGuardian();
+
+    const ctx = await reResolveTrustOnResetDrift("user@example.com", "vellum");
+
+    expect(ctx).toBeNull();
+    expect(healWrites).toEqual([]);
+  });
+
+  test("threads sourceChannel into the returned ctx", async () => {
+    mockGuardianList = [gatewayGuardian("vellum-principal-new")];
+    mockLocalContact = localGuardian();
+
+    const ctx = await reResolveTrustOnResetDrift(
+      "vellum-principal-old",
+      "telegram",
+    );
+
+    expect(ctx?.sourceChannel).toBe("telegram");
+  });
+});

package/src/runtime/__tests__/is-guardian-bound-for-channel.test.ts

@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Gateway guardian-delivery list: null = couldn't determine (transport failure
+// OR gateway-side resolver/DB error), [] = authoritative unbound, one active
+// entry = bound.
+let mockGuardianList: Array<Record<string, unknown>> | null = [];
+const freshCalls: Array<{ channelTypes?: string[] } | undefined> = [];
+
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  // Existence guard reads fresh (uncached); the binding/identity reads use the
+  // cached variant. The service imports both, so both must be stubbed.
+  getGuardianDeliveryFresh: (input?: { channelTypes?: string[] }) => {
+    freshCalls.push(input);
+    return Promise.resolve(mockGuardianList);
+  },
+  getGuardianDelivery: () => Promise.resolve(mockGuardianList),
+  guardianForChannel: (
+    list: Array<{ channelType: string; status: string }>,
+    channelType: string,
+  ) => list.find((g) => g.channelType === channelType && g.status === "active"),
+}));
+
+const { isGuardianBoundForChannel } = await import(
+  "../channel-verification-service.js"
+);
+
+describe("isGuardianBoundForChannel", () => {
+  beforeEach(() => {
+    mockGuardianList = [];
+    freshCalls.length = 0;
+  });
+
+  test("reads fresh so a stale cached empty list can't mask a present guardian", async () => {
+    await isGuardianBoundForChannel("telegram");
+    expect(freshCalls).toEqual([{ channelTypes: ["telegram"] }]);
+  });
+
+  test("returns false when no guardian is bound", async () => {
+    mockGuardianList = [];
+    expect(await isGuardianBoundForChannel("telegram")).toBe(false);
+  });
+
+  test("returns true when a guardian is bound", async () => {
+    mockGuardianList = [{ channelType: "telegram", status: "active" }];
+    expect(await isGuardianBoundForChannel("telegram")).toBe(true);
+  });
+
+  test("null list (gateway unreachable) is treated as bound", async () => {
+    mockGuardianList = null;
+    expect(await isGuardianBoundForChannel("telegram")).toBe(true);
+  });
+
+  test("gateway resolver error (null, not []) is treated as bound — no duplicate", async () => {
+    // A gateway-side DB/resolver error now reaches the reader as null (the
+    // handler no longer swallows it into an empty list), so the guard's
+    // null fail-safe applies and reports bound instead of mis-reading the
+    // error as "no guardian" and allowing a duplicate binding.
+    mockGuardianList = null;
+    expect(await isGuardianBoundForChannel("telegram")).toBe(true);
+  });
+
+  test("genuine empty ([], not null) reports unbound so first-bind is allowed", async () => {
+    mockGuardianList = [];
+    expect(await isGuardianBoundForChannel("telegram")).toBe(false);
+  });
+});

package/src/runtime/__tests__/local-principal-trust.test.ts

@@ -0,0 +1,162 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ChannelId } from "../../channels/types.js";
+
+// Gateway guardian-delivery list: null = couldn't determine (gateway
+// unreachable), [] = authoritatively no guardian, one active entry = bound.
+let mockGuardianList: Array<Record<string, unknown>> | null = [];
+
+// Both the async path (resolveLocalPrincipalTrustContext) and the sync
+// resolveActorTrust read the same gateway delivery list — async via
+// getGuardianDelivery, sync via the peek snapshot.
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: (_input?: { channelTypes?: string[] }) =>
+    Promise.resolve(mockGuardianList),
+  peekCachedGuardianDelivery: (input?: { channelTypes?: string[] }) => {
+    if (mockGuardianList == null) return undefined;
+    if (!input?.channelTypes) return mockGuardianList;
+    return mockGuardianList.filter((g) =>
+      input.channelTypes!.includes(g.channelType as string),
+    );
+  },
+  guardianForChannel: (
+    list: Array<Record<string, unknown>>,
+    channelType: string,
+  ) => list.find((g) => g.channelType === channelType && g.status === "active"),
+}));
+
+// Member ACL rides on memberRecord, sourced from the member-verdict cache; this
+// suite only exercises the gateway-guardian path, so no member resolves.
+mock.module("../../contacts/contact-store.js", () => ({
+  findContactByAddress: (_channelType: string, _address: string) => null,
+}));
+
+const { resolveLocalPrincipalTrustContext } = await import(
+  "../local-principal-trust.js"
+);
+const { resolveActorTrust, toTrustContext } = await import(
+  "../actor-trust-resolver.js"
+);
+
+const SOURCE_CHANNEL: ChannelId = "vellum";
+const CONVERSATION_ID = "conv-1";
+const GUARDIAN_PRINCIPAL_ID = "principal-guardian";
+const GUARDIAN_ADDRESS = "guardian-address";
+const GUARDIAN_CHAT_ID = "guardian-chat";
+
+describe("resolveLocalPrincipalTrustContext", () => {
+  beforeEach(() => {
+    mockGuardianList = [];
+  });
+
+  test("principal matching the gateway guardian → guardian ctx", async () => {
+    mockGuardianList = [
+      {
+        channelType: "vellum",
+        contactId: "contact-1",
+        principalId: GUARDIAN_PRINCIPAL_ID,
+        address: GUARDIAN_ADDRESS,
+        externalChatId: GUARDIAN_CHAT_ID,
+        status: "active",
+      },
+    ];
+
+    const ctx = await resolveLocalPrincipalTrustContext({
+      actorPrincipalId: GUARDIAN_PRINCIPAL_ID,
+      sourceChannel: SOURCE_CHANNEL,
+      conversationExternalId: CONVERSATION_ID,
+    });
+
+    expect(ctx.trustClass).toBe("guardian");
+    expect(ctx.guardianPrincipalId).toBe(GUARDIAN_PRINCIPAL_ID);
+    expect(ctx.guardianExternalUserId).toBe(GUARDIAN_ADDRESS);
+    expect(ctx.guardianChatId).toBe(GUARDIAN_CHAT_ID);
+    expect(ctx.requesterExternalUserId).toBe(GUARDIAN_PRINCIPAL_ID);
+    expect(ctx.requesterChatId).toBe(CONVERSATION_ID);
+    expect(ctx.sourceChannel).toBe(SOURCE_CHANNEL);
+  });
+
+  test("guardian ctx is equivalent to the prior toTrustContext output", async () => {
+    // The actor IS the guardian: its principal id is the guardian binding's
+    // address (vellum canonicalization is pass-through) so the local resolver
+    // classifies it guardian and we can compare the two outputs directly.
+    mockGuardianList = [
+      {
+        channelType: "vellum",
+        contactId: "contact-1",
+        principalId: GUARDIAN_ADDRESS,
+        address: GUARDIAN_ADDRESS,
+        externalChatId: GUARDIAN_CHAT_ID,
+        status: "active",
+      },
+    ];
+
+    const expected = toTrustContext(
+      resolveActorTrust({
+        assistantId: "assistant-1",
+        sourceChannel: SOURCE_CHANNEL,
+        conversationExternalId: CONVERSATION_ID,
+        actorExternalId: GUARDIAN_ADDRESS,
+      }),
+      CONVERSATION_ID,
+    );
+
+    const actual = await resolveLocalPrincipalTrustContext({
+      actorPrincipalId: GUARDIAN_ADDRESS,
+      sourceChannel: SOURCE_CHANNEL,
+      conversationExternalId: CONVERSATION_ID,
+    });
+
+    expect(actual).toEqual(expected);
+  });
+
+  test("non-matching principal → unknown ctx", async () => {
+    mockGuardianList = [
+      {
+        channelType: "vellum",
+        contactId: "contact-1",
+        principalId: GUARDIAN_PRINCIPAL_ID,
+        address: GUARDIAN_ADDRESS,
+        externalChatId: GUARDIAN_CHAT_ID,
+        status: "active",
+      },
+    ];
+
+    const ctx = await resolveLocalPrincipalTrustContext({
+      actorPrincipalId: "principal-other",
+      sourceChannel: SOURCE_CHANNEL,
+      conversationExternalId: CONVERSATION_ID,
+    });
+
+    expect(ctx.trustClass).toBe("unknown");
+    expect(ctx.requesterExternalUserId).toBe("principal-other");
+    expect(ctx.requesterChatId).toBe(CONVERSATION_ID);
+    expect(ctx.sourceChannel).toBe(SOURCE_CHANNEL);
+    expect(ctx.guardianPrincipalId).toBeUndefined();
+  });
+
+  test("empty guardian list → unknown ctx", async () => {
+    mockGuardianList = [];
+
+    const ctx = await resolveLocalPrincipalTrustContext({
+      actorPrincipalId: GUARDIAN_PRINCIPAL_ID,
+      sourceChannel: SOURCE_CHANNEL,
+      conversationExternalId: CONVERSATION_ID,
+    });
+
+    expect(ctx.trustClass).toBe("unknown");
+  });
+
+  test("null guardian list (gateway unreachable) → unknown (fail closed)", async () => {
+    mockGuardianList = null;
+
+    const ctx = await resolveLocalPrincipalTrustContext({
+      actorPrincipalId: GUARDIAN_PRINCIPAL_ID,
+      sourceChannel: SOURCE_CHANNEL,
+      conversationExternalId: CONVERSATION_ID,
+    });
+
+    expect(ctx.trustClass).toBe("unknown");
+    expect(ctx.requesterExternalUserId).toBe(GUARDIAN_PRINCIPAL_ID);
+  });
+});

package/src/runtime/__tests__/member-verdict-cache.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Unit tests for the in-memory member-verdict cache: set→get round-trip, TTL
+ * expiry, memberless verdicts not cached, and max-size eviction.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { TrustVerdict } from "@vellumai/gateway-client";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+import {
+  __resetMemberVerdictCacheForTest,
+  getCachedMemberAcl,
+  setMemberVerdict,
+} from "../member-verdict-cache.js";
+
+const PHONE = "+15559871234";
+
+function memberVerdict(
+  overrides: Partial<TrustVerdict> = {},
+): TrustVerdict {
+  return {
+    trustClass: "trusted_contact",
+    canonicalSenderId: PHONE,
+    contactId: "contact-1",
+    channelId: "ch-1",
+    status: "active",
+    policy: "allow",
+    ...overrides,
+  };
+}
+
+const realNow = Date.now;
+
+describe("member-verdict-cache", () => {
+  beforeEach(() => {
+    __resetMemberVerdictCacheForTest();
+  });
+
+  afterEach(() => {
+    Date.now = realNow;
+  });
+
+  test("set then get returns the derived ACL view", () => {
+    setMemberVerdict("phone", PHONE, memberVerdict());
+    expect(getCachedMemberAcl("phone", PHONE)).toEqual({
+      status: "active",
+      policy: "allow",
+      role: "contact",
+    });
+  });
+
+  test("guardian trustClass derives the guardian role", () => {
+    setMemberVerdict("phone", PHONE, memberVerdict({ trustClass: "guardian" }));
+    expect(getCachedMemberAcl("phone", PHONE)?.role).toBe("guardian");
+  });
+
+  test("read canonicalizes the actor id like the write", () => {
+    // Phone numbers normalize to E.164; a raw-format write is readable by the
+    // same raw-format read.
+    setMemberVerdict("phone", "(555) 987-1234", memberVerdict());
+    expect(getCachedMemberAcl("phone", "(555) 987-1234")).toBeDefined();
+  });
+
+  test("empty actor id is a no-op on set and get", () => {
+    setMemberVerdict("phone", undefined, memberVerdict());
+    expect(getCachedMemberAcl("phone", undefined)).toBeUndefined();
+    expect(getCachedMemberAcl("phone", "   ")).toBeUndefined();
+  });
+
+  test("memberless verdict is not cached", () => {
+    setMemberVerdict(
+      "phone",
+      PHONE,
+      memberVerdict({ contactId: undefined, channelId: undefined }),
+    );
+    expect(getCachedMemberAcl("phone", PHONE)).toBeUndefined();
+  });
+
+  test("memberless verdict clears a stale active entry for the actor", () => {
+    setMemberVerdict("phone", PHONE, memberVerdict());
+    expect(getCachedMemberAcl("phone", PHONE)).toBeDefined();
+    // A later memberless verdict (deleted contact / stranger) must invalidate
+    // the stale active ACL, not leave it readable for the rest of the TTL.
+    setMemberVerdict(
+      "phone",
+      PHONE,
+      memberVerdict({ contactId: undefined, channelId: undefined }),
+    );
+    expect(getCachedMemberAcl("phone", PHONE)).toBeUndefined();
+  });
+
+  test("expired entry returns undefined", () => {
+    const t0 = realNow();
+    Date.now = () => t0;
+    setMemberVerdict("phone", PHONE, memberVerdict());
+    Date.now = () => t0 + 300_001;
+    expect(getCachedMemberAcl("phone", PHONE)).toBeUndefined();
+  });
+
+  test("evicts the oldest-expiring entry past the bound", () => {
+    const t0 = realNow();
+    // telegram IDs pass through unchanged, so each key is distinct. Fill past
+    // capacity with monotonically increasing expiry stamps.
+    for (let i = 0; i < 2001; i++) {
+      Date.now = () => t0 + i;
+      setMemberVerdict("telegram", `tg-${i}`, memberVerdict());
+    }
+    Date.now = () => t0 + 2001;
+    // The oldest-expiring entry is evicted on the over-capacity insert; the
+    // latest survives.
+    expect(getCachedMemberAcl("telegram", "tg-0")).toBeUndefined();
+    expect(getCachedMemberAcl("telegram", "tg-2000")).toBeDefined();
+  });
+});