imbas-verify 0.0.0-stage → 0.1.1

package/verify.d.ts

@@ -0,0 +1,6 @@
+import type { Args } from "./args.js";
+/** Runs verify. Returns 0 or 1, naming the first check that failed. */
+export declare function runVerify(args: Args, writers: {
+    out(t: string): void;
+    err(t: string): void;
+}): number;

package/verify.js

@@ -0,0 +1,145 @@
+/**
+ * The verify command, separated from `attest.ts` so it can be published.
+ *
+ * `attest.ts` holds five commands, four of which need the engine: the signing key, the
+ * data dir, the job store, the pipeline. `verify` needs none of them — it reads a record,
+ * a public key and a patch, and answers. Keeping it in the same module meant that
+ * importing the verifier pulled `loadConfig`, and `config.ts` reads `.env`. Measured: a
+ * child process importing `dist/cli/attest.js` with a `.env` in its cwd gained all 25
+ * names from that file.
+ *
+ * This file is the verifier's entry point and it imports nothing from the engine's
+ * configuration, storage or pipeline. Everything it needs is in `evidence/`.
+ */
+import { resolve } from "node:path";
+import { readAttestationFile, verifyAttestation, } from "./attestation.js";
+import { tryKeyIdOfPem } from "./key.js";
+import { describeVerdict, readRetirementList, verifyListSignature, } from "./retirement.js";
+import { describeListSignature } from "./describe.js";
+import { readBinaryFile, readTextFile } from "./read-file.js";
+/** Runs verify. Returns 0 or 1, naming the first check that failed. */
+export function runVerify(args, writers) {
+    const pems = [];
+    for (const path of args.keys) {
+        const read = readTextFile(resolve(path));
+        if (!read.ok) {
+            writers.err(`FAILED at "${read.check}": ${read.message}\n`);
+            return 1;
+        }
+        pems.push(read.text);
+    }
+    const fileRead = readAttestationFile(resolve(args.file));
+    if (!fileRead.ok) {
+        writers.err(`FAILED at "${fileRead.check}": ${fileRead.message}\n`);
+        return 1;
+    }
+    const patchRead = args.patch ? readBinaryFile(resolve(args.patch)) : null;
+    if (patchRead && !patchRead.ok) {
+        writers.err(`FAILED at "${patchRead.check}": ${patchRead.message}\n`);
+        return 1;
+    }
+    const patch = patchRead?.ok ? patchRead.bytes : undefined;
+    /*
+     * The retirement list is read before verifying, so a list the verifier cannot read is
+     * reported as itself rather than as a record failure. A malformed list says nothing
+     * about the record, and blaming the record for it would send a reader to the wrong file.
+     */
+    let retirements = null;
+    let listSignature = null;
+    if (args.retirements) {
+        const listRead = readRetirementList(resolve(args.retirements));
+        if (!listRead.ok) {
+            writers.err(`FAILED at "${listRead.code}": ${listRead.message}\n`);
+            return 1;
+        }
+        if (!listRead.found) {
+            // Named rather than silently empty. An operator who pointed at the wrong path would
+            // otherwise get a clean "not listed" verdict about every key in the world.
+            writers.err(`FAILED at "retirements_unreadable": ${resolve(args.retirements)} does not exist. A list that was never found cannot say a key is not retired.\n`);
+            return 1;
+        }
+        /*
+         * The list's own signature is checked *before* any entry is used.
+         *
+         * This is the order that matters. Reading entries first and checking the signature
+         * afterwards would mean acting on unauthenticated input for the length of one bug —
+         * exactly the mistake `verifyAttestation` is built to avoid, and the reason it parses
+         * the statement only after the bytes are known to be the signed ones.
+         */
+        let policyPem = null;
+        if (args.retirementsKey) {
+            const keyRead = readTextFile(resolve(args.retirementsKey));
+            if (!keyRead.ok) {
+                writers.err(`FAILED at "${keyRead.check}": ${keyRead.message}\n`);
+                return 1;
+            }
+            if (tryKeyIdOfPem(keyRead.text) === null) {
+                writers.err(`FAILED at "key_not_public": ${args.retirementsKey} is not a PEM public key, so the list's signature cannot be checked with it.\n`);
+                return 1;
+            }
+            policyPem = keyRead.text;
+        }
+        const checked = verifyListSignature(listRead.envelope === null
+            ? { retirements: listRead.list.retirements, schema_version: listRead.list.schema_version }
+            : { entries: { retirements: listRead.list.retirements, schema_version: listRead.list.schema_version }, envelope: listRead.envelope }, policyPem);
+        listSignature = checked.state;
+        if (!checked.ok && checked.state.state !== "unverified_signature" && checked.state.state !== "unsigned") {
+            // A present-but-wrong signature is a refusal: the entries are not the signed ones, so
+            // using them would answer a question about a document nobody attested.
+            writers.err(`FAILED at "retirements_signature": ${checked.message}\n`);
+            return 1;
+        }
+        retirements = listRead.list;
+    }
+    const outcome = verifyAttestation({
+        file: fileRead.file,
+        publicPem: pems,
+        ...(patch ? { patch } : {}),
+        ...(args.requireSigners.length ? { requireKeyids: args.requireSigners } : {}),
+        retirements,
+    });
+    if (!outcome.ok) {
+        writers.err(`FAILED at "${outcome.check}": ${outcome.message}\n`);
+        return 1;
+    }
+    if (!args.quiet) {
+        writers.out("Verified OK\n");
+        // Every signer, not only the first: a counter-signed record's value is that there is
+        // more than one, and printing one keyid would undo the thing the signature added.
+        for (const signer of outcome.signers)
+            writers.out(`  signed by  ${signer}\n`);
+        writers.out(`  job        ${outcome.statement.predicate.job_id}\n`);
+        writers.out(`  subject    ${outcome.statement.subject[0]?.name ?? "(none)"}\n`);
+        writers.out(`  sha256     ${outcome.statement.subject[0]?.digest.sha256 ?? ""}\n`);
+        // Printed only when the signed subject carries one. A verifier needs to know which
+        // commit the approval became, and printing a blank or a placeholder would suggest the
+        // patch was applied when it was not.
+        const commit = outcome.statement.subject[0]?.gitCommit;
+        if (commit)
+            writers.out(`  commit     ${commit}\n`);
+        writers.out(`  records    ${outcome.statement.predicate.provenance.record_count}\n`);
+        if (args.patch)
+            writers.out("  patch      matches the subject digest\n");
+        /*
+         * The retirement answer is printed even when it is "unchecked", because silence reads
+         * as "nothing to report". The three states are deliberately not reducible to a tick:
+         * `not listed` means the verifier looked and found nothing, `unchecked` means nobody
+         * gave them anything to look at, and only the first is a fact about the key.
+         */
+        for (const verdict of outcome.retirements) {
+            writers.out(`  retirement ${describeVerdict(verdict)}\n`);
+        }
+        /*
+         * The list's own integrity, printed beside its answer.
+         *
+         * Without this the verdict above would be presented with the same confidence whether
+         * the list that produced it was signed or typed by anybody. `unsigned` and
+         * `unverified_signature` are both reported, and neither is a refusal — the record
+         * still verifies — but a reader is told what the list is worth.
+         */
+        if (listSignature !== null) {
+            writers.out(`  retirements-list ${describeListSignature(listSignature)}\n`);
+        }
+    }
+    return 0;
+}