@vellumai/assistant 0.10.2-dev.202606250318.5e7cfb0 → 0.10.2

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

@@ -1,164 +0,0 @@
-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/anchored-guardian.test.ts

@@ -1,156 +0,0 @@
-/**
- * Unit tests for `resolveAnchoredGuardian`.
- *
- * Covers the gateway arms (source-channel match validated against the vellum
- * anchor, vellum-anchor fallback), the LOCAL-store fallback when the gateway
- * list is empty, and the cosmetic `requireAnchorPrincipal` guard.
- */
-import { afterEach, describe, expect, mock, test } from "bun:test";
-
-import type { GuardianDelivery } from "@vellumai/gateway-client";
-
-// Local store fallback is mocked so we can drive both arms deterministically.
-let localGuardians: Record<
-  string,
-  { contact: { principalId: string | null; displayName: string }; channel: { address: string; type: string } } | null
-> = {};
-mock.module("../contacts/contact-store.js", () => ({
-  findGuardianForChannel: (channelType: string) =>
-    localGuardians[channelType] ?? null,
-}));
-
-const { resolveAnchoredGuardian } = await import("./anchored-guardian.js");
-
-function gw(g: Partial<GuardianDelivery> & { channelType: string; address: string }): GuardianDelivery {
-  return {
-    contactId: `c-${g.channelType}`,
-    status: "active",
-    ...g,
-  };
-}
-
-afterEach(() => {
-  localGuardians = {};
-});
-
-describe("resolveAnchoredGuardian — gateway arm", () => {
-  test("source-channel guardian matching the anchor wins", () => {
-    const result = resolveAnchoredGuardian({
-      guardians: [
-        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
-        gw({ channelType: "telegram", address: "tg-addr", principalId: "p-anchor", displayName: "Alice" }),
-      ],
-      sourceChannel: "telegram",
-    });
-    expect(result).toEqual({
-      principalId: "p-anchor",
-      address: "tg-addr",
-      displayName: "Alice",
-      channelType: "telegram",
-      source: "source-channel-contact",
-    });
-  });
-
-  test("source-channel guardian NOT matching the anchor falls back to vellum-anchor", () => {
-    const result = resolveAnchoredGuardian({
-      guardians: [
-        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
-        gw({ channelType: "telegram", address: "tg-addr", principalId: "p-other", displayName: "Stale" }),
-      ],
-      sourceChannel: "telegram",
-    });
-    expect(result).toEqual({
-      principalId: "p-anchor",
-      address: "v-addr",
-      displayName: "Vellum",
-      channelType: "vellum",
-      source: "vellum-anchor",
-    });
-  });
-
-  test("no source-channel guardian falls back to vellum-anchor", () => {
-    const result = resolveAnchoredGuardian({
-      guardians: [
-        gw({ channelType: "vellum", address: "v-addr", principalId: "p-anchor", displayName: "Vellum" }),
-      ],
-      sourceChannel: "telegram",
-    });
-    expect(result?.source).toBe("vellum-anchor");
-    expect(result?.principalId).toBe("p-anchor");
-  });
-});
-
-describe("resolveAnchoredGuardian — local fallback", () => {
-  test("gateway empty + local source-channel match returns the local record", () => {
-    localGuardians = {
-      vellum: { contact: { principalId: "p-local", displayName: "LocalVellum" }, channel: { address: "lv-addr", type: "vellum" } },
-      telegram: { contact: { principalId: "p-local", displayName: "LocalAlice" }, channel: { address: "ltg-addr", type: "telegram" } },
-    };
-    const result = resolveAnchoredGuardian({
-      guardians: null,
-      sourceChannel: "telegram",
-      useLocalFallback: true,
-    });
-    expect(result).toEqual({
-      principalId: "p-local",
-      address: "ltg-addr",
-      displayName: "LocalAlice",
-      channelType: "telegram",
-      source: "source-channel-contact",
-    });
-  });
-
-  test("gateway empty + only local vellum returns the local vellum-anchor", () => {
-    localGuardians = {
-      vellum: { contact: { principalId: "p-local", displayName: "LocalVellum" }, channel: { address: "lv-addr", type: "vellum" } },
-    };
-    const result = resolveAnchoredGuardian({
-      guardians: null,
-      sourceChannel: "telegram",
-      useLocalFallback: true,
-    });
-    expect(result?.source).toBe("vellum-anchor");
-    expect(result?.address).toBe("lv-addr");
-  });
-
-  test("gateway empty + no local + fallback disabled returns null", () => {
-    const result = resolveAnchoredGuardian({
-      guardians: null,
-      sourceChannel: "telegram",
-    });
-    expect(result).toBeNull();
-  });
-
-  test("nothing anywhere returns null", () => {
-    const result = resolveAnchoredGuardian({
-      guardians: [],
-      sourceChannel: "telegram",
-      useLocalFallback: true,
-    });
-    expect(result).toBeNull();
-  });
-});
-
-describe("resolveAnchoredGuardian — requireAnchorPrincipal (cosmetic label)", () => {
-  test("vellum guardian with a null principal degrades to null", () => {
-    const result = resolveAnchoredGuardian({
-      guardians: [
-        gw({ channelType: "vellum", address: "v-addr", principalId: null, displayName: "Vellum" }),
-      ],
-      sourceChannel: "telegram",
-      requireAnchorPrincipal: true,
-    });
-    expect(result).toBeNull();
-  });
-
-  test("without requireAnchorPrincipal a null-principal vellum still resolves", () => {
-    const result = resolveAnchoredGuardian({
-      guardians: [
-        gw({ channelType: "vellum", address: "v-addr", principalId: null, displayName: "Vellum" }),
-      ],
-      sourceChannel: "telegram",
-    });
-    expect(result?.source).toBe("vellum-anchor");
-    expect(result?.principalId).toBeNull();
-  });
-});

package/src/runtime/anchored-guardian.ts

@@ -1,135 +0,0 @@
-/**
- * Shared anchored-guardian resolution.
- *
- * Resolves the guardian identity for an inbound access request using the
- * assistant's vellum principal as the trust anchor: a source-channel guardian
- * is only accepted when its principal matches the anchor, otherwise the vellum
- * anchor identity is used. This blocks stale or cross-assistant contacts from
- * being bound to a request.
- *
- * Gateway-first: resolves from the gateway delivery list, then falls back to
- * the LOCAL dual-written binding when the gateway read is empty/unavailable
- * (restart, timeout, malformed IPC). The local fallback is transitional and is
- * removed in a later step.
- */
-
-import type { GuardianDelivery } from "@vellumai/gateway-client";
-
-import type { ChannelId } from "../channels/types.js";
-import { findGuardianForChannel } from "../contacts/contact-store.js";
-import { guardianForChannel } from "../contacts/guardian-delivery-reader.js";
-import type { GuardianResolutionSource } from "../notifications/signal.js";
-
-/** Resolved guardian identity, anchored on the assistant's vellum principal. */
-export interface AnchoredGuardian {
-  principalId: string | null;
-  address: string;
-  displayName: string | null;
-  channelType: string;
-  source: GuardianResolutionSource;
-}
-
-export interface ResolveAnchoredGuardianInput {
-  /** Gateway delivery list; `null` when the gateway read failed/was empty. */
-  guardians: GuardianDelivery[] | null;
-  sourceChannel: ChannelId;
-  /**
-   * Fall back to the LOCAL dual-written binding when the gateway arm resolves
-   * nothing. Access-request enables this to avoid an undecidable request; the
-   * cosmetic guardian-label path leaves it off so a missing gateway read
-   * degrades gracefully to the default reference.
-   */
-  useLocalFallback?: boolean;
-  /**
-   * Require a non-null anchor principal for the vellum-anchor arm. When the
-   * vellum guardian has no principal, return `null` instead of a vellum-anchor
-   * record. Matches the cosmetic label path, which degrades to the default
-   * reference when the anchor principal is absent.
-   */
-  requireAnchorPrincipal?: boolean;
-}
-
-/**
- * Resolve the anchored guardian for `sourceChannel`, or `null` when none can be
- * resolved. Gateway source-channel match → that record; gateway anchor-only →
- * vellum-anchor; gateway empty + local has it → local fallback record.
- */
-export function resolveAnchoredGuardian(
-  input: ResolveAnchoredGuardianInput,
-): AnchoredGuardian | null {
-  const { sourceChannel, useLocalFallback, requireAnchorPrincipal } = input;
-  const guardians = input.guardians ?? [];
-
-  const vellumGuardian = guardianForChannel(guardians, "vellum");
-  const anchorPrincipalId = vellumGuardian?.principalId;
-
-  let resolved: AnchoredGuardian | null = null;
-
-  // Source-channel guardian, but only when it maps to the assistant's anchored
-  // principal. This blocks cross-assistant/stale binding selection.
-  const sourceGuardian = guardianForChannel(guardians, sourceChannel);
-  if (
-    anchorPrincipalId &&
-    sourceGuardian &&
-    sourceGuardian.principalId === anchorPrincipalId
-  ) {
-    resolved = {
-      principalId: sourceGuardian.principalId,
-      address: sourceGuardian.address,
-      displayName: sourceGuardian.displayName ?? null,
-      channelType: sourceGuardian.channelType,
-      source: "source-channel-contact",
-    };
-  } else if (vellumGuardian && !(requireAnchorPrincipal && !anchorPrincipalId)) {
-    // Source-channel resolution did not match the anchor → use the anchored
-    // vellum identity.
-    resolved = {
-      principalId: anchorPrincipalId ?? null,
-      address: vellumGuardian.address,
-      displayName: vellumGuardian.displayName ?? null,
-      channelType: "vellum",
-      source: "vellum-anchor",
-    };
-  }
-
-  // Gateway resolved a principal — done.
-  if (resolved?.principalId) {
-    return resolved;
-  }
-
-  if (!useLocalFallback) {
-    return resolved;
-  }
-
-  // Fallback: gateway read was empty/unavailable (or carried no principal), so
-  // resolve from the LOCAL dual-written binding to avoid an undecidable
-  // request. A local match overwrites the principal-less gateway record; with
-  // no local match the gateway record (if any) is retained.
-  const localVellum = findGuardianForChannel("vellum");
-  const localAnchorPrincipalId = localVellum?.contact.principalId;
-  const localSource = findGuardianForChannel(sourceChannel);
-  if (
-    localAnchorPrincipalId &&
-    localSource &&
-    localSource.contact.principalId === localAnchorPrincipalId
-  ) {
-    return {
-      principalId: localSource.contact.principalId,
-      address: localSource.channel.address,
-      displayName: localSource.contact.displayName,
-      channelType: localSource.channel.type,
-      source: "source-channel-contact",
-    };
-  }
-  if (localVellum) {
-    return {
-      principalId: localAnchorPrincipalId ?? null,
-      address: localVellum.channel.address,
-      displayName: localVellum.contact.displayName,
-      channelType: "vellum",
-      source: "vellum-anchor",
-    };
-  }
-
-  return resolved;
-}

package/src/runtime/auth/__tests__/require-bound-guardian.test.ts

@@ -1,99 +0,0 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
-
-import type { GuardianDelivery } from "@vellumai/gateway-client";
-
-let mockGuardians: GuardianDelivery[] | null = null;
-let authDisabled = false;
-
-mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
-  getGuardianDelivery: async () => mockGuardians,
-  // Real active-status selector so the auth gate enforces status==="active".
-  guardianForChannel: (list: GuardianDelivery[], channelType: string) =>
-    list.find((g) => g.channelType === channelType && g.status === "active"),
-}));
-
-mock.module("../../../config/env.js", () => ({
-  isHttpAuthDisabled: () => authDisabled,
-}));
-
-import { requireBoundGuardian } from "../require-bound-guardian.js";
-import type { AuthContext } from "../types.js";
-
-function ctx(actorPrincipalId?: string): AuthContext {
-  return {
-    subject: "sub",
-    principalType: "actor",
-    assistantId: "self",
-    actorPrincipalId,
-    scopeProfile: "actor_client_v1",
-    scopes: new Set(),
-    policyEpoch: 0,
-  };
-}
-
-function guardian(principalId: string): GuardianDelivery {
-  return {
-    channelType: "vellum",
-    contactId: "guardian-contact",
-    principalId,
-    address: principalId,
-    status: "active",
-  };
-}
-
-describe("requireBoundGuardian", () => {
-  beforeEach(() => {
-    mockGuardians = null;
-    authDisabled = false;
-  });
-
-  test("admits the bound guardian", async () => {
-    mockGuardians = [guardian("vellum-principal-abc")];
-    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
-    expect(result).toBeNull();
-  });
-
-  test("denies a non-guardian actor", async () => {
-    mockGuardians = [guardian("vellum-principal-abc")];
-    const result = await requireBoundGuardian(ctx("vellum-principal-other"));
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
-  });
-
-  test("denies when actor principal is missing", async () => {
-    mockGuardians = [guardian("vellum-principal-abc")];
-    const result = await requireBoundGuardian(ctx(undefined));
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
-  });
-
-  test("fails closed on a null list (gateway unreachable)", async () => {
-    mockGuardians = null;
-    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
-  });
-
-  test("denies when no vellum guardian is bound", async () => {
-    mockGuardians = [];
-    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
-  });
-
-  test("denies a non-active (revoked) vellum row matching the actor", async () => {
-    mockGuardians = [
-      { ...guardian("vellum-principal-abc"), status: "revoked" },
-    ];
-    const result = await requireBoundGuardian(ctx("vellum-principal-abc"));
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
-  });
-
-  test("dev bypass admits when auth is disabled", async () => {
-    authDisabled = true;
-    mockGuardians = null;
-    const result = await requireBoundGuardian(ctx(undefined));
-    expect(result).toBeNull();
-  });
-});

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

@@ -1,52 +0,0 @@
-/**
- * Derives a local principal's {@link TrustContext} from the gateway guardian
- * binding. Fails closed to unknown on a missing or null read.
- */
-
-import type { ChannelId } from "../channels/types.js";
-import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
-import type { TrustContext } from "../daemon/trust-context.js";
-import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
-
-export interface ResolveLocalPrincipalTrustInput {
-  actorPrincipalId: string;
-  sourceChannel: ChannelId;
-  conversationExternalId: string;
-}
-
-/** Guardian match → guardian ctx; miss or null read → unknown (fail closed). */
-export async function resolveLocalPrincipalTrustContext(
-  input: ResolveLocalPrincipalTrustInput,
-): Promise<TrustContext> {
-  const unknownContext: TrustContext = {
-    sourceChannel: input.sourceChannel,
-    trustClass: "unknown",
-    requesterExternalUserId: input.actorPrincipalId,
-    requesterChatId: input.conversationExternalId,
-  };
-
-  // Fail closed: a null read means the gateway is unreachable — never grant
-  // guardian on a miss.
-  const guardians = await getGuardianDelivery({ channelTypes: ["vellum"] });
-  if (!guardians) return unknownContext;
-
-  const guardian = guardians.find(
-    (g) => g.principalId === input.actorPrincipalId,
-  );
-  if (!guardian) return unknownContext;
-
-  return {
-    sourceChannel: input.sourceChannel,
-    trustClass: "guardian",
-    guardianChatId: guardian.externalChatId ?? input.conversationExternalId,
-    guardianExternalUserId:
-      canonicalizeInboundIdentity(input.sourceChannel, guardian.address) ??
-      undefined,
-    guardianPrincipalId: guardian.principalId ?? undefined,
-    // Mirror toTrustContext: with no username the requester identifier is the
-    // canonical sender id, which for a vellum principal is actorPrincipalId.
-    requesterIdentifier: input.actorPrincipalId,
-    requesterExternalUserId: input.actorPrincipalId,
-    requesterChatId: input.conversationExternalId,
-  };
-}