approval-md 0.0.1 → 0.2.0

package/dist/src/core/verified-snapshot.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The verified-head snapshot (APRV-188): what a process that already walked the
+ * log publishes, so the next process does not have to walk it again.
+ *
+ * ## The cost this removes
+ *
+ * Every hook-gated tool call is a fresh process with an empty
+ * {@link VerifiedReadCache}, so it verifies the log from genesis before it may
+ * decide anything. APRV-186 and APRV-206 made that walk as cheap as a walk can
+ * be; what they could not change is that it is O(records) per gated command.
+ * Measured on this repository's shape at 10k records: 65 ms of the 371 ms a
+ * gated invocation costs, growing at 6.5 ms per thousand records, which is the
+ * term that turns into seconds as a log grows. The daemon, meanwhile, holds a
+ * warm cache and re-verifies only the tail on every tick. This module is how
+ * what it verified reaches the next hook process.
+ *
+ * ## Why a file and not a socket
+ *
+ * The hook's request path is synchronous end to end — `commandHook` returns an
+ * exit code, and the wait loop sleeps synchronously — so a `node:net` client
+ * could not be awaited from it, and a `spawnSync` helper to do the awaiting
+ * would cost more node startup (20-40 ms) than the walk it saves. A published
+ * file needs one `readFileSync`. It also spawns no child and opens no socket,
+ * so there is no environment to scrub (APRV-205) and no fd to leak.
+ *
+ * ## What a snapshot is, and what it is emphatically not
+ *
+ * It is an **endorsement of bytes**. It says: *the first `byte_length` bytes of
+ * this log, whose SHA-256 is this, verified clean, and they end at this head.*
+ * It carries no records, and a reader never learns anything from it that it
+ * cannot check against the log file in its own hands. A reader that cannot
+ * re-prove every one of those claims ignores the file and walks the log, which
+ * is the behaviour with no snapshot at all.
+ *
+ * ## Global invariant 1, "enforcement paths read only verified records"
+ *
+ * This is the invariant the module touches, so the argument is written out
+ * rather than assumed. The structure is APRV-43's, with the verifier in another
+ * process:
+ *
+ *  - {@link admitSnapshot} hashes the prefix bytes **it read itself** and
+ *    requires the digest the snapshot names. That is what makes "the bytes the
+ *    publisher verified" and "the bytes on disk now" the same bytes; it is the
+ *    identical proof the in-process cache pays on every cached read, and no
+ *    amount of `stat` substitutes for it.
+ *  - The reader parses the prefix lines itself and re-derives the head and the
+ *    line count from its own parse. A snapshot naming a different head, or a
+ *    different number of lines, is rejected by the reader's own arithmetic.
+ *  - The reader then re-checks the chain links (`alg`, `seq` succession, `prev`
+ *    linkage, hash shape) over those parsed records. This is a deliberate
+ *    SUBSET of `core/verify.ts`'s ladder and never a replacement for it: it can
+ *    only reject. `core/verify.ts` remains the one implementation of the
+ *    verdict, and the appended tail beyond the prefix is walked by it in full.
+ *  - What is therefore taken on the publisher's word is exactly two checks over
+ *    bytes already proved identical: the `event` schema validation and the
+ *    per-record hash recompute.
+ *
+ * **Why that residue is not a new capability.** A snapshot can only endorse
+ * bytes that are already in the log file. To exploit the residue an attacker
+ * must write `verified-head.json`, which sits in the same directory as
+ * `events.jsonl` under the same permissions — and the chain is unkeyed, so an
+ * attacker who can write that directory can simply recompute a self-consistent
+ * forged log, which passes a *cold* walk too. The snapshot grants nothing that
+ * write access to the log directory did not already grant. The ownership and
+ * permission checks in {@link readSnapshot} are what keep that sentence true
+ * under a loose umask: a snapshot any other user could have written is refused
+ * before it is read.
+ *
+ * Fail closed throughout. Every check here can only reject, every rejection
+ * falls back to the cold walk, and nothing in this module can turn a log that
+ * does not verify into a verdict — the reader either proves the prefix or walks
+ * it.
+ */
+import type { LogHead } from "./log.js";
+import type { VerifiedPrefix } from "./verify.js";
+/** The snapshot format version. A reader admits exactly this one. */
+export declare const SNAPSHOT_VERSION = 1;
+/**
+ * The published snapshot, as it sits on disk.
+ *
+ * Field names are snake_case to match every other file this project writes.
+ * There is no JSON Schema for it, deliberately: schemas in `schema/` describe
+ * the log's records, which are evidence, and this file is not evidence. It is
+ * validated field by field by {@link parseSnapshot}, strictly, in one place.
+ */
+export interface VerifiedSnapshot {
+    v: number;
+    /** Resolved path of the log these bytes belong to. */
+    log: string;
+    /** Resolved schema directory the publisher verified against ("" = default). */
+    schema_dir: string;
+    /** Length of the endorsed prefix in bytes. Always ends just after a newline. */
+    byte_length: number;
+    /** SHA-256 (hex) over exactly those bytes. The proof a reader re-computes. */
+    sha256: string;
+    /** Complete lines in the prefix, so a resumed walk numbers lines absolutely. */
+    lines: number;
+    /** The prefix's chain head. A reader re-derives it and must agree. */
+    head: LogHead;
+    /** When it was published. Diagnostics only; no check depends on it. */
+    verified_at: string;
+    /** Publisher pid. Diagnostics only; no check depends on it. */
+    pid: number;
+}
+/**
+ * Where the snapshot for `logPath` lives: beside the log, named for what it is.
+ *
+ * Derived, never configured. One log has one snapshot, and a reader that had to
+ * be *told* where to look could be pointed at a snapshot for another log — a
+ * mistake the `log` field would catch and that this removes entirely.
+ */
+export declare function snapshotPathFor(logPath: string): string;
+/** Forget what this process published. For tests, and for {@link clearSnapshot}. */
+export declare function forgetPublishedSnapshots(logPath?: string): void;
+/**
+ * Publish a snapshot for a log the caller has just verified clean.
+ *
+ * `raw` must be the exact bytes the caller verified, `sha256` their digest,
+ * `head` the head that walk produced and `lines` its record count: this function
+ * checks none of that and cannot — it is the caller's own verification being
+ * published. Every caller is therefore immediately after a `clean` verdict over
+ * these bytes. The digest is a parameter rather than a recomputation because the
+ * caller has just proved it (APRV-206's argument, and APRV-211's measurement:
+ * hashing megabytes twice per read was 45% of a tick).
+ *
+ * The write is atomic (a temp file in the same directory, then `rename`) so a
+ * reader never sees half a snapshot, and mode 0600 so the ownership argument in
+ * the module header holds. Any failure is swallowed: a snapshot is an
+ * optimization, and a daemon must not die because a cache file could not be
+ * written. The return value says whether it landed, for the tests and the
+ * doctor row; `false` also covers "these exact bytes are already published",
+ * which is a write skipped rather than a write that failed.
+ */
+export declare function publishSnapshot(logPath: string, raw: Uint8Array, digest: string, lines: number, head: LogHead, schemaDir: string | undefined, now?: () => string): boolean;
+/**
+ * {@link publishSnapshot} for a caller that never held the whole file.
+ *
+ * The incremental read (APRV-217) reads the head line and the appended bytes
+ * and proves the digest from a carried hash state, so it has the two facts this
+ * function needs — how long the verified prefix is and whether it ends at a
+ * line boundary — without a buffer of the log to derive them from. Nothing else
+ * differs: the same suppression memo, the same atomic 0600 write, the same
+ * snapshot fields. `publishSnapshot` is this function with those two facts read
+ * off a buffer.
+ */
+export declare function publishVerifiedPrefix(logPath: string, byteLength: number, endsWithNewline: boolean, digest: string, lines: number, head: LogHead, schemaDir: string | undefined, now?: () => string): boolean;
+/**
+ * Why a snapshot was not used. Every value means the same thing operationally —
+ * walk the log — and exists so the doctor row and the tests can say which check
+ * rejected it.
+ */
+export type SnapshotRefusal = "absent" | "unreadable" | "not-a-file" | "foreign-owner" | "loose-permissions" | "malformed" | "version" | "other-log" | "other-schema-dir" | "shorter-file" | "not-line-aligned" | "digest-mismatch" | "line-count-mismatch" | "head-mismatch" | "chain-broken";
+export interface SnapshotRejected {
+    ok: false;
+    reason: SnapshotRefusal;
+    detail: string;
+}
+export type SnapshotRead = {
+    ok: true;
+    snapshot: VerifiedSnapshot;
+} | SnapshotRejected;
+/**
+ * Read the snapshot for `logPath`, refusing one this user did not write.
+ *
+ * The ownership and permission checks are taken from the open file descriptor
+ * rather than from the path, so what is checked and what is read are the same
+ * inode: a snapshot swapped between the `stat` and the read cannot be admitted
+ * on the strength of the file that used to be there.
+ */
+export declare function readSnapshot(logPath: string): SnapshotRead;
+export type SnapshotAdmission = {
+    ok: true;
+    prefix: VerifiedPrefix;
+    /**
+     * SHA-256 of the endorsed prefix, as this call re-proved it. Handed back
+     * so a caller that caches the prefix does not hash the same bytes twice.
+     */
+    digest: string;
+} | SnapshotRejected;
+/**
+ * Decide whether `snapshot` may stand for the first bytes of `raw`, and return
+ * the {@link VerifiedPrefix} a resumed walk chains onto when it may.
+ *
+ * `raw` is the caller's own read of the whole log. Every check below is made
+ * against those bytes; nothing is re-`stat`ed, re-read, or taken from the
+ * snapshot without being re-derived. The order is cheapest-first, but only the
+ * digest is load-bearing — everything before it rejects an obviously
+ * inapplicable snapshot without hashing megabytes, and everything after it
+ * re-derives from the reader's own parse what the snapshot merely claimed.
+ */
+export declare function admitSnapshot(logPath: string, raw: Uint8Array, snapshot: VerifiedSnapshot, schemaDir: string | undefined): SnapshotAdmission;
+/**
+ * {@link readSnapshot} then {@link admitSnapshot}: the whole path a reader takes.
+ *
+ * Returns the prefix to resume behind, or the reason there is none. Every reason
+ * means "walk the log", which is what the caller does with no snapshot at all.
+ */
+export declare function snapshotPrefix(logPath: string, raw: Uint8Array, schemaDir: string | undefined): SnapshotAdmission;
+/** Read the snapshot's own text, for the doctor row. Never throws. */
+export declare function snapshotSummary(logPath: string): SnapshotRead;
+/** Remove a snapshot. Used by tests and by anything that invalidates one. */
+export declare function clearSnapshot(logPath: string): void;
+/** Read the log's bytes, for callers that want the same view a reader admits. */
+export declare function logBytes(logPath: string): Uint8Array | null;