@remnic/core 9.54.4 → 9.54.6

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

@@ -0,0 +1,156 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  SupportPassportCardListSchema,
+  SupportPassportCardSchema,
+  SupportPassportManualDraftInputSchema,
+  SupportPassportNamespaceSchema,
+  SupportPassportReplaceCardInputSchema,
+  SupportPassportSourceMemoryIdSchema,
+  computeSupportPassportCardRevision,
+} from "./contracts.js";
+
+function makeCard(cardId: string) {
+  const fields = {
+    cardId,
+    title: "Quiet space",
+    statement: "Offer me a quiet place and time.",
+    category: "environment" as const,
+    status: "active" as const,
+    updatedAt: "2026-08-11T12:00:00.000Z",
+    reviewBy: "2027-02-07T12:00:00.000Z",
+  };
+  return { ...fields, revision: computeSupportPassportCardRevision(fields) };
+}
+
+test("the public support card contract rejects unknown fields", () => {
+  assert.equal(SupportPassportCardSchema.safeParse({ ...makeCard("card-1"), note: "private" }).success, false);
+});
+
+test("the support card list contract rejects duplicate card IDs", () => {
+  const card = makeCard("card-1");
+  assert.equal(SupportPassportCardListSchema.safeParse([card, card]).success, false);
+});
+
+test("manual and replacement drafts require the owner's review date", () => {
+  const draft = {
+    principal: "owner:alice",
+    title: "Quiet space",
+    statement: "Offer me a quiet place and time.",
+    category: "environment",
+  };
+  assert.equal(SupportPassportManualDraftInputSchema.safeParse(draft).success, false);
+  assert.equal(
+    SupportPassportReplaceCardInputSchema.safeParse({
+      ...draft,
+      cardId: "card-1",
+      expectedRevision: "a".repeat(64),
+    }).success,
+    false
+  );
+});
+
+test("support card dates reject invalid calendar values and timezone offsets", () => {
+  for (const reviewBy of ["2027-02-31T12:00:00Z", "2027-01-01T00:00:00+25:00"]) {
+    const draft = {
+      principal: "owner:alice",
+      title: "Quiet space",
+      statement: "Offer me a quiet place and time.",
+      category: "environment",
+      reviewBy,
+    };
+    assert.equal(SupportPassportManualDraftInputSchema.safeParse(draft).success, false);
+    assert.equal(
+      SupportPassportReplaceCardInputSchema.safeParse({
+        ...draft,
+        cardId: "card-1",
+        expectedRevision: "a".repeat(64),
+      }).success,
+      false
+    );
+    assert.equal(SupportPassportCardSchema.safeParse({ ...makeCard("card-1"), reviewBy }).success, false);
+  }
+});
+
+test("support card titles reject attribute delimiters and line breaks", () => {
+  for (const title of ["Quiet ] space", "Quiet\nspace", "Quiet\rspace"]) {
+    const manualDraft = {
+      principal: "owner:alice",
+      title,
+      statement: "Offer me a quiet place and time.",
+      category: "environment",
+      reviewBy: "2027-02-07T12:00:00.000Z",
+    };
+    assert.equal(SupportPassportManualDraftInputSchema.safeParse(manualDraft).success, false);
+    assert.equal(
+      SupportPassportReplaceCardInputSchema.safeParse({
+        ...manualDraft,
+        cardId: "card-1",
+        expectedRevision: "a".repeat(64),
+      }).success,
+      false
+    );
+    assert.equal(SupportPassportCardSchema.safeParse({ ...makeCard("card-1"), title }).success, false);
+  }
+});
+
+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 [
+    "team.alpha-1",
+    "team support:primary",
+    "tenant/default",
+    "alice\\bob",
+    "alice]bob",
+    "alice..bob",
+    "alice\nbob",
+    "alice\0bob",
+    "n".repeat(4096),
+  ]) {
+    assert.equal(SupportPassportNamespaceSchema.safeParse(namespace).success, true);
+  }
+});
+
+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({
+    cardId: initial.cardId,
+    title: initial.title,
+    statement: "Offer me a quiet room and time.",
+    category: initial.category,
+    status: initial.status,
+    updatedAt: initial.updatedAt,
+    reviewBy: initial.reviewBy,
+  });
+  assert.notEqual(changed, initial.revision);
+});
+
+test("support card revisions ignore object key insertion order", () => {
+  const initial = makeCard("card-1");
+  const reordered = {
+    reviewBy: initial.reviewBy,
+    updatedAt: initial.updatedAt,
+    status: initial.status,
+    category: initial.category,
+    statement: initial.statement,
+    title: initial.title,
+    cardId: initial.cardId,
+  };
+
+  assert.equal(computeSupportPassportCardRevision(reordered), initial.revision);
+});

package/src/support-passport/contracts.ts

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+import { normalizeNamespaceIdentity } from "../namespaces/identity.js";
+import { parseIsoOffsetTimestamp } from "../utils/iso-timestamp.js";
+
+export const SUPPORT_PASSPORT_CARD_CATEGORIES = [
+  "communication",
+  "environment",
+  "transitions",
+  "sensory",
+  "regulation",
+  "interests",
+  "other",
+] as const;
+
+export const SUPPORT_PASSPORT_CARD_STATUSES = [
+  "pending_review",
+  "active",
+  "rejected",
+  "superseded",
+  "archived",
+] as const;
+
+export const SupportPassportCardCategorySchema = z.enum(SUPPORT_PASSPORT_CARD_CATEGORIES);
+export const SupportPassportCardStatusSchema = z.enum(SUPPORT_PASSPORT_CARD_STATUSES);
+export const SupportPassportCardTitleSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(80)
+  .refine((title) => !title.includes("]") && !title.includes("\n") && !title.includes("\r"), {
+    message: "card titles cannot contain closing brackets or line breaks",
+  });
+
+const IsoTimestampSchema = z
+  .string()
+  .datetime({ offset: true })
+  .refine((value) => parseIsoOffsetTimestamp(value) !== null, {
+    message: "timestamps must be valid ISO 8601 values",
+  });
+export const SupportPassportNamespaceSchema = z
+  .string()
+  .min(1)
+  .refine((namespace) => namespace === normalizeNamespaceIdentity(namespace), {
+    message: "namespaces must be canonical",
+  });
+export const SupportPassportMemoryIdSchema = z
+  .string()
+  .trim()
+  .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({
+    cardId: SupportPassportMemoryIdSchema,
+    title: SupportPassportCardTitleSchema,
+    statement: z.string().trim().min(1).max(500),
+    category: SupportPassportCardCategorySchema,
+    status: SupportPassportCardStatusSchema,
+    updatedAt: IsoTimestampSchema,
+    reviewBy: IsoTimestampSchema,
+    revision: z.string().regex(/^[a-f0-9]{64}$/),
+  })
+  .strict();
+
+export const SupportPassportCardListSchema = z
+  .array(SupportPassportCardSchema)
+  .max(100)
+  .superRefine((cards, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, card] of cards.entries()) {
+      if (seen.has(card.cardId)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "card IDs must be unique",
+          path: [index, "cardId"],
+        });
+      }
+      seen.add(card.cardId);
+    }
+  });
+
+export const SupportPassportListCardsInputSchema = z
+  .object({
+    principal: z.string().trim().min(1).max(512),
+  })
+  .strict();
+
+export const SupportPassportManualDraftInputSchema = z
+  .object({
+    principal: z.string().trim().min(1).max(512),
+    title: SupportPassportCardTitleSchema,
+    statement: z.string().trim().min(1).max(500),
+    category: SupportPassportCardCategorySchema,
+    reviewBy: IsoTimestampSchema,
+  })
+  .strict();
+
+export const SupportPassportCardMutationInputSchema = z
+  .object({
+    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();
+
+export const SupportPassportReplaceCardInputSchema = SupportPassportCardMutationInputSchema.extend({
+  title: SupportPassportCardTitleSchema,
+  statement: z.string().trim().min(1).max(500),
+  category: SupportPassportCardCategorySchema,
+  reviewBy: IsoTimestampSchema,
+}).strict();
+
+export type SupportPassportCard = z.infer<typeof SupportPassportCardSchema>;
+export type SupportPassportCardCategory = z.infer<typeof SupportPassportCardCategorySchema>;
+export type SupportPassportCardStatus = z.infer<typeof SupportPassportCardStatusSchema>;
+export type SupportPassportManualDraftInput = z.input<typeof SupportPassportManualDraftInputSchema>;
+export type SupportPassportCardMutationInput = z.input<typeof SupportPassportCardMutationInputSchema>;
+export type SupportPassportReplaceCardInput = z.input<typeof SupportPassportReplaceCardInputSchema>;
+
+type RevisionFields = Omit<SupportPassportCard, "revision">;
+
+export function computeSupportPassportCardRevision(fields: RevisionFields): string {
+  const canonicalFields = {
+    cardId: fields.cardId,
+    category: fields.category,
+    reviewBy: fields.reviewBy,
+    statement: fields.statement,
+    status: fields.status,
+    title: fields.title,
+    updatedAt: fields.updatedAt,
+  };
+  return createHash("sha256").update(JSON.stringify(canonicalFields)).digest("hex");
+}

package/src/support-passport/errors.ts

@@ -0,0 +1,30 @@
+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";
+
+export class SupportPassportError extends Error {
+  readonly code: SupportPassportErrorCode;
+  readonly status: number;
+
+  constructor(code: SupportPassportErrorCode, message: string, status: number) {
+    super(message);
+    this.name = "SupportPassportError";
+    this.code = code;
+    this.status = status;
+  }
+}