approval-md 0.0.1 → 0.2.0

package/dist/src/daemon/git-evidence.js

@@ -0,0 +1,345 @@
+/**
+ * Per-event git commits — SPEC.md §8's optional hardening (APRV-42).
+ *
+ * > "Optionally, the log directory is a git repo and the daemon commits per
+ * > event with its own identity, giving signed, distributed tamper evidence for
+ * > free."
+ *
+ * The chain in `events.jsonl` already detects mutation and truncation on its
+ * own. What a git repository adds is a *second, independent* record of the same
+ * bytes: a mutation that is plausible against one layer has to be plausible
+ * against the other at the same time, and the second layer is one an operator
+ * can clone, mirror, and diff from somewhere the tamperer does not control.
+ * Neither layer is trusted to police the other, which is the point of having
+ * two: `approval log verify` never consults git, and nothing here ever reads a
+ * verdict out of a commit.
+ *
+ * ## Opt-in, and only for a standalone log deployment
+ *
+ * This is off unless the operator asks for it, and refuses to turn on unless the
+ * log's own directory is a repository *root*. The two layouts do not mix:
+ *
+ * - **Standalone log deployment.** The log home (`.approval/`, or whatever
+ *   directory holds the log when it is not under a `log/` folder) is its own git
+ *   repository, containing the log, the payload store, and nothing else. Enable
+ *   the opt-in here.
+ * - **Nested project layout** — this repository's own dogfood arrangement, where
+ *   `.approval/` is committed as part of a larger project repo. Perfectly valid,
+ *   and the opt-in is REFUSED for it.
+ *
+ * Why refuse the nested case rather than make it work? Because a hash chain does
+ * not survive a merge. Two branches that each append independently produce a
+ * chain that is corrupt by construction, and no merge strategy repairs the
+ * semantics. An outer repository's ordinary history operations — rebase, amend,
+ * squash, force-push, `filter-branch` — rewrite the very bytes the evidence is
+ * made of, and a daemon committing into someone else's branch would be a second
+ * writer to a history the project's humans also write. Evidence that the subject
+ * of the investigation can rewrite is not evidence. So the runtime does not try
+ * to be clever about it: own-root repository, or no git evidence at all.
+ *
+ * ## What it does, precisely
+ *
+ * After every tick in which the log moved, the daemon calls {@link
+ * GitEvidenceRecorder.commit} with the verified head it just read. The recorder
+ * stages the log file and the payload store, and commits with a message naming
+ * the head's `(seq, hash)`. Batching is **one commit per tick**, not literally
+ * one per event: ticks are the only moment the daemon has a verified head in
+ * hand, and a commit is only meaningful against a head that verified. A tick
+ * that observed three appends produces one commit naming the new head and the
+ * number of records it covers — the intermediate states are still fully
+ * recoverable from the log itself, which is the artifact being witnessed.
+ *
+ * ## What it deliberately does not do
+ *
+ * It never pushes, never fetches, never creates or moves a branch by name, never
+ * touches a remote, and never writes to any git config outside the single
+ * `git commit` invocation (identity is passed with `-c`, per command, so the
+ * operator's `user.name` is neither read into the commit nor overwritten on
+ * disk). Commits are local, to the log's own repository, authored by the daemon
+ * as itself. A failure to commit is a warning, never a stop: git evidence is
+ * hardening on top of the chain, and a daemon that halted approvals because a
+ * disk was full of git objects would have converted a redundancy into a
+ * dependency.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { childEnvironment } from "../core/child-env.js";
+import { PAYLOAD_STORE_DIRNAME } from "../core/payload-store.js";
+/**
+ * The daemon's own git identity. Never the operator's: a commit that says a
+ * human made it is a false statement about who wrote the evidence, and the whole
+ * value of the second layer is that its authorship is unambiguous.
+ *
+ * The version is pinned to `package.json` by a test rather than read at runtime,
+ * because a module that resolves its own package root differs between the source
+ * tree and the build output for no benefit at all.
+ */
+export const APPROVALD_VERSION = "0.2.0";
+/** `user.name` on every commit this module makes. */
+export const GIT_EVIDENCE_AUTHOR_NAME = `approvald ${APPROVALD_VERSION}`;
+/** `user.email` on every commit: fixed, and deliberately undeliverable. */
+export const GIT_EVIDENCE_AUTHOR_EMAIL = "approvald@noreply.approval.md";
+/**
+ * Why enabling git evidence was refused. **Frozen union**, additive-only, in the
+ * same sense as every other refusal vocabulary in this codebase (SPEC.md §11.1
+ * invariant 6: refusals are machine-readable and distinct). An operator's
+ * supervisor branches on these to tell "install git" apart from "your layout is
+ * wrong", and the repair differs for every one of them.
+ */
+export const GIT_EVIDENCE_REFUSAL_CODES = [
+    /** No usable `git` on PATH. The daemon runs fine without the opt-in. */
+    "git-unavailable",
+    /** The directory that would hold the evidence repository does not exist. */
+    "log-dir-missing",
+    /** It exists and is not a git repository. The repair is `git init` there. */
+    "log-dir-not-repo",
+    /**
+     * It is inside a working tree it does not own — either some outer repository
+     * tracks it, or it is a repository whose root is somewhere above. Hash chains
+     * do not survive merges and an outer history rewrites evidence.
+     */
+    "log-dir-nested",
+];
+// ---------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------
+/**
+ * The directory that must be the evidence repository's root, for a given log.
+ *
+ * The same rule `payloadStoreDirFor` uses, for the same reason: SPEC.md §9 fixes
+ * the log at `<home>/log/events.jsonl` and the payload store at
+ * `<home>/payloads/`, so the only directory that contains *both* is `<home>`.
+ * Rooting the repository at the log's immediate directory would leave every
+ * payload file outside the evidence, which is precisely where a tamperer would
+ * then work. When a caller points `--log` somewhere flatter, the log's own
+ * directory is the home and the rule still holds.
+ */
+export function evidenceRootFor(logPath) {
+    const logDir = dirname(logPath);
+    return basename(logDir) === "log" ? dirname(logDir) : logDir;
+}
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * One git invocation, non-interactive.
+ *
+ * `GIT_TERMINAL_PROMPT=0` and an emptied `GIT_DIR`/`GIT_WORK_TREE` keep an
+ * inherited environment from redirecting the command at some other repository,
+ * and nothing here ever prompts: a daemon blocked on a credential prompt is a
+ * daemon that has silently stopped.
+ *
+ * The environment is built by the APRV-205 scrub rather than copied. The daemon
+ * spawns no granted command (it advances the log and never executes an action),
+ * so this is not the task's load-bearing case; it is the daemon being the
+ * process that holds the passphrase and the token, and `git log` having no use
+ * for either.
+ */
+function git(args, cwd) {
+    const env = { ...childEnvironment().env, GIT_TERMINAL_PROMPT: "0" };
+    delete env["GIT_DIR"];
+    delete env["GIT_WORK_TREE"];
+    const result = spawnSync("git", args, { cwd, encoding: "utf8", env });
+    if (result.error !== undefined || result.status === null) {
+        return { ok: false, stdout: "", stderr: detail(result.error ?? "git did not run") };
+    }
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+/** A path with symlinks resolved, or the path itself when it cannot be. */
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/** The working tree root containing `dir`, or `null` when there is none. */
+function topLevel(dir) {
+    const result = git(["rev-parse", "--show-toplevel"], dir);
+    if (!result.ok)
+        return null;
+    const root = result.stdout.trim();
+    return root.length === 0 ? null : root;
+}
+/**
+ * Check every precondition and, when they all hold, build the recorder.
+ *
+ * Fail closed and fail *loudly*: each refusal is distinct, names the directory
+ * it judged, and states the repair. An operator who mistyped `--log` and an
+ * operator whose log lives inside a project repository need different sentences,
+ * and a single "git evidence unavailable" would have sent both of them looking
+ * in the wrong place.
+ */
+export function enableGitEvidence(logPath, sink) {
+    const root = evidenceRootFor(logPath);
+    const version = git(["--version"], process.cwd());
+    if (!version.ok) {
+        return {
+            ok: false,
+            code: "git-unavailable",
+            message: `--git-evidence needs a working \`git\` on PATH and none ran (${version.stderr.trim()}); install git, or drop the flag — the daemon's hash chain is unaffected either way`,
+        };
+    }
+    let isDir = false;
+    try {
+        isDir = statSync(root).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        return {
+            ok: false,
+            code: "log-dir-missing",
+            message: `--git-evidence would commit into ${root}, which is not a directory; create the log's home first (the evidence repository is rooted where the log and its payload store both live)`,
+        };
+    }
+    const own = topLevel(root);
+    if (own === null) {
+        return {
+            ok: false,
+            code: "log-dir-not-repo",
+            message: `--git-evidence requires ${root} to be a git repository of its own and it is not one; run \`git init\` in ${root} and re-run. It must be its OWN root: a log tracked by some outer repository is evidence that repository's history operations can rewrite`,
+        };
+    }
+    if (real(own) !== real(root)) {
+        return {
+            ok: false,
+            code: "log-dir-nested",
+            message: `--git-evidence requires ${root} to be its own repository root, and it sits inside the working tree rooted at ${own}. Refused: a hash chain does not survive a merge (two branches appending independently produce a corrupt chain by construction, and no merge strategy repairs it), and an outer repository's rebases, amends and force-pushes rewrite the bytes the evidence is made of. Either run \`git init\` in ${root} so the log deployment stands alone, or run without --git-evidence — the nested layout is fully valid, it just gets its tamper evidence from the chain alone`,
+        };
+    }
+    // An own-root repository can still be *contained* by an outer working tree
+    // (a nested repo inside a project checkout, this repository's own dogfood
+    // shape if someone ran `git init` in `.approval/`). The parent directory is
+    // the only place that shows it, and containment is exactly the hazard: the
+    // outer repo's operations move the directory these commits live in.
+    const parent = dirname(root);
+    if (parent !== root && existsSync(parent)) {
+        const outer = topLevel(parent);
+        if (outer !== null) {
+            return {
+                ok: false,
+                code: "log-dir-nested",
+                message: `--git-evidence requires a standalone log deployment, and ${root} — though a repository root itself — is nested inside the working tree rooted at ${outer}. Refused: the outer repository's history operations rewrite or relocate the directory these commits witness, and a hash chain does not survive a merge. Move the log outside that working tree, or run without --git-evidence (the nested layout is valid; it relies on the chain alone)`,
+            };
+        }
+    }
+    return { ok: true, root, recorder: new GitEvidence(root, logPath, sink) };
+}
+// ---------------------------------------------------------------------------
+// Committing
+// ---------------------------------------------------------------------------
+/**
+ * The recorder proper: stateless except for the last head it committed, which
+ * exists only so a tick with nothing new does no git work at all.
+ */
+class GitEvidence {
+    root;
+    logPath;
+    sink;
+    lastSeq = null;
+    constructor(root, logPath, sink) {
+        this.root = root;
+        this.logPath = logPath;
+        this.sink = sink;
+    }
+    commit(head) {
+        // An empty log has nothing to witness, and a head that has not moved since
+        // the last commit has already been witnessed. Payload files land with the
+        // event that references them, so the head is a sound trigger for both.
+        if (head === null)
+            return;
+        if (this.lastSeq !== null && head.seq <= this.lastSeq)
+            return;
+        const paths = [this.logPath];
+        const payloads = join(this.root, PAYLOAD_STORE_DIRNAME);
+        if (existsSync(payloads))
+            paths.push(payloads);
+        const staged = this.run(["add", "--", ...paths], "add");
+        if (!staged)
+            return;
+        // Nothing staged means the log on disk is byte-identical to the committed
+        // one. That is not a failure and it is not silence worth reporting: it is
+        // the ordinary case for a tick whose appends were already committed.
+        const pending = git(["diff", "--cached", "--quiet"], this.root);
+        if (pending.ok) {
+            this.lastSeq = head.seq;
+            return;
+        }
+        // The batch size, taken from git rather than from a remembered sequence
+        // number: the log is append-only, so staged added lines *are* the records
+        // this commit covers, and the count stays right across a daemon restart
+        // that has no memory of the previous commit at all.
+        const records = this.stagedRecords();
+        const committed = this.run([
+            "-c",
+            `user.name=${GIT_EVIDENCE_AUTHOR_NAME}`,
+            "-c",
+            `user.email=${GIT_EVIDENCE_AUTHOR_EMAIL}`,
+            "-c",
+            "commit.gpgsign=false",
+            "commit",
+            "--no-verify",
+            "--quiet",
+            "-m",
+            message(head, records),
+        ], "commit");
+        if (!committed)
+            return;
+        const sha = git(["rev-parse", "--short", "HEAD"], this.root);
+        this.lastSeq = head.seq;
+        this.sink({
+            event: "git_evidence",
+            commit: sha.ok ? sha.stdout.trim() : "unknown",
+            seq: head.seq,
+            hash: head.hash,
+            records,
+        });
+    }
+    /** Staged added lines of the log file, or `null` when git would not say. */
+    stagedRecords() {
+        const numstat = git(["diff", "--cached", "--numstat", "--", this.logPath], this.root);
+        if (!numstat.ok)
+            return null;
+        const added = numstat.stdout.trim().split("\n")[0]?.split("\t")[0];
+        if (added === undefined)
+            return null;
+        const count = Number(added);
+        return Number.isInteger(count) ? count : null;
+    }
+    /** One git step, reporting a failure as a warning and never throwing. */
+    run(args, step) {
+        const result = git(args, this.root);
+        if (result.ok)
+            return true;
+        this.sink({
+            event: "git_evidence_failed",
+            step,
+            message: `git ${step} in ${this.root} failed: ${(result.stderr.trim() || result.stdout.trim()) === ""
+                ? "no output"
+                : result.stderr.trim() || result.stdout.trim()}; the log itself is untouched and its hash chain is the primary evidence`,
+        });
+        return false;
+    }
+}
+/**
+ * The commit message: the head's `(seq, hash)` on the subject line, so a reader
+ * of `git log --oneline` can check a commit against the chain without opening
+ * anything, and the batch size in the body so the per-tick batching is visible
+ * rather than inferred.
+ */
+export function message(head, records) {
+    const subject = `seq ${String(head.seq)} sha256:${head.hash}`;
+    const covered = records === null
+        ? "record count unavailable"
+        : `${String(records)} record(s) since the previous commit`;
+    return `${subject}\n\napprovald ${APPROVALD_VERSION} tamper evidence: ${covered}.\nOne commit per daemon tick, witnessing the verified head named above.\n`;
+}
+//# sourceMappingURL=git-evidence.js.map

package/dist/src/daemon/git-evidence.js.map

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

package/dist/src/daemon/projection.d.ts

@@ -0,0 +1,180 @@
+/**
+ * The daemon's pure projections (SPEC.md §6.3, §10.2).
+ *
+ * Everything the daemon *decides* lives here, and everything it *does* lives in
+ * `daemon.ts`. The split is the same one `core/loop.ts` draws for loop safety:
+ * a projection over verified records is a pure function of (records, instant,
+ * TTL), so it can be replayed, unit-tested against an injected clock, and never
+ * disagrees with itself between two callers.
+ *
+ * Nothing here reads the clock, the filesystem, or the network, and nothing
+ * here appends. Three questions are answered:
+ *
+ * 1. **What does the log say a task's envelope `state:` should be?**
+ *    {@link taskEnvelopeState}. §6.3: "`state` is a projection of log events;
+ *    the file is updated by the daemon after the event is appended, never the
+ *    reverse." The daemon compares the file's claim against this answer, and a
+ *    file that contradicts it is `envelope.drift`.
+ * 2. **Which live requests have lapsed with no `approval.expired` on record?**
+ *    {@link lapsedRequests}. The gate already judges TTL lazily at decision
+ *    time (a late grant is refused whether or not an expiry event exists), so
+ *    the sweep changes no verdict; it makes the verdict *visible* in the log
+ *    and in every projection built from it.
+ * 3. **Has this exact drift already been recorded?** {@link driftAlreadyLogged}.
+ *    A watcher fires on every save and the periodic tick re-scans regardless,
+ *    so without a dedupe rule one unfixed file would append an unbounded run of
+ *    identical events. The rule is stated on that function.
+ *
+ * The state derivation itself is NOT reimplemented here: every action's state
+ * comes from `core/state.ts`'s `requestState`, the same derivation the gate,
+ * the token module, and the executor read. This module only rolls action states
+ * up to the task level, and that rollup is the one new rule it owns.
+ */
+import type { EventRecord } from "../core/log.js";
+import { type RequestDerivation } from "../core/state.js";
+/**
+ * The envelope's `state:` vocabulary (`envelope.schema.json`, SPEC.md §6.3).
+ *
+ * Spelled here rather than imported from the schema because the schema is data
+ * read at runtime and this is a type; `tests/daemon-projection.test.ts` pins the
+ * two against each other so they cannot drift apart.
+ */
+export declare const ENVELOPE_STATES: readonly ["proposed", "awaiting", "approved", "executed", "rejected", "expired", "revoked"];
+export type EnvelopeState = (typeof ENVELOPE_STATES)[number];
+/** Is this the envelope's `state:` value? Used to read an untrusted file. */
+export declare function isEnvelopeState(value: unknown): value is EnvelopeState;
+/** One declared action of a task, as the log records it, with its derived state. */
+export interface ActionProjection {
+    actionKey: string;
+    derivation: RequestDerivation;
+}
+/** What the log says about one task. */
+export interface TaskProjection {
+    task: string;
+    /** A `task.registered` record exists for this task id. */
+    registered: boolean;
+    /** The envelope `state:` the log implies (SPEC.md §6.3). */
+    state: EnvelopeState;
+    /** Every action key the latest registration declared, with its derivation. */
+    actions: ActionProjection[];
+}
+/** Every action key the latest `task.registered` for `task` declared, in order. */
+export declare function registeredActionKeys(records: EventRecord[], task: string): string[];
+/**
+ * The envelope `state:` the log implies for `task`, at instant `ts`.
+ *
+ * ## The rollup rule, stated once
+ *
+ * §6.3's lifecycle is drawn for one action; a task may declare several, so the
+ * projection needs a rule for a task whose actions disagree. It is this, in
+ * order, and the order is the point:
+ *
+ * 1. any action with a live request → **awaiting**. A human owes an answer, and
+ *    that fact outranks every other, because it is the only state that asks
+ *    something of a person.
+ * 2. else any granted action that has not executed → **approved**.
+ * 3. else any action with an `execution.completed` → **executed**.
+ * 4. else **revoked**, then **rejected**, then **expired** — human decisions
+ *    outrank a runtime lapse, so a task with one revoked and one expired action
+ *    reads as revoked, naming the decision a person actually made.
+ * 5. else **proposed**: registered (or not) and nothing has happened.
+ *
+ * A task with exactly one action — the common case — collapses to §6.3's
+ * lifecycle exactly, which is the property the rule was chosen for.
+ *
+ * An unregistered task projects to `proposed`: the log knows of no declaration,
+ * so nothing has been proposed *to the gate* yet. A file claiming `approved`
+ * for a task the log never registered therefore contradicts the log, which is
+ * exactly the reading §6.3 wants.
+ */
+export declare function taskEnvelopeState(records: EventRecord[], task: string, ts: string, ttlMs: number | null): TaskProjection;
+/** One request the TTL sweep would materialise an `approval.expired` for. */
+export interface LapsedRequest {
+    actionKey: string;
+    task: string | null;
+    /** The `ts` of the `approval.requested` that lapsed. */
+    requestedTs: string | null;
+}
+/**
+ * Live requests whose TTL has lapsed and which carry no `approval.expired`.
+ *
+ * Idempotence is structural rather than remembered: the answer is re-derived
+ * from the verified log every sweep, and an action whose expiry has been
+ * appended no longer satisfies the predicate. Two sweeps over the same log
+ * therefore produce the same list, and a sweep that follows a successful one
+ * produces an empty list — with no state carried between them, and no way for a
+ * restarted daemon to expire something twice.
+ *
+ * `ttlMs === null` (a policy that declares no `defaults.approval_ttl`) yields no
+ * candidates at all: nothing lapses when nothing was bounded, and inventing a
+ * deadline is not the daemon's to invent.
+ *
+ * Returned in first-request order, so a sweep's appends land in a deterministic
+ * sequence.
+ */
+export declare function lapsedRequests(records: EventRecord[], ts: string, ttlMs: number | null): LapsedRequest[];
+/**
+ * Why an `envelope.drift` record was written (APRV-63).
+ *
+ * `state-mismatch` is the original reading of SPEC.md §6.3: the file makes a
+ * claim about `state:` and the log implies another one. `envelope-missing` is
+ * the loss case observed live in APRV-60: the log holds a `task.registered` for
+ * the task, and the file that declared it now carries no `approval:` key at all.
+ * They are separated because they call for different human actions — one is an
+ * edit to reconcile, the other is a *deletion to restore* — and a reader who
+ * could not tell them apart would treat a lost envelope as a stale one.
+ *
+ * `reason` is absent from records written before this vocabulary existed;
+ * readers (including {@link driftAlreadyLogged}) treat absence as
+ * `state-mismatch`, which is what every such record was.
+ */
+export declare const DRIFT_REASONS: readonly ["state-mismatch", "envelope-missing"];
+export type DriftReason = (typeof DRIFT_REASONS)[number];
+export { latestRegistration } from "../core/registration.js";
+/** The facts one `envelope.drift` record carries, and the dedupe key. */
+export interface DriftFacts {
+    /** The `state:` the file claims, or `null` when it declares none. */
+    declaredState: string | null;
+    /** The state the log implies (SPEC.md §6.3). */
+    derivedState: EnvelopeState;
+    /**
+     * SHA-256 over the RFC 8785 form of the file's whole `approval:` envelope, or
+     * `null` when the envelope could not be canonicalized. Part of the dedupe key
+     * so that editing a file from one contradiction into a different one is a new
+     * drift and not a suppressed one.
+     */
+    envelopeDigest: string | null;
+    /**
+     * Which kind of drift this is (APRV-63). Part of the dedupe key: a file that
+     * contradicts the log and a file that lost its envelope are different facts
+     * about the same task, and neither may suppress the other. Absent means
+     * `state-mismatch`, matching every record written before the vocabulary
+     * existed.
+     */
+    reason?: DriftReason;
+}
+/**
+ * Has this exact drift already been recorded for `task`?
+ *
+ * The rule: compare against the **latest** `envelope.drift` for the task. Equal
+ * `(reason, declared_state, derived_state, envelope_sha256)` means the situation
+ * the log already describes is the situation now, so nothing is appended. Any
+ * difference
+ * — the human edited the file again, or the log moved and the derived state
+ * changed — is a new fact and is recorded.
+ *
+ * Comparing against the latest record rather than against any record is
+ * deliberate: a task that drifts, is repaired, and drifts the same way again has
+ * genuinely drifted twice, and an audit that collapsed those into one would be
+ * hiding a repetition from the person whose attention this system spends.
+ *
+ * For `envelope-missing` (APRV-63) the same rule reads as: one record per
+ * episode of loss, re-derived every tick from the file and the log rather than
+ * remembered, and a new record when the derived state moves underneath a file
+ * that is still stripped. Its limit is stated where it is felt: a file whose
+ * envelope is restored by hand *in agreement with the log* leaves no record of
+ * the restoration, so a second loss at the same derived state reads as the same
+ * episode and is not appended twice. Recording the restoration would need an
+ * event nobody has specified; detection does not invent one.
+ */
+export declare function driftAlreadyLogged(records: EventRecord[], task: string, facts: DriftFacts): boolean;