@remnic/core 9.54.5 → 9.54.7

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

@@ -0,0 +1,272 @@
+import { z } from "zod";
+
+import { defineOperation } from "../access-boundary.js";
+import {
+  SupportPassportCardCategorySchema,
+  SupportPassportMemoryIdSchema,
+  SupportPassportSourceMemoryIdSchema,
+} from "./contracts.js";
+import { SupportPassportCreateGrantRequestSchema } from "./grant-contracts.js";
+
+const IsoTimestampSchema = z.string().datetime({ offset: true });
+const RevisionSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const ReasonCodeSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9-]+$/);
+const GrantIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_-]+$/);
+const EmptySchema = z.object({}).strict();
+
+const ManualDraftSchema = z
+  .object({
+    title: z.string().trim().min(1).max(80),
+    statement: z.string().trim().min(1).max(500),
+    category: SupportPassportCardCategorySchema,
+    reviewBy: IsoTimestampSchema,
+  })
+  .strict();
+
+const GenerateDraftsSchema = z
+  .object({
+    sourceMemoryIds: z.array(SupportPassportSourceMemoryIdSchema).min(1).max(20),
+    sourceMemoryRevisions: z
+      .array(z.object({ memoryId: SupportPassportSourceMemoryIdSchema, revision: RevisionSchema }).strict())
+      .min(1)
+      .max(20),
+    consent: z.literal(true),
+  })
+  .strict()
+  .superRefine((input, ctx) => {
+    if (new Set(input.sourceMemoryIds).size !== input.sourceMemoryIds.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "source memory IDs must be unique",
+        path: ["sourceMemoryIds"],
+      });
+    }
+    const revisionIds = input.sourceMemoryRevisions.map((source) => source.memoryId);
+    if (
+      new Set(revisionIds).size !== revisionIds.length ||
+      revisionIds.length !== input.sourceMemoryIds.length ||
+      input.sourceMemoryIds.some((memoryId) => !revisionIds.includes(memoryId))
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "source memory revisions must match the selected memory IDs",
+        path: ["sourceMemoryRevisions"],
+      });
+    }
+  });
+
+const ReplaceCardSchema = ManualDraftSchema.extend({
+  cardId: SupportPassportMemoryIdSchema,
+  expectedRevision: RevisionSchema,
+}).strict();
+
+const CardMutationSchema = z
+  .object({
+    cardId: SupportPassportMemoryIdSchema,
+    expectedRevision: RevisionSchema,
+    reasonCode: ReasonCodeSchema,
+  })
+  .strict();
+
+const RevokeGrantSchema = z
+  .object({
+    grantId: GrantIdSchema,
+    expectedVersion: z.number().int().positive(),
+  })
+  .strict();
+
+const PublicGrantSchema = z
+  .object({
+    grantId: GrantIdSchema,
+    secret: z.string().regex(/^[A-Za-z0-9_-]{32,256}$/),
+  })
+  .strict();
+
+const AskGrantSchema = PublicGrantSchema.extend({
+  question: z.string().trim().min(1).max(500),
+}).strict();
+
+function principal(value: string | undefined): string {
+  return value ?? "";
+}
+
+export const supportPassportMemoryPreviewOperation = defineOperation({
+  name: "support_passport_memory_preview",
+  description: "Preview one owner memory and bind it to a support-card consent revision.",
+  schema: z.object({ memoryId: SupportPassportSourceMemoryIdSchema }).strict(),
+  handler: async (input, ctx) => ({
+    result: await ctx.service.supportPassportPreviewMemory(principal(ctx.authenticatedPrincipal), input.memoryId),
+  }),
+});
+
+export const supportPassportCardsListOperation = defineOperation({
+  name: "support_passport_cards_list",
+  description: "List the authenticated owner's support cards.",
+  schema: EmptySchema,
+  handler: async (_input, ctx) => ({
+    result: { cards: await ctx.service.supportPassportListCards(principal(ctx.authenticatedPrincipal)) },
+  }),
+});
+
+export const supportPassportDraftCreateOperation = defineOperation({
+  name: "support_passport_draft_create",
+  description: "Create one support card draft for the authenticated owner.",
+  schema: ManualDraftSchema,
+  handler: async (input, ctx) => ({
+    result: {
+      card: await ctx.service.supportPassportCreateManualDraft(
+        principal(ctx.authenticatedPrincipal),
+        input,
+        {
+          ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}),
+          ...(ctx.hooks?.recordWriteCommit ? { onCommitted: ctx.hooks.recordWriteCommit } : {}),
+        }
+      ),
+    },
+  }),
+});
+
+export const supportPassportDraftsGenerateOperation = defineOperation({
+  name: "support_passport_drafts_generate",
+  description: "Draft support cards from selected owner memories after explicit consent.",
+  schema: GenerateDraftsSchema,
+  handler: async (input, ctx) => ({
+    result: {
+      cards: await ctx.service.supportPassportGenerateDrafts(principal(ctx.authenticatedPrincipal), {
+        ...input,
+        signal: ctx.abortSignal,
+        ...(ctx.hooks?.recordWriteCommit ? { onCommitted: ctx.hooks.recordWriteCommit } : {}),
+      }),
+    },
+  }),
+});
+
+export const supportPassportCardReplaceOperation = defineOperation({
+  name: "support_passport_card_replace",
+  description: "Replace one support card with a new owner-reviewed draft.",
+  schema: ReplaceCardSchema,
+  handler: async ({ cardId, ...input }, ctx) => ({
+    result: {
+      card: await ctx.service.supportPassportReplaceCard(
+        principal(ctx.authenticatedPrincipal),
+        cardId,
+        input,
+        {
+          ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}),
+          ...(ctx.hooks?.recordWriteCommit ? { onCommitted: ctx.hooks.recordWriteCommit } : {}),
+        }
+      ),
+    },
+  }),
+});
+
+function defineCardMutation(
+  name: "support_passport_card_approve" | "support_passport_card_reject" | "support_passport_card_withdraw",
+  description: string,
+  run: "supportPassportApproveCard" | "supportPassportRejectCard" | "supportPassportWithdrawCard"
+) {
+  return defineOperation({
+    name,
+    description,
+    schema: CardMutationSchema,
+    handler: async ({ cardId, ...input }, ctx) => ({
+      result: {
+        card: await ctx.service[run](
+          principal(ctx.authenticatedPrincipal),
+          cardId,
+          input,
+          {
+            ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}),
+            ...(ctx.hooks?.recordWriteCommit ? { onCommitted: ctx.hooks.recordWriteCommit } : {}),
+          }
+        ),
+      },
+    }),
+  });
+}
+
+export const supportPassportCardApproveOperation = defineCardMutation(
+  "support_passport_card_approve",
+  "Approve one pending support card as its authenticated owner.",
+  "supportPassportApproveCard"
+);
+export const supportPassportCardRejectOperation = defineCardMutation(
+  "support_passport_card_reject",
+  "Reject one pending support card as its authenticated owner.",
+  "supportPassportRejectCard"
+);
+export const supportPassportCardWithdrawOperation = defineCardMutation(
+  "support_passport_card_withdraw",
+  "Withdraw one approved support card as its authenticated owner.",
+  "supportPassportWithdrawCard"
+);
+
+export const supportPassportGrantCreateOperation = defineOperation({
+  name: "support_passport_grant_create",
+  description: "Create one timed share link for exact approved support card versions.",
+  schema: SupportPassportCreateGrantRequestSchema,
+  handler: async (input, ctx) => ({
+    result: await ctx.service.supportPassportCreateGrant(
+      principal(ctx.authenticatedPrincipal),
+      input,
+      {
+        ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}),
+        ...(ctx.hooks?.recordWriteCommit ? { onCommitted: ctx.hooks.recordWriteCommit } : {}),
+      }
+    ),
+  }),
+});
+
+export const supportPassportGrantsListOperation = defineOperation({
+  name: "support_passport_grants_list",
+  description: "List the authenticated owner's support passport share links without secrets.",
+  schema: EmptySchema,
+  handler: async (_input, ctx) => ({
+    result: { grants: await ctx.service.supportPassportListGrants(principal(ctx.authenticatedPrincipal)) },
+  }),
+});
+
+export const supportPassportGrantRevokeOperation = defineOperation({
+  name: "support_passport_grant_revoke",
+  description: "Stop one support passport share link as its authenticated owner.",
+  schema: RevokeGrantSchema,
+  handler: async ({ grantId, ...input }, ctx) => ({
+    result: await ctx.service.supportPassportRevokeGrant(
+      principal(ctx.authenticatedPrincipal),
+      grantId,
+      input,
+      {
+        ...(ctx.abortSignal ? { signal: ctx.abortSignal } : {}),
+        ...(ctx.hooks?.recordWriteCommit ? { onCommitted: ctx.hooks.recordWriteCommit } : {}),
+      }
+    ),
+  }),
+});
+
+export const supportPassportGrantReadOperation = defineOperation({
+  name: "support_passport_grant_read",
+  description: "Read one active support passport share link.",
+  schema: PublicGrantSchema,
+  handler: async ({ grantId, secret }, ctx) => ({
+    result: await ctx.service.supportPassportReadGrant(grantId, secret),
+  }),
+});
+
+export const supportPassportGrantAskOperation = defineOperation({
+  name: "support_passport_grant_ask",
+  description: "Answer one helper question from an active support passport share link.",
+  schema: AskGrantSchema,
+  handler: async ({ grantId, secret, question }, ctx) => ({
+    result: await ctx.service.supportPassportAskGrant(grantId, secret, question, ctx.abortSignal),
+  }),
+});

package/src/support-passport/access-service-base.test.ts

@@ -0,0 +1,193 @@
+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 { EngramAccessForbiddenError } from "../access-errors.js";
+import { tokenCapabilityStore } from "../access-token-capabilities.js";
+import { parseConfig } from "../config.js";
+import { StorageManager } from "../storage.js";
+import { SupportPassportAccessServiceBase } from "./access-service-base.js";
+import type { SupportPassportModelRoute } from "./model-adapter.js";
+
+test("support passport stays disabled when a partial host config omits its settings", async () => {
+  class TestService extends SupportPassportAccessServiceBase {
+    readonly configRef = {} as ReturnType<typeof parseConfig>;
+    readonly localLlmRef = null;
+
+    async getWritableStorageForNamespace(): Promise<never> {
+      throw new Error("not used");
+    }
+
+    async getStorageForResolvedNamespace(): Promise<never> {
+      throw new Error("not used");
+    }
+  }
+
+  const service = new TestService();
+  assert.equal(service.supportPassportEnabled, false);
+  await assert.rejects(service.supportPassportListCards("owner:alice"), /Support passport is disabled/);
+  await assert.rejects(service.supportPassportReadGrant("grant", "secret"), /share link was not found/);
+});
+
+test("support passport stays unavailable when private file pinning is unsupported", async () => {
+  class TestService extends SupportPassportAccessServiceBase {
+    readonly configRef = parseConfig({ supportPassport: { enabled: true } });
+    readonly localLlmRef = null;
+
+    override get supportPassportPlatformRef(): NodeJS.Platform {
+      return "win32";
+    }
+
+    async getWritableStorageForNamespace(): Promise<never> {
+      throw new Error("owner resolution must not run");
+    }
+
+    async getStorageForResolvedNamespace(): Promise<never> {
+      throw new Error("namespace resolution must not run");
+    }
+  }
+
+  const service = new TestService();
+  assert.equal(service.supportPassportEnabled, false);
+  await assert.rejects(service.supportPassportListCards("owner:alice"), /Support passport is disabled/);
+  await assert.rejects(service.supportPassportReadGrant("grant", "secret"), /share link was not found/);
+});
+
+test("support passport owner operations enforce the presenting token namespace", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-scope-"));
+  try {
+    const storage = new StorageManager(path.join(root, "owner"));
+    await storage.ensureDirectories();
+    class TestService extends SupportPassportAccessServiceBase {
+      readonly configRef = parseConfig({
+        memoryDir: root,
+        defaultNamespace: "default",
+        supportPassport: { enabled: true },
+      });
+      readonly localLlmRef = null;
+
+      async getWritableStorageForNamespace(_namespace?: string, principal?: string) {
+        return { principal: principal ?? "system", namespace: "owner", storage };
+      }
+
+      async getStorageForResolvedNamespace() {
+        return storage;
+      }
+    }
+    const service = new TestService();
+
+    await assert.rejects(
+      tokenCapabilityStore.run({ version: 1, namespaces: ["other"] }, () =>
+        service.supportPassportListCards("owner:alice")
+      ),
+      EngramAccessForbiddenError
+    );
+    assert.deepEqual(
+      await tokenCapabilityStore.run({ version: 1, namespaces: ["owner"] }, () =>
+        service.supportPassportListCards("owner:alice")
+      ),
+      []
+    );
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  }
+});
+
+test("support passport preserves every configured default namespace identity", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-default-namespace-"));
+  try {
+    const storage = new StorageManager(path.join(root, "owner"));
+    await storage.ensureDirectories();
+    class TestService extends SupportPassportAccessServiceBase {
+      readonly configRef = parseConfig({
+        memoryDir: root,
+        defaultNamespace: "team../support\\care]primary",
+        supportPassport: { enabled: true },
+      });
+      readonly localLlmRef = null;
+
+      async getWritableStorageForNamespace(_namespace?: string, principal?: string) {
+        return {
+          principal: principal ?? "system",
+          namespace: this.configRef.defaultNamespace,
+          storage,
+        };
+      }
+
+      async getStorageForResolvedNamespace() {
+        return storage;
+      }
+    }
+
+    assert.deepEqual(await new TestService().supportPassportListCards("owner:alice"), []);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  }
+});
+
+test("support passport access uses a host-injected gateway route without a direct API key", async () => {
+  StorageManager.clearAllStaticCaches();
+  const root = await mkdtemp(path.join(tmpdir(), "remnic-support-gateway-"));
+  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 route: SupportPassportModelRoute = {
+      kind: "gateway",
+      invoke: async () => ({
+        modelUsed: "gateway/local-model",
+        content: JSON.stringify({
+          cards: [
+            {
+              title: "Plan changes",
+              statement: "Tell me before plans change.",
+              category: "transitions",
+              sourceMemoryIds: [source.id],
+            },
+          ],
+        }),
+      }),
+    };
+    class TestService extends SupportPassportAccessServiceBase {
+      readonly configRef = parseConfig({
+        memoryDir: root,
+        modelSource: "gateway",
+        openaiApiKey: false,
+        supportPassport: { enabled: true },
+      });
+      readonly localLlmRef = null;
+      override get supportPassportGatewayRouteRef() {
+        return route;
+      }
+
+      async getWritableStorageForNamespace(_namespace?: string, principal?: string) {
+        return { principal: principal ?? "system", namespace: "owner", storage };
+      }
+
+      async getStorageForResolvedNamespace() {
+        return storage;
+      }
+    }
+    const service = new TestService();
+    const preview = await service.supportPassportPreviewMemory("owner:alice", source.id);
+    assert.equal(preview.found, true);
+    if (!preview.found) throw new Error("source preview was not found");
+
+    const cards = await service.supportPassportGenerateDrafts("owner:alice", {
+      sourceMemoryIds: [source.id],
+      sourceMemoryRevisions: [{ memoryId: source.id, revision: preview.memory.revision }],
+      consent: true,
+    });
+
+    assert.equal(cards[0]?.title, "Plan changes");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  }
+});

package/src/support-passport/access-service-base.ts

@@ -0,0 +1,176 @@
+import { enforceNamespaceAllowList, tokenCapabilityStore } from "../access-token-capabilities.js";
+import type { StorageManager } from "../index.js";
+import type { LocalLlmClient } from "../local-llm.js";
+import type { PluginConfig } from "../types.js";
+import {
+  SupportPassportAccessSurface,
+  type SupportPassportCreateGrantResult,
+  type SupportPassportMemoryPreview,
+  type SupportPassportRevokeGrantResult,
+} from "./access-surface.js";
+import type { SupportPassportOwnerScope } from "./card-state.js";
+import type { SupportPassportCard, SupportPassportCardCategory } from "./contracts.js";
+import { SupportPassportError } from "./errors.js";
+import type {
+  SupportPassportCreateGrantRequest,
+  SupportPassportOwnerGrant,
+  SupportPassportPublicGuide,
+} from "./grant-contracts.js";
+import { type SupportPassportModelRoute, createSupportPassportModelAdapter } from "./model-adapter.js";
+import type { SupportPassportAnswerOutput } from "./model-contracts.js";
+import { supportsSupportPassportPrivateFiles } from "./private-file.js";
+
+export abstract class SupportPassportAccessServiceBase {
+  private _supportPassportSurface: SupportPassportAccessSurface | undefined;
+
+  abstract get configRef(): PluginConfig;
+  abstract get localLlmRef(): LocalLlmClient | null;
+  abstract getWritableStorageForNamespace(namespace?: string, principal?: string): Promise<SupportPassportOwnerScope>;
+  abstract getStorageForResolvedNamespace(namespace: string): Promise<StorageManager>;
+
+  get supportPassportGatewayRouteRef(): SupportPassportModelRoute | null {
+    return null;
+  }
+
+  get supportPassportPlatformRef(): NodeJS.Platform {
+    return process.platform;
+  }
+
+  private getSupportPassportSurface(publicRequest = false): SupportPassportAccessSurface {
+    if (!this.supportPassportEnabled) {
+      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);
+    }
+    if (!this._supportPassportSurface) {
+      this._supportPassportSurface = new SupportPassportAccessSurface({
+        config: this.configRef,
+        platform: this.supportPassportPlatformRef,
+        resolveOwner: async (principal) => {
+          const owner = await this.getWritableStorageForNamespace(undefined, principal);
+          enforceNamespaceAllowList(tokenCapabilityStore.getStore(), owner.namespace, this.configRef.defaultNamespace);
+          return owner;
+        },
+        resolveNamespace: (namespace) => this.getStorageForResolvedNamespace(namespace),
+        modelAdapter: createSupportPassportModelAdapter(this.configRef, {
+          localLlm: this.localLlmRef ?? undefined,
+          gatewayRoute: this.supportPassportGatewayRouteRef ?? undefined,
+        }),
+      });
+    }
+    return this._supportPassportSurface;
+  }
+
+  get supportPassportEnabled(): boolean {
+    return (
+      this.configRef.supportPassport?.enabled === true &&
+      supportsSupportPassportPrivateFiles(this.supportPassportPlatformRef)
+    );
+  }
+
+  async supportPassportListCards(principal: string): Promise<SupportPassportCard[]> {
+    return this.getSupportPassportSurface().listCards(principal);
+  }
+
+  async supportPassportPreviewMemory(principal: string, memoryId: string): Promise<SupportPassportMemoryPreview> {
+    return this.getSupportPassportSurface().previewMemory(principal, memoryId);
+  }
+
+  async supportPassportCreateManualDraft(
+    principal: string,
+    input: { title: string; statement: string; category: SupportPassportCardCategory; reviewBy: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    return this.getSupportPassportSurface().createManualDraft(principal, input, options);
+  }
+
+  async supportPassportGenerateDrafts(
+    principal: string,
+    input: {
+      sourceMemoryIds: string[];
+      sourceMemoryRevisions: Array<{ memoryId: string; revision: string }>;
+      consent: boolean;
+      signal?: AbortSignal;
+      onCommitted?: () => void;
+    }
+  ): Promise<SupportPassportCard[]> {
+    return this.getSupportPassportSurface().generateDrafts(principal, input);
+  }
+
+  async supportPassportReplaceCard(
+    principal: string,
+    cardId: string,
+    input: {
+      title: string;
+      statement: string;
+      category: SupportPassportCardCategory;
+      reviewBy: string;
+      expectedRevision: string;
+    },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    return this.getSupportPassportSurface().replaceCard(principal, cardId, input, options);
+  }
+
+  async supportPassportApproveCard(
+    principal: string,
+    cardId: string,
+    input: { expectedRevision: string; reasonCode?: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    return this.getSupportPassportSurface().approveCard(principal, cardId, input, options);
+  }
+
+  async supportPassportRejectCard(
+    principal: string,
+    cardId: string,
+    input: { expectedRevision: string; reasonCode?: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    return this.getSupportPassportSurface().rejectCard(principal, cardId, input, options);
+  }
+
+  async supportPassportWithdrawCard(
+    principal: string,
+    cardId: string,
+    input: { expectedRevision: string; reasonCode?: string },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCard> {
+    return this.getSupportPassportSurface().withdrawCard(principal, cardId, input, options);
+  }
+
+  async supportPassportCreateGrant(
+    principal: string,
+    input: SupportPassportCreateGrantRequest,
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportCreateGrantResult> {
+    return this.getSupportPassportSurface().createGrant(principal, input, options);
+  }
+
+  async supportPassportListGrants(principal: string): Promise<SupportPassportOwnerGrant[]> {
+    return this.getSupportPassportSurface().listGrants(principal);
+  }
+
+  async supportPassportRevokeGrant(
+    principal: string,
+    grantId: string,
+    input: { expectedVersion?: number },
+    options: { signal?: AbortSignal; onCommitted?: () => void } = {}
+  ): Promise<SupportPassportRevokeGrantResult> {
+    return this.getSupportPassportSurface().revokeGrant(principal, grantId, input, options);
+  }
+
+  async supportPassportReadGrant(grantId: string, secret: string): Promise<SupportPassportPublicGuide> {
+    return this.getSupportPassportSurface(true).readGrant(grantId, secret);
+  }
+
+  async supportPassportAskGrant(
+    grantId: string,
+    secret: string,
+    question: string,
+    signal?: AbortSignal
+  ): Promise<SupportPassportAnswerOutput> {
+    return this.getSupportPassportSurface(true).askGrant(grantId, secret, question, signal);
+  }
+}