@forgezero/runtime 0.1.4 → 0.1.6

package/README.md

@@ -5,7 +5,7 @@ themselves, keyed queues, a transactional outbox, a hash-chained audit trail,
 templated mail, encrypted backups, schema validation, and money that is never a
 floating-point number.
 
-Thirty-three public modules. Each is its own entry point, so you install one package and
+Thirty-four public modules. Each is its own entry point, so you install one package and
 your bundler includes only what you imported.
 
 ```bash
@@ -24,7 +24,7 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 
 | | |
 |---|---|
-| **Spine** | `jobs` `queue` `outbox` |
+| **Spine** | `query` `jobs` `queue` `outbox` |
 | **Record** | `audit` `backup` `compliance` `calendar` |
 | **Identity** | `identity` `totp` `notify` `notify/templates` `schema` `schema/typebox` |
 | **Finance** | `finance/money` `finance/storage` `finance/ledger` `finance/commission` `finance/rates` `finance/transfers` `finance/tax` `finance/chain` `finance/custody` `finance/derive` `finance/venues` `finance/binance` |
@@ -32,6 +32,28 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 None of it knows what your product does. You bind your own rules to these; you
 do not fork them.
 
+## Typed function queries
+
+`query` binds typed input/output codecs to an ordinary function and any context
+you choose. It has no database or ForgeZero realm dependency. Inputs may decode
+wire values; outputs are checked strictly so a wrong handler result cannot be
+coerced into looking correct.
+
+```ts
+import { defineQuery, implementQuery } from '@forgezero/runtime/query';
+import { typeboxQueryCodec, T } from '@forgezero/runtime/schema/typebox';
+
+const contract = defineQuery({
+  name: 'invoice.by-reference',
+  input: typeboxQueryCodec(T.Object({ reference: T.String() })),
+  output: typeboxQueryCodec(T.Object({ total: T.String() }))
+});
+
+const findInvoice = implementQuery(contract, async (services: MyServices, input, { signal }) =>
+  services.invoices.find(input.reference, { signal })
+);
+```
+
 ## One reusable async queue
 
 `queue` is deliberately memory-only: it accepts a function, returns that

package/dist/backup.d.ts

@@ -32,11 +32,11 @@
  * refuse rather than doing their best.
  */
 export declare class BackupError extends Error {
-    readonly code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY';
-    constructor(code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY', message: string);
+    readonly code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'MAINTENANCE_REQUIRED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY';
+    constructor(code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'MAINTENANCE_REQUIRED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY', message: string);
 }
 /** Bumped only for a change that an older reader cannot handle. */
-export declare const SNAPSHOT_FORMAT = 1;
+export declare const SNAPSHOT_FORMAT = 2;
 export interface ChunkRecord {
     index: number;
     /** Object key in the store. */
@@ -55,7 +55,11 @@ export interface SnapshotManifest {
     collections: Record<string, number>;
     chunks: readonly ChunkRecord[];
     totalRows: number;
-    /** Digest over every chunk digest — one value that fixes the whole snapshot. */
+    /**
+     * HMAC-SHA-256 over the canonical manifest body. Despite the legacy field
+     * name this is a keyed authenticator, not a plain digest. Format 1 used an
+     * unkeyed digest and is deliberately not accepted by this reader.
+     */
     sealDigest: string;
     /** Free-form: schema version, application version, who triggered it. */
     labels?: Record<string, string>;
@@ -76,8 +80,14 @@ export interface ObjectStore {
 }
 /** Where the rows come from. Async-iterable so a large collection never lands in memory whole. */
 export interface RowSource {
+    /** Acquire a point-in-time source transaction or equivalent read fence. */
+    begin?(): Promise<void>;
     collections(): Promise<string[]>;
     rows(collection: string): AsyncIterable<Record<string, unknown>>;
+    /** Release the read fence after every row has been captured. */
+    commit?(): Promise<void>;
+    /** Release it after an interrupted or failed capture. */
+    abort?(): Promise<void>;
 }
 /** Where they go on the way back. */
 export interface RowSink {
@@ -90,7 +100,10 @@ export interface RowSink {
     write(collection: string, rows: Record<string, unknown>[]): Promise<void>;
     /** Called before anything is written. The sink's chance to refuse or truncate. */
     begin?(manifest: SnapshotManifest): Promise<void>;
+    /** Commit all staged rows atomically. */
     finish?(manifest: SnapshotManifest): Promise<void>;
+    /** Roll back all staged rows after any write or commit failure. */
+    abort?(manifest: SnapshotManifest): Promise<void>;
 }
 export interface SnapshotOptions {
     store: ObjectStore;
@@ -174,6 +187,7 @@ export declare function restore(options: RestoreOptions): Promise<RestoreReport>
 export declare function listSnapshots(args: {
     store: ObjectStore;
     realm: string;
+    masterSeed: Uint8Array;
     prefix?: string;
 }): Promise<SnapshotManifest[]>;
 export interface RetentionPolicy {
@@ -200,6 +214,7 @@ export declare function selectForDeletion(manifests: readonly SnapshotManifest[]
 export declare function prune(args: {
     store: ObjectStore;
     realm: string;
+    masterSeed: Uint8Array;
     policy?: RetentionPolicy;
     prefix?: string;
     /** Report what would go without removing it. */

package/dist/backup.js

@@ -7,7 +7,14 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/backup.ts
-import { hkdf, seal, open, sha256, timingSafeEqual } from "@forgezero/access/security";
+import {
+  hkdf,
+  hmacSha256,
+  seal,
+  open,
+  sha256,
+  timingSafeEqual
+} from "@forgezero/access/security";
 
 class BackupError extends Error {
   code;
@@ -17,15 +24,145 @@ class BackupError extends Error {
     this.name = "BackupError";
   }
 }
-var SNAPSHOT_FORMAT = 1;
+var SNAPSHOT_FORMAT = 2;
 var keyFor = (masterSeed, realm, snapshotId) => hkdf(masterSeed, `forgezero:backup:v1:${realm}:${snapshotId}`, 32);
+var manifestKeyFor = (masterSeed, realm, snapshotId) => hkdf(masterSeed, `forgezero:backup:manifest:v2:${realm}:${snapshotId}`, 32);
 var aadFor = (realm, snapshotId, index) => `backup:${realm}:${snapshotId}:${index}`;
 var objectKey = (prefix, realm, id, part) => `${prefix}${realm}/${id}/${part}`;
+function canonicalManifest(manifest) {
+  return JSON.stringify([
+    manifest.format,
+    manifest.id,
+    manifest.realm,
+    manifest.createdAtMs,
+    Object.entries(manifest.collections).sort(([left], [right]) => left.localeCompare(right)),
+    manifest.chunks.map((chunk) => [
+      chunk.index,
+      chunk.object,
+      chunk.digest,
+      chunk.rows,
+      chunk.bytes
+    ]),
+    manifest.totalRows,
+    manifest.labels ? Object.entries(manifest.labels).sort(([left], [right]) => left.localeCompare(right)) : null
+  ]);
+}
+async function sealManifest(manifest, masterSeed) {
+  const key = await manifestKeyFor(masterSeed, manifest.realm, manifest.id);
+  return hmacSha256(key, canonicalManifest(manifest));
+}
+var MANIFEST_KEYS = new Set([
+  "format",
+  "id",
+  "realm",
+  "createdAtMs",
+  "collections",
+  "chunks",
+  "totalRows",
+  "sealDigest",
+  "labels"
+]);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function manifestProblem(value) {
+  if (!isRecord(value))
+    return "The manifest is not an object.";
+  if (Object.keys(value).some((key) => !MANIFEST_KEYS.has(key)))
+    return "The manifest has unknown fields.";
+  if (value.format !== SNAPSHOT_FORMAT) {
+    return `Snapshot format ${String(value.format)} is not supported by this reader (${SNAPSHOT_FORMAT}).`;
+  }
+  if (typeof value.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value.id)) {
+    return "The snapshot id is invalid.";
+  }
+  if (typeof value.realm !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value.realm)) {
+    return "The snapshot realm is invalid.";
+  }
+  if (!Number.isSafeInteger(value.createdAtMs) || value.createdAtMs <= 0) {
+    return "The snapshot creation time is invalid.";
+  }
+  if (!isRecord(value.collections) || Object.keys(value.collections).length === 0) {
+    return "The manifest has no collection inventory.";
+  }
+  for (const [collection, count] of Object.entries(value.collections)) {
+    if (!/^[a-z][a-z0-9_]*$/.test(collection) || !Number.isSafeInteger(count) || count < 0) {
+      return `The collection inventory entry "${collection}" is invalid.`;
+    }
+  }
+  if (!Array.isArray(value.chunks) || value.chunks.length === 0)
+    return "The manifest has no chunks.";
+  if (!Number.isSafeInteger(value.totalRows) || value.totalRows <= 0) {
+    return "The manifest row total is invalid.";
+  }
+  if (typeof value.sealDigest !== "string" || !/^[a-f0-9]{64}$/.test(value.sealDigest)) {
+    return "The manifest authenticator is invalid.";
+  }
+  if (value.labels !== undefined) {
+    if (!isRecord(value.labels))
+      return "The manifest labels are invalid.";
+    for (const [label, content] of Object.entries(value.labels)) {
+      if (label.length === 0 || label.length > 128 || typeof content !== "string" || content.length > 1024) {
+        return `The manifest label "${label}" is invalid.`;
+      }
+    }
+  }
+  let chunkRows = 0;
+  let root;
+  for (const [position, candidate] of value.chunks.entries()) {
+    if (!isRecord(candidate))
+      return `Chunk ${position} is not an object.`;
+    const keys = Object.keys(candidate).sort().join(",");
+    if (keys !== "bytes,digest,index,object,rows")
+      return `Chunk ${position} has an invalid shape.`;
+    if (candidate.index !== position)
+      return `Chunk indexes are not contiguous at position ${position}.`;
+    if (typeof candidate.object !== "string" || candidate.object.length > 1024) {
+      return `Chunk ${position} has an invalid object key.`;
+    }
+    const filename = `chunk-${String(position).padStart(5, "0")}.json`;
+    const suffix = `${value.realm}/${value.id}/${filename}`;
+    if (!candidate.object.endsWith(suffix))
+      return `Chunk ${position} is outside the snapshot prefix.`;
+    const candidateRoot = candidate.object.slice(0, -filename.length);
+    root ??= candidateRoot;
+    if (candidateRoot !== root)
+      return `Chunk ${position} does not share the snapshot prefix.`;
+    if (typeof candidate.digest !== "string" || !/^[a-f0-9]{64}$/.test(candidate.digest)) {
+      return `Chunk ${position} has an invalid digest.`;
+    }
+    if (!Number.isSafeInteger(candidate.rows) || candidate.rows <= 0) {
+      return `Chunk ${position} has an invalid row count.`;
+    }
+    if (!Number.isSafeInteger(candidate.bytes) || candidate.bytes <= 0) {
+      return `Chunk ${position} has an invalid byte count.`;
+    }
+    chunkRows += candidate.rows;
+  }
+  if (chunkRows !== value.totalRows)
+    return "Chunk row counts do not equal the manifest total.";
+  const collectionRows = Object.values(value.collections).reduce((sum, count) => sum + count, 0);
+  if (collectionRows !== value.totalRows)
+    return "Collection row counts do not equal the manifest total.";
+  return null;
+}
 async function snapshot(options) {
   const now = options.now ?? Date.now;
   const chunkRows = options.chunkRows ?? 1000;
   const prefix = options.prefix ?? "snapshots/";
-  const id = options.id ?? `snap_${new Date(now()).toISOString().replace(/[-:.]/g, "").slice(0, 15)}`;
+  const nonce = crypto.getRandomValues(new Uint8Array(8));
+  const randomSuffix = Array.from(nonce, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  const id = options.id ?? `snap_${new Date(now()).toISOString().replace(/[-:.TZ]/g, "")}_${randomSuffix}`;
+  if (!Number.isSafeInteger(chunkRows) || chunkRows <= 0) {
+    throw new BackupError("BAD_MANIFEST", "chunkRows must be a positive safe integer.");
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(options.realm)) {
+    throw new BackupError("BAD_MANIFEST", "The snapshot realm is not safe for an object key.");
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(id)) {
+    throw new BackupError("BAD_MANIFEST", "The snapshot id is not safe for an object key.");
+  }
+  if (!prefix || prefix.includes("..") || prefix.startsWith("/") || !prefix.endsWith("/")) {
+    throw new BackupError("BAD_MANIFEST", "The snapshot prefix must be a relative object prefix ending in /.");
+  }
   const key = await keyFor(options.masterSeed, options.realm, id);
   const chunks = [];
   const collections = {};
@@ -47,26 +184,38 @@ async function snapshot(options) {
       bytes: body.length
     });
   };
-  for (const collection of await options.source.collections()) {
-    let batch = [];
-    let count = 0;
-    for await (const row of options.source.rows(collection)) {
-      batch.push(row);
-      count += 1;
-      if (batch.length >= chunkRows) {
-        await flush(collection, batch);
-        batch = [];
+  let sourceFinalized = false;
+  try {
+    await options.source.begin?.();
+    for (const collection of await options.source.collections()) {
+      let batch = [];
+      let count = 0;
+      for await (const row of options.source.rows(collection)) {
+        batch.push(row);
+        count += 1;
+        if (batch.length >= chunkRows) {
+          await flush(collection, batch);
+          batch = [];
+        }
       }
+      await flush(collection, batch);
+      collections[collection] = count;
+      totalRows += count;
+      options.onProgress?.({ collection, rows: count, chunks: chunks.length });
     }
-    await flush(collection, batch);
-    collections[collection] = count;
-    totalRows += count;
-    options.onProgress?.({ collection, rows: count, chunks: chunks.length });
+    await options.source.commit?.();
+    sourceFinalized = true;
+  } catch (cause) {
+    if (!sourceFinalized)
+      await options.source.abort?.().catch(() => {
+        return;
+      });
+    throw cause;
   }
   if (totalRows === 0) {
     throw new BackupError("EMPTY_SNAPSHOT", "The source produced no rows. Refusing to write an empty snapshot.");
   }
-  const manifest = {
+  const unsigned = {
     format: SNAPSHOT_FORMAT,
     id,
     realm: options.realm,
@@ -74,9 +223,12 @@ async function snapshot(options) {
     collections,
     chunks,
     totalRows,
-    sealDigest: await sha256(chunks.map((chunk) => chunk.digest).join("")),
     ...options.labels ? { labels: options.labels } : {}
   };
+  const manifest = {
+    ...unsigned,
+    sealDigest: await sealManifest(unsigned, options.masterSeed)
+  };
   await options.store.putObject({
     key: objectKey(prefix, options.realm, id, "manifest.json"),
     body: JSON.stringify(manifest, null, 2),
@@ -86,9 +238,9 @@ async function snapshot(options) {
 }
 async function verifySnapshot(args) {
   const problems = [];
-  const key = await keyFor(args.masterSeed, args.manifest.realm, args.manifest.id);
   let rowsChecked = 0;
-  if (args.manifest.format > SNAPSHOT_FORMAT) {
+  const invalid = manifestProblem(args.manifest);
+  if (invalid) {
     return {
       ok: false,
       id: args.manifest.id,
@@ -97,12 +249,25 @@ async function verifySnapshot(args) {
       problems: [
         {
           chunk: -1,
-          code: "UNSUPPORTED_FORMAT",
-          message: `Snapshot format ${args.manifest.format} is newer than this reader (${SNAPSHOT_FORMAT}).`
+          code: args.manifest.format !== SNAPSHOT_FORMAT ? "UNSUPPORTED_FORMAT" : "BAD_MANIFEST",
+          message: invalid
         }
       ]
     };
   }
+  const { sealDigest, ...unsigned } = args.manifest;
+  const expectedSeal = await sealManifest(unsigned, args.masterSeed);
+  if (!timingSafeEqual(expectedSeal, sealDigest)) {
+    return {
+      ok: false,
+      id: args.manifest.id,
+      chunksChecked: 0,
+      rowsChecked: 0,
+      problems: [{ chunk: -1, code: "BAD_MANIFEST", message: "The manifest did not authenticate." }]
+    };
+  }
+  const key = await keyFor(args.masterSeed, args.manifest.realm, args.manifest.id);
+  const collectionRows = {};
   for (const chunk of args.manifest.chunks) {
     let raw;
     try {
@@ -135,15 +300,34 @@ async function verifySnapshot(args) {
       });
       continue;
     }
-    rowsChecked += JSON.parse(plaintext).rows.length;
+    let parsed;
+    try {
+      parsed = JSON.parse(plaintext);
+    } catch {
+      problems.push({ chunk: chunk.index, code: "BAD_MANIFEST", message: `${chunk.object} is not JSON.` });
+      continue;
+    }
+    if (!isRecord(parsed) || typeof parsed.collection !== "string" || !Object.hasOwn(args.manifest.collections, parsed.collection) || !Array.isArray(parsed.rows) || parsed.rows.length !== chunk.rows || parsed.rows.some((row) => !isRecord(row))) {
+      problems.push({
+        chunk: chunk.index,
+        code: "BAD_MANIFEST",
+        message: `${chunk.object} does not match its declared collection and row count.`
+      });
+      continue;
+    }
+    collectionRows[parsed.collection] = (collectionRows[parsed.collection] ?? 0) + parsed.rows.length;
+    rowsChecked += parsed.rows.length;
   }
-  const sealDigest = await sha256(args.manifest.chunks.map((chunk) => chunk.digest).join(""));
-  if (!timingSafeEqual(sealDigest, args.manifest.sealDigest)) {
-    problems.push({
-      chunk: -1,
-      code: "BAD_MANIFEST",
-      message: "The manifest does not match its own seal — a chunk was added to or removed from the list."
-    });
+  if (problems.length === 0) {
+    for (const [collection, expectedRows] of Object.entries(args.manifest.collections)) {
+      if ((collectionRows[collection] ?? 0) === expectedRows)
+        continue;
+      problems.push({
+        chunk: -1,
+        code: "BAD_MANIFEST",
+        message: `Collection ${collection} restored ${collectionRows[collection] ?? 0} rows, expected ${expectedRows}.`
+      });
+    }
   }
   return {
     ok: problems.length === 0,
@@ -158,8 +342,8 @@ async function restore(options) {
   if (manifest.realm !== options.realm) {
     throw new BackupError("REALM_MISMATCH", `This snapshot belongs to realm "${manifest.realm}" and cannot be restored into "${options.realm}".`);
   }
-  if (manifest.format > SNAPSHOT_FORMAT) {
-    throw new BackupError("UNSUPPORTED_FORMAT", `Snapshot format ${manifest.format} is newer than this reader (${SNAPSHOT_FORMAT}). Restoring it would silently drop whatever the newer format added.`);
+  if (manifest.format !== SNAPSHOT_FORMAT) {
+    throw new BackupError("UNSUPPORTED_FORMAT", `Snapshot format ${manifest.format} is not supported by this reader (${SNAPSHOT_FORMAT}).`);
   }
   if (!options.skipVerify) {
     const report = await verifySnapshot({
@@ -172,21 +356,31 @@ async function restore(options) {
       throw new BackupError(first.code, `Refusing to restore: ${report.problems.length} problem(s), first at chunk ${first.chunk} — ${first.message}`);
     }
   }
-  await options.sink.begin?.(manifest);
   const key = await keyFor(options.masterSeed, manifest.realm, manifest.id);
   const collections = {};
   let rowsRestored = 0;
-  for (const chunk of manifest.chunks) {
-    const raw = await options.store.getObject(chunk.object);
-    const sealed = JSON.parse(new TextDecoder().decode(raw));
-    const plaintext = await open(key, sealed, aadFor(manifest.realm, manifest.id, chunk.index));
-    const { collection, rows } = JSON.parse(plaintext);
-    await options.sink.write(collection, rows);
-    collections[collection] = (collections[collection] ?? 0) + rows.length;
-    rowsRestored += rows.length;
-    options.onProgress?.({ chunk: chunk.index + 1, of: manifest.chunks.length, rows: rowsRestored });
+  let sinkFinalized = false;
+  try {
+    await options.sink.begin?.(manifest);
+    for (const chunk of manifest.chunks) {
+      const raw = await options.store.getObject(chunk.object);
+      const sealed = JSON.parse(new TextDecoder().decode(raw));
+      const plaintext = await open(key, sealed, aadFor(manifest.realm, manifest.id, chunk.index));
+      const { collection, rows } = JSON.parse(plaintext);
+      await options.sink.write(collection, rows);
+      collections[collection] = (collections[collection] ?? 0) + rows.length;
+      rowsRestored += rows.length;
+      options.onProgress?.({ chunk: chunk.index + 1, of: manifest.chunks.length, rows: rowsRestored });
+    }
+    await options.sink.finish?.(manifest);
+    sinkFinalized = true;
+  } catch (cause) {
+    if (!sinkFinalized)
+      await options.sink.abort?.(manifest).catch(() => {
+        return;
+      });
+    throw cause;
   }
-  await options.sink.finish?.(manifest);
   return { id: manifest.id, rowsRestored, collections };
 }
 async function listSnapshots(args) {
@@ -197,7 +391,14 @@ async function listSnapshots(args) {
     if (!object.key.endsWith("/manifest.json"))
       continue;
     try {
-      manifests.push(JSON.parse(new TextDecoder().decode(await args.store.getObject(object.key))));
+      const manifest = JSON.parse(new TextDecoder().decode(await args.store.getObject(object.key)));
+      const invalid = manifestProblem(manifest);
+      if (invalid || manifest.realm !== args.realm)
+        continue;
+      const { sealDigest, ...unsigned } = manifest;
+      if (!timingSafeEqual(await sealManifest(unsigned, args.masterSeed), sealDigest))
+        continue;
+      manifests.push(manifest);
     } catch {}
   }
   return manifests.sort((a, b) => b.createdAtMs - a.createdAtMs);
@@ -245,7 +446,12 @@ function selectForDeletion(manifests, policy = DEFAULT_RETENTION) {
   return newestFirst.filter((manifest) => !keep.has(manifest.id));
 }
 async function prune(args) {
-  const manifests = await listSnapshots({ store: args.store, realm: args.realm, prefix: args.prefix });
+  const manifests = await listSnapshots({
+    store: args.store,
+    realm: args.realm,
+    masterSeed: args.masterSeed,
+    prefix: args.prefix
+  });
   const doomed = selectForDeletion(manifests, args.policy);
   if (doomed.length >= manifests.length) {
     throw new BackupError("RETENTION_WOULD_EMPTY", "This policy would delete every snapshot. Refusing.");
@@ -276,6 +482,7 @@ function backupJob(options) {
       const pruned = await prune({
         store: options.store,
         realm: options.realm,
+        masterSeed: options.masterSeed,
         policy: options.policy,
         prefix: options.prefix
       });

package/dist/custody-crypto.d.ts

@@ -28,13 +28,15 @@ export declare function openWithKey(key: Uint8Array, box: CipherBox, aad: string
  * plaintext — so a captured response is ciphertext, and opening it requires the
  * factor itself.
  *
- * X25519 + HKDF-SHA256 + AES-256-GCM, with the ephemeral public key carried in
- * the box. Nothing bespoke: the ephemeral-static shape is what every sealed-box
- * construction uses, and doing it by hand is how people lose the AAD.
+ * ML-KEM-768 + X25519 + HKDF-SHA256 + AES-256-GCM. Both KEM halves are
+ * mandatory: a captured custody envelope remains confidential after a future
+ * break of X25519, while the classical half hedges a failure in the newer KEM.
+ * The version is explicit and the opener accepts no legacy X25519-only shape.
  */
 export interface SealedToKey extends CipherBox {
-    /** base64 — the ephemeral public key this box was sealed with. */
-    ephemeral: string;
+    version: 2;
+    /** base64 — the mandatory hybrid ML-KEM-768 + X25519 ciphertext. */
+    kemCiphertext: string;
 }
 /** Seal to a recipient's public key. */
 export declare function sealToKey(recipientPublicKey: Uint8Array, plaintext: Uint8Array, aad: string): SealedToKey;

package/dist/custody-crypto.js

@@ -8,9 +8,9 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 
 // src/custody-crypto.ts
 import { gcm } from "@noble/ciphers/aes.js";
-import { x25519 } from "@noble/curves/ed25519.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256 } from "@noble/hashes/sha2.js";
+import { ml_kem768_x25519 } from "@noble/post-quantum/hybrid.js";
 var KEY_BYTES = 32;
 var NONCE_BYTES = 12;
 var toBase64 = (bytes) => {
@@ -44,40 +44,62 @@ function openWithKey(key, box, aad) {
     throw new Error(`custody: unknown algorithm ${box.alg}`);
   return gcm(key, fromBase64(box.nonce), utf8(aad)).decrypt(fromBase64(box.ciphertext));
 }
-var WRAP_INFO = "forgezero:custody:wrap:v1";
-var wrapKey = (shared, ephemeral, recipient) => hkdf(sha256, shared, concatBytes(ephemeral, recipient), utf8(WRAP_INFO), 32);
-function concatBytes(left, right) {
-  const out = new Uint8Array(left.length + right.length);
-  out.set(left, 0);
-  out.set(right, left.length);
-  return out;
-}
+var WRAP_INFO = "forgezero:custody:wrap:ml-kem-768+x25519:v2";
+var WRAP_SEED_SALT = utf8("forgezero:custody:wrapkey:ml-kem-768+x25519:v2");
+var wrapKey = (shared) => hkdf(sha256, shared, undefined, utf8(WRAP_INFO), 32);
 function sealToKey(recipientPublicKey, plaintext, aad) {
-  const ephemeralSecret = x25519.utils.randomSecretKey();
-  const ephemeralPublic = x25519.getPublicKey(ephemeralSecret);
-  const shared = x25519.getSharedSecret(ephemeralSecret, recipientPublicKey);
-  const key = wrapKey(shared, ephemeralPublic, recipientPublicKey);
+  if (recipientPublicKey.length !== ml_kem768_x25519.lengths.publicKey) {
+    throw new Error("custody: invalid hybrid recipient public key");
+  }
+  const { cipherText, sharedSecret } = ml_kem768_x25519.encapsulate(recipientPublicKey);
+  const shared = Uint8Array.from(sharedSecret);
+  const ciphertext = Uint8Array.from(cipherText);
+  const key = wrapKey(shared);
   try {
-    return { ...sealWithKey(key, plaintext, aad), ephemeral: toBase64(ephemeralPublic) };
+    return {
+      version: 2,
+      ...sealWithKey(key, plaintext, aad),
+      kemCiphertext: toBase64(ciphertext)
+    };
   } finally {
     key.fill(0);
-    ephemeralSecret.fill(0);
+    shared.fill(0);
   }
 }
 function openFromKey(recipientSecretKey, box, aad) {
-  const ephemeralPublic = fromBase64(box.ephemeral);
-  const recipientPublic = x25519.getPublicKey(recipientSecretKey);
-  const shared = x25519.getSharedSecret(recipientSecretKey, ephemeralPublic);
-  const key = wrapKey(shared, ephemeralPublic, recipientPublic);
+  if (box?.version !== 2 || typeof box.kemCiphertext !== "string") {
+    throw new Error("custody: unsupported sealed-to-key envelope");
+  }
+  if (recipientSecretKey.length !== ml_kem768_x25519.lengths.secretKey) {
+    throw new Error("custody: invalid hybrid recipient secret key");
+  }
+  const ciphertext = fromBase64(box.kemCiphertext);
+  if (ciphertext.length !== ml_kem768_x25519.lengths.cipherText) {
+    throw new Error("custody: invalid hybrid KEM ciphertext");
+  }
+  const shared = Uint8Array.from(ml_kem768_x25519.decapsulate(ciphertext, recipientSecretKey));
+  const key = wrapKey(shared);
   try {
     return openWithKey(key, box, aad);
   } finally {
     key.fill(0);
+    shared.fill(0);
   }
 }
 function wrappingKeyPair(factorMaterial, info) {
-  const secretKey = hkdf(sha256, factorMaterial, utf8("forgezero:custody:wrapkey:v1"), utf8(info), 32);
-  return { secretKey, publicKey: x25519.getPublicKey(secretKey) };
+  if (factorMaterial.length < 32) {
+    throw new Error("custody: wrapping factor material must be at least 32 bytes");
+  }
+  const seed = hkdf(sha256, factorMaterial, WRAP_SEED_SALT, utf8(info), 32);
+  try {
+    const pair = ml_kem768_x25519.keygen(seed);
+    return {
+      secretKey: Uint8Array.from(pair.secretKey),
+      publicKey: Uint8Array.from(pair.publicKey)
+    };
+  } finally {
+    seed.fill(0);
+  }
 }
 export {
   wrappingKeyPair,

package/dist/custody-share.d.ts

@@ -1,6 +1,8 @@
 import { type CipherBox, type SealedToKey } from './custody-crypto';
 export interface SealedShare {
     shareIndex: number;
+    /** Account credential whose PRF deterministically derives this passkey key. */
+    passkeyCredentialId?: string;
     passkeyEnvelope: CipherBox;
     phraseEnvelope: CipherBox;
     /** base64 — the HKDF salt for the phrase key and the verifier. */
@@ -42,6 +44,8 @@ export declare function openShareWithPhrase(sealed: SealedShare, custodianKey: s
  * ever sent.
  */
 export interface WrappingKeys {
+    /** The verified, PRF-capable account credential selected by the browser. */
+    passkeyCredentialId: string;
     passkeyPublicKey: string;
     phrasePublicKey: string;
     phraseSalt: string;
@@ -60,6 +64,7 @@ export declare function phraseWrappingKey(custodianKey: string, phraseWords: str
 /** Everything the server needs, and nothing it must not have. */
 export declare function wrappingKeysFor(args: {
     custodianKey: string;
+    passkeyCredentialId: string;
     passkeyPrfOutput: Uint8Array;
     phraseWords: string[];
 }): WrappingKeys;