@remnic/core 9.54.5 → 9.54.7

package/src/support-passport/access-surface.test.ts

@@ -0,0 +1,283 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+
+import { parseConfig } from "../config.js";
+import { StorageManager } from "../storage.js";
+import { SupportPassportAccessSurface } from "./access-surface.js";
+import { SupportPassportError } from "./errors.js";
+import { SupportPassportModelAdapter, type SupportPassportModelRoute } from "./model-adapter.js";
+import { computeSupportPassportSourceRevision } from "./model-service.js";
+
+test("the access surface runs the owner and helper lifecycle without exposing a secret in owner lists", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-access-"));
+  try {
+    const storage = new StorageManager(path.join(root, "owner"));
+    await storage.ensureDirectories();
+    const now = new Date("2026-08-11T12:00:00.000Z");
+    const source = await storage.writeMemory("preference", "Tell me before plans change.", { source: "test" });
+    const route: SupportPassportModelRoute = {
+      kind: "local",
+      invoke: async (_messages, options) => ({
+        modelUsed: "local/test-model",
+        content:
+          options.operation === "support-passport-draft"
+            ? JSON.stringify({
+                cards: [
+                  {
+                    title: "Plan changes",
+                    statement: "Tell me before plans change.",
+                    category: "transitions",
+                    sourceMemoryIds: [source.id],
+                  },
+                ],
+              })
+            : JSON.stringify({
+                answer: "Tell this person before plans change.",
+                citedCardIds: [approvedCardId],
+                coverage: "grounded",
+              }),
+      }),
+    };
+    let approvedCardId = "";
+    const surface = new SupportPassportAccessSurface({
+      config: parseConfig({ memoryDir: root, supportPassport: { enabled: true } }),
+      resolveOwner: async (principal) => {
+        assert.equal(principal, "owner:test");
+        return { principal, namespace: "owner", storage };
+      },
+      resolveNamespace: async (namespace) => {
+        assert.equal(namespace, "owner");
+        return storage;
+      },
+      modelAdapter: new SupportPassportModelAdapter({ routes: [route] }),
+      audit: { record: async () => undefined },
+      now: () => now,
+    });
+
+    const preview = await surface.previewMemory("owner:test", source.id);
+    assert.equal(preview.found, true);
+    if (!preview.found) throw new Error("source preview was not found");
+    assert.equal(preview.memory.content, "Tell me before plans change.");
+    assert.match(preview.memory.revision, /^[a-f0-9]{64}$/);
+    const drafts = await surface.generateDrafts("owner:test", {
+      sourceMemoryIds: [source.id],
+      sourceMemoryRevisions: [{ memoryId: source.id, revision: preview.memory.revision }],
+      consent: true,
+    });
+    const draft = drafts[0];
+    assert.ok(draft);
+    const approved = await surface.approveCard("owner:test", draft.cardId, {
+      expectedRevision: draft.revision,
+      reasonCode: "owner-approved",
+    });
+    approvedCardId = approved.cardId;
+    await assert.rejects(
+      surface.createGrant("owner:test", {
+        cardIds: [approved.cardId],
+        cardRevisions: [{ cardId: approved.cardId, revision: "0".repeat(64) }],
+        expiresAt: "2026-08-11T14:00:00.123Z",
+      }),
+      (error: unknown) => error instanceof SupportPassportError && error.code === "revision_conflict"
+    );
+    await assert.rejects(
+      surface.createGrant("owner:test", {
+        cardIds: [approved.cardId],
+        cardRevisions: [{ cardId: approved.cardId, revision: approved.revision }],
+        expiresAt: "2026-08-11T12:04:59.999Z",
+      }),
+      (error: unknown) => error instanceof SupportPassportError && error.code === "invalid_input"
+    );
+    const created = await surface.createGrant("owner:test", {
+      cardIds: [approved.cardId],
+      cardRevisions: [{ cardId: approved.cardId, revision: approved.revision }],
+      durationMs: 300_000,
+    });
+    assert.equal(created.expiresAt, "2026-08-11T12:05:00.000Z");
+
+    const ownerGrants = await surface.listGrants("owner:test");
+    assert.equal(ownerGrants.length, 1);
+    assert.equal(JSON.stringify(ownerGrants).includes(created.secret), false);
+    const guide = await surface.readGrant(created.grantId, created.secret);
+    assert.equal(guide.cards[0]?.cardId, approved.cardId);
+    const answer = await surface.askGrant(created.grantId, created.secret, "What should I do?");
+    assert.deepEqual(answer.citedCardIds, [approved.cardId]);
+    const stopped = await surface.revokeGrant("owner:test", created.grantId, {
+      expectedVersion: created.version,
+    });
+    assert.equal(stopped.version, 2);
+    await assert.rejects(
+      surface.readGrant(created.grantId, created.secret),
+      (error: unknown) => error instanceof SupportPassportError && error.code === "grant_gone"
+    );
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("the access surface fails closed while the feature flag is off", async () => {
+  const config = parseConfig({ supportPassport: { enabled: false } });
+  const surface = new SupportPassportAccessSurface({
+    config,
+    resolveOwner: async () => {
+      throw new Error("owner resolution must not run");
+    },
+    resolveNamespace: async () => {
+      throw new Error("namespace resolution must not run");
+    },
+    modelAdapter: new SupportPassportModelAdapter({ routes: [] }),
+    audit: { record: async () => undefined },
+  });
+
+  await assert.rejects(
+    surface.listCards("owner:test"),
+    (error: unknown) => error instanceof SupportPassportError && error.code === "feature_disabled"
+  );
+  await assert.rejects(
+    surface.readGrant("missing", "missing"),
+    (error: unknown) => error instanceof SupportPassportError && error.code === "grant_not_found"
+  );
+});
+
+test("memory preview hides sources that cannot be drafted", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-preview-"));
+  try {
+    const storage = new StorageManager(path.join(root, "owner"));
+    await storage.ensureDirectories();
+    const source = await storage.writeMemory("preference", "Tell me before plans change.", { source: "test" });
+    const surface = new SupportPassportAccessSurface({
+      config: parseConfig({ memoryDir: root, supportPassport: { enabled: true } }),
+      resolveOwner: async (principal) => ({ principal, namespace: "owner", storage }),
+      resolveNamespace: async () => storage,
+      modelAdapter: new SupportPassportModelAdapter({ routes: [] }),
+      audit: { record: async () => undefined },
+    });
+
+    for (const lifecycle of [
+      { status: "archived" as const, archivedAt: "2026-08-12T12:00:00.000Z" },
+      { status: "active" as const, archivedAt: undefined, blockedBy: "memory-review" },
+      { status: "active" as const, blockedBy: undefined, supersededBy: "replacement-memory" },
+    ]) {
+      const current = await storage.getMemoryById(source.id);
+      assert.ok(current);
+      assert.equal(
+        await storage.writeMemoryFrontmatterIfUnchanged(current, {
+          status: lifecycle.status,
+          archivedAt: lifecycle.archivedAt,
+          blockedBy: lifecycle.blockedBy,
+          supersededBy: lifecycle.supersededBy,
+        }),
+        true
+      );
+      assert.deepEqual(await surface.previewMemory("owner:test", source.id), { found: false });
+    }
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("memory preview preserves literal attribute-style text without structured attributes", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-preview-literal-"));
+  try {
+    const storage = new StorageManager(path.join(root, "owner"));
+    await storage.ensureDirectories();
+    const content = "Give me time to answer.\n[Attributes: this is part of my note]";
+    const source = await storage.writeMemory("preference", content, { source: "test" });
+    const surface = new SupportPassportAccessSurface({
+      config: parseConfig({ memoryDir: root, supportPassport: { enabled: true } }),
+      resolveOwner: async (principal) => ({ principal, namespace: "owner", storage }),
+      resolveNamespace: async () => storage,
+      modelAdapter: new SupportPassportModelAdapter({ routes: [] }),
+      audit: { record: async () => undefined },
+    });
+
+    const preview = await surface.previewMemory("owner:test", source.id);
+    assert.equal(preview.found, true);
+    if (!preview.found) throw new Error("source preview was not found");
+    assert.equal(preview.memory.content, content);
+    assert.equal(preview.memory.revision, computeSupportPassportSourceRevision(content));
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("memory preview validates the resolved owner before reading private text", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-preview-owner-"));
+  try {
+    const storage = new StorageManager(path.join(root, "other-owner"));
+    await storage.ensureDirectories();
+    const source = await storage.writeMemory("preference", "Private text for another owner.", { source: "test" });
+    let reads = 0;
+    const getMemoryById = storage.getMemoryById.bind(storage);
+    storage.getMemoryById = async (memoryId) => {
+      reads += 1;
+      return await getMemoryById(memoryId);
+    };
+    const surface = new SupportPassportAccessSurface({
+      config: parseConfig({ memoryDir: root, supportPassport: { enabled: true } }),
+      resolveOwner: async () => ({ principal: "owner:other", namespace: "other", storage }),
+      resolveNamespace: async () => storage,
+      modelAdapter: new SupportPassportModelAdapter({ routes: [] }),
+      audit: { record: async () => undefined },
+    });
+
+    await assert.rejects(
+      surface.previewMemory("owner:test", source.id),
+      (error: unknown) => error instanceof SupportPassportError && error.code === "card_data_invalid"
+    );
+    assert.equal(reads, 0);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("memory preview hides sources that exceed the draft model input limit", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-preview-limit-"));
+  try {
+    const storage = new StorageManager(path.join(root, "owner"));
+    await storage.ensureDirectories();
+    const source = await storage.writeMemory("preference", "x".repeat(20_001), { source: "test" });
+    const surface = new SupportPassportAccessSurface({
+      config: parseConfig({ memoryDir: root, supportPassport: { enabled: true } }),
+      resolveOwner: async (principal) => ({ principal, namespace: "owner", storage }),
+      resolveNamespace: async () => storage,
+      modelAdapter: new SupportPassportModelAdapter({ routes: [] }),
+      audit: { record: async () => undefined },
+    });
+
+    assert.deepEqual(await surface.previewMemory("owner:test", source.id), { found: false });
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("owner operations reject a missing trusted principal as forbidden", async () => {
+  const surface = new SupportPassportAccessSurface({
+    config: parseConfig({ supportPassport: { enabled: true } }),
+    resolveOwner: async () => {
+      throw new Error("owner resolution must not run");
+    },
+    resolveNamespace: async () => {
+      throw new Error("namespace resolution must not run");
+    },
+    modelAdapter: new SupportPassportModelAdapter({ routes: [] }),
+    audit: { record: async () => undefined },
+  });
+
+  await assert.rejects(
+    surface.listCards(" "),
+    (error: unknown) => error instanceof SupportPassportError && error.code === "forbidden" && error.status === 403
+  );
+});

package/src/support-passport/access-surface.ts

@@ -0,0 +1,286 @@
+import type { StorageManager } from "../index.js";
+import { stripAttributesSuffix } from "../structured-attributes.js";
+import type { PluginConfig } from "../types.js";
+import { SupportPassportCardService } from "./card-service.js";
+import { type SupportPassportOwnerScope, validateOwnerScope } from "./card-state.js";
+import type { SupportPassportCard, SupportPassportCardCategory } from "./contracts.js";
+import { SupportPassportError } from "./errors.js";
+import {
+  type SupportPassportCreateGrantRequest,
+  SupportPassportCreateGrantRequestSchema,
+  type SupportPassportOwnerGrant,
+  type SupportPassportPublicGuide,
+} from "./grant-contracts.js";
+import { SupportPassportGrantService } from "./grant-service.js";
+import { SupportPassportGrantStore } from "./grant-store.js";
+import { type SupportPassportModelAdapter, createSupportPassportModelAdapter } from "./model-adapter.js";
+import { type SupportPassportModelAuditSink, SupportPassportModelAuditStore } from "./model-audit.js";
+import { type SupportPassportAnswerOutput, SupportPassportDraftModelInputSchema } from "./model-contracts.js";
+import {
+  SupportPassportDraftService,
+  SupportPassportQuestionService,
+  computeSupportPassportSourceRevision,
+  isSupportPassportSourceEligible,
+} from "./model-service.js";
+import { supportsSupportPassportPrivateFiles } from "./private-file.js";
+
+export interface SupportPassportAccessSurfaceDependencies {
+  config: PluginConfig;
+  resolveOwner(principal: string): Promise<SupportPassportOwnerScope>;
+  resolveNamespace(namespace: string): Promise<StorageManager>;
+  modelAdapter?: SupportPassportModelAdapter;
+  audit?: SupportPassportModelAuditSink;
+  now?: () => Date;
+  platform?: NodeJS.Platform;
+}
+
+export interface SupportPassportCreateGrantResult {
+  grantId: string;
+  secret: string;
+  expiresAt: string;
+  version: number;
+}
+
+export interface SupportPassportRevokeGrantResult {
+  grantId: string;
+  revokedAt: string;
+  version: number;
+}
+
+export type SupportPassportMemoryPreview =
+  | { found: false }
+  | { found: true; memory: { id: string; content: string; revision: string } };
+
+export class SupportPassportAccessSurface {
+  private readonly config: PluginConfig;
+  private readonly cardService: SupportPassportCardService;
+  private readonly grantService: SupportPassportGrantService;
+  private readonly draftService: SupportPassportDraftService;
+  private readonly questionService: SupportPassportQuestionService;
+  private readonly resolveOwner: SupportPassportAccessSurfaceDependencies["resolveOwner"];
+  private readonly now: () => Date;
+  private readonly platformSupported: boolean;
+
+  constructor(dependencies: SupportPassportAccessSurfaceDependencies) {
+    this.config = dependencies.config;
+    this.resolveOwner = dependencies.resolveOwner;
+    this.now = dependencies.now ?? (() => new Date());
+    this.platformSupported = supportsSupportPassportPrivateFiles(dependencies.platform);
+    this.cardService = new SupportPassportCardService({
+      resolveOwner: dependencies.resolveOwner,
+      now: this.now,
+    });
+    this.grantService = new SupportPassportGrantService({
+      grantStore: new SupportPassportGrantStore({ memoryDir: dependencies.config.memoryDir, now: this.now }),
+      resolveOwner: dependencies.resolveOwner,
+      resolveNamespace: dependencies.resolveNamespace,
+      now: this.now,
+    });
+    const modelAdapter = dependencies.modelAdapter ?? createSupportPassportModelAdapter(dependencies.config);
+    const audit =
+      dependencies.audit ?? new SupportPassportModelAuditStore({ memoryDir: dependencies.config.memoryDir });
+    this.draftService = new SupportPassportDraftService({
+      cardService: this.cardService,
+      modelAdapter,
+      resolveOwner: dependencies.resolveOwner,
+      audit,
+      now: this.now,
+    });
+    this.questionService = new SupportPassportQuestionService({
+      grantService: this.grantService,
+      modelAdapter,
+      audit,
+      now: this.now,
+    });
+  }
+
+  async listCards(principal: string): Promise<SupportPassportCard[]> {
+    this.requireEnabled();
+    return this.cardService.listCards({ principal: this.requirePrincipal(principal) });
+  }
+
+  async previewMemory(principal: string, memoryId: string): Promise<SupportPassportMemoryPreview> {
+    this.requireEnabled();
+    const requestedPrincipal = this.requirePrincipal(principal);
+    const owner = validateOwnerScope(await this.resolveOwner(requestedPrincipal), requestedPrincipal);
+    const memory = await owner.storage.getMemoryById(memoryId);
+    if (!memory || !isSupportPassportSourceEligible(memory)) return { found: false };
+    const structuredAttributes = memory.frontmatter.structuredAttributes;
+    const content = structuredAttributes ? stripAttributesSuffix(memory.content) : memory.content;
+    if (
+      !SupportPassportDraftModelInputSchema.safeParse({
+        consent: true,
+        memories: [{ memoryId: memory.frontmatter.id, content }],
+      }).success
+    ) {
+      return { found: false };
+    }
+    return {
+      found: true,
+      memory: {
+        id: memory.frontmatter.id,
+        content,
+        revision: computeSupportPassportSourceRevision(memory.content, structuredAttributes),
+      },
+    };
+  }
+
+  async createManualDraft(
+    principal: string,
+    input: { title: string; statement: string; category: SupportPassportCardCategory; reviewBy: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    this.requireEnabled();
+    return this.cardService.createManualDraft({ principal: this.requirePrincipal(principal), ...input }, options);
+  }
+
+  async generateDrafts(
+    principal: string,
+    input: {
+      sourceMemoryIds: string[];
+      sourceMemoryRevisions: Array<{ memoryId: string; revision: string }>;
+      consent: boolean;
+      signal?: AbortSignal;
+      onCommitted?: () => void;
+    }
+  ): Promise<SupportPassportCard[]> {
+    this.requireEnabled();
+    return this.draftService.draftCards({
+      principal: this.requirePrincipal(principal),
+      sourceMemoryIds: input.sourceMemoryIds,
+      sourceMemoryRevisions: input.sourceMemoryRevisions,
+      consent: input.consent,
+      signal: input.signal,
+      ...(input.onCommitted ? { onCommitted: input.onCommitted } : {}),
+    });
+  }
+
+  async replaceCard(
+    principal: string,
+    cardId: string,
+    input: {
+      title: string;
+      statement: string;
+      category: SupportPassportCardCategory;
+      reviewBy: string;
+      expectedRevision: string;
+    },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    this.requireEnabled();
+    return this.cardService.replaceCard({ principal: this.requirePrincipal(principal), cardId, ...input }, options);
+  }
+
+  async approveCard(
+    principal: string,
+    cardId: string,
+    input: { expectedRevision: string; reasonCode?: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    this.requireEnabled();
+    return this.cardService.approveCard({ principal: this.requirePrincipal(principal), cardId, ...input }, options);
+  }
+
+  async rejectCard(
+    principal: string,
+    cardId: string,
+    input: { expectedRevision: string; reasonCode?: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    this.requireEnabled();
+    return this.cardService.rejectCard({ principal: this.requirePrincipal(principal), cardId, ...input }, options);
+  }
+
+  async withdrawCard(
+    principal: string,
+    cardId: string,
+    input: { expectedRevision: string; reasonCode?: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    this.requireEnabled();
+    return this.cardService.withdrawCard({ principal: this.requirePrincipal(principal), cardId, ...input }, options);
+  }
+
+  async createGrant(
+    principal: string,
+    input: SupportPassportCreateGrantRequest,
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCreateGrantResult> {
+    this.requireEnabled();
+    const parsed = SupportPassportCreateGrantRequestSchema.safeParse(input);
+    if (!parsed.success) throw this.invalidGrantInput();
+    const created = await this.grantService.createGrant(
+      {
+        principal: this.requirePrincipal(principal),
+        cards: parsed.data.cardRevisions,
+        ...(parsed.data.expiresAt !== undefined
+          ? { expiresAt: parsed.data.expiresAt }
+          : { durationMs: parsed.data.durationMs }),
+      },
+      options
+    );
+    return {
+      grantId: created.grant.grantId,
+      secret: created.secret,
+      expiresAt: created.grant.expiresAt,
+      version: created.grant.stateVersion,
+    };
+  }
+
+  async listGrants(principal: string): Promise<SupportPassportOwnerGrant[]> {
+    this.requireEnabled();
+    return this.grantService.listGrants({ principal: this.requirePrincipal(principal) });
+  }
+
+  async revokeGrant(
+    principal: string,
+    grantId: string,
+    input: { expectedVersion?: number },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportRevokeGrantResult> {
+    this.requireEnabled();
+    const grant = await this.grantService.revokeGrant(
+      {
+        principal: this.requirePrincipal(principal),
+        grantId,
+        expectedStateVersion: input.expectedVersion,
+      },
+      options
+    );
+    if (!grant.revokedAt) {
+      throw new SupportPassportError("storage_conflict", "The share link could not be stopped.", 500);
+    }
+    return { grantId: grant.grantId, revokedAt: grant.revokedAt, version: grant.stateVersion };
+  }
+
+  async readGrant(grantId: string, secret: string): Promise<SupportPassportPublicGuide> {
+    this.requireEnabled(true);
+    return this.grantService.readGrant({ grantId, secret });
+  }
+
+  async askGrant(
+    grantId: string,
+    secret: string,
+    question: string,
+    signal?: AbortSignal
+  ): Promise<SupportPassportAnswerOutput> {
+    this.requireEnabled(true);
+    return this.questionService.askGrant({ grantId, secret, question, signal });
+  }
+
+  private requireEnabled(publicRequest = false): void {
+    if (this.config.supportPassport.enabled && this.platformSupported) return;
+    if (publicRequest) throw new SupportPassportError("grant_not_found", "The share link was not found.", 404);
+    throw new SupportPassportError("feature_disabled", "Support passport is disabled.", 404);
+  }
+
+  private requirePrincipal(principal: string): string {
+    const normalized = principal?.trim();
+    if (!normalized) throw new SupportPassportError("forbidden", "An authenticated owner is required.", 403);
+    return normalized;
+  }
+
+  private invalidGrantInput(): SupportPassportError {
+    return new SupportPassportError("invalid_input", "The share link request is invalid.", 400);
+  }
+}

package/src/support-passport/card-projection.test.ts

@@ -86,6 +86,14 @@ test("card projection rejects duplicate normalized source IDs", () => {
   assert.equal(projectSupportPassportCard(makeMemory({ sourceMemoryIds: "source-1, source-1 " })), null);
 });
 
+test("card projection reads opaque source IDs from core lineage", () => {
+  const memory = makeMemory();
+  memory.frontmatter.lineage = ["Imported memory / café, 1"];
+  delete memory.frontmatter.structuredAttributes?.["support-passport-source-ids"];
+
+  assert.deepEqual(projectSupportPassportCard(memory)?.sourceMemoryIds, ["Imported memory / café, 1"]);
+});
+
 test("card projection rejects superseded status without relying on supersededBy", () => {
   assert.equal(projectSupportPassportCard(makeMemory({ status: "superseded" })), null);
 });