approval-md 0.0.1 → 0.2.0

package/dist/src/core/attest.js

@@ -0,0 +1,589 @@
+/**
+ * Policy attestation (SPEC.md §5.2, §11) — the mechanical form of "agents MUST
+ * NOT be able to modify `APPROVAL.md`".
+ *
+ * The problem this solves is not that an agent *can* edit the policy file — on
+ * a single machine nothing stops it — but that an edited policy would otherwise
+ * take effect silently. Attestation closes that: a human runs
+ * `approval policy attest`, which appends a `policy.updated` event carrying the
+ * SHA-256 of the policy file's exact bytes. From then on the live file either
+ * hashes to the latest attestation or it does not, and {@link checkAttestation}
+ * says which. Gate operations (request intake, grant recording, token minting —
+ * APRV-16) refuse on anything but a match. An edited policy is inoperative
+ * until a human re-attests it.
+ *
+ * ## What this proves, and what it does not
+ *
+ * Human identity at v0.1 is **config-declared**: `--as human:<id>` or the
+ * `APPROVAL_HUMAN` environment variable (see {@link resolveHumanActor}). The
+ * trust boundary is the local machine. Anyone who can set that environment
+ * variable and write to the log is inside the boundary, so an attestation
+ * proves that *someone with local control* signed off — not *who*. There is no
+ * cryptographic identity here and this module claims none; that is future work,
+ * stated plainly rather than dressed up. What attestation buys, even so, is
+ * real: a policy edit made by an agent mid-run cannot become operative without
+ * a separate, deliberate, logged human act.
+ *
+ * ## Fail closed, in this order
+ *
+ * A policy file that cannot be read is `unreadable`, never `attested`. No
+ * attestation at all is `not-attested`. Bytes that do not match the latest
+ * attestation are `hash-mismatch`. Only an exact match is `attested`.
+ *
+ * Everything here is read-only except {@link appendAttestation}, which writes
+ * through `core/log.ts`'s `appendEvent` — the one sanctioned append path — and
+ * therefore inherits its locking, chain stamping, and write-boundary schema
+ * validation. Nothing in this file opens the log itself.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { tick } from "./clock.js";
+import { builtinProtectedPathClass, isGateOrganPath, normalizePathSpelling, } from "./command-class.js";
+import { APPEND_ERROR_CODES, appendEvent, } from "./log.js";
+/**
+ * Actors permitted to attest. Deliberately narrower than the event schema's
+ * `^(human|agent|system):.+`: attestation is the one verb an agent must not be
+ * able to perform, so `agent:` and `system:` are refused here — in code, not
+ * only in prose.
+ */
+const HUMAN_ACTOR = /^human:.+/;
+/** Environment variable naming the human on whose behalf the CLI attests. */
+export const HUMAN_ACTOR_ENV = "APPROVAL_HUMAN";
+/**
+ * The machine-readable refusal code emitted when policy is not attested.
+ *
+ * Deliberately distinct from any generic policy-load failure. A caller must be
+ * able to tell "the policy says manual" from "the policy is unverified", because
+ * the repairs are different: the first is answered by asking a human to approve
+ * an action, the second by asking a human to attest a file.
+ */
+export const ATTESTATION_REFUSAL = "policy-not-attested";
+/**
+ * The payload field carrying the attested policy hash a gate event was decided
+ * under (APRV-118, amended SPEC.md §5.2).
+ *
+ * Written on `approval.requested` and `approval.granted`, and named here rather
+ * than in `core/gate.ts` because the value is this module's: it is the SHA-256
+ * the live policy file matched when {@link checkAttestation} said `attested`.
+ * Pinning it lets a reader of the log answer a question attestation alone cannot
+ * — whether the approver decided under the rules the requester was routed by.
+ */
+export const POLICY_HASH_FIELD = "policy_sha256";
+/** Is `value` a lowercase-hex SHA-256, the shape {@link POLICY_HASH_FIELD} takes? */
+export function isPolicySha256(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+}
+/**
+ * Why an attestation append failed: every reason `appendEvent` can give, plus
+ * the one rule this module enforces on its own.
+ *
+ * ### Why `actor-not-human` lives here and not in `core/log.ts`
+ *
+ * Until APRV-20 pass two the non-human-actor refusal reused `validation`, which
+ * conflated two different facts: "the record failed `event.schema.json` at the
+ * write boundary" and "the caller is not allowed to perform this verb". A
+ * caller branching on `validation` could not tell a malformed event from a
+ * forbidden one, and the two call for opposite responses (fix the record;
+ * fetch a human).
+ *
+ * The fix does **not** add the code to `APPEND_ERROR_CODES`. That union is the
+ * log writer's vocabulary — the ways a byte can fail to reach the file — and
+ * "only humans may attest" is a fact about attestation, not about writing.
+ * Widening the writer's union to carry a caller's policy rule would oblige every
+ * future append site to consider a code that can only ever come from this one,
+ * and would make `core/log.ts` the place people look for permission rules.
+ * Instead this module widens the union *for itself*: `AppendResult` remains
+ * assignable to {@link AttestationAppendResult}, so nothing downstream is
+ * forced to change, and the CLI adds one case.
+ */
+export const ATTEST_ERROR_CODES = [...APPEND_ERROR_CODES, "actor-not-human"];
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * SHA-256 (lowercase hex) of a file's **exact bytes**.
+ *
+ * Bytes, not text: no encoding round-trip, no newline normalization, no parse.
+ * A policy file that differs only in trailing whitespace is a different policy
+ * file as far as attestation is concerned, which is the conservative reading
+ * and the only one that survives an adversary who knows what gets normalized.
+ *
+ * Throws if the file cannot be read; callers that need a status rather than an
+ * exception use {@link checkAttestation}, which converts that into
+ * `unreadable`.
+ */
+export function policyFileHash(path) {
+    return policyBytesHash(readFileSync(path));
+}
+/**
+ * SHA-256 (lowercase hex) of policy bytes a caller has already read.
+ *
+ * The same digest {@link policyFileHash} computes, over bytes rather than a
+ * path. It exists so a gate operation can read `APPROVAL.md` once and hash the
+ * exact buffer it is also about to parse (APRV-142): hashing by path a second
+ * time would reopen the window where the attestation check and the parse can
+ * see different bytes.
+ */
+export function policyBytesHash(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Append a `policy.updated` attestation for `policyPath` to `logPath`.
+ *
+ * `actor` MUST match `^human:.+`. An `agent:` or `system:` actor is refused
+ * before anything is read or written — the refusal is a structured result,
+ * never a throw, consistent with the rest of the write path. Its code is
+ * `actor-not-human`, this module's own (see {@link ATTEST_ERROR_CODES}): the
+ * actor failed the rule *this verb* enforces, which is a different fact from a
+ * record failing the event schema, and the two used to share `validation`.
+ *
+ * The event is deliberately minimal:
+ *
+ * ```json
+ * { "event": "policy.updated", "actor": "human:alice",
+ *   "payload": { "policy_path": "APPROVAL.md", "sha256": "<64 hex>" } }
+ * ```
+ *
+ * `policy_path` is the **basename**, not the absolute path: the log is meant to
+ * be copied, exported, and read on other machines, and an absolute path would
+ * leak the writer's home directory into a permanent record while saying nothing
+ * a reader can use. `sha256` is the file's byte digest — the field
+ * {@link checkAttestation} compares against.
+ *
+ * `ts` is **not** a parameter. `policy.updated` is one of the gate-typed events
+ * of amended SPEC.md §8 (A2), so its timestamp is assigned by the runtime at the
+ * write boundary — read once from {@link AttestOptions.clock}, which defaults to
+ * the real clock and which tests inject. Attestation is the verb that decides
+ * which policy bytes are operative from a moment onward; a caller that could
+ * choose that moment could backdate the answer.
+ *
+ * ## Why this append carries no `expectedHead` (APRV-20 finding B1)
+ *
+ * Every *other* append site in the codebase reads the log, decides something
+ * from what it read, and must therefore prove the log has not moved before it
+ * writes. This one does not read the log at all. Its only precondition is the
+ * actor check and the policy file's bytes — neither of which the log can
+ * invalidate — so there is no check-then-act window to close. A concurrent
+ * appender simply means this attestation lands after that record, which is
+ * correct: attestation is an unconditional assertion about a file's bytes at a
+ * moment, and the *latest* attestation is the one `checkAttestation` honors.
+ * Passing a precondition here would only manufacture spurious failures.
+ */
+export function appendAttestation(logPath, policyPath, actor, options = {}) {
+    if (!HUMAN_ACTOR.test(actor)) {
+        return {
+            ok: false,
+            error: {
+                code: "actor-not-human",
+                message: `attestation requires a human actor matching ^human:.+, got ${JSON.stringify(actor)}; attestation is the one verb an agent must not perform, and the log was left unchanged`,
+            },
+        };
+    }
+    let sha256;
+    try {
+        // One read supplies both the expected-digest check and the recorded digest.
+        // A later edit naturally leaves the live policy hash-mismatched; it cannot
+        // make this record attest bytes other than the ones checked here.
+        sha256 = policyBytesHash(readFileSync(policyPath));
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            error: {
+                code: "io",
+                message: `policy ${policyPath} could not be read for attestation: ${detail(cause)}`,
+            },
+        };
+    }
+    if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256) {
+        return {
+            ok: false,
+            error: {
+                code: "io",
+                message: `policy ${policyPath} changed after the reviewed bytes were shown; expected sha256 ${options.expectedSha256}, found ${sha256}; the log was left unchanged`,
+            },
+        };
+    }
+    return appendEvent(logPath, {
+        ts: tick(options),
+        event: "policy.updated",
+        actor,
+        payload: { policy_path: basename(policyPath), sha256 },
+    }, options);
+}
+/**
+ * Is this record an attestation — a `policy.updated` carrying a `sha256`?
+ *
+ * `policy.updated` records **without** a `payload.sha256` are ignored for
+ * attestation purposes. Two reasons, one forward and one backward: the event
+ * type predates this verb (SPEC.md §8 has always had it, and the schema keeps
+ * it base-only with no required payload fields), so pre-attestation logs and
+ * hand-rolled tooling may carry `policy.updated` events that assert nothing
+ * about bytes; and treating such a record as an attestation would mean a
+ * payload-less event could *satisfy* the guard, which is exactly backwards.
+ * Ignoring them means an old log reads as `not-attested` — fail closed.
+ */
+function attestationSha256(record) {
+    if (record.event !== "policy.updated")
+        return null;
+    const payload = record.payload;
+    if (payload === undefined)
+        return null;
+    const value = payload["sha256"];
+    return typeof value === "string" ? value : null;
+}
+/**
+ * Compare the live policy file against the latest attestation in `records`.
+ *
+ * `records` is the log in append order, as a caller has already read and
+ * verified it; this function does no I/O on the log and never writes. The
+ * **latest** attestation wins — re-attesting after an edit is the supported
+ * repair, and an older attestation must not be able to vouch for bytes that a
+ * newer one already disagreed with.
+ *
+ * `payload.policy_path` is recorded but deliberately **not** matched against
+ * `policyPath`: v0.1 has exactly one policy file per approval home (SPEC.md
+ * §5), and a filename filter would let an attestation of `APPROVALS.md` and a
+ * live `APPROVAL.md` drift apart silently. Comparing only bytes means the
+ * mismatch surfaces as a mismatch.
+ */
+export function checkAttestation(records, policyPath) {
+    // Read the live file first: unreadable is its own status, and it outranks
+    // "never attested" because it is the fact we are most sure of.
+    let bytes;
+    try {
+        bytes = readFileSync(policyPath);
+    }
+    catch (cause) {
+        return unreadablePolicyStatus(policyPath, detail(cause));
+    }
+    return checkAttestationOfBytes(records, bytes);
+}
+/** The `unreadable` status for a policy read the caller performed itself. */
+export function unreadablePolicyStatus(policyPath, cause) {
+    return {
+        status: "unreadable",
+        message: `policy ${policyPath} could not be read: ${cause}`,
+    };
+}
+/**
+ * {@link checkAttestation} against bytes the caller already holds.
+ *
+ * Same comparison, no read. A gate operation reads the policy file once and
+ * passes that one buffer here and to the parser (APRV-142), which is what makes
+ * "attested one policy, enforced another" structurally impossible rather than
+ * merely unlikely.
+ *
+ * The `unreadable` status has no counterpart here: bytes that exist were read.
+ * A caller whose read failed calls {@link unreadablePolicyStatus} instead, so
+ * the fail-closed ordering of {@link checkAttestation} survives the split.
+ */
+export function checkAttestationOfBytes(records, bytes) {
+    const liveSha256 = policyBytesHash(bytes);
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const record = records[index];
+        const attested = attestationSha256(record);
+        if (attested === null)
+            continue;
+        if (attested === liveSha256) {
+            return { status: "attested", seq: record.seq, sha256: liveSha256 };
+        }
+        return {
+            status: "hash-mismatch",
+            attestedSha256: attested,
+            liveSha256,
+            seq: record.seq,
+        };
+    }
+    return { status: "not-attested" };
+}
+/**
+ * The refusal for a non-`attested` status, or `null` when policy is attested.
+ *
+ * One code (`policy-not-attested`) with a `detail` discriminator, rather than
+ * three codes: a caller that wants to refuse needs to branch on one value, and
+ * a caller that wants to explain has `detail` and `message`.
+ */
+export function attestationRefusal(status) {
+    switch (status.status) {
+        case "attested":
+            return null;
+        case "not-attested":
+            return {
+                code: ATTESTATION_REFUSAL,
+                detail: "not-attested",
+                message: "the policy file has never been attested; a human must run `approval policy attest` before gated operations can proceed",
+            };
+        case "hash-mismatch":
+            return {
+                code: ATTESTATION_REFUSAL,
+                detail: "hash-mismatch",
+                message: `the policy file has changed since it was attested at seq ${status.seq} (attested ${status.attestedSha256}, live ${status.liveSha256}); an edited policy is inoperative until a human re-attests it`,
+            };
+        case "unreadable":
+            return {
+                code: ATTESTATION_REFUSAL,
+                detail: "unreadable",
+                message: `${status.message}; an unverifiable policy is treated as unattested`,
+            };
+    }
+}
+/**
+ * The human identity to record as `actor`, or `null` when none is declared.
+ *
+ * Precedence: `options.actor` (the CLI's `--as`) first, then the
+ * `APPROVAL_HUMAN` environment variable. An explicit `--as` that does not match
+ * `^human:.+` yields `null` rather than falling back to the environment —
+ * silently substituting a different identity for the one the caller typed would
+ * be worse than refusing.
+ *
+ * This is **config-declared identity**. The trust boundary is the local
+ * machine: whoever can set `APPROVAL_HUMAN` and write to the log is inside it.
+ * v0.1 makes no cryptographic claim about who attested, only that a locally
+ * privileged act occurred and was recorded.
+ */
+export function resolveHumanActor(options = {}) {
+    const explicit = options.actor;
+    if (explicit !== undefined) {
+        return HUMAN_ACTOR.test(explicit) ? explicit : null;
+    }
+    const fromEnv = process.env[HUMAN_ACTOR_ENV];
+    if (fromEnv !== undefined && HUMAN_ACTOR.test(fromEnv))
+        return fromEnv;
+    return null;
+}
+// ===========================================================================
+// Organ attestation (APRV-272, amended SPEC.md §5.2 and §8)
+// ===========================================================================
+/**
+ * The event an ORGAN attestation is: a human's sign-off on the exact bytes of
+ * one of the gate's own organ files.
+ *
+ * ## Why the organs need this at all
+ *
+ * `.claude/settings.json` and Cursor's hook files classify `policy.core`, and
+ * `policy.core` is human-only in this repository's policy and inert to agents
+ * by §11.1 invariant 9. So the gate mints NOTHING for them: `core/gate.ts`
+ * refuses a human-only class before any record is appended, which means the
+ * protected-path guard's `granted-file` and `granted-command` verdicts cannot
+ * exist for an organ, however correctly a human edited it. PR #300 is that hole,
+ * exactly: a human hand-committed hook entries and CI failed the change because
+ * the only evidence the guard could accept was evidence the gate is designed
+ * never to produce.
+ *
+ * Attestation is the primitive that already fits. It records "a human saw these
+ * exact bytes", it needs no grant, and it matches CONTENT rather than a path, so
+ * the guard can hash the blob at head and ask the log about it.
+ *
+ * ## Why a separate event type
+ *
+ * `core/log.ts`'s `EventType` note carries the argument in full. In one line:
+ * every reader of the POLICY attestation selects on `event === "policy.updated"`,
+ * so a distinct type is invisible to all of them by construction, and
+ * {@link checkAttestationOfBytes} returns at the first `sha256`-bearing record
+ * it meets scanning backwards — an organ record wearing `policy.updated` would
+ * have made a correctly attested policy read as `hash-mismatch`.
+ */
+export const ORGAN_ATTESTATION_EVENT = "gate.organ.attested";
+/**
+ * The payload field naming which organ was attested.
+ *
+ * Repository-relative and `/`-separated, never absolute: the log is meant to be
+ * copied and read on other machines, and an absolute path would leak the
+ * writer's home directory into a permanent record. Unlike the policy
+ * attestation, which records a BASENAME because v0.1 has exactly one policy file
+ * per approval home, an organ record has to carry the whole relative path —
+ * there are several organs, they live in different directories, and the guard's
+ * rule is that a digest attested for one path is not evidence for another.
+ */
+export const ORGAN_PATH_FIELD = "organ_path";
+/**
+ * Why an organ attestation was refused: the policy attestation's codes, plus
+ * the two rules this verb has of its own.
+ *
+ * Two codes and not one, because the repairs are different and a caller must be
+ * able to tell them apart. `path-is-policy` means the caller aimed the organ
+ * verb at the policy file, whose attestation is `approval policy attest` with no
+ * `--organ` and which the gate reads on every operation. `path-not-organ` covers
+ * everything else the runtime will not attest this way: the approval home, whose
+ * contents are the human's own ceremony surface, and any ordinary file, which is
+ * not part of the gate and needs no attestation to be edited.
+ */
+export const ORGAN_ATTEST_ERROR_CODES = [
+    ...ATTEST_ERROR_CODES,
+    "path-not-organ",
+    "path-is-policy",
+];
+/**
+ * Append a `gate.organ.attested` record for `target` to `logPath`.
+ *
+ * The rules, all of them refused as structured results and never as throws, in
+ * the order they are checked:
+ *
+ * 1. `actor` MUST match `^human:.+`. Attestation is the verb an agent must not
+ *    perform, and it is refused here in code and again at the CLI, exactly as
+ *    {@link appendAttestation} is.
+ * 2. The path must be repository-relative: absolute paths and `..` are refused,
+ *    because the recorded identity has to mean the same file on the machine
+ *    that later reads the log.
+ * 3. The policy file is refused with its own code. It has its own attestation
+ *    and the gate reads it on every operation; letting the organ verb write a
+ *    record about it would create a second thing that looks like a policy
+ *    attestation and is not one.
+ * 4. The path must be a gate organ ({@link isGateOrganPath}). Nothing else is
+ *    attestable this way, so the verb cannot be turned into a general
+ *    "bless these bytes" primitive for any file at all.
+ *
+ * The digest is computed by the runtime from the file's exact bytes. There is
+ * no parameter for it, which is the same reason there is no `ts` parameter: a
+ * caller who could supply the hash could attest bytes nobody read, and a caller
+ * who could supply the moment could backdate what was operative when.
+ *
+ * Like {@link appendAttestation} this append carries no `expectedHead`. It reads
+ * nothing from the log, so it has no check-then-act window to close; a
+ * concurrent appender only means this record lands after theirs.
+ */
+export function appendOrganAttestation(logPath, target, actor, options = {}) {
+    if (!HUMAN_ACTOR.test(actor)) {
+        return {
+            ok: false,
+            error: {
+                code: "actor-not-human",
+                message: `attesting a gate organ requires a human actor matching ^human:.+, got ${JSON.stringify(actor)}; the organs are the files that install the hook, so an agent that could attest one could vouch for its own way out of the gate, and the log was left unchanged`,
+            },
+        };
+    }
+    const refusal = organPathRefusal(target.path);
+    if (refusal !== null)
+        return { ok: false, error: refusal };
+    const organPath = normalizePathSpelling(target.path);
+    let sha256;
+    try {
+        sha256 = policyFileHash(join(target.root, organPath));
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            error: {
+                code: "io",
+                message: `gate organ ${organPath} could not be read under ${target.root} for attestation: ${detail(cause)}`,
+            },
+        };
+    }
+    return appendEvent(logPath, {
+        ts: tick(options),
+        event: ORGAN_ATTESTATION_EVENT,
+        actor,
+        payload: { [ORGAN_PATH_FIELD]: organPath, sha256 },
+    }, options);
+}
+/** Rules 2 to 4 of {@link appendOrganAttestation}, or `null` when the path passes. */
+function organPathRefusal(candidate) {
+    const normalized = normalizePathSpelling(candidate);
+    if (normalized.length === 0 || isAbsolute(candidate) || normalized.split("/").includes("..")) {
+        return {
+            code: "path-not-organ",
+            message: `${JSON.stringify(candidate)} is not a repository-relative path; an organ attestation records the path itself, so it must name the same file on every machine that later reads the log`,
+        };
+    }
+    if (isGateOrganPath(normalized))
+        return null;
+    if (builtinProtectedPathClass(normalized) === "policy.core") {
+        const last = normalized.split("/").pop() ?? normalized;
+        if (POLICY_FILE_NAMES.includes(last)) {
+            return {
+                code: "path-is-policy",
+                message: `${normalized} is the policy file, not a gate organ; its attestation is \`approval policy attest\` with no --organ, and the gate reads that one on every operation`,
+            };
+        }
+        return {
+            code: "path-not-organ",
+            message: `${normalized} is inside the approval home, which is the human's own ceremony surface and is not attested this way; the gate organs are the harness files that install the hook`,
+        };
+    }
+    return {
+        code: "path-not-organ",
+        message: `${normalized} does not classify policy.core, so it is not one of the gate's organs; only the harness files that install the hook are attested by content, and an ordinary protected path is edited through the gate and evidenced by the grant`,
+    };
+}
+/**
+ * The policy filenames, for the one refusal that has to name them.
+ *
+ * Spelled here rather than imported from `core/policy-load.ts`: this module is
+ * below the policy loader and stays there, and the two candidate names are a
+ * SPEC.md §5 constant rather than a loader detail.
+ */
+const POLICY_FILE_NAMES = ["APPROVAL.md", "APPROVALS.md"];
+/**
+ * Is this record an organ attestation, and which bytes of which file does it
+ * vouch for?
+ *
+ * A record missing either field is ignored, for the reason a `policy.updated`
+ * with no `sha256` is ignored: a record that asserts nothing about bytes must
+ * never be able to SATISFY a check about bytes. Fail closed.
+ */
+export function organAttestationOf(record) {
+    if (record.event !== ORGAN_ATTESTATION_EVENT)
+        return null;
+    const payload = record.payload;
+    if (payload === undefined)
+        return null;
+    const organPath = payload[ORGAN_PATH_FIELD];
+    const sha256 = payload["sha256"];
+    if (typeof organPath !== "string" || typeof sha256 !== "string")
+        return null;
+    const normalized = normalizePathSpelling(organPath);
+    if (normalized.length === 0)
+        return null;
+    return { organPath: normalized, sha256 };
+}
+/**
+ * The record in which a human attested THIS digest FOR THIS path, latest first,
+ * or `null`.
+ *
+ * Both halves are required and that is the whole rule: a digest attested for
+ * some other organ is not evidence for this one. Two organ files with identical
+ * bytes (two checkouts of the same hook entry, say) are still two files, and a
+ * human who signed one has said nothing about the other.
+ *
+ * Unlike the policy attestation there is no "latest wins" supersession here.
+ * Every organ attestation stands for the bytes it names: the guard asks about a
+ * blob at a commit that may be months old, and the newest attestation of a file
+ * says nothing about whether an older set of bytes was once signed off. The
+ * gate reads none of these records, so a stale one authorizes nothing on its
+ * own — it is evidence about a change, and evidence does not expire the way an
+ * operative policy does.
+ */
+export function findOrganAttestation(records, organPath, sha256) {
+    const want = normalizePathSpelling(organPath);
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const record = records[index];
+        const fields = organAttestationOf(record);
+        if (fields === null)
+            continue;
+        if (fields.organPath === want && fields.sha256 === sha256)
+            return record;
+    }
+    return null;
+}
+/**
+ * The most recent attestation of `organPath` at ANY digest, or `null`.
+ *
+ * What a status surface needs to tell "this file has never been attested" from
+ * "this file was attested and has been edited since". Nothing enforcing reads
+ * it: {@link findOrganAttestation} is the question the guard asks.
+ */
+export function latestOrganAttestation(records, organPath) {
+    const want = normalizePathSpelling(organPath);
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const record = records[index];
+        const fields = organAttestationOf(record);
+        if (fields === null)
+            continue;
+        if (fields.organPath === want)
+            return { ...fields, record };
+    }
+    return null;
+}
+//# sourceMappingURL=attest.js.map

package/dist/src/core/attest.js.map

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