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

package/src/runtime/anchored-guardian.test.ts

@@ -0,0 +1,156 @@
+/**
+ * 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

@@ -0,0 +1,135 @@
+/**
+ * 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/assistant-event-hub.ts

@@ -749,7 +749,7 @@ async function createCanonicalRequestForConfirmation(
     });
 
     if (trustContext && conversation) {
-      bridgeConfirmationRequestToGuardian({
+      await bridgeConfirmationRequestToGuardian({
         canonicalRequest,
         trustContext,
         conversationId,

package/src/runtime/assistant-stream-state.ts

@@ -50,14 +50,21 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import {
+  SSE_REPLAY_RING_AGE_LIMIT_MS,
+  SSE_REPLAY_RING_COUNT_LIMIT,
+} from "../api/constants/sse-replay.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import type { AssistantEvent } from "./assistant-event.js";
 
 // ── Tunables ─────────────────────────────────────────────────────────
 
-const RING_COUNT_LIMIT = 200;
+// Count and age bounds on the replay ring. Shared with the web client
+// (via `@vellumai/assistant-api`) so its seq-gap tolerance is sized
+// against the same numbers the daemon buffers against.
+const RING_COUNT_LIMIT = SSE_REPLAY_RING_COUNT_LIMIT;
 const RING_SIZE_LIMIT_BYTES = 256 * 1024;
-const RING_AGE_LIMIT_MS = 30_000;
+const RING_AGE_LIMIT_MS = SSE_REPLAY_RING_AGE_LIMIT_MS;
 
 /**
  * Cap on how many conversations retain a persisted-seq entry. Unlike the

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

@@ -0,0 +1,99 @@
+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/auth/require-bound-guardian.ts

@@ -1,15 +1,20 @@
 import { isHttpAuthDisabled } from "../../config/env.js";
-import { findGuardianForChannel } from "../../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+} from "../../contacts/guardian-delivery-reader.js";
 import { httpError } from "../http-errors.js";
 import type { AuthContext } from "./types.js";
 
 /**
  * Verify the actor from AuthContext is the bound guardian for the vellum channel.
- * Returns an error Response if not, or null if allowed.
+ * Sources the guardian from the gateway binding and fails closed when the
+ * gateway is unreachable (null list). Returns an error Response if not
+ * authorized, or null if allowed.
  */
-export function requireBoundGuardian(
+export async function requireBoundGuardian(
   authContext: AuthContext,
-): Response | null {
+): Promise<Response | null> {
   // Dev bypass: when auth is disabled, skip guardian binding check
   // (mirrors enforcePolicy dev bypass in route-policy.ts)
   if (isHttpAuthDisabled()) {
@@ -22,17 +27,22 @@ export function requireBoundGuardian(
       403,
     );
   }
-  const guardianResult = findGuardianForChannel("vellum");
-  if (!guardianResult) {
-    // No guardian yet — in pre-bootstrap state, allow through
-    return null;
-  }
-  if (guardianResult.channel.address !== authContext.actorPrincipalId) {
+  const guardians = await getGuardianDelivery({ channelTypes: ["vellum"] });
+  if (!guardians) {
+    // Gateway unreachable — fail closed.
     return httpError(
       "FORBIDDEN",
       "Actor is not the bound guardian for this channel",
       403,
     );
   }
-  return null;
+  const guardian = guardianForChannel(guardians, "vellum");
+  if (guardian && guardian.principalId === authContext.actorPrincipalId) {
+    return null;
+  }
+  return httpError(
+    "FORBIDDEN",
+    "Actor is not the bound guardian for this channel",
+    403,
+  );
 }

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

@@ -9,8 +9,12 @@
 import { createHash, randomBytes } from "crypto";
 import { v4 as uuid } from "uuid";
 
-import { findGuardianForChannel } from "../contacts/contact-store.js";
 import { revokeGuardianBinding } from "../contacts/contacts-write.js";
+import {
+  getGuardianDelivery,
+  getGuardianDeliveryFresh,
+  guardianForChannel,
+} from "../contacts/guardian-delivery-reader.js";
 import type {
   GuardianBinding,
   IdentityBindingStatus,
@@ -319,50 +323,71 @@ export function validateAndConsumeVerification(
 
 /**
  * Look up the active guardian binding for a given assistant and channel.
- * Reads from the contacts table via findGuardianForChannel and
- * synthesizes a GuardianBinding-shaped object.
- * Returns null when no contacts match.
+ * Reads the gateway-owned GuardianDelivery and synthesizes a
+ * GuardianBinding-shaped object. Returns null when no guardian is bound or
+ * the gateway is unreachable.
  */
-export function getGuardianBinding(
+export async function getGuardianBinding(
   assistantId: string,
   channel: string,
-): GuardianBinding | null {
-  const result = findGuardianForChannel(channel);
-  if (result) {
-    return {
-      id: result.channel.id,
-      assistantId,
-      channel,
-      guardianExternalUserId: result.channel.address,
-      guardianDeliveryChatId: result.channel.externalChatId ?? "",
-      guardianPrincipalId: result.contact.principalId ?? "",
-      status: "active" as const,
-      verifiedAt: result.channel.verifiedAt ?? 0,
-      verifiedVia: result.channel.verifiedVia ?? "",
-      metadataJson: null,
-      createdAt: result.channel.createdAt,
-      updatedAt: result.channel.updatedAt ?? result.channel.createdAt,
-    };
-  }
+): Promise<GuardianBinding | null> {
+  const list = await getGuardianDelivery({ channelTypes: [channel] });
+  const delivery = list ? guardianForChannel(list, channel) : undefined;
+  if (!delivery) return null;
 
-  return null;
+  const now = Date.now();
+  return {
+    id: delivery.contactId,
+    assistantId,
+    channel,
+    guardianExternalUserId: delivery.address,
+    guardianDeliveryChatId: delivery.externalChatId ?? "",
+    guardianPrincipalId: delivery.principalId ?? "",
+    status: "active" as const,
+    verifiedAt: delivery.verifiedAt ?? 0,
+    // verifiedVia is not carried on the delivery contract; a bound guardian
+    // is verified by definition.
+    verifiedVia: "verified",
+    metadataJson: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * Gateway-backed guardian-existence check: is a guardian already bound for
+ * this channel? Presence-only idempotency guard, NOT an ACL-field read.
+ *
+ * Null-list fail direction: a `null` from the gateway (unreachable / malformed)
+ * is "unknown" — returns `true` so an unreachable gateway is treated as
+ * already-bound. Callers gate session creation on a falsy result, so this
+ * blocks a new binding on a transient miss rather than spuriously creating a
+ * second one.
+ */
+export async function isGuardianBoundForChannel(
+  channel: string,
+): Promise<boolean> {
+  // Existence guards read fresh because gateway-side binding writes don't
+  // invalidate the daemon cache.
+  const list = await getGuardianDeliveryFresh({ channelTypes: [channel] });
+  if (list === null) return true;
+  return !!guardianForChannel(list, channel);
 }
 
 /**
  * Check whether the given external user is the active guardian for
  * the specified assistant and channel.
  */
-export function isGuardian(
+export async function isGuardian(
   assistantId: string,
   channel: string,
   address: string,
-): boolean {
-  const result = findGuardianForChannel(channel);
-  if (result) {
-    return result.channel.address.toLowerCase() === address.toLowerCase();
-  }
+): Promise<boolean> {
+  const list = await getGuardianDelivery({ channelTypes: [channel] });
+  const delivery = list ? guardianForChannel(list, channel) : undefined;
+  if (!delivery) return false;
 
-  return false;
+  return delivery.address.toLowerCase() === address.toLowerCase();
 }
 
 /**

package/src/runtime/confirmation-request-guardian-bridge.ts

@@ -70,9 +70,9 @@ export type BridgeConfirmationRequestResult =
  *
  * Fire-and-forget safe: notification emission errors are logged but not propagated.
  */
-export function bridgeConfirmationRequestToGuardian(
+export async function bridgeConfirmationRequestToGuardian(
   params: BridgeConfirmationRequestParams,
-): BridgeConfirmationRequestResult {
+): Promise<BridgeConfirmationRequestResult> {
   const {
     canonicalRequest,
     trustContext,
@@ -100,7 +100,7 @@ export function bridgeConfirmationRequestToGuardian(
   }
 
   const sourceChannel = trustContext.sourceChannel;
-  const binding = getGuardianBinding(assistantId, sourceChannel);
+  const binding = await getGuardianBinding(assistantId, sourceChannel);
   if (!binding) {
     log.debug(
       { sourceChannel, assistantId },