approval-md 0.0.1 → 0.2.0

package/dist/src/core/verify.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Hash-chain verification for `.approval/log/events.jsonl` (SPEC.md §8:
+ * "`approval log verify` MUST detect any mutation or truncation").
+ *
+ * This module is the read side of the append-only log. It re-derives every
+ * record's digest from its canonical serialization and walks the `prev` chain
+ * and the `seq` succession end to end, reporting the *first* place the log
+ * stops being self-consistent.
+ *
+ * **Read-only, by definition.** Verification opens the log for reading and
+ * nothing else: it never truncates, never rewrites, never repairs, and never
+ * creates a lockfile. A torn tail is *reported*, never auto-truncated — a log
+ * that heals itself is a log that can be made to forget. Repair is a human
+ * decision, made explicitly: a later CLI task may offer it behind an explicit
+ * flag, but the core provides detection only.
+ *
+ * **What verification detects.** Any mutation of a record without a full
+ * recompute of every descendant; truncation of the tail (with an external
+ * anchor); deletion, insertion, reorder, or splice anywhere in the chain;
+ * `alg` tampering; a malformed or schema-invalid line; a duplicated or skipped
+ * `seq`; a non-genesis first record; and — given an anchor — a fully
+ * recomputed forged suffix.
+ *
+ * **The detection boundary — state it plainly.** A hash chain is
+ * tamper-*evident*, not tamper-*proof*. A forger who rewrites record N and then
+ * recomputes every descendant (new hash, fixed `prev`) produces a file that is
+ * internally self-consistent in every respect, and `verify(logPath)` on that
+ * file alone CANNOT distinguish it from an honest log. The same is true of
+ * dropping records off the tail: the surviving prefix is a valid chain. Closing
+ * that gap requires something the forger does not control:
+ *
+ * - an externally anchored head — pass {@link VerifyOptions.expectedHead} with
+ *   a `(seq, hash)` pair recorded elsewhere (a channel message, another host, a
+ *   human's notes); a mismatch is reported as `head-mismatch`;
+ * - a retained copy of the log held outside the writer's reach;
+ * - the optional per-event git commits of SPEC.md §8, where the daemon commits
+ *   each record under its own identity, giving signed, distributed evidence.
+ *
+ * Three questions that keep arriving separately have one answer (APRV-141, F7):
+ * the digest covers each record's CANONICAL CONTENT, its RFC 8785
+ * serialization, and never the bytes of the line it was read from, so a
+ * re-serialization that changes only byte format verifies clean, a line
+ * carrying a duplicate key is settled by the JSON parse that precedes
+ * canonicalization rather than by the chain, and an unanchored tail truncation
+ * leaves a valid prefix that nothing inside the file can contradict.
+ *
+ * **Anomalies, which are reported and never enforced (APRV-40).** SPEC.md §8
+ * requires that "verification treats gate-type events with implausible skew
+ * relative to their neighbors as a reportable anomaly, never silently accepted".
+ * Every non-corrupt result therefore carries {@link VerifyResult.anomalies}, a
+ * list that says nothing about integrity: a clean log with anomalies is clean,
+ * exits 0, and authorizes exactly what it authorized before. The separation is
+ * the point. Chain integrity is a proof, skew is a judgment, and folding a
+ * judgment into a proof would turn `log verify` into a check people learn to
+ * pass a flag to silence. See {@link chainAnomalies}.
+ *
+ * Determinism: the result is a pure function of (log bytes, schema files,
+ * options). No clock, no network, no cross-call state — the anomaly pass reads
+ * the records' own timestamps and never the current time.
+ */
+import { type EventRecord, type LogHead } from "./log.js";
+import { type ValidateOptions } from "./validate.js";
+/**
+ * A chain head: the last record's position and digest.
+ *
+ * Defined in `core/log.ts` (the writer needs it for its compare-and-append
+ * precondition and cannot import this module) and re-exported here, where
+ * readers expect to find it. One definition, one meaning.
+ */
+export type { LogHead };
+/**
+ * The skew allowance, in milliseconds, before a backwards step between two
+ * gate-typed records is reported.
+ *
+ * ### Why 2 seconds, and why any number at all
+ *
+ * Gate-typed timestamps are stamped by `core/clock.ts` at the write boundary. In
+ * one process they come from one `Date.now()` and never go backwards. Across
+ * processes and hosts — the daemon on one machine, a CLI verb on another, both
+ * appending to a shared log — they come from separate wall clocks, and two
+ * healthy NTP-disciplined clocks routinely disagree by tens of milliseconds and
+ * occasionally by a few hundred during a step correction. A tolerance of zero
+ * would therefore report ordinary distributed operation as an anomaly, which is
+ * the fastest way to make an anomaly channel ignored.
+ *
+ * 2000 ms is chosen as roughly an order of magnitude above the disagreement a
+ * synchronized fleet actually exhibits, and two to three orders of magnitude
+ * below the skew that a *useful* lie requires. The thing this check exists to
+ * catch is a timestamp placed to change a judgment: a `ts` inside a lapsed TTL
+ * (minutes to hours), or one moved outside a rolling budget window (hours). No
+ * attack is bought by 1.9 seconds, and no healthy fleet needs 2.1.
+ *
+ * It is the DEFAULT rather than the only value since APRV-58: an operator
+ * running a single host may tighten it to 250 ms, one running across a WAN with
+ * poor time discipline may loosen it to 5 s, and `audit.skew_tolerance` in the
+ * policy is where they say so. A policy that declares nothing (or that fails to
+ * load at all) leaves this number in force, so the reference runtime still has
+ * exactly one value that every reader can see.
+ *
+ * Widening the tolerance permits nothing: the threshold is report-only in both
+ * directions, so a loosened value hides evidence from a human and cannot make
+ * any action allowed that was refused before.
+ */
+export declare const GATE_TS_SKEW_TOLERANCE_MS = 2000;
+/**
+ * `audit.skew_tolerance` in milliseconds, or the default when it says nothing.
+ *
+ * Fails closed to the default exactly as `daemon/prune.ts`'s retention read
+ * does: a policy that cannot be loaded configures nothing, and for THIS key the
+ * safe fallback is the shipped number rather than zero — a zero allowance would
+ * report every ordinary clock disagreement as an anomaly, and an anomaly channel
+ * that cries wolf is one operators stop reading. An unparseable duration never
+ * reaches here: the schema's duration pattern rejects it and `loadPolicy` fails
+ * the whole policy, precisely as a bad `defaults.approval_ttl` does.
+ */
+export declare function skewToleranceMsOf(policy: {
+    dir?: string;
+    file?: string;
+}, schemaDir?: string): number;
+/**
+ * Machine-readable anomaly kinds. Closed union, additive-only, each pinned by a
+ * test — the same contract every other frozen union in this codebase carries.
+ */
+export declare const CHAIN_ANOMALY_KINDS: readonly [
+/**
+ * A gate-typed record's `ts` is earlier than the previous gate-typed record's
+ * `ts` by more than {@link GATE_TS_SKEW_TOLERANCE_MS}.
+ *
+ * One kind covers both directions SPEC.md §8 describes. "Earlier than its
+ * predecessor" and "later than its successor" are the same disagreement seen
+ * from the two ends of one adjacent pair, and reporting it twice would double
+ * every entry without adding a fact.
+ */
+"gate-ts-regression"];
+export type ChainAnomalyKind = (typeof CHAIN_ANOMALY_KINDS)[number];
+/** One reportable oddity in a log that verifies. Never a verdict. */
+export interface ChainAnomaly {
+    kind: ChainAnomalyKind;
+    /** The record the anomaly is reported against. */
+    seq: number;
+    ts: string;
+    event: string;
+    /** The gate-typed record it was compared with. */
+    previousSeq: number;
+    previousTs: string;
+    /** How far back the step is, in milliseconds. Always positive. */
+    skewMs: number;
+    message: string;
+}
+/**
+ * Timestamp anomalies among the gate-typed records of a verified chain.
+ *
+ * Pure: a function of the records alone, with no clock and no I/O. Comparison is
+ * between each gate-typed record and the previous **gate-typed** record, not the
+ * previous record of any kind, for the reason {@link isGateTyped} states.
+ *
+ * This changes no verdict. A log full of anomalies is still `clean` if its chain
+ * verifies, still exits 0, and still authorizes exactly what it authorized
+ * before. Skew is evidence for a human to weigh, and a verifier that refused on
+ * it would be refusing on a heuristic — which is how a tamper-evidence tool
+ * starts being run with a flag that turns it off.
+ */
+export declare function chainAnomalies(records: readonly EventRecord[], toleranceMs?: number): ChainAnomaly[];
+/** Machine-readable reason a log failed verification. Closed set. */
+export type VerifyFailureReason = "malformed-line" | "schema-invalid" | "bad-alg" | "hash-mismatch" | "prev-mismatch" | "seq-gap" | "seq-duplicate" | "not-genesis" | "head-mismatch";
+/**
+ * Outcome of a verification run. A discriminated union on `status`:
+ *
+ * - `clean` — every complete line verified; `head` is `null` for an empty or
+ *   absent log.
+ * - `torn-tail` — the file's final line is torn (it is not newline-terminated,
+ *   i.e. a writer died mid-line) while every complete line before it verifies.
+ *   This is the crashed-write signature and is deliberately distinct from
+ *   corruption: it is an incomplete write, not evidence of tampering.
+ * - `corrupt` — everything else, reported at the first offending record.
+ */
+export type VerifyResult = {
+    status: "clean";
+    records: number;
+    head: LogHead | null;
+    anomalies: ChainAnomaly[];
+} | {
+    status: "torn-tail";
+    records: number;
+    intactThroughSeq: number;
+    message: string;
+    anomalies: ChainAnomaly[];
+} | {
+    status: "corrupt";
+    firstBadSeq: number | null;
+    reason: VerifyFailureReason;
+    message: string;
+    anomalies: ChainAnomaly[];
+};
+/** Options accepted by {@link verify}. */
+export interface VerifyOptions extends ValidateOptions {
+    /**
+     * Externally anchored head. When supplied, a log that verifies internally is
+     * additionally required to end at exactly this `(seq, hash)`. This is the
+     * only defence against tail truncation and against a fully recomputed forged
+     * suffix; see the detection boundary in the module header.
+     */
+    expectedHead?: LogHead;
+    /**
+     * Where the policy carrying `audit.skew_tolerance` lives (APRV-58), with
+     * `loadPolicy`'s semantics. Supplied by a caller that has a policy to hand;
+     * absent means {@link GATE_TS_SKEW_TOLERANCE_MS}.
+     *
+     * It reaches exactly one thing, the anomaly threshold, and anomalies change no
+     * verdict. Verification's answer to "does this chain hold" is a function of
+     * the log bytes and the schemas, and no policy — loadable, absent, hostile, or
+     * edited — can move it.
+     */
+    policy?: {
+        dir?: string;
+        file?: string;
+    };
+    /**
+     * The tolerance, already resolved, in milliseconds. Overrides
+     * {@link VerifyOptions.policy} when both are given, and exists so the pure
+     * paths and the tests can state a threshold without a file on disk.
+     */
+    skewToleranceMs?: number;
+    /**
+     * Called as the walk advances, so a caller can say what is taking so long
+     * (APRV-167).
+     *
+     * `approval policy amend` sat silent for thirty-three seconds re-verifying a
+     * three-thousand-record chain before it printed its first line, read as
+     * frozen, and was once abandoned mid-ceremony — which left the repository's
+     * gate fail-closed for every agent session until somebody tried again. The
+     * work was never the problem; the silence was.
+     *
+     * It OBSERVES and never decides. Nothing in the walk consults it, no verdict,
+     * message, line number or record depends on whether it was supplied, and a
+     * listener that throws would fail the verification of a sound log — so
+     * callers must not throw from it. Counts are absolute over the whole log
+     * (a resumed read behind a {@link VerifiedPrefix} reports the same numbers a
+     * cold one does) and strictly increasing within one run. The final call
+     * reports `done === total` when the chain held, and the length of the
+     * verified prefix when it did not — a meter must not claim work that was
+     * refused.
+     */
+    onProgress?: VerifyProgressListener;
+}
+/** How far along a verification walk is. Counts are records, not bytes. */
+export interface VerifyProgress {
+    /** Records verified so far. Monotonically increasing within one run. */
+    done: number;
+    /** Records this run will cover in total, known before the walk starts. */
+    total: number;
+}
+export type VerifyProgressListener = (progress: VerifyProgress) => void;
+/**
+ * How many records pass between progress calls.
+ *
+ * Count-based rather than time-based, and reported here rather than throttled
+ * here: this module has no clock, a listener that fires on a deterministic
+ * schedule is a listener a test can assert on exactly, and the decision about
+ * how often a HUMAN should see a repaint belongs to the thing holding the
+ * terminal (`cli/progress.ts`), which is the only layer that knows whether
+ * there is one.
+ */
+export declare const PROGRESS_INTERVAL = 250;
+/**
+ * A verification run plus the records it verified.
+ *
+ * `records` holds every record the walk accepted, in log order: the whole log
+ * when `result.status` is `clean`, the intact prefix when it is `torn-tail`, and
+ * the prefix before the first failure when it is `corrupt` (where it carries no
+ * authority and callers must ignore it).
+ */
+export interface VerifiedLog {
+    result: VerifyResult;
+    records: EventRecord[];
+}
+/**
+ * {@link verify}, returning the verified records alongside the verdict.
+ *
+ * This exists so that a reader which needs *both* — the gate, the token module,
+ * the executor, via `core/state.ts` — can have one walk produce both, rather
+ * than verifying with this module and then parsing the same bytes a second time
+ * with a private walk that could disagree with it (APRV-20 finding S1).
+ */
+export declare function verifyWithRecords(logPath: string, options?: VerifyOptions): VerifiedLog;
+/**
+ * A prefix of a log that *this process* has already verified in full, together
+ * with the evidence needed to resume behind it.
+ *
+ * Handing one of these to {@link verifyText} skips re-verification of the prefix
+ * entirely, which is sound only under the caller's obligation stated on
+ * {@link records}: the bytes now on disk in `[0, byteLength)` must be proved
+ * byte-identical to the bytes that produced these records. `core/state.ts` is
+ * the only caller, and it discharges that obligation by re-hashing the prefix
+ * bytes on every use. Verification is a pure function of (bytes, schemas,
+ * options), so identical bytes re-verify identically by construction; nothing
+ * weaker (a matching size, a matching mtime, a matching head line) implies it.
+ */
+export interface VerifiedPrefix {
+    /** Byte length of the prefix. Always immediately after a newline. */
+    byteLength: number;
+    /** Number of complete lines in the prefix, for file-absolute line numbers. */
+    lines: number;
+    /** The prefix's chain head, which the resumed walk chains onto. */
+    head: LogHead;
+    /** The records the prefix verified to, in log order. */
+    records: readonly EventRecord[];
+}
+/**
+ * {@link verifyWithRecords} over text already in hand, optionally resuming
+ * behind a {@link VerifiedPrefix}.
+ *
+ * With `prefix === null`, `text` is the whole log and the walk starts at
+ * genesis: this is exactly what {@link verifyWithRecords} does, and the two
+ * share every check, message, and line number as a result. With a `prefix`,
+ * `text` is the *remainder* of the file (the bytes from `prefix.byteLength` on)
+ * and the walk chains onto `prefix.head` with line numbers offset by
+ * `prefix.lines`, so a resumed verdict is textually identical to the cold one.
+ *
+ * Exported for `core/state.ts`'s verified-read cache and for nothing else. Every
+ * schema check, hash recompute, `seq` succession check, and `prev` link check
+ * still runs on every record the walk covers; resuming changes only *which*
+ * records are covered, never how.
+ */
+export declare function verifyText(logPath: string, text: string, options?: VerifyOptions, prefix?: VerifiedPrefix | null): VerifiedLog;
+/**
+ * Verify the hash chain of the log at `logPath`.
+ *
+ * An absent file is an empty log, which is clean with zero records and a `null`
+ * head — an audit trail that has recorded nothing is not evidence of tampering.
+ *
+ * The file is opened for reading only; see the module header for the recovery
+ * stance and the detection boundary. This is {@link verifyWithRecords} with the
+ * records dropped — one walk, one implementation.
+ */
+export declare function verify(logPath: string, options?: VerifyOptions): VerifyResult;