@forgezero/runtime 0.1.0

package/dist/audit.js

@@ -0,0 +1,291 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/serial.ts
+function createKeyedSerial(options = {}) {
+  const maxKeys = options.maxKeys ?? 1e4;
+  const chains = new Map;
+  return {
+    run(key, work) {
+      const previous = chains.get(key) ?? Promise.resolve();
+      const next = previous.then(work, work);
+      const settled = next.then(() => {
+        return;
+      }, () => {
+        return;
+      });
+      chains.set(key, settled);
+      settled.then(() => {
+        if (chains.get(key) === settled)
+          chains.delete(key);
+      });
+      if (chains.size > maxKeys) {
+        console.warn(`[serial] ${chains.size} keys in flight, above the ${maxKeys} guideline.`);
+      }
+      return next;
+    },
+    size: () => chains.size,
+    drain: async () => {
+      await Promise.allSettled([...chains.values()]);
+    }
+  };
+}
+
+// src/audit.ts
+import { sha256, timingSafeEqual } from "@forgezero/access/security";
+class AuditChainError extends Error {
+  code;
+  at;
+  constructor(code, message, at) {
+    super(message);
+    this.code = code;
+    this.at = at;
+    this.name = "AuditChainError";
+  }
+}
+var GENESIS_DIGEST = "0".repeat(64);
+function canonicalise(record) {
+  const detail = record.detail ? Object.keys(record.detail).sort().map((key) => `${key}=${String(record.detail[key])}`).join("\x1F") : "";
+  return [
+    record.sequence,
+    record.previousDigest,
+    record.atMs,
+    record.action,
+    record.outcome,
+    record.actor ?? "",
+    record.realm ?? "",
+    record.targetCollection ?? "",
+    record.targetKey ?? "",
+    record.reason ?? "",
+    detail
+  ].join("\x1E");
+}
+var hashDigester = (input) => sha256(input);
+var sealedDigester = (key) => {
+  return async (input) => {
+    const { hmacSha256 } = await import("@forgezero/access/security");
+    return hmacSha256(key, input);
+  };
+};
+async function appendRecord(store, entry, options = {}) {
+  const digester = options.digester ?? hashDigester;
+  const previous = await store.tail(entry.realm);
+  const unsigned = {
+    ...entry,
+    sequence: (previous?.sequence ?? 0) + 1,
+    atMs: (options.now ?? Date.now)(),
+    previousDigest: previous?.digest ?? GENESIS_DIGEST
+  };
+  const record = { ...unsigned, digest: await digester(canonicalise(unsigned)) };
+  await store.append(record);
+  return record;
+}
+async function verifyChain(records, options = {}) {
+  const digester = options.digester ?? hashDigester;
+  if (records.length === 0) {
+    return { ok: true, checked: 0 };
+  }
+  if (options.expectGenesis && records[0].previousDigest !== GENESIS_DIGEST) {
+    return {
+      ok: false,
+      checked: 0,
+      brokenAt: records[0].sequence,
+      reason: "NOT_GENESIS",
+      message: `The chain starts at sequence ${records[0].sequence} without a genesis link — records before it are missing.`
+    };
+  }
+  let previous;
+  for (const [index, record] of records.entries()) {
+    if (previous) {
+      if (record.sequence !== previous.sequence + 1) {
+        return {
+          ok: false,
+          checked: index,
+          brokenAt: record.sequence,
+          reason: "OUT_OF_ORDER",
+          message: `Sequence jumps from ${previous.sequence} to ${record.sequence}; ${record.sequence - previous.sequence - 1} record(s) are missing.`
+        };
+      }
+      if (!timingSafeEqual(record.previousDigest, previous.digest)) {
+        return {
+          ok: false,
+          checked: index,
+          brokenAt: record.sequence,
+          reason: "BROKEN_LINK",
+          message: `Record ${record.sequence} does not follow record ${previous.sequence} — one of them was altered.`
+        };
+      }
+    }
+    const expected = await digester(canonicalise(record));
+    if (!timingSafeEqual(expected, record.digest)) {
+      return {
+        ok: false,
+        checked: index,
+        brokenAt: record.sequence,
+        reason: "BAD_DIGEST",
+        message: `Record ${record.sequence} does not hash to its own digest — its contents were edited in place.`
+      };
+    }
+    previous = record;
+  }
+  return { ok: true, checked: records.length };
+}
+async function exportRange(store, args, options = {}) {
+  const digester = options.digester ?? hashDigester;
+  if (args.toSequence < args.fromSequence) {
+    throw new AuditChainError("EMPTY_RANGE", "The range ends before it starts.");
+  }
+  const records = await store.range(args.realm, args.fromSequence, args.toSequence);
+  if (records.length === 0) {
+    throw new AuditChainError("EMPTY_RANGE", "No records in that range.");
+  }
+  const verdict = await verifyChain(records, {
+    digester,
+    expectGenesis: args.fromSequence <= 1
+  });
+  if (!verdict.ok) {
+    throw new AuditChainError(verdict.reason, verdict.message, verdict.brokenAt);
+  }
+  return {
+    realm: args.realm,
+    fromSequence: records[0].sequence,
+    toSequence: records.at(-1).sequence,
+    anchorDigest: records[0].previousDigest,
+    records,
+    sealDigest: await digester(records.map((record) => record.digest).join("\x1E")),
+    exportedAtMs: (options.now ?? Date.now)()
+  };
+}
+async function verifyExport(slice, options = {}) {
+  const digester = options.digester ?? hashDigester;
+  const verdict = await verifyChain(slice.records, {
+    digester,
+    expectGenesis: slice.anchorDigest === GENESIS_DIGEST
+  });
+  if (!verdict.ok)
+    return verdict;
+  if (slice.records[0].previousDigest !== slice.anchorDigest) {
+    return {
+      ok: false,
+      checked: 0,
+      brokenAt: slice.fromSequence,
+      reason: "BROKEN_LINK",
+      message: "The slice does not hang from the anchor it claims."
+    };
+  }
+  const seal = await digester(slice.records.map((record) => record.digest).join("\x1E"));
+  if (!timingSafeEqual(seal, slice.sealDigest)) {
+    return {
+      ok: false,
+      checked: slice.records.length,
+      brokenAt: slice.fromSequence,
+      reason: "BAD_DIGEST",
+      message: "The slice does not match its own seal — records were added or removed after export."
+    };
+  }
+  if (options.expectSealDigest && !timingSafeEqual(seal, options.expectSealDigest)) {
+    return {
+      ok: false,
+      checked: slice.records.length,
+      brokenAt: slice.fromSequence,
+      reason: "BAD_DIGEST",
+      message: "The slice does not match the seal that was published at the time — history was rewritten after it."
+    };
+  }
+  return verdict;
+}
+function createAuditChain(options) {
+  const digester = options.digester ?? hashDigester;
+  const serial = createKeyedSerial();
+  const enqueue = (realm, run) => serial.run(realm ?? "\x00platform", run);
+  return {
+    append: (entry) => enqueue(entry.realm, () => appendRecord(options.store, entry, { ...options, digester })),
+    verify: async (realm, fromSequence = 1, toSequence = Number.MAX_SAFE_INTEGER) => {
+      const records = await options.store.range(realm, fromSequence, toSequence);
+      return verifyChain(records, { digester, expectGenesis: fromSequence <= 1 });
+    },
+    export: (args) => exportRange(options.store, args, { ...options, digester }),
+    sink: {
+      write(record) {
+        const entry = {
+          action: `route.${record.route}`,
+          outcome: record.outcome,
+          actor: record.userKey,
+          realm: record.realm,
+          targetKey: record.targetKey,
+          detail: {
+            method: record.method,
+            status: record.status,
+            ...record.code ? { code: record.code } : {},
+            ...flattenDetail(record.detail)
+          },
+          ...record.outcome === "denied" && record.code ? { reason: record.code } : {}
+        };
+        enqueue(record.realm, () => appendRecord(options.store, entry, { ...options, digester })).catch((error) => options.onError?.(error, entry));
+      }
+    }
+  };
+}
+function flattenDetail(detail) {
+  if (!detail)
+    return {};
+  const flat = {};
+  for (const [key, value] of Object.entries(detail)) {
+    if (value === null || value === undefined)
+      flat[key] = null;
+    else if (typeof value === "object")
+      flat[key] = JSON.stringify(value);
+    else if (typeof value === "bigint")
+      flat[key] = value.toString();
+    else
+      flat[key] = value;
+  }
+  return flat;
+}
+function memoryStore() {
+  const chains = new Map;
+  const keyOf = (realm) => realm ?? "\x00platform";
+  return {
+    async tail(realm) {
+      return chains.get(keyOf(realm))?.at(-1) ?? null;
+    },
+    async append(record) {
+      const key = keyOf(record.realm);
+      const chain = chains.get(key) ?? [];
+      if (chain.some((existing) => existing.sequence === record.sequence)) {
+        throw new AuditChainError("OUT_OF_ORDER", `Sequence ${record.sequence} already exists in this realm.`, record.sequence);
+      }
+      chain.push(record);
+      chains.set(key, chain);
+    },
+    async range(realm, fromSequence, toSequence) {
+      return (chains.get(keyOf(realm)) ?? []).filter((record) => record.sequence >= fromSequence && record.sequence <= toSequence).sort((a, b) => a.sequence - b.sequence);
+    },
+    all(realm) {
+      return [...chains.get(keyOf(realm)) ?? []];
+    },
+    clear() {
+      chains.clear();
+    }
+  };
+}
+var VERSION = "0.1.0";
+export {
+  verifyExport,
+  verifyChain,
+  sealedDigester,
+  memoryStore,
+  hashDigester,
+  exportRange,
+  createAuditChain,
+  canonicalise,
+  appendRecord,
+  VERSION,
+  GENESIS_DIGEST,
+  AuditChainError
+};

package/dist/backup.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Encrypted snapshots, and the restore that reads them back.
+ *
+ * A backup nobody has restored is a hypothesis. The two halves are one module
+ * precisely so the restore is exercised by the same test that writes the
+ * snapshot — the alternative is a backup job that has run nightly for a year
+ * and a restore path that has never been executed, which is the configuration
+ * everybody discovers on the worst possible day.
+ *
+ * ## Sealed before it leaves the machine
+ *
+ * Every chunk is encrypted under a key derived from the realm master seed, with
+ * AAD binding the realm, the snapshot and the chunk index. The object store —
+ * ours or the tenant's — holds ciphertext it cannot read, which is what makes
+ * "point it at your own bucket" a real offer rather than a compliance-flavoured
+ * one. It also means a snapshot lifted from realm A fails its GCM tag when
+ * restored into realm B rather than quietly loading someone else's data.
+ *
+ * ## Chunked, and each chunk verified
+ *
+ * A snapshot is written in chunks with a digest per chunk in the manifest. A
+ * truncated upload — the ordinary outcome of a network failure mid-transfer —
+ * otherwise produces an object that exists, has a plausible size, and restores
+ * into a silently incomplete database. Verification catches it while there is
+ * still a good copy to fall back on.
+ *
+ * ## Restore refuses more than it accepts
+ *
+ * A failed restore is recoverable; a corrupt one is not, because it overwrites
+ * the thing it was supposed to save. Every check therefore fails closed: a
+ * missing chunk, a digest mismatch, a realm mismatch and an unknown format all
+ * 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);
+}
+/** Bumped only for a change that an older reader cannot handle. */
+export declare const SNAPSHOT_FORMAT = 1;
+export interface ChunkRecord {
+    index: number;
+    /** Object key in the store. */
+    object: string;
+    /** SHA-256 of the PLAINTEXT, so a restore verifies what it actually recovered. */
+    digest: string;
+    rows: number;
+    bytes: number;
+}
+export interface SnapshotManifest {
+    format: number;
+    id: string;
+    realm: string;
+    createdAtMs: number;
+    /** Which collections, and how many rows from each. */
+    collections: Record<string, number>;
+    chunks: readonly ChunkRecord[];
+    totalRows: number;
+    /** Digest over every chunk digest — one value that fixes the whole snapshot. */
+    sealDigest: string;
+    /** Free-form: schema version, application version, who triggered it. */
+    labels?: Record<string, string>;
+}
+/** The subset of an object store this needs. `@forgezero/providers/storage` satisfies it. */
+export interface ObjectStore {
+    putObject(args: {
+        key: string;
+        body: Uint8Array | string;
+        contentType?: string;
+    }): Promise<unknown>;
+    getObject(key: string): Promise<Uint8Array>;
+    listObjects(prefix?: string, limit?: number): Promise<{
+        key: string;
+        size: number;
+    }[]>;
+    deleteObject(key: string): Promise<void>;
+}
+/** Where the rows come from. Async-iterable so a large collection never lands in memory whole. */
+export interface RowSource {
+    collections(): Promise<string[]>;
+    rows(collection: string): AsyncIterable<Record<string, unknown>>;
+}
+/** Where they go on the way back. */
+export interface RowSink {
+    /**
+     * Called once per chunk with the rows it held.
+     *
+     * Per chunk rather than per row so a sink can use a bulk import, and so a
+     * failure names a bounded set of rows rather than one.
+     */
+    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>;
+    finish?(manifest: SnapshotManifest): Promise<void>;
+}
+export interface SnapshotOptions {
+    store: ObjectStore;
+    source: RowSource;
+    realm: string;
+    masterSeed: Uint8Array;
+    /** Rows per chunk. Smaller means more objects; larger means more memory. */
+    chunkRows?: number;
+    prefix?: string;
+    labels?: Record<string, string>;
+    id?: string;
+    now?: () => number;
+    onProgress?: (progress: {
+        collection: string;
+        rows: number;
+        chunks: number;
+    }) => void;
+}
+/**
+ * Write a snapshot.
+ *
+ * The manifest is written **last**, deliberately. Its presence is what marks a
+ * snapshot complete, so a run that dies halfway leaves orphaned chunks and no
+ * manifest — which `listSnapshots` skips and `prune` can collect. The opposite
+ * order produces a manifest advertising chunks that were never uploaded, and
+ * that snapshot looks valid until somebody needs it.
+ */
+export declare function snapshot(options: SnapshotOptions): Promise<SnapshotManifest>;
+export interface VerifyReport {
+    ok: boolean;
+    id: string;
+    chunksChecked: number;
+    rowsChecked: number;
+    problems: {
+        chunk: number;
+        code: BackupError['code'];
+        message: string;
+    }[];
+}
+/**
+ * Read every chunk, decrypt it, and check it against the manifest.
+ *
+ * Reports EVERY problem rather than the first, which is the opposite of the
+ * audit chain's rule and correct for the same underlying reason: chunks are
+ * independent, so a second failure is genuinely new information, whereas a
+ * second broken chain link is only a consequence of the first. Knowing whether
+ * one chunk or forty are bad decides whether the snapshot is repairable.
+ */
+export declare function verifySnapshot(args: {
+    store: ObjectStore;
+    manifest: SnapshotManifest;
+    masterSeed: Uint8Array;
+}): Promise<VerifyReport>;
+export interface RestoreOptions {
+    store: ObjectStore;
+    sink: RowSink;
+    manifest: SnapshotManifest;
+    masterSeed: Uint8Array;
+    /** The realm being restored INTO. Must match the manifest. */
+    realm: string;
+    /**
+     * Skip the verify pass.
+     *
+     * Exists for a restore under time pressure on a snapshot verified an hour
+     * ago. Off by default: writing unverified data over a broken database is how
+     * a recoverable outage becomes data loss.
+     */
+    skipVerify?: boolean;
+    onProgress?: (progress: {
+        chunk: number;
+        of: number;
+        rows: number;
+    }) => void;
+}
+export interface RestoreReport {
+    id: string;
+    rowsRestored: number;
+    collections: Record<string, number>;
+}
+export declare function restore(options: RestoreOptions): Promise<RestoreReport>;
+export declare function listSnapshots(args: {
+    store: ObjectStore;
+    realm: string;
+    prefix?: string;
+}): Promise<SnapshotManifest[]>;
+export interface RetentionPolicy {
+    /** Most recent N, regardless of age. */
+    keepLast: number;
+    keepDaily?: number;
+    keepWeekly?: number;
+    keepMonthly?: number;
+}
+export declare const DEFAULT_RETENTION: RetentionPolicy;
+/**
+ * Decide what to keep.
+ *
+ * Grandfather-father-son: the newest few unconditionally, then one per day, per
+ * week and per month. The alternative — "delete anything older than N days" —
+ * loses the ability to recover from a corruption that was introduced before the
+ * window and only noticed afterwards, which is the common case for corruption.
+ *
+ * The **newest snapshot is never selected for deletion**, whatever the policy
+ * says. A retention rule that can empty the bucket is a data-loss bug waiting
+ * for a clock skew or a misconfigured `keepLast: 0`.
+ */
+export declare function selectForDeletion(manifests: readonly SnapshotManifest[], policy?: RetentionPolicy): SnapshotManifest[];
+export declare function prune(args: {
+    store: ObjectStore;
+    realm: string;
+    policy?: RetentionPolicy;
+    prefix?: string;
+    /** Report what would go without removing it. */
+    dryRun?: boolean;
+}): Promise<{
+    deleted: string[];
+    kept: number;
+}>;
+/**
+ * The nightly snapshot, as a job spec.
+ *
+ * Verification runs immediately after the write, on purpose. Verifying a
+ * snapshot a week later tells you it was broken a week ago; verifying it now
+ * tells you while the source data still exists to take another one.
+ */
+export declare function backupJob(options: SnapshotOptions & {
+    policy?: RetentionPolicy;
+    key?: string;
+    everyMs?: number;
+}): {
+    key: string;
+    everyMs: number;
+    run: () => Promise<{
+        ok: boolean;
+        detail: {
+            id: string;
+            problems: number;
+            rows?: undefined;
+            pruned?: undefined;
+        };
+    } | {
+        ok: boolean;
+        detail: {
+            id: string;
+            rows: number;
+            pruned: number;
+            problems?: undefined;
+        };
+    }>;
+};
+export declare const VERSION = "0.1.0";