@remnic/core 9.54.5 → 9.54.7

package/src/support-passport/card-state.ts

@@ -0,0 +1,158 @@
+import type { StorageManager } from "../index.js";
+import type { MemoryFile } from "../types.js";
+import {
+  SUPPORT_PASSPORT_ATTRIBUTE_KEYS,
+  type StoredSupportPassportCard,
+  activeSupportPassportReplacementPredecessorIds,
+  computeSupportPassportOwnerKey,
+  decodeSupportPassportNamespaceAttributes,
+  projectSupportPassportCard,
+} from "./card-projection.js";
+import { type SupportPassportCard, computeSupportPassportCardRevision } from "./contracts.js";
+import { SupportPassportListCardsInputSchema, SupportPassportNamespaceSchema } from "./contracts.js";
+import { SupportPassportError } from "./errors.js";
+
+export interface SupportPassportOwnerScope {
+  principal: string;
+  namespace: string;
+  storage: StorageManager;
+}
+
+export interface SupportPassportCardServiceDependencies {
+  resolveOwner(principal: string): Promise<SupportPassportOwnerScope>;
+  now?: () => Date;
+}
+
+export function invalidInput(): SupportPassportError {
+  return new SupportPassportError("invalid_input", "The support card request is invalid.", 400);
+}
+
+export function isStorageConflict(error: unknown): error is SupportPassportError {
+  return error instanceof SupportPassportError && error.code === "storage_conflict";
+}
+
+export function once(callback: (() => void) | undefined): () => void {
+  let called = false;
+  return () => {
+    if (called) return;
+    called = true;
+    callback?.();
+  };
+}
+
+export function validateOwnerScope(owner: SupportPassportOwnerScope, principal: string): SupportPassportOwnerScope {
+  const requestedPrincipal = SupportPassportListCardsInputSchema.safeParse({ principal });
+  const namespace = SupportPassportNamespaceSchema.safeParse(owner.namespace);
+  const ownerPrincipal = SupportPassportListCardsInputSchema.safeParse({ principal: owner.principal });
+  if (
+    !requestedPrincipal.success ||
+    !namespace.success ||
+    !ownerPrincipal.success ||
+    ownerPrincipal.data.principal !== requestedPrincipal.data.principal
+  ) {
+    throw new SupportPassportError("card_data_invalid", "The support passport owner scope is invalid.", 500);
+  }
+  return { ...owner, principal: ownerPrincipal.data.principal, namespace: namespace.data };
+}
+
+export const MAX_OWNER_VISIBLE_CARDS = 100;
+
+const OWNER_VISIBLE_STATUSES = new Set(["pending_review", "active"]);
+
+export function revisionFor(
+  card: SupportPassportCard,
+  status: SupportPassportCard["status"],
+  updatedAt: string
+): string {
+  return computeSupportPassportCardRevision({
+    cardId: card.cardId,
+    title: card.title,
+    statement: card.statement,
+    category: card.category,
+    status,
+    updatedAt,
+    reviewBy: card.reviewBy,
+  });
+}
+
+export function projectRequiredCard(
+  memory: MemoryFile,
+  namespace: string,
+  principal: string
+): StoredSupportPassportCard {
+  const card = projectSupportPassportCard(memory);
+  if (!card) throw new SupportPassportError("card_data_invalid", "The support card data is invalid.", 500);
+  if (card.namespace !== namespace || card.owner !== computeSupportPassportOwnerKey(principal)) {
+    throw new SupportPassportError("card_not_found", "The support card was not found.", 404);
+  }
+  return card;
+}
+
+export function projectOwnedCard(
+  memory: MemoryFile,
+  namespace: string,
+  principal: string
+): StoredSupportPassportCard | null {
+  const card = projectSupportPassportCard(memory);
+  return card?.namespace === namespace && card.owner === computeSupportPassportOwnerKey(principal) ? card : null;
+}
+
+export function ownsMemory(memory: MemoryFile, namespace: string, principal: string): boolean {
+  const attributes = memory.frontmatter.structuredAttributes;
+  return (
+    attributes !== undefined &&
+    decodeSupportPassportNamespaceAttributes(attributes) === namespace &&
+    attributes[SUPPORT_PASSPORT_ATTRIBUTE_KEYS.owner] === computeSupportPassportOwnerKey(principal)
+  );
+}
+
+export function requireRevision(card: StoredSupportPassportCard, expectedRevision: string): void {
+  if (card.card.revision !== expectedRevision) {
+    throw new SupportPassportError("revision_conflict", "The support card changed after it was loaded.", 409);
+  }
+}
+
+export function requireStatus(card: StoredSupportPassportCard, status: SupportPassportCard["status"]): void {
+  if (card.card.status !== status) {
+    throw new SupportPassportError("invalid_card_status", `The support card must have status ${status}.`, 409);
+  }
+}
+
+export function ownerVisibleCards(storedCards: StoredSupportPassportCard[]): StoredSupportPassportCard[] {
+  const visibleCards = storedCards.filter(
+    (item) => OWNER_VISIBLE_STATUSES.has(item.card.status) && !item.draftReplacementPrepared
+  );
+  if (visibleCards.length <= MAX_OWNER_VISIBLE_CARDS) return visibleCards;
+  const cardsWithPendingReplacements = new Set(
+    visibleCards
+      .filter((item) => item.card.status === "pending_review")
+      .map((item) => item.memory.frontmatter.supersedes)
+      .filter((cardId): cardId is string => typeof cardId === "string")
+  );
+  return visibleCards.filter(
+    (item) => item.card.status !== "active" || !cardsWithPendingReplacements.has(item.card.cardId)
+  );
+}
+
+export function ownerListCards(storedCards: StoredSupportPassportCard[]): StoredSupportPassportCard[] {
+  const visibleCards = ownerVisibleCards(storedCards);
+  const byId = new Map(storedCards.map((item) => [item.card.cardId, item]));
+  const activeReplacementPredecessors = activeSupportPassportReplacementPredecessorIds(visibleCards);
+  const replacedDraftIds = new Set(
+    visibleCards
+      .filter(
+        (item) =>
+          item.card.status === "pending_review" &&
+          item.replacesDraftId !== undefined &&
+          byId.get(item.replacesDraftId)?.card.status === "pending_review"
+      )
+      .map((item) => item.replacesDraftId as string)
+  );
+  return visibleCards.filter((item) => {
+    if (activeReplacementPredecessors.has(item.card.cardId)) return false;
+    if (replacedDraftIds.has(item.card.cardId)) return false;
+    if (!item.replacesDraftId) return true;
+    const replacedStatus = byId.get(item.replacesDraftId)?.card.status;
+    return replacedStatus === "pending_review" || replacedStatus === "rejected";
+  });
+}

package/src/support-passport/config-model-routing.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "../config.js";
+
+function withOpenaiBaseUrl(value: string, run: () => void): void {
+  const original = process.env.OPENAI_BASE_URL;
+  process.env.OPENAI_BASE_URL = value;
+  try {
+    run();
+  } finally {
+    if (original === undefined) delete process.env.OPENAI_BASE_URL;
+    else process.env.OPENAI_BASE_URL = original;
+  }
+}
+
+test("disabled direct models ignore an ambient OpenAI endpoint", () => {
+  withOpenaiBaseUrl("not-an-absolute-url", () => {
+    const config = parseConfig({
+      openaiApiKey: false,
+      localLlmEnabled: true,
+    });
+
+    assert.equal(config.openaiApiKey, undefined);
+    assert.equal(config.openaiBaseUrl, undefined);
+    assert.equal(config.localLlmEnabled, true);
+  });
+});
+
+test("direct models still validate an ambient OpenAI endpoint", () => {
+  withOpenaiBaseUrl("not-an-absolute-url", () => {
+    assert.throws(
+      () => parseConfig({ openaiApiKey: "fixture-key" }),
+      /OPENAI_BASE_URL must be an absolute HTTP or HTTPS URL/,
+    );
+  });
+});

package/src/support-passport/config.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseConfig } from "../config.js";
+
+test("support passport config defaults off and accepts an explicit opt-in", () => {
+  assert.deepEqual(parseConfig({}).supportPassport, { enabled: false, trustedProxyAddresses: [] });
+  assert.deepEqual(parseConfig({ supportPassport: { enabled: true } }).supportPassport, {
+    enabled: true,
+    trustedProxyAddresses: [],
+  });
+  assert.deepEqual(
+    parseConfig({
+      supportPassport: { enabled: "true", trustedProxyAddresses: ["127.0.0.1", "::1"] },
+    }).supportPassport,
+    { enabled: true, trustedProxyAddresses: ["127.0.0.1", "::1"] }
+  );
+  for (const enabled of ["false", "0", "no", "off"]) {
+    assert.deepEqual(parseConfig({ supportPassport: { enabled } }).supportPassport, {
+      enabled: false,
+      trustedProxyAddresses: [],
+    });
+  }
+});
+
+test("support passport config rejects malformed and unknown fields", () => {
+  assert.throws(() => parseConfig({ supportPassport: true }), /supportPassport/);
+  assert.throws(() => parseConfig({ supportPassport: { enabled: "maybe" } }), /supportPassport/);
+  assert.throws(
+    () => parseConfig({ supportPassport: { trustedProxyAddresses: ["not-an-address"] } }),
+    /supportPassport/
+  );
+  assert.throws(() => parseConfig({ supportPassport: { enabled: true, extra: true } }), /supportPassport/);
+});

package/src/support-passport/config.ts

@@ -0,0 +1,41 @@
+import { isIP } from "node:net";
+
+import { z } from "zod";
+
+import { coerceBool } from "../connectors/coerce.js";
+import type { SupportPassportConfig } from "../types.js";
+
+export const DEFAULT_SUPPORT_PASSPORT_CONFIG: SupportPassportConfig = {
+  enabled: false,
+  trustedProxyAddresses: [],
+};
+
+export function parseSupportPassportConfig(raw: unknown): SupportPassportConfig {
+  if (raw === undefined) {
+    return {
+      ...DEFAULT_SUPPORT_PASSPORT_CONFIG,
+      trustedProxyAddresses: [...DEFAULT_SUPPORT_PASSPORT_CONFIG.trustedProxyAddresses],
+    };
+  }
+  const schema = z
+    .object({
+      enabled: z
+        .preprocess((value) => {
+          if (value === undefined) return false;
+          return coerceBool(value) ?? value;
+        }, z.boolean())
+        .default(false),
+      trustedProxyAddresses: z
+        .array(z.string().trim().refine((value) => isIP(value) !== 0, "must contain IP addresses"))
+        .max(32)
+        .default([]),
+    })
+    .strict();
+  const parsed = schema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(
+      "supportPassport must contain only enabled and up to 32 trustedProxyAddresses IP addresses"
+    );
+  }
+  return parsed.data;
+}

package/src/support-passport/contracts.test.ts

@@ -7,6 +7,7 @@ import {
   SupportPassportManualDraftInputSchema,
   SupportPassportNamespaceSchema,
   SupportPassportReplaceCardInputSchema,
+  SupportPassportSourceMemoryIdSchema,
   computeSupportPassportCardRevision,
 } from "./contracts.js";
 
@@ -94,8 +95,11 @@ test("support card titles reject attribute delimiters and line breaks", () => {
   }
 });
 
-test("support passport namespaces use the shared canonical identity grammar", () => {
-  for (const namespace of ["", " alice", "alice "]) {
+test("support passport namespaces preserve configured default identities", () => {
+  for (const namespace of ["alice/bob", "alice\\bob", "alice]bob", "alice..bob", "alice\nbob", "alice\0bob"]) {
+    assert.equal(SupportPassportNamespaceSchema.safeParse(namespace).success, true);
+  }
+  for (const namespace of ["", " team", "team "]) {
     assert.equal(SupportPassportNamespaceSchema.safeParse(namespace).success, false);
   }
   for (const namespace of [
@@ -113,6 +117,15 @@ test("support passport namespaces use the shared canonical identity grammar", ()
   }
 });
 
+test("source memory IDs use the core opaque ID contract", () => {
+  for (const memoryId of ["Imported memory / café 1", "team,care]note", "記憶 1"]) {
+    assert.equal(SupportPassportSourceMemoryIdSchema.safeParse(memoryId).success, true);
+  }
+  assert.equal(SupportPassportSourceMemoryIdSchema.safeParse(" ").success, false);
+  assert.equal(SupportPassportSourceMemoryIdSchema.safeParse("m".repeat(513)).success, false);
+  assert.equal(SupportPassportCardSchema.safeParse({ ...makeCard("card/one"), cardId: "card/one" }).success, false);
+});
+
 test("support card revisions change when any public field changes", () => {
   const initial = makeCard("card-1");
   const changed = computeSupportPassportCardRevision({

package/src/support-passport/contracts.ts

@@ -51,6 +51,12 @@ export const SupportPassportMemoryIdSchema = z
   .min(1)
   .max(128)
   .regex(/^[A-Za-z0-9._:-]+$/);
+export const SUPPORT_PASSPORT_SOURCE_MEMORY_ID_MAX_LENGTH = 512;
+export const SupportPassportSourceMemoryIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(SUPPORT_PASSPORT_SOURCE_MEMORY_ID_MAX_LENGTH);
 
 export const SupportPassportCardSchema = z
   .object({
@@ -103,6 +109,13 @@ export const SupportPassportCardMutationInputSchema = z
     principal: z.string().trim().min(1).max(512),
     cardId: SupportPassportMemoryIdSchema,
     expectedRevision: z.string().regex(/^[a-f0-9]{64}$/),
+    reasonCode: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64)
+      .regex(/^[a-z0-9-]+$/)
+      .optional(),
   })
   .strict();
 

package/src/support-passport/errors.ts

@@ -1,12 +1,18 @@
 export type SupportPassportErrorCode =
   | "card_data_invalid"
   | "card_not_found"
+  | "consent_required"
+  | "feature_disabled"
+  | "forbidden"
   | "grant_expired"
   | "grant_gone"
   | "grant_not_found"
   | "grant_stale"
   | "invalid_card_status"
   | "invalid_input"
+  | "model_output_invalid"
+  | "provider_unavailable"
+  | "rate_limited"
   | "revision_conflict"
   | "state_conflict"
   | "storage_conflict";

package/src/support-passport/generated-batch.test.ts

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+
+import { StorageManager } from "../storage.js";
+import type { StoredSupportPassportCard } from "./card-projection.js";
+import { computeSupportPassportOwnerKey } from "./card-projection.js";
+import { SupportPassportCardService } from "./card-service.js";
+import { SupportPassportError } from "./errors.js";
+import {
+  commitSupportPassportGeneratedBatch,
+  persistSupportPassportGeneratedBatchMarker,
+  rollbackSupportPassportGeneratedBatch,
+} from "./generated-batch.js";
+
+test("generated batch setup hardens an existing writable directory", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-passport-batch-mode-"));
+  const storage = new StorageManager(path.join(root, "shared"));
+  await storage.ensureDirectories();
+  const batchRoot = path.join(storage.dir, "state", "support-passport", "generated-batches");
+  await mkdir(batchRoot, { recursive: true, mode: 0o777 });
+  await chmod(batchRoot, 0o777);
+
+  try {
+    await persistSupportPassportGeneratedBatchMarker(
+      {
+        storage,
+        principal: "owner:alice",
+        namespace: "team",
+        now: () => new Date("2026-08-13T12:00:00.000Z"),
+        requireOwnerLock: async () => undefined,
+      },
+      "00000000-0000-4000-8000-000000000000",
+      1
+    );
+
+    assert.equal((await stat(batchRoot)).mode & 0o777, 0o700);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a visible generated batch marker reconciles its durability error as success", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-passport-batch-durability-"));
+  const storage = new StorageManager(path.join(root, "shared"));
+  await storage.ensureDirectories();
+  const principal = "owner:alice";
+  const namespace = "team";
+  const context = {
+    storage,
+    principal,
+    namespace,
+    now: () => new Date("2026-08-13T12:00:00.000Z"),
+    requireOwnerLock: async () => undefined,
+  };
+  const batchId = "00000000-0000-4000-8000-000000000001";
+
+  try {
+    const marker = await persistSupportPassportGeneratedBatchMarker(context, batchId, 1);
+    const markerPath = path.join(storage.dir, "state", "support-passport", "generated-batches", `${batchId}.json`);
+    const card = {
+      namespace,
+      owner: computeSupportPassportOwnerKey(principal),
+      generatedBatchId: batchId,
+      generatedBatchSize: 1,
+      card: { cardId: "00000000-0000-4000-8000-000000000002", status: "pending_review" },
+    } as StoredSupportPassportCard;
+    const durabilityError = Object.assign(new Error("simulated directory sync failure"), { code: "EIO" });
+
+    await commitSupportPassportGeneratedBatch(context, marker, [card], async (_storage, committed) => {
+        await writeFile(markerPath, `${JSON.stringify(committed)}\n`, "utf8");
+        throw durabilityError;
+      });
+    assert.equal((JSON.parse(await readFile(markerPath, "utf8")) as { complete: boolean }).complete, true);
+    assert.equal(await rollbackSupportPassportGeneratedBatch(context, batchId, [card.card.cardId]), false);
+    assert.equal((JSON.parse(await readFile(markerPath, "utf8")) as { complete: boolean }).complete, true);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("generated batch recovery reads only markers referenced by the requested owner", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-passport-batches-"));
+  const storage = new StorageManager(path.join(root, "shared"));
+  await storage.ensureDirectories();
+  const service = new SupportPassportCardService({
+    resolveOwner: async (principal) => ({ principal, namespace: "team", storage }),
+  });
+
+  try {
+    const cards = new Map<string, Awaited<ReturnType<typeof service.createGeneratedDrafts>>>();
+    for (const principal of ["owner:alice", "owner:bob"]) {
+      cards.set(
+        principal,
+        await service.createGeneratedDrafts({
+          principal,
+          cards: [
+            {
+              title: `${principal} support`,
+              statement: "Give me time to answer.",
+              category: "communication",
+              sourceMemoryIds: ["source-1"],
+            },
+          ],
+        })
+      );
+    }
+
+    const markerRoot = path.join(storage.dir, "state", "support-passport", "generated-batches");
+    const [bobCard] = cards.get("owner:bob") ?? [];
+    assert.ok(bobCard);
+    const bobMemory = await storage.getMemoryById(bobCard.cardId);
+    const bobBatchId = bobMemory?.frontmatter.structuredAttributes?.["support-passport-generated-batch-id"];
+    assert.ok(bobBatchId);
+    const bobMarkerPath = path.join(markerRoot, `${bobBatchId}.json`);
+    await writeFile(bobMarkerPath, "not-json\n", "utf8");
+
+    assert.equal((await service.listCards({ principal: "owner:alice" })).length, 1);
+    await assert.rejects(
+      service.listCards({ principal: "owner:bob" }),
+      (error: unknown) => error instanceof SupportPassportError && error.code === "card_data_invalid"
+    );
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a missing marker hides an approved generated card without blocking manual cards", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-passport-missing-batch-"));
+  const storage = new StorageManager(path.join(root, "shared"));
+  await storage.ensureDirectories();
+  const principal = "owner:alice";
+  const service = new SupportPassportCardService({
+    resolveOwner: async () => ({ principal, namespace: "team", storage }),
+  });
+
+  try {
+    const manual = await service.createManualDraft({
+      principal,
+      title: "Manual support",
+      statement: "Give me time to answer.",
+      category: "communication",
+      reviewBy: "2026-09-01T00:00:00.000Z",
+    });
+    const [generated] = await service.createGeneratedDrafts({
+      principal,
+      cards: [
+        {
+          title: "Generated support",
+          statement: "Tell me before plans change.",
+          category: "transitions",
+          sourceMemoryIds: ["source-1"],
+        },
+      ],
+    });
+    assert.ok(generated);
+    await service.approveCard({
+      principal,
+      cardId: generated.cardId,
+      expectedRevision: generated.revision,
+    });
+
+    const memory = await storage.getMemoryById(generated.cardId);
+    const batchId = memory?.frontmatter.structuredAttributes?.["support-passport-generated-batch-id"];
+    assert.equal(typeof batchId, "string");
+    await rm(path.join(storage.dir, "state", "support-passport", "generated-batches", `${batchId}.json`));
+
+    assert.deepEqual(
+      (await service.listCards({ principal })).map((card) => card.cardId),
+      [manual.cardId],
+    );
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true });
+  }
+});