primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/snapshot-audit-store.js

@@ -0,0 +1,196 @@
+/**
+ * The audit's local reconstruction, over js-bao's own Node SQLite store
+ * (#3433, criterion 10).
+ *
+ * This is the half of the audit that must NOT be a reimplementation: the base
+ * is materialised by the checked-in loader and the overlays are folded by the
+ * client's own fold, so what the audit compares with the table is what a
+ * browser would have computed from the same artifacts. A hand-rolled fold here
+ * would make the audit agree with itself rather than with a client.
+ *
+ * Everything lives in one throwaway SQLite file, removed when the audit ends —
+ * including the `audit_seen` table, which is what keeps memory to one page
+ * plus the store: the ids the table has already shown are marked rather than
+ * held.
+ */
+import { createRequire } from "node:module";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const require_ = createRequire(import.meta.url);
+/** `yjs` as the CLI resolves it. */
+async function loadYjs() {
+    const yModule = await import(require_.resolve("yjs"));
+    return yModule.default ?? yModule;
+}
+/** `js-bao` and `yjs` as the CLI resolves them, loaded only when audited. */
+async function loadRuntime() {
+    const baoModule = await import(require_.resolve("js-bao"));
+    return {
+        bao: baoModule.default ?? baoModule,
+        Y: await loadYjs(),
+    };
+}
+function hex(bytes) {
+    let out = "";
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, "0");
+    return out;
+}
+/**
+ * The fence's reader: how far one overlay update has got, deletions included.
+ *
+ * A state vector alone is NOT that. It carries one clock per client and a Yjs
+ * deletion creates no struct, so removing a key leaves it exactly where it
+ * was — and a legacy nested-map record deleted between the audit's capture and
+ * its comparison would then pass the fence and be reported as a record only
+ * the recomputed chain holds, which is corruption's own signature (finding
+ * 3433-C05; the deletion shape is pinned by `large-document-snapshot-verify`'s
+ * E4 case). So the fingerprint is the state vector AND a digest of the
+ * update's delete set: every client's deleted ranges, in a fixed order.
+ *
+ * Yjs is loaded once and handed back as a synchronous function, so the audit's
+ * fence stays a plain comparison rather than an awaited one — and so the
+ * library itself never has to import Yjs.
+ */
+export async function createChainFingerprintReader() {
+    const Y = await loadYjs();
+    return (update) => {
+        const vector = hex(Y.encodeStateVectorFromUpdate(update));
+        const clients = Y.decodeUpdate(update).ds.clients;
+        const deletes = Array.from(clients.entries())
+            .map(([client, ranges]) => {
+            const sorted = ranges
+                .map((range) => `${range.clock}+${range.len}`)
+                .sort();
+            return `${client}:${sorted.join(",")}`;
+        })
+            .sort()
+            .join(";");
+        return `${vector}/${deletes}`;
+    };
+}
+/**
+ * The stringset fields a base manifest records, per model.
+ *
+ * A Map rather than an object because a model's name is data: an undeclared
+ * model is whatever `_type` the records route was handed, so `constructor` and
+ * `toString` are names this can be asked for, and on a plain object either
+ * answers a function off the prototype rather than nothing at all (3433-C11).
+ * The manifest is the only record of what a model declares for a model no
+ * later overlay touched, which is exactly where these have to come from.
+ */
+export function stringSetFieldsFromManifest(manifest) {
+    const out = new Map();
+    const schema = manifest.schema ?? {};
+    for (const [model, declared] of Object.entries(schema)) {
+        const fields = declared?.stringSetFields;
+        out.set(model, new Set(Array.isArray(fields) ? fields.map(String) : []));
+    }
+    return out;
+}
+const SEEN_DDL = `CREATE TABLE IF NOT EXISTS audit_seen (
+  model TEXT NOT NULL, id TEXT NOT NULL, PRIMARY KEY (model, id))`;
+/**
+ * Build a local store for one audit attempt.
+ *
+ * A fresh database per attempt by design: an attempt the fence discards must
+ * leave nothing behind for the next one to read.
+ */
+export async function createAuditLocalStore(documentId) {
+    const { bao, Y } = await loadRuntime();
+    const directory = mkdtempSync(join(tmpdir(), "primitive-audit-"));
+    const doc = new Y.Doc();
+    const init = await bao.initJsBao({
+        databaseConfig: {
+            type: "node-sqlite",
+            options: { filePath: join(directory, "audit.db") },
+        },
+        models: [],
+    });
+    await init.connectDocument(documentId, doc, "read-write", {
+        documentFormat: 2,
+    });
+    const sql = init.dbEngine.createFormat2Sql();
+    const { records } = bao.format2TableNames(documentId);
+    sql.exec(SEEN_DDL);
+    const rows = (query, ...bindings) => Array.from(sql.exec(query, ...bindings));
+    let stringSets = new Map();
+    const parse = (data) => {
+        try {
+            return JSON.parse(String(data ?? "{}"));
+        }
+        catch {
+            return {};
+        }
+    };
+    return {
+        async loadSnapshot(manifest, fetchChunk) {
+            stringSets = stringSetFieldsFromManifest(manifest);
+            await init.format2LoadSnapshot(documentId, manifest, (chunk) => fetchChunk(chunk), {});
+        },
+        async applyOverlay(update) {
+            // Each epoch's overlay is its own document, so each is folded from its
+            // own `Y.Doc` — and through the CLIENT's fold, which is the whole point:
+            // a divergence between what the room projects and what a client computes
+            // is invisible to every check that runs on one side of it.
+            const overlay = new Y.Doc();
+            Y.applyUpdate(overlay, update);
+            const store = bao.BaseModel.getFormat2Store(documentId);
+            if (!store) {
+                throw new Error(`the local record store for ${documentId} is not available, so the ` +
+                    `chain cannot be recomputed`);
+            }
+            bao.foldFormat2Overlay(overlay, store);
+            // The in-process host folds inside the call above; this yields once so
+            // an async host's queued batch has settled before anything reads.
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        },
+        async models() {
+            // The scan the SERVER may not do (criterion 5) is fine here: this table
+            // is the reconstruction the audit is already holding, on the operator's
+            // own machine, not a 2GB Durable Object's storage under an alarm budget.
+            return rows(`SELECT DISTINCT _type FROM ${records} ORDER BY _type`).map((row) => String(row._type));
+        },
+        async take(model, ids) {
+            const out = new Map();
+            if (ids.length === 0)
+                return out;
+            const placeholders = ids.map(() => "?").join(",");
+            for (const row of rows(`SELECT _id, _data FROM ${records} WHERE _type = ? AND _id IN (${placeholders})`, model, ...ids)) {
+                out.set(String(row._id), parse(row._data));
+            }
+            for (const id of ids) {
+                sql.exec(`INSERT OR IGNORE INTO audit_seen (model, id) VALUES (?, ?)`, model, id);
+            }
+            return out;
+        },
+        async remaining(model, after, limit) {
+            const bounded = after === null
+                ? rows(`SELECT _id, _data FROM ${records} r
+              WHERE r._type = ?
+                AND NOT EXISTS (SELECT 1 FROM audit_seen s WHERE s.model = r._type AND s.id = r._id)
+              ORDER BY r._id LIMIT ?`, model, limit)
+                : rows(`SELECT _id, _data FROM ${records} r
+              WHERE r._type = ? AND r._id > ?
+                AND NOT EXISTS (SELECT 1 FROM audit_seen s WHERE s.model = r._type AND s.id = r._id)
+              ORDER BY r._id LIMIT ?`, model, after, limit);
+            return bounded.map((row) => ({
+                id: String(row._id),
+                data: parse(row._data),
+            }));
+        },
+        stringSetFields(model) {
+            return stringSets.get(model) ?? new Set();
+        },
+        async close() {
+            try {
+                await bao.resetJsBao();
+            }
+            finally {
+                rmSync(directory, { recursive: true, force: true });
+            }
+        },
+    };
+}
+//# sourceMappingURL=snapshot-audit-store.js.map

package/dist/src/lib/snapshot-audit-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-audit-store.js","sourceRoot":"","sources":["../../../src/lib/snapshot-audit-store.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/snapshot-audit.d.ts

@@ -0,0 +1,207 @@
+/**
+ * `snapshot ⊕ overlays == table`, recomputed and compared (#3433, criterion 10).
+ *
+ * Per-build verification checks a base against the table it was built FROM:
+ * the chunks are read back, their digests match, their id sequences cover the
+ * ranges. What it cannot check is the other half of the contract — that
+ * folding the overlays onto that base, the way a CLIENT folds them, arrives at
+ * the document the server holds. A fold that means something slightly
+ * different on the two ends puts records into a client's authoritative table
+ * that the server never wrote, silently, because on a format-2 document there
+ * is no whole-document comparison left downstream to catch it.
+ *
+ * So this runs OUTSIDE the Durable Object, on the CLI:
+ *
+ * 0. Read the document's schema, which is the same permission the table pages
+ *    need. The chain export takes the app-admin arm and the pages take the
+ *    console arm or a read grant on the document, so a caller holding only the
+ *    first is refused here rather than after downloading the whole chain
+ *    (3433-C08).
+ * 1. Export the chain — the newest complete base, every overlay sealed after
+ *    it, and the open epoch's overlay inline.
+ * 2. Load the base through the checked-in loader into a local record store,
+ *    then fold each overlay in order with the client's own fold.
+ * 3. Page the authoritative table through the records API and compare it,
+ *    record by record, with the recomputed view.
+ *
+ * Running it inside the room would need a scratch copy of up to 2 GB of rows
+ * and a new multi-tick state machine; running it with the SERVER's fold would
+ * make it agree with the room by construction.
+ *
+ * ## The fence, and why there is one
+ *
+ * The chain export captures the open overlay once (`Y.encodeStateAsUpdate` at
+ * one moment); each records page is an independent query of the live table
+ * later (3433-R03). An ordinary write in between would read as corruption. The
+ * export is therefore its own fence: after the last page the chain is exported
+ * AGAIN and the open epoch number and a fingerprint of the inline overlay are
+ * compared with the capture. The fingerprint is the overlay's state vector AND
+ * its delete set, because a Yjs deletion creates no struct and therefore never
+ * moves a state vector (3433-C05) — and a record deleted under the comparison
+ * is precisely what a divergence looks like. The epoch moves on every
+ * rotation, so it is checked on its own. Either moving means the document
+ * changed under the comparison: that attempt yields NO VERDICT and is retried
+ * from a fresh capture; a document that moves on every attempt is reported as
+ * `none` rather than as a divergence.
+ */
+import { type ManifestChunkLike, type ManifestLike } from "./snapshot-manifest-layout.js";
+/** One artifact of the chain, as the export names it. */
+export interface AuditChainDownload {
+    path: string;
+}
+/** What `GET .../export/chain` answers for a large document. */
+export interface AuditChainDescriptor {
+    documentFormat?: number;
+    documentId?: string;
+    epoch: number;
+    base: {
+        epoch: number;
+        buildId: string;
+        rows?: number;
+        download: AuditChainDownload;
+    } | null;
+    overlays: Array<{
+        epoch: number;
+        download: AuditChainDownload;
+    }>;
+    current: {
+        epoch: number;
+        update: string;
+    };
+}
+/** One page of the authoritative table, as the records route answers it. */
+export interface AuditTablePage {
+    items: Array<Record<string, unknown>>;
+    nextCursor?: string | null;
+}
+/**
+ * Everything the audit reads from the SERVER.
+ *
+ * Injected rather than reached for, so the whole decision — the fence, the
+ * model union, the comparison — is gradeable against a source a test can move
+ * between calls, which is the one thing a live run cannot stage reliably.
+ */
+export interface AuditSource {
+    /** Export the chain. Throws the server's refusal verbatim. */
+    chain(): Promise<AuditChainDescriptor>;
+    /** One artifact, by its path within the chain's grant. */
+    download(path: string): Promise<Uint8Array>;
+    /**
+     * Every model the authoritative table holds a row of (#3433, behavior 30).
+     *
+     * Read before the chain is exported: it comes off the schema response, which
+     * takes the same permission the table pages do, so it is also the audit's
+     * check that the caller can finish (3433-C08).
+     */
+    tableModels(): Promise<string[]>;
+    /** One page of a model's records, in the route's own order. */
+    readPage(model: string, cursor?: string): Promise<AuditTablePage>;
+    /**
+     * The stringset fields the DOCUMENT declares now, per model.
+     *
+     * The base manifest carries the declarations as they stood when it was
+     * built, which is the only record for a model no later overlay touched — but
+     * a model or a field declared AFTER the base is not in it, and a stringset
+     * compared as an ordered array is a divergence the moment the two sides
+     * added the same members in a different order (finding 3433-C06). The two
+     * sources are unioned; what a field MEANS is the schema's job either way.
+     */
+    stringSetFields?(): Promise<Record<string, string[]>>;
+}
+/**
+ * The local reconstruction the audit compares against.
+ *
+ * A port rather than a concrete store: the verb builds it over js-bao's Node
+ * SQLite engine, and the hermetic tests build it over a map, so the comparison
+ * is graded without a database and the database is proven separately.
+ */
+export interface AuditLocalStore {
+    /** Materialise the base. `fetchChunk` is handed each manifest entry. */
+    loadSnapshot(manifest: ManifestLike, fetchChunk: (chunk: ManifestChunkLike) => Promise<Uint8Array>): Promise<void>;
+    /** Fold one overlay update — sealed or open — in chain order. */
+    applyOverlay(update: Uint8Array): Promise<void>;
+    /** Every model the reconstruction holds a row of. */
+    models(): Promise<string[]>;
+    /**
+     * The recomputed rows for these ids, and mark them compared.
+     *
+     * Reading and marking together is what keeps the audit's memory to one page
+     * plus the store: the ids the server has already shown are never held.
+     */
+    take(model: string, ids: readonly string[]): Promise<Map<string, Record<string, unknown>>>;
+    /** Rows of a model no page asked for, in id order, after `after`. */
+    remaining(model: string, after: string | null, limit: number): Promise<Array<{
+        id: string;
+        data: Record<string, unknown>;
+    }>>;
+    /** Stringset fields per model, as the base manifest's schema declares them. */
+    stringSetFields(model: string): ReadonlySet<string>;
+    close(): Promise<void>;
+}
+/** What one model's comparison found. */
+export interface AuditModelReport {
+    model: string;
+    /** Records present on both sides and compared. */
+    compared: number;
+    /** Ids the recomputed view holds and the table does not. */
+    onlyRecomputed: string[];
+    /** Ids the table holds and the recomputed view does not. */
+    onlyTable: string[];
+    /** Records both hold, with the fields that differ. */
+    differing: Array<{
+        id: string;
+        fields: string[];
+    }>;
+    /** A list above was capped at `maxDivergences`. */
+    truncated: boolean;
+}
+/** What the audit decided, and what it looked at. */
+export interface AuditReport {
+    verdict: "match" | "divergence" | "none";
+    /** Attempts made, including the ones the fence discarded. */
+    attempts: number;
+    /** Why there is no verdict. Absent on `match` and `divergence`. */
+    reason?: string;
+    buildId: string | null;
+    epoch: number | null;
+    models: AuditModelReport[];
+}
+export interface AuditOptions {
+    /** A fresh store per attempt: an attempt the fence discards is thrown away. */
+    store: () => Promise<AuditLocalStore>;
+    /** Ids listed per model per category before the report says `truncated`. */
+    maxDivergences?: number;
+    /** Attempts before the audit gives up on a moving document. */
+    retries?: number;
+    /** Records per page asked of the table. */
+    pageSize?: number;
+    /**
+     * How far one overlay update has got — its state vector AND its delete set.
+     *
+     * Injected because it is the one thing in the fence that needs Yjs, and the
+     * library is graded without it. `createChainFingerprintReader` is what the
+     * verb passes; a reader that answered with the state vector alone would miss
+     * a deletion (3433-C05).
+     */
+    fingerprint: (update: Uint8Array) => string;
+}
+/** The server refused to export a chain; there is nothing to audit. */
+export declare const EXPORT_CHAIN_INCOMPLETE = "EXPORT_CHAIN_INCOMPLETE";
+/**
+ * The stringset fields a schema response declares, per model.
+ *
+ * `GET documents/:id/schema` answers `{ schema: { models: { Note: { fields:
+ * { tags: { type: "stringset" } } } } } }` — the declarations the document's
+ * `_meta_` maps carry, which is where a field added after the base snapshot
+ * says what it is. A model with no stringset is left out rather than mapped to
+ * an empty list, so the union with the manifest's is a plain spread.
+ */
+export declare function stringSetFieldsFromSchema(schema: any): Record<string, string[]>;
+/**
+ * Recompute a document's chain locally and compare it with its table.
+ *
+ * Returns a verdict rather than throwing: a divergence is the answer the
+ * command exists to give, and "no verdict" is a third answer the validation
+ * child scripts on, not an error to catch.
+ */
+export declare function auditSnapshotChain(source: AuditSource, options: AuditOptions): Promise<AuditReport>;