@remnic/core 9.54.4 → 9.54.6

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 });
+  }
+});

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

@@ -0,0 +1,338 @@
+import path from "node:path";
+
+import { z } from "zod";
+
+import type { StorageManager } from "../index.js";
+import type { MemoryFile } from "../types.js";
+import {
+  type StoredSupportPassportCard,
+  computeSupportPassportOwnerKey,
+  projectSupportPassportCard,
+} from "./card-projection.js";
+import { SupportPassportNamespaceSchema } from "./contracts.js";
+import { SupportPassportError } from "./errors.js";
+import {
+  ensurePrivateDirectoryNoFollow,
+  ensurePrivateDirectoryTreeNoFollow,
+  readPrivateFileNoFollow,
+  removePrivateFilesNoFollow,
+  writePrivateFileAtomicallyNoFollow,
+} from "./private-file.js";
+
+const BatchIdSchema = z
+  .string()
+  .uuid()
+  .transform((value) => value.toLowerCase());
+const GeneratedBatchMarkerSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    batchId: BatchIdSchema,
+    size: z.number().int().min(1).max(8),
+    namespace: SupportPassportNamespaceSchema,
+    owner: z.string().regex(/^[a-f0-9]{64}$/),
+    complete: z.boolean(),
+  })
+  .strict();
+
+export type GeneratedBatchMarker = z.infer<typeof GeneratedBatchMarkerSchema>;
+
+export interface GeneratedBatchContext {
+  storage: StorageManager;
+  principal: string;
+  namespace: string;
+  now: () => Date;
+  requireOwnerLock: () => Promise<void>;
+  onCommitted?: () => void;
+}
+
+type GeneratedBatchMarkerWriter = (storage: StorageManager, marker: GeneratedBatchMarker) => Promise<void>;
+
+const BATCH_ERROR = "The generated draft batch state is not safe.";
+
+function batchDirectory(storage: StorageManager): string {
+  return path.join(storage.dir, "state", "support-passport", "generated-batches");
+}
+
+function batchFileName(batchId: string): string {
+  return `${BatchIdSchema.parse(batchId)}.json`;
+}
+
+function batchPath(storage: StorageManager, batchId: string): string {
+  return path.join(batchDirectory(storage), batchFileName(batchId));
+}
+
+function markerFor(context: GeneratedBatchContext, batchId: string, size: number, complete: boolean) {
+  return GeneratedBatchMarkerSchema.parse({
+    schemaVersion: 1,
+    batchId,
+    size,
+    namespace: context.namespace,
+    owner: computeSupportPassportOwnerKey(context.principal),
+    complete,
+  });
+}
+
+function sameOwner(marker: GeneratedBatchMarker, context: GeneratedBatchContext): boolean {
+  return marker.namespace === context.namespace && marker.owner === computeSupportPassportOwnerKey(context.principal);
+}
+
+async function ensureBatchDirectory(storage: StorageManager): Promise<void> {
+  const directory = batchDirectory(storage);
+  await ensurePrivateDirectoryTreeNoFollow(directory, BATCH_ERROR);
+  await ensurePrivateDirectoryNoFollow(storage.dir, directory, BATCH_ERROR);
+}
+
+export async function readSupportPassportGeneratedBatchMarker(
+  storage: StorageManager,
+  batchId: string
+): Promise<GeneratedBatchMarker | null> {
+  const directory = batchDirectory(storage);
+  try {
+    const content = await readPrivateFileNoFollow(directory, batchPath(storage, batchId), BATCH_ERROR, storage.dir);
+    let value: unknown;
+    try {
+      value = JSON.parse(content);
+    } catch {
+      throw new SupportPassportError("card_data_invalid", "The generated draft batch state is invalid.", 500);
+    }
+    const parsed = GeneratedBatchMarkerSchema.safeParse(value);
+    if (!parsed.success || parsed.data.batchId !== BatchIdSchema.parse(batchId)) {
+      throw new SupportPassportError("card_data_invalid", "The generated draft batch state is invalid.", 500);
+    }
+    return parsed.data;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function isSupportPassportGeneratedBatchCommitted(
+  context: GeneratedBatchContext,
+  marker: GeneratedBatchMarker
+): Promise<boolean> {
+  const current = await readSupportPassportGeneratedBatchMarker(context.storage, marker.batchId);
+  return Boolean(current?.complete && sameOwner(current, context) && current.size === marker.size);
+}
+
+async function writeBatchMarker(storage: StorageManager, marker: GeneratedBatchMarker): Promise<void> {
+  const directory = batchDirectory(storage);
+  await writePrivateFileAtomicallyNoFollow(
+    directory,
+    batchPath(storage, marker.batchId),
+    `${JSON.stringify(marker)}\n`,
+    BATCH_ERROR,
+    storage.dir
+  );
+}
+
+async function removeBatchMarker(storage: StorageManager, batchId: string): Promise<void> {
+  await removePrivateFilesNoFollow(batchDirectory(storage), [batchFileName(batchId)], BATCH_ERROR, storage.dir);
+}
+
+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 async function persistSupportPassportGeneratedBatchMarker(
+  context: GeneratedBatchContext,
+  batchId: string,
+  size: number,
+  writeMarker: GeneratedBatchMarkerWriter = writeBatchMarker
+): Promise<GeneratedBatchMarker> {
+  const marker = markerFor(context, batchId, size, false);
+  await context.requireOwnerLock();
+  await ensureBatchDirectory(context.storage);
+  await writeMarker(context.storage, marker);
+  context.onCommitted?.();
+  return marker;
+}
+
+export async function commitSupportPassportGeneratedBatch(
+  context: GeneratedBatchContext,
+  marker: GeneratedBatchMarker,
+  cards: readonly StoredSupportPassportCard[],
+  writeMarker: GeneratedBatchMarkerWriter = writeBatchMarker
+): Promise<void> {
+  const cardIds = cards.map((card) => card.card.cardId);
+  if (!sameOwner(marker, context) || cards.length !== marker.size || new Set(cardIds).size !== cards.length) {
+    throw new SupportPassportError("storage_conflict", "The generated draft batch is incomplete.", 409);
+  }
+  for (const card of cards) {
+    if (
+      card.namespace !== context.namespace ||
+      card.owner !== computeSupportPassportOwnerKey(context.principal) ||
+      card.card.status !== "pending_review" ||
+      card.generatedBatchId !== marker.batchId ||
+      card.generatedBatchSize !== marker.size
+    ) {
+      throw new SupportPassportError("storage_conflict", "The generated draft batch is incomplete.", 409);
+    }
+  }
+  await context.requireOwnerLock();
+  const committed = { ...marker, complete: true };
+  try {
+    await writeMarker(context.storage, committed);
+  } catch (error) {
+    if (!(await isSupportPassportGeneratedBatchCommitted(context, marker))) throw error;
+  }
+  context.onCommitted?.();
+}
+
+async function rejectGeneratedDraft(context: GeneratedBatchContext, cardId: string): Promise<boolean> {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const memory = await context.storage.getMemoryById(cardId);
+    if (!memory) return true;
+    const stored = projectOwnedCard(memory, context.namespace, context.principal);
+    if (!stored) return false;
+    if (stored.card.status === "rejected") return true;
+    if (stored.card.status !== "pending_review") return false;
+    await context.requireOwnerLock();
+    if (
+      await context.storage.writeMemoryFrontmatterIfUnchanged(
+        memory,
+        { status: "rejected", updated: context.now().toISOString() },
+        { actor: context.principal, reasonCode: "draft-batch-failed" }
+      )
+    ) {
+      context.onCommitted?.();
+      return true;
+    }
+  }
+  return false;
+}
+
+export async function rollbackSupportPassportGeneratedBatch(
+  context: GeneratedBatchContext,
+  batchId: string,
+  knownCardIds: readonly string[]
+): Promise<boolean> {
+  const marker = await readSupportPassportGeneratedBatchMarker(context.storage, batchId);
+  if (marker && !sameOwner(marker, context)) return false;
+  if (marker?.complete) return false;
+  const cardIds = new Set(knownCardIds);
+  let scanComplete = true;
+  try {
+    for (const memory of await context.storage.readAllMemories()) {
+      const card = projectOwnedCard(memory, context.namespace, context.principal);
+      if (card?.generatedBatchId === batchId) cardIds.add(card.card.cardId);
+    }
+  } catch {
+    scanComplete = false;
+  }
+  let complete = scanComplete;
+  for (const cardId of cardIds) {
+    try {
+      if (!(await rejectGeneratedDraft(context, cardId))) complete = false;
+    } catch {
+      complete = false;
+    }
+  }
+  if (!complete) return false;
+  try {
+    await removeBatchMarker(context.storage, batchId);
+    context.onCommitted?.();
+  } catch {
+    complete = false;
+  }
+  return complete;
+}
+
+export async function isCommittedGeneratedCard(
+  storage: StorageManager,
+  card: StoredSupportPassportCard,
+  markerCache?: Map<string, GeneratedBatchMarker | null>
+): Promise<boolean> {
+  if (!card.generatedBatchId) return true;
+  let marker = markerCache?.get(card.generatedBatchId);
+  if (!markerCache?.has(card.generatedBatchId)) {
+    marker = await readSupportPassportGeneratedBatchMarker(storage, card.generatedBatchId);
+    markerCache?.set(card.generatedBatchId, marker);
+  }
+  return Boolean(
+    marker?.complete &&
+      marker.size === card.generatedBatchSize &&
+      marker.namespace === card.namespace &&
+      marker.owner === card.owner
+  );
+}
+
+export async function projectCommittedSupportPassportCards(
+  storage: StorageManager,
+  memories: readonly MemoryFile[],
+  namespace: string,
+  principal: string
+): Promise<StoredSupportPassportCard[]> {
+  const projected = memories
+    .map(projectSupportPassportCard)
+    .filter(
+      (card): card is StoredSupportPassportCard =>
+        card?.namespace === namespace && card.owner === computeSupportPassportOwnerKey(principal)
+    );
+  const markers = new Map<string, GeneratedBatchMarker | null>();
+  const committed: StoredSupportPassportCard[] = [];
+  for (const card of projected) {
+    if (await isCommittedGeneratedCard(storage, card, markers)) committed.push(card);
+  }
+  const ids = new Set<string>();
+  for (const card of committed) {
+    if (ids.has(card.card.cardId)) {
+      throw new SupportPassportError("card_data_invalid", "Support card IDs must be unique.", 500);
+    }
+    ids.add(card.card.cardId);
+  }
+  return committed;
+}
+
+export async function readCommittedSupportPassportCards(
+  storage: StorageManager,
+  namespace: string,
+  principal: string
+): Promise<StoredSupportPassportCard[]> {
+  return await projectCommittedSupportPassportCards(
+    storage,
+    await storage.readAllMemories(),
+    namespace,
+    principal
+  );
+}
+
+export async function recoverSupportPassportGeneratedBatches(
+  context: GeneratedBatchContext,
+  memories: readonly MemoryFile[]
+): Promise<void> {
+  const cardsByBatch = new Map<string, StoredSupportPassportCard[]>();
+  for (const memory of memories) {
+    const card = projectOwnedCard(memory, context.namespace, context.principal);
+    if (!card?.generatedBatchId) continue;
+    const cards = cardsByBatch.get(card.generatedBatchId) ?? [];
+    cards.push(card);
+    cardsByBatch.set(card.generatedBatchId, cards);
+  }
+  for (const [batchId, cards] of cardsByBatch) {
+    const marker = await readSupportPassportGeneratedBatchMarker(context.storage, batchId);
+    if (marker?.complete === true && sameOwner(marker, context)) continue;
+    if (!marker) {
+      let recovered = true;
+      for (const card of cards) {
+        if (card.card.status !== "pending_review") continue;
+        try {
+          if (!(await rejectGeneratedDraft(context, card.card.cardId))) recovered = false;
+        } catch {
+          recovered = false;
+        }
+      }
+      if (recovered) continue;
+      throw new SupportPassportError("storage_conflict", "An incomplete generated draft batch could not recover.", 500);
+    }
+    if (
+      !(await rollbackSupportPassportGeneratedBatch(
+        context,
+        batchId,
+        cards.map((card) => card.card.cardId)
+      ))
+    ) {
+      throw new SupportPassportError("storage_conflict", "An incomplete generated draft batch could not recover.", 500);
+    }
+  }
+}

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

@@ -0,0 +1,183 @@
+import { z } from "zod";
+
+import { parseIsoOffsetTimestamp } from "../utils/iso-timestamp.js";
+import {
+  SupportPassportCardCategorySchema,
+  SupportPassportMemoryIdSchema,
+  SupportPassportNamespaceSchema,
+} from "./contracts.js";
+
+const IsoTimestampSchema = z
+  .string()
+  .datetime({ offset: true })
+  .refine((value) => parseIsoOffsetTimestamp(value) !== null, "timestamp must be a real date");
+const RevisionSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const GrantIdSchema = z
+  .string()
+  .uuid()
+  .transform((value) => value.toLowerCase());
+
+export const SupportPassportGrantCardRefSchema = z
+  .object({
+    cardId: SupportPassportMemoryIdSchema,
+    revision: RevisionSchema,
+  })
+  .strict();
+
+export const SupportPassportGrantStateSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    stateVersion: z.number().int().positive(),
+    grantId: GrantIdSchema,
+    namespace: SupportPassportNamespaceSchema,
+    principalHash: RevisionSchema,
+    ownerLockKey: RevisionSchema,
+    secretHash: RevisionSchema,
+    cards: z.array(SupportPassportGrantCardRefSchema).min(1).max(8),
+    createdAt: IsoTimestampSchema,
+    expiresAt: IsoTimestampSchema,
+    revokedAt: IsoTimestampSchema.optional(),
+  })
+  .strict()
+  .superRefine((grant, ctx) => {
+    const ids = new Set<string>();
+    for (const [index, card] of grant.cards.entries()) {
+      if (ids.has(card.cardId)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "card IDs must be unique",
+          path: ["cards", index, "cardId"],
+        });
+      }
+      ids.add(card.cardId);
+    }
+    if (Date.parse(grant.expiresAt) <= Date.parse(grant.createdAt)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: "expiresAt must follow createdAt", path: ["expiresAt"] });
+    }
+  });
+
+export const SupportPassportCreateGrantInputSchema = z
+  .object({
+    principal: z.string().trim().min(1).max(512),
+    cards: z.array(SupportPassportGrantCardRefSchema).min(1).max(8),
+    expiresAt: IsoTimestampSchema.optional(),
+    durationMs: z.number().int().min(300_000).max(604_800_000).optional(),
+  })
+  .strict()
+  .superRefine((input, ctx) => {
+    const ids = new Set<string>();
+    for (const [index, card] of input.cards.entries()) {
+      if (ids.has(card.cardId)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "card IDs must be unique",
+          path: ["cards", index, "cardId"],
+        });
+      }
+      ids.add(card.cardId);
+    }
+    if ((input.expiresAt === undefined) === (input.durationMs === undefined)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "one expiry value is required",
+        path: ["expiresAt"],
+      });
+    }
+  });
+
+export const SupportPassportCreateGrantRequestSchema = z
+  .object({
+    cardIds: z.array(SupportPassportMemoryIdSchema).min(1).max(8),
+    cardRevisions: z.array(SupportPassportGrantCardRefSchema).min(1).max(8),
+    expiresAt: IsoTimestampSchema.optional(),
+    durationMs: z.number().int().min(300_000).max(604_800_000).optional(),
+  })
+  .strict()
+  .superRefine((input, ctx) => {
+    const cardIds = new Set(input.cardIds);
+    const revisionIds = new Set(input.cardRevisions.map((card) => card.cardId));
+    if (
+      cardIds.size !== input.cardIds.length ||
+      revisionIds.size !== input.cardRevisions.length ||
+      cardIds.size !== revisionIds.size ||
+      input.cardIds.some((cardId) => !revisionIds.has(cardId))
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "card revisions must match the selected card IDs",
+        path: ["cardRevisions"],
+      });
+    }
+    if ((input.expiresAt === undefined) === (input.durationMs === undefined)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "one expiry value is required",
+        path: ["expiresAt"],
+      });
+    }
+  });
+
+export const SupportPassportOwnerCreateGrantRequestSchema = SupportPassportCreateGrantRequestSchema;
+
+export const SupportPassportOwnerGrantSchema = z
+  .object({
+    grantId: GrantIdSchema,
+    stateVersion: z.number().int().positive(),
+    cards: z.array(SupportPassportGrantCardRefSchema).min(1).max(8),
+    createdAt: IsoTimestampSchema,
+    expiresAt: IsoTimestampSchema,
+    revokedAt: IsoTimestampSchema.optional(),
+    status: z.enum(["active", "expired", "revoked"]),
+  })
+  .strict();
+
+export const SupportPassportCreatedGrantSchema = z
+  .object({
+    grant: SupportPassportOwnerGrantSchema,
+    secret: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+  })
+  .strict();
+
+export const SupportPassportPublicCardSchema = z
+  .object({
+    cardId: SupportPassportMemoryIdSchema,
+    title: z.string().trim().min(1).max(80),
+    statement: z.string().trim().min(1).max(500),
+    category: SupportPassportCardCategorySchema,
+    updatedAt: IsoTimestampSchema,
+  })
+  .strict();
+
+export const SupportPassportPublicGuideSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    grantId: GrantIdSchema,
+    expiresAt: IsoTimestampSchema,
+    updatedAt: IsoTimestampSchema,
+    cards: z.array(SupportPassportPublicCardSchema).min(1).max(8),
+  })
+  .strict();
+
+export const SupportPassportRevokeGrantInputSchema = z
+  .object({
+    principal: z.string().trim().min(1).max(512),
+    grantId: GrantIdSchema,
+    expectedStateVersion: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export const SupportPassportListGrantsInputSchema = z
+  .object({
+    principal: z.string().trim().min(1).max(512),
+  })
+  .strict();
+
+export type SupportPassportGrantCardRef = z.infer<typeof SupportPassportGrantCardRefSchema>;
+export type SupportPassportGrantState = z.infer<typeof SupportPassportGrantStateSchema>;
+export type SupportPassportCreateGrantInput = z.input<typeof SupportPassportCreateGrantInputSchema>;
+export type SupportPassportCreateGrantRequest = z.input<typeof SupportPassportCreateGrantRequestSchema>;
+export type SupportPassportOwnerCreateGrantRequest = z.input<typeof SupportPassportOwnerCreateGrantRequestSchema>;
+export type SupportPassportOwnerGrant = z.infer<typeof SupportPassportOwnerGrantSchema>;
+export type SupportPassportCreatedGrant = z.infer<typeof SupportPassportCreatedGrantSchema>;
+export type SupportPassportPublicGuide = z.infer<typeof SupportPassportPublicGuideSchema>;
+export type SupportPassportRevokeGrantInput = z.input<typeof SupportPassportRevokeGrantInputSchema>;