@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

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

@@ -0,0 +1,164 @@
+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 = [];
+
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: (_input?: { channelTypes?: string[] }) =>
+    Promise.resolve(mockGuardianList),
+}));
+
+// Local-resolver guardian binding, used to construct the expected guardian
+// TrustContext via the existing resolver and prove equivalence.
+let mockGuardianRecord: {
+  contact: Record<string, unknown>;
+  channel: Record<string, unknown>;
+} | null = null;
+
+mock.module("../../contacts/contact-store.js", () => ({
+  findGuardianForChannel: (_channelType: string) => mockGuardianRecord,
+  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 = [];
+    mockGuardianRecord = null;
+  });
+
+  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",
+      },
+    ];
+    mockGuardianRecord = {
+      contact: { id: "contact-1", principalId: GUARDIAN_ADDRESS },
+      channel: {
+        type: "vellum",
+        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__/trust-verdict-consumer.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import type { TrustVerdict } from "@vellumai/gateway-client";
 
+import { channelStatusToMemberStatus } from "../../contacts/member-status.js";
 import type {
   ContactChannel,
   ContactWithChannels,
@@ -9,8 +10,12 @@ import type {
 import type { ActorTrustContext } from "../actor-trust-resolver.js";
 import { toTrustContext } from "../actor-trust-resolver.js";
 import {
+  actorTrustContextFromVerdict,
   resolvedMemberFromVerdict,
   trustContextFromVerdict,
+  verdictHasMemberIdentity,
+  verdictMemberFromVerdict,
+  verdictMemberUnresolvable,
 } from "../trust-verdict-consumer.js";
 
 const CONV = "conv-123";
@@ -163,6 +168,195 @@ describe("trustContextFromVerdict", () => {
   });
 });
 
+describe("actorTrustContextFromVerdict", () => {
+  test("maps guardian verdict fields", () => {
+    const verdict = {
+      trustClass: "guardian",
+      canonicalSenderId: "+15550100",
+      guardianExternalUserId: "+15550100",
+      guardianDeliveryChatId: "chat-9",
+      guardianPrincipalId: "vellum-principal-abc",
+      memberDisplayName: "Alice",
+    } satisfies TrustVerdict;
+
+    const ctx = actorTrustContextFromVerdict(verdict, {
+      sourceChannel: "phone",
+      conversationExternalId: CONV,
+      actorUsername: "alice",
+      actorDisplayName: "Alice Sender",
+    });
+
+    expect(ctx).toEqual({
+      canonicalSenderId: "+15550100",
+      guardianBindingMatch: {
+        guardianExternalUserId: "+15550100",
+        guardianDeliveryChatId: "chat-9",
+      },
+      guardianPrincipalId: "vellum-principal-abc",
+      memberRecord: null,
+      trustClass: "guardian",
+      actorMetadata: {
+        identifier: "@alice",
+        displayName: "Alice",
+        senderDisplayName: "Alice Sender",
+        memberDisplayName: "Alice",
+        username: "alice",
+        channel: "phone",
+        trustStatus: "guardian",
+      },
+    });
+  });
+
+  test("guardianBindingMatch is null without guardianExternalUserId", () => {
+    const verdict = {
+      trustClass: "trusted_contact",
+      canonicalSenderId: "+15550101",
+      memberDisplayName: "Bob",
+    } satisfies TrustVerdict;
+
+    const ctx = actorTrustContextFromVerdict(verdict, {
+      sourceChannel: "phone",
+      conversationExternalId: CONV,
+    });
+
+    expect(ctx.guardianBindingMatch).toBeNull();
+    expect(ctx.trustClass).toBe("trusted_contact");
+    // identifier falls back to canonicalSenderId when no username.
+    expect(ctx.actorMetadata.identifier).toBe("+15550101");
+    // displayName uses memberDisplayName when present.
+    expect(ctx.actorMetadata.displayName).toBe("Bob");
+    expect(ctx.actorMetadata.channel).toBe("phone");
+    expect(ctx.memberRecord).toBeNull();
+  });
+
+  test("displayName falls back to actorDisplayName; identifier uses @username", () => {
+    const verdict = {
+      trustClass: "unverified_contact",
+      canonicalSenderId: "u-1",
+    } satisfies TrustVerdict;
+
+    const ctx = actorTrustContextFromVerdict(verdict, {
+      sourceChannel: "slack",
+      conversationExternalId: CONV,
+      actorUsername: "carol",
+      actorDisplayName: "Carol Display",
+    });
+
+    expect(ctx.trustClass).toBe("unverified_contact");
+    expect(ctx.actorMetadata.identifier).toBe("@carol");
+    expect(ctx.actorMetadata.displayName).toBe("Carol Display");
+    expect(ctx.actorMetadata.memberDisplayName).toBeUndefined();
+    expect(ctx.actorMetadata.trustStatus).toBe("unverified_contact");
+  });
+
+  test("maps unknown verdict with no identity overrides", () => {
+    const verdict = {
+      trustClass: "unknown",
+      canonicalSenderId: "u-2",
+    } satisfies TrustVerdict;
+
+    const ctx = actorTrustContextFromVerdict(verdict, {
+      sourceChannel: "slack",
+      conversationExternalId: CONV,
+    });
+
+    expect(ctx.trustClass).toBe("unknown");
+    expect(ctx.guardianBindingMatch).toBeNull();
+    expect(ctx.guardianPrincipalId).toBeUndefined();
+    expect(ctx.memberRecord).toBeNull();
+    expect(ctx.actorMetadata.identifier).toBe("u-2");
+    expect(ctx.actorMetadata.displayName).toBeUndefined();
+  });
+
+  test("member verdict populates memberRecord from the verdict (voice ACL)", () => {
+    const verdict = {
+      trustClass: "trusted_contact",
+      canonicalSenderId: "u-1",
+      contactId: "contact-1",
+      channelId: "channel-1",
+      type: "slack",
+      address: "u-1",
+      status: "blocked",
+      policy: "deny",
+    } satisfies TrustVerdict;
+
+    const ctx = actorTrustContextFromVerdict(verdict, {
+      sourceChannel: "slack",
+      conversationExternalId: CONV,
+    });
+
+    expect(ctx.memberRecord).not.toBeNull();
+    expect(ctx.memberRecord!.contact.id).toBe("contact-1");
+    expect(ctx.memberRecord!.channel.id).toBe("channel-1");
+    expect(ctx.memberRecord!.channel.status).toBe("blocked");
+    expect(ctx.memberRecord!.channel.policy).toBe("deny");
+  });
+
+  test("stranger verdict (no contactId/channelId) leaves memberRecord null", () => {
+    const verdict = {
+      trustClass: "unknown",
+      canonicalSenderId: "u-9",
+    } satisfies TrustVerdict;
+
+    const ctx = actorTrustContextFromVerdict(verdict, {
+      sourceChannel: "slack",
+      conversationExternalId: CONV,
+    });
+
+    expect(ctx.memberRecord).toBeNull();
+  });
+
+  test("malformed member verdict (unknown status) leaves memberRecord null (fail-closed)", () => {
+    const verdict = {
+      trustClass: "trusted_contact",
+      canonicalSenderId: "u-10",
+      contactId: "contact-10",
+      channelId: "channel-10",
+      status: "quarantined",
+      policy: "allow",
+    } satisfies TrustVerdict;
+
+    const ctx = actorTrustContextFromVerdict(verdict, {
+      sourceChannel: "slack",
+      conversationExternalId: CONV,
+    });
+
+    expect(ctx.memberRecord).toBeNull();
+  });
+
+  test("trustContextFromVerdict equals member stamp applied to toTrustContext(actorTrustContextFromVerdict)", () => {
+    const verdict = {
+      trustClass: "trusted_contact",
+      canonicalSenderId: "u-1",
+      contactId: "contact-1",
+      channelId: "channel-1",
+      type: "slack",
+      address: "u-1",
+      status: "unverified",
+      policy: "escalate",
+      memberDisplayName: "Dora",
+    } satisfies TrustVerdict;
+    const input = {
+      sourceChannel: "slack",
+      conversationExternalId: CONV,
+      actorUsername: "dora",
+      actorDisplayName: "Dora Display",
+    } as const;
+
+    const expected = toTrustContext(
+      actorTrustContextFromVerdict(verdict, input),
+      input.conversationExternalId,
+    );
+    const member = resolvedMemberFromVerdict(verdict);
+    expect(member).not.toBeNull();
+    expected.requesterContactId = member!.contact.id;
+    expected.memberStatus = channelStatusToMemberStatus(member!.channel.status);
+    expected.memberPolicy = member!.channel.policy;
+
+    expect(trustContextFromVerdict(verdict, input)).toEqual(expected);
+  });
+});
+
 describe("toTrustContext member grounding", () => {
   function memberChannel(
     overrides: Partial<ContactChannel> = {},
@@ -207,9 +401,7 @@ describe("toTrustContext member grounding", () => {
     };
   }
 
-  function ctxWithMember(
-    channel: ContactChannel,
-  ): ActorTrustContext {
+  function ctxWithMember(channel: ContactChannel): ActorTrustContext {
     return {
       canonicalSenderId: "+15550100",
       guardianBindingMatch: null,
@@ -415,3 +607,143 @@ describe("resolvedMemberFromVerdict", () => {
     }
   });
 });
+
+describe("verdictMemberFromVerdict", () => {
+  test("active member verdict yields the narrow ACL view", () => {
+    const verdict = {
+      trustClass: "trusted_contact",
+      canonicalSenderId: "u-1",
+      contactId: "contact-1",
+      channelId: "channel-1",
+      type: "slack",
+      address: "u-1",
+      status: "active",
+      policy: "allow",
+      verifiedAt: 1700000000,
+      memberDisplayName: "Dora",
+    } satisfies TrustVerdict;
+
+    expect(verdictMemberFromVerdict(verdict)).toEqual({
+      contactId: "contact-1",
+      channelId: "channel-1",
+      status: "active",
+      policy: "allow",
+      verifiedAt: 1700000000,
+      displayName: "Dora",
+    });
+  });
+
+  test("blocked member verdict surfaces status/policy verbatim, null defaults", () => {
+    const verdict = {
+      trustClass: "unknown",
+      canonicalSenderId: "u-3",
+      contactId: "contact-3",
+      channelId: "channel-3",
+      status: "blocked",
+      policy: "deny",
+    } satisfies TrustVerdict;
+
+    expect(verdictMemberFromVerdict(verdict)).toEqual({
+      contactId: "contact-3",
+      channelId: "channel-3",
+      status: "blocked",
+      policy: "deny",
+      verifiedAt: null,
+      displayName: null,
+    });
+  });
+
+  test("memberless verdict (no contactId/channelId) returns null", () => {
+    expect(
+      verdictMemberFromVerdict({
+        trustClass: "unknown",
+        canonicalSenderId: "u-2",
+      } satisfies TrustVerdict),
+    ).toBeNull();
+  });
+
+  test("invalid enum (unknown status/policy) returns null (fail-closed)", () => {
+    expect(
+      verdictMemberFromVerdict({
+        trustClass: "trusted_contact",
+        canonicalSenderId: "u-7",
+        contactId: "contact-7",
+        channelId: "channel-7",
+        status: "quarantined",
+        policy: "allow",
+      } satisfies TrustVerdict),
+    ).toBeNull();
+    expect(
+      verdictMemberFromVerdict({
+        trustClass: "trusted_contact",
+        canonicalSenderId: "u-6",
+        contactId: "contact-6",
+        channelId: "channel-6",
+        status: "active",
+        policy: "bogus",
+      } satisfies TrustVerdict),
+    ).toBeNull();
+  });
+});
+
+describe("verdict predicates", () => {
+  test("verdictHasMemberIdentity is true with contactId or channelId", () => {
+    expect(
+      verdictHasMemberIdentity({
+        trustClass: "unknown",
+        canonicalSenderId: "u-1",
+        contactId: "contact-1",
+      } satisfies TrustVerdict),
+    ).toBe(true);
+    expect(
+      verdictHasMemberIdentity({
+        trustClass: "unknown",
+        canonicalSenderId: "u-1",
+        channelId: "channel-1",
+      } satisfies TrustVerdict),
+    ).toBe(true);
+  });
+
+  test("verdictHasMemberIdentity is false for a memberless verdict", () => {
+    expect(
+      verdictHasMemberIdentity({
+        trustClass: "unknown",
+        canonicalSenderId: "u-1",
+      } satisfies TrustVerdict),
+    ).toBe(false);
+  });
+
+  test("verdictMemberUnresolvable is true when member identity present but ACL unsynthesizable", () => {
+    expect(
+      verdictMemberUnresolvable({
+        trustClass: "trusted_contact",
+        canonicalSenderId: "u-1",
+        contactId: "contact-1",
+        channelId: "channel-1",
+        policy: "allow",
+      } satisfies TrustVerdict),
+    ).toBe(true);
+  });
+
+  test("verdictMemberUnresolvable is false for a usable member verdict", () => {
+    expect(
+      verdictMemberUnresolvable({
+        trustClass: "trusted_contact",
+        canonicalSenderId: "u-1",
+        contactId: "contact-1",
+        channelId: "channel-1",
+        status: "active",
+        policy: "allow",
+      } satisfies TrustVerdict),
+    ).toBe(false);
+  });
+
+  test("verdictMemberUnresolvable is false for a memberless verdict", () => {
+    expect(
+      verdictMemberUnresolvable({
+        trustClass: "unknown",
+        canonicalSenderId: "u-1",
+      } satisfies TrustVerdict),
+    ).toBe(false);
+  });
+});

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

@@ -12,7 +12,7 @@
  */
 
 import type { ChannelId } from "../channels/types.js";
-import { findGuardianForChannel } from "../contacts/contact-store.js";
+import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
 import type { ChannelStatus } from "../contacts/types.js";
 import {
   createCanonicalGuardianRequest,
@@ -25,6 +25,7 @@ import {
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import type { GuardianResolutionSource } from "../notifications/signal.js";
 import { getLogger } from "../util/logger.js";
+import { resolveAnchoredGuardian } from "./anchored-guardian.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "./routes/channel-route-shared.js";
 
 const log = getLogger("access-request-helper");
@@ -70,12 +71,12 @@ export type AccessRequestResult =
  * trust anchor and only accepts source-channel contacts that match it. This
  * prevents stale or cross-assistant contacts from being bound to the request.
  *
- * This is intentionally synchronous with respect to the canonical store writes
- * and fire-and-forget for the notification signal emission.
+ * The canonical store writes complete before this resolves; the notification
+ * signal emission is fire-and-forget.
  */
-export function notifyGuardianOfAccessRequest(
+export async function notifyGuardianOfAccessRequest(
   params: AccessRequestParams,
-): AccessRequestResult {
+): Promise<AccessRequestResult> {
   const {
     canonicalAssistantId,
     sourceChannel,
@@ -94,40 +95,19 @@ export function notifyGuardianOfAccessRequest(
     return { notified: false, reason: "no_sender_id" };
   }
 
-  // Resolve guardian identity with assistant-anchored strategy:
-  // 1. Ensure the assistant has a vellum guardian principal (trust anchor)
-  // 2. Use source-channel guardian only when principal matches anchor
-  // 3. Fallback to vellum guardian identity for this assistant principal
-  let guardianExternalUserId: string | null = null;
-  let guardianPrincipalId: string | null = null;
-  let guardianBindingChannel: string | null = null;
-  let guardianResolutionSource: GuardianResolutionSource = "none";
-
-  const vellumGuardian = findGuardianForChannel("vellum");
-  const assistantGuardianPrincipalId = vellumGuardian?.contact.principalId;
-
-  // Try source-channel guardian, but only if it maps to the assistant's
-  // anchored principal. This blocks cross-assistant/stale contact selection.
-  const sourceGuardian = findGuardianForChannel(sourceChannel);
-  if (
-    assistantGuardianPrincipalId &&
-    sourceGuardian &&
-    sourceGuardian.contact.principalId === assistantGuardianPrincipalId
-  ) {
-    guardianExternalUserId = sourceGuardian.channel.address;
-    guardianPrincipalId = sourceGuardian.contact.principalId;
-    guardianBindingChannel = sourceGuardian.channel.type;
-    guardianResolutionSource = "source-channel-contact";
-  }
-
-  // Access requests always require a principal. If source-channel resolution
-  // did not match the assistant anchor, use the anchored vellum identity.
-  if (!guardianPrincipalId && vellumGuardian) {
-    guardianExternalUserId = vellumGuardian.channel.address;
-    guardianPrincipalId = assistantGuardianPrincipalId ?? null;
-    guardianBindingChannel = guardianBindingChannel ?? "vellum";
-    guardianResolutionSource = "vellum-anchor";
-  }
+  // Resolve guardian identity with the assistant-anchored strategy (gateway
+  // source-channel match validated against the vellum anchor, else the vellum
+  // anchor), with a LOCAL-store fallback when the gateway read is empty.
+  const anchored = resolveAnchoredGuardian({
+    guardians: await getGuardianDelivery(),
+    sourceChannel,
+    useLocalFallback: true,
+  });
+  const guardianExternalUserId = anchored?.address ?? null;
+  const guardianPrincipalId = anchored?.principalId ?? null;
+  const guardianBindingChannel = anchored?.channelType ?? null;
+  const guardianResolutionSource: GuardianResolutionSource =
+    anchored?.source ?? "none";
 
   log.debug(
     {

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

@@ -323,8 +323,8 @@ export function toTrustContext(
     requesterMemberDisplayName: ctx.actorMetadata.memberDisplayName,
     requesterExternalUserId: ctx.canonicalSenderId ?? undefined,
     requesterChatId: conversationExternalId,
-    // Member grounding from a real memberRecord (voice path); the verdict path
-    // (memberRecord=null) stamps these from the verdict instead.
+    // Member grounding from the resolved memberRecord (voice + verdict paths
+    // both populate it).
     requesterContactId: ctx.memberRecord?.contact.id,
     memberStatus: ctx.memberRecord
       ? channelStatusToMemberStatus(ctx.memberRecord.channel.status)