imbas-verify 0.0.0-stage → 0.1.0

package/statement.js

@@ -0,0 +1,73 @@
+/**
+ * The in-toto Statement, and the envelope it travels in.
+ *
+ * An in-toto Statement answers two questions and refuses to mix them: *what* is
+ * being attested (the `subject`) and *what is being said about it* (the `predicate`,
+ * named by its `predicateType`). Keeping them apart is what lets a third party read
+ * the subject — a digest of a patch — and check it against a file they already have,
+ * without having to understand or trust the predicate at all.
+ *
+ * The predicate here is an approval record. It is not a claim that code is correct,
+ * and the predicate says so in its own words (step 3). A signed record that overstates
+ * what it proves is worse than no record, because it gets believed.
+ */
+import { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE, signEnvelope, } from "./dsse.js";
+/** Builds a statement around a predicate. The caller supplies the subject. */
+export function buildStatement(subject, predicate) {
+    return {
+        _type: IN_TOTO_STATEMENT_TYPE,
+        subject: [subject],
+        predicateType: APPROVAL_PREDICATE_TYPE,
+        predicate,
+    };
+}
+/**
+ * Serialises a statement and signs it.
+ *
+ * The bytes that get signed are the bytes produced here, and those are the bytes that
+ * travel in the envelope — not a re-serialisation. Anything that parsed the statement
+ * and wrote it back out would reorder keys or change whitespace, and the signature
+ * would then cover a slightly different document than the one on disk. So the payload
+ * is built once, as a Buffer, and never rebuilt.
+ *
+ * Key order is insertion order, which `JSON.stringify` preserves for string keys, so
+ * the output is deterministic for a given statement — two attestations of the same
+ * job produce byte-identical payloads, which makes them comparable.
+ */
+export function sealStatement(statement, key) {
+    const payload = Buffer.from(JSON.stringify(statement, null, 2), "utf8");
+    return { payload, envelope: signEnvelope(payload, key) };
+}
+export function readStatement(payload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        return { ok: false, check: "statement_json", message: "The payload is not JSON." };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, check: "statement_json", message: "The payload is not a JSON object." };
+    }
+    const statement = parsed;
+    if (statement._type !== IN_TOTO_STATEMENT_TYPE) {
+        return {
+            ok: false,
+            check: "statement_type",
+            message: `_type is "${String(statement._type)}", expected "${IN_TOTO_STATEMENT_TYPE}".`,
+        };
+    }
+    if (statement.predicateType !== APPROVAL_PREDICATE_TYPE) {
+        return {
+            ok: false,
+            check: "predicate_type",
+            message: `predicateType is "${String(statement.predicateType)}", expected "${APPROVAL_PREDICATE_TYPE}".`,
+        };
+    }
+    if (!Array.isArray(statement.subject) || statement.subject.length === 0) {
+        return { ok: false, check: "statement_json", message: "The statement names no subject." };
+    }
+    return { ok: true, statement: statement };
+}
+/** Re-exported so a caller needs one import for the whole format. */
+export { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE };

package/verify-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/verify-cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * `imbas-verify` — check a signed Imbas approval record without the engine.
+ *
+ * This is the free verifier from `docs/COMMERCIALS.md` §3.3, packaged. The claim it makes
+ * is narrow and worth stating plainly: given a record and the public key of the
+ * installation that signed it, it tells you whether the signature holds and what the record
+ * says. It does not talk to a network, read a config file, or need a data directory.
+ *
+ * The command syntax mirrors `imbas verify`, because they are the same implementation and
+ * a person moving between the two should not have to relearn the flags.
+ *
+ * Exit codes are the interface: 0 verified, 1 failed, 2 usage. Prose is for people.
+ */
+import { runVerify } from "./verify.js";
+import { VERIFY_USAGE, parseVerifyArgs } from "./args.js";
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+    process.stderr.write(`${VERIFY_USAGE}\n`);
+    process.exitCode = argv.length === 0 ? 2 : 0;
+}
+else {
+    const parsed = parseVerifyArgs(argv);
+    if (!parsed.ok) {
+        process.stderr.write(`${parsed.message}\n${VERIFY_USAGE}\n`);
+        process.exitCode = 2;
+    }
+    else {
+        process.exitCode = runVerify(parsed.args, {
+            out: (text) => process.stdout.write(text),
+            err: (text) => process.stderr.write(text),
+        });
+    }
+}

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;
+}