imbas-verify 0.0.0-stage → 0.1.1

package/retirement.js

@@ -0,0 +1,521 @@
+/**
+ * Key retirements: what a verifier is told when a key stops being trusted.
+ *
+ * The failure this exists for is not exotic. An installation key is on a laptop that is
+ * later stolen, or on a machine that is decommissioned and its disk handed to somebody
+ * else. Every record that key ever signed still verifies, forever, and a verifier has no
+ * way to learn that anything changed. The chain makes an edit visible, which is the honest
+ * boundary — but "verifiable now and verifiable in a hundred years, identically" is not a
+ * boundary, it is a missing feature.
+ *
+ * ## What a retirement is, and what it is not
+ *
+ * It is a statement of **distrust from a moment**, written by the operator and handed to
+ * a verifier. It is not a claim that past records were bad. The distinction is the whole
+ * design:
+ *
+ * - A record signed *before* the retirement was signed by a key that was trusted at the
+ *   time. It is exactly as good as it ever was, and saying otherwise would retroactively
+ *   convict every honest approval the machine ever made.
+ * - A record signed *after* the retirement claims to be signed by a key its own operator
+ *   had already disowned. Either the retirement is wrong or the record is; either way a
+ *   reader must be told.
+ *
+ * ## Why the list is a file, and why that is stated loudly
+ *
+ * There is no transparency log here. The list is a file the operator maintains and
+ * chooses to hand out, which means an operator who withholds it proves nothing, and one
+ * who holds it can leave an entry out. That is a real limit and `docs/EVIDENCE.md` says
+ * so in the same breath as the feature. The alternative — publishing retirements to a
+ * public log — is the thing this product deliberately does not do with an operator's
+ * signing history.
+ *
+ * The list is **append-only and never rewritten**. A "remove this retirement" operation
+ * would make the file worthless: a verifier reading the current state could not tell a
+ * key that was never retired from one whose retirement was quietly withdrawn.
+ */
+import { readFileSync } from "node:fs";
+import { verifyEnvelopeSignatures } from "./dsse.js";
+import { tryKeyIdOfPem } from "./key.js";
+import { join, resolve } from "node:path";
+/**
+ * The version this code writes.
+ *
+ * 2.0.0 added `supersedes`. It is a major bump rather than a minor one because the entries
+ * are **signed**: a list written at 1.0.0 and a list written at 2.0.0 are different
+ * documents, and a verifier re-serialising one to check the other would produce bytes that
+ * never existed. Calling that a minor change would invite exactly that mistake.
+ */
+export const RETIREMENT_SCHEMA_VERSION = "2.0.0";
+/**
+ * Every version this code can read, and what each one permits.
+ *
+ * `1.0.0` is still read, because lists have already been handed out. It is not *upgraded*
+ * on read — it stays 1.0.0 and is reported as such — and it is never refused for lacking
+ * `supersedes`, which it could not have had.
+ */
+const READABLE_VERSIONS = ["1.0.0", "2.0.0"];
+/**
+ * The version assumed when a list carries none.
+ *
+ * The **oldest** readable one, not the newest. A document with no version predates the
+ * field, so reading it as 2.0.0 would be the silent reinterpretation this whole mechanism
+ * exists to prevent — and it would silently permit `supersedes` in a document that never
+ * declared it could carry it.
+ */
+const ASSUMED_VERSION = "1.0.0";
+/** The payload type for a retirement list. Distinct from an attestation's, so a list can
+ *  never be presented as a record or the other way round. */
+export const RETIREMENT_PAYLOAD_TYPE = "application/vnd.imbas.retirements+json";
+export class RetirementError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RetirementError";
+    }
+}
+/** Where the retirement list lives inside a data dir. */
+export function retirementsPath(dataDir) {
+    return join(resolve(dataDir), "keys", "retirements.json");
+}
+export function readRetirementList(path) {
+    let text;
+    try {
+        text = readFileSync(resolve(path), "utf8");
+    }
+    catch {
+        // Absent, or unreadable. Both mean "you have not been given a list", which the caller
+        // must be able to distinguish from "you were given a list and the key is not in it".
+        return { ok: true, list: { schema_version: RETIREMENT_SCHEMA_VERSION, retirements: [] }, found: false, envelope: null };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return {
+            ok: false,
+            code: "retirements_json",
+            message: `${path} is not valid JSON, so nothing can be concluded about which keys were retired.`,
+        };
+    }
+    // Both file shapes are read: the `{ entries, envelope }` form this slice writes, and the
+    // bare `{ retirements }` form written before signing existed. A verifier handed an old
+    // list must not be told their file is malformed — they must be told it is unsigned.
+    const signedShape = parseSignedList(parsed);
+    if (!signedShape.ok) {
+        return { ok: false, code: "retirements_unreadable", message: signedShape.message };
+    }
+    const { entries, envelope } = signedShape.list;
+    return {
+        ok: true,
+        list: { schema_version: entries.schema_version, retirements: entries.retirements },
+        found: true,
+        envelope,
+    };
+}
+/**
+ * Validates a parsed retirement list.
+ *
+ * Strict about shape and lenient about nothing, because the failure mode of a
+ * half-understood retirement list is a verifier that silently checks fewer entries than
+ * its author wrote. An entry missing `retired_at` would otherwise become `undefined`, and
+ * `new Date(undefined)` is an Invalid Date that compares false against everything — so a
+ * malformed entry would read as "retired after all records", or as "retired never",
+ * depending on which way the comparison fell. Refusing the file is the only safe answer.
+ */
+export function parseRetirementList(value) {
+    if (typeof value !== "object" || value === null) {
+        return { ok: false, message: "A retirement list must be a JSON object with a `retirements` array." };
+    }
+    const candidate = value;
+    if (!Array.isArray(candidate.retirements)) {
+        return { ok: false, message: "A retirement list must have a `retirements` array." };
+    }
+    /*
+     * The version decides what the entries are allowed to contain.
+     *
+     * An unknown version is refused by name rather than guessed at. A 3.0.0 list might permit
+     * a field this code would silently drop — and dropping a signed field is worse than
+     * refusing the file, because the signature would still verify over a document this
+     * verifier has half-understood.
+     */
+    const declared = candidate.schema_version;
+    if (declared !== undefined && !READABLE_VERSIONS.includes(declared)) {
+        return {
+            ok: false,
+            message: `This registry declares schema_version "${String(declared)}", and this verifier reads ${READABLE_VERSIONS.join(" and ")}. Refusing rather than guessing at what an unknown version permits.`,
+        };
+    }
+    const version = (declared ?? ASSUMED_VERSION);
+    const retirements = [];
+    for (const [index, entry] of candidate.retirements.entries()) {
+        const shaped = parseRetirement(entry, version);
+        if (!shaped.ok) {
+            return { ok: false, message: `Retirement ${index} is not usable: ${shaped.message}` };
+        }
+        retirements.push(shaped.retirement);
+    }
+    return {
+        ok: true,
+        // The declared version, so a 1.0.0 list stays 1.0.0 when it is read back out. Returning
+        // the current version instead would relabel every old list as one that permits a field
+        // it never had.
+        list: { schema_version: version, retirements },
+    };
+}
+function parseRetirement(value, version = ASSUMED_VERSION) {
+    if (typeof value !== "object" || value === null) {
+        return { ok: false, message: "it is not an object." };
+    }
+    const candidate = value;
+    if (typeof candidate.keyid !== "string" || candidate.keyid.trim().length === 0) {
+        return { ok: false, message: "it has no `keyid`." };
+    }
+    if (typeof candidate.retired_at !== "string" || !isIsoDate(candidate.retired_at)) {
+        return {
+            ok: false,
+            message: `its \`retired_at\` is ${candidate.retired_at === undefined ? "missing" : "not an ISO 8601 timestamp"}. A retirement with no moment is a retirement that cannot be compared against anything.`,
+        };
+    }
+    if (typeof candidate.reason !== "string" || candidate.reason.trim().length === 0) {
+        return { ok: false, message: "it has no `reason`. A retirement nobody explained cannot be reviewed." };
+    }
+    /*
+     * `supersedes` is optional, and the two ways it can be wrong are different mistakes.
+     *
+     * Absent is legitimate — a stolen laptop has no successor — so a 1.0.0 entry that never
+     * had the field, and a 2.0.0 entry that deliberately omits it, both parse. Present but
+     * empty is refused: `supersedes: ""` would name no key at all while looking like it named
+     * one, and a reader would follow it to nothing.
+     */
+    let supersedes;
+    if (candidate.supersedes !== undefined) {
+        /*
+         * A 1.0.0 list cannot carry this field.
+         *
+         * Not a technicality: if it appears, either the version is mislabelled or somebody added
+         * a signed field without declaring it. Both mean the document is not what it says it is,
+         * and continuing would apply a successor the declared version never permitted.
+         */
+        if (version === "1.0.0") {
+            return {
+                ok: false,
+                message: "it carries `supersedes`, but the list declares schema_version 1.0.0, which has no such field. Either the version is wrong or a field was added without declaring it — a verifier cannot tell which, so it will not guess.",
+            };
+        }
+        if (typeof candidate.supersedes !== "string" || candidate.supersedes.trim().length === 0) {
+            return {
+                ok: false,
+                message: "its `supersedes` is present but names no key. Leave it out when the key has no successor; an empty one would look like a successor a reader could follow.",
+            };
+        }
+        /*
+         * Deliberately *not* a 64-hex shape check, matching how `keyid` itself is validated.
+         * Refusing a `supersedes` that `keyid` would accept would make the list inconsistent
+         * with itself — a strict shape here and a non-empty check there. What matters is that it
+         * names a *different* key, which is the check below.
+         */
+        if (candidate.supersedes === candidate.keyid) {
+            return {
+                ok: false,
+                message: "its `supersedes` names the key being retired. A key cannot succeed itself, and following that note would loop forever.",
+            };
+        }
+        supersedes = candidate.supersedes;
+    }
+    return {
+        ok: true,
+        retirement: {
+            keyid: candidate.keyid,
+            retired_at: candidate.retired_at,
+            reason: candidate.reason,
+            recorded_at: typeof candidate.recorded_at === "string" && isIsoDate(candidate.recorded_at)
+                ? candidate.recorded_at
+                : candidate.retired_at,
+            // Spread rather than `supersedes: undefined`: the signed bytes must not gain a key
+            // that was never there, or a 1.0.0 list and a re-written one would differ.
+            ...(supersedes === undefined ? {} : { supersedes }),
+        },
+    };
+}
+/**
+ * True when the text is an ISO 8601 timestamp that names a real instant.
+ *
+ * `new Date("nonsense")` produces an Invalid Date rather than throwing, and every
+ * comparison against an Invalid Date is `false` — including `>=` and `<=`. A timestamp
+ * that cannot be compared is worse than a missing one, because it silently answers "no"
+ * to every question asked of it.
+ */
+export function isIsoDate(text) {
+    const parsed = Date.parse(text);
+    return Number.isFinite(parsed);
+}
+/**
+ * Appends a retirement.
+ *
+ * Refuses a duplicate keyid. Retiring the same key twice would produce a list where an
+ * earlier moment and a later one both claim to be the retirement, and a comparison that
+ * read the wrong one would call a post-retirement record genuine. The refusal is by name
+ * so an operator who runs the command twice learns what happened.
+ *
+ * Refuses to move a retirement *earlier* as well, for the same reason in the other
+ * direction: shortening the trusted period after records have been signed would
+ * retroactively disown approvals the operator made in good faith. A later retirement is
+ * a widening of trust, and this refuses that too — a list whose entries can be revised is
+ * a list a verifier cannot reason about.
+ */
+/**
+ * Serialises the entries once and signs those bytes.
+ *
+ * `JSON.stringify` without indentation, not the two-space form the file is written with.
+ * The signature must cover a canonical byte string so that a verifier can reproduce it from
+ * `entries` alone without knowing how the writer chose to format the file. Key order is
+ * insertion order, which is deterministic for a given object, and the entries are built in
+ * one place — so a re-serialisation by `verifyListSignature` produces the same bytes.
+ */
+/**
+ * Checks the signature over a list, before any entry is read.
+ *
+ * Returns one of five states rather than a boolean, because "there is no signature", "the
+ * signature is wrong" and "I was given no key to check it with" are three different facts
+ * and only one of them says somebody tampered.
+ *
+ * `policyPem` is optional. When it is absent a signed list reports
+ * `unverified_signature` — a list that *has* a signature nobody checked, which is again
+ * different from a list with none. Collapsing those would let an operator hand a verifier
+ * an unsigned list and have it read as "unsigned is normal here".
+ */
+export function verifyListSignature(list, policyPem) {
+    const shaped = parseSignedList(list);
+    if (!shaped.ok) {
+        return { ok: false, state: { state: "signature_invalid", message: shaped.message }, message: shaped.message };
+    }
+    const { entries, envelope } = shaped.list;
+    if (envelope === null) {
+        // A bare list. Nothing has been altered — there is simply nothing to check. Reported,
+        // never refused, because a list written before this feature existed is not a forgery.
+        return { ok: true, state: { state: "unsigned" }, list: entries };
+    }
+    const keys = [];
+    if (policyPem !== null) {
+        const keyid = tryKeyIdOfPem(policyPem);
+        if (keyid === null) {
+            return {
+                ok: false,
+                state: { state: "signature_invalid", message: "The policy key supplied is not a PEM public key." },
+                message: "The policy key supplied is not a PEM public key, so the list's signature cannot be checked.",
+            };
+        }
+        keys.push({ publicPem: policyPem, keyid });
+    }
+    if (keys.length === 0) {
+        return {
+            ok: false,
+            state: { state: "unverified_signature" },
+            message: "This retirement list carries a signature, but no policy public key was supplied to check it. Pass --retirements-key, or the signature is decoration.",
+        };
+    }
+    const outcome = verifyEnvelopeSignatures(envelope, keys, { expectedPayloadType: RETIREMENT_PAYLOAD_TYPE });
+    if (!outcome.ok) {
+        if (outcome.check === "keyid") {
+            const signer = envelope.signatures[0]?.keyid ?? "(none)";
+            return {
+                ok: false,
+                state: { state: "unknown_signer", keyid: signer },
+                message: `This retirement list was signed by ${signer.slice(0, 16)}…, and the policy key you supplied is not it. Either you were given the wrong policy key, or the list was re-signed by somebody else.`,
+            };
+        }
+        return {
+            ok: false,
+            state: { state: "signature_invalid", message: outcome.message },
+            message: `The retirement list's signature does not verify: ${outcome.message} These are not the entries the policy key signed.`,
+        };
+    }
+    /*
+     * The signed bytes must equal the entries the file carries.
+     *
+     * Without this, an attacker could keep a valid envelope and swap `entries` for their own:
+     * the signature would still verify, because it verifies over the *payload inside the
+     * envelope*, and nothing would have compared that payload to what the reader will use.
+     * This is the one check that ties the signature to the thing being read.
+     */
+    const signedEntries = parseEntriesFromPayload(outcome.payload);
+    if (!signedEntries.ok) {
+        return { ok: false, state: { state: "signature_invalid", message: signedEntries.message }, message: signedEntries.message };
+    }
+    if (JSON.stringify(signedEntries.entries) !== JSON.stringify(entries)) {
+        const message = "The retirement list's signature covers different entries from the ones in the file. Somebody has changed the list since it was signed.";
+        return { ok: false, state: { state: "signature_invalid", message }, message };
+    }
+    return { ok: true, state: { state: "signed", keyid: outcome.signatures[0]?.keyid ?? "" }, list: entries };
+}
+/** Reads the entries out of a verified payload. */
+function parseEntriesFromPayload(payload) {
+    if (payload === null)
+        return { ok: false, message: "The retirement list's payload could not be decoded." };
+    let parsed;
+    try {
+        parsed = JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        return { ok: false, message: "The retirement list's signed payload is not JSON." };
+    }
+    return parseEntries(parsed);
+}
+/** Validates an entries object. Shared by the signed and unsigned readers. */
+function parseEntries(value) {
+    const list = parseRetirementList(value);
+    if (!list.ok)
+        return { ok: false, message: list.message };
+    return { ok: true, entries: { schema_version: list.list.schema_version, retirements: list.list.retirements } };
+}
+/** Accepts either a bare list or a `{ entries, envelope }` file. */
+function parseSignedList(value) {
+    if (typeof value !== "object" || value === null) {
+        return { ok: false, message: "A retirement list must be a JSON object." };
+    }
+    const candidate = value;
+    if ("entries" in candidate) {
+        const entries = parseEntries(candidate.entries);
+        if (!entries.ok)
+            return { ok: false, message: entries.message };
+        const envelope = candidate.envelope;
+        if (envelope === undefined || envelope === null) {
+            return { ok: true, list: { entries: entries.entries, envelope: null } };
+        }
+        if (typeof envelope !== "object" ||
+            typeof envelope.payloadType !== "string" ||
+            typeof envelope.payload !== "string" ||
+            !Array.isArray(envelope.signatures)) {
+            return { ok: false, message: "The retirement list's `envelope` is not a usable DSSE envelope." };
+        }
+        if (envelope.payloadType !== RETIREMENT_PAYLOAD_TYPE) {
+            return {
+                ok: false,
+                message: `The retirement list's envelope declares payloadType "${envelope.payloadType}", not "${RETIREMENT_PAYLOAD_TYPE}". A record envelope cannot stand in for a list's.`,
+            };
+        }
+        return { ok: true, list: { entries: entries.entries, envelope } };
+    }
+    // A bare list. Treated as unsigned rather than as a shape error, so a file written
+    // before signing existed still reads — and is reported as `unsigned`.
+    const entries = parseEntries(value);
+    if (!entries.ok)
+        return { ok: false, message: entries.message };
+    return { ok: true, list: { entries: entries.entries, envelope: null } };
+}
+/**
+ * Follows the successors from a keyid, to the end of the chain.
+ *
+ * Read-only: it walks the signed list and invents nothing, signs nothing, and changes no
+ * trust. The walk terminates on the first key that is not retired, on a successor the list
+ * does not mention, or on a repeat — and reports *which* it was, because they mean
+ * different things to a reader deciding whether a signature is still worth anything.
+ *
+ * It checks no signature. Call `verifyListSignature` first: following an unverified list is
+ * following an unsigned claim, which this whole module exists to avoid.
+ */
+export function followSuccessors(list, keyid) {
+    const path = [];
+    let current = keyid;
+    for (;;) {
+        const alreadyWalked = path.find((hop) => hop.keyid === current);
+        if (alreadyWalked !== undefined) {
+            return { state: "cycle", keyid, path, repeated: alreadyWalked.keyid };
+        }
+        const retirement = list.retirements.find((entry) => entry.keyid === current);
+        if (retirement === undefined) {
+            // An empty path means the key asked about was never listed — the one answer that is a
+            // fact about the key rather than about the chain.
+            if (path.length === 0)
+                return { state: "not_retired", keyid };
+            return { state: "successor_not_listed", keyid, path, successor: current };
+        }
+        path.push({ keyid: current, retirement });
+        if (retirement.supersedes === undefined) {
+            return { state: "retired_without_successor", keyid, path };
+        }
+        current = retirement.supersedes;
+    }
+}
+/**
+ * The walk in one sentence.
+ *
+ * Deliberately talks about *notes* rather than trust. A chain ending at "key C" says the
+ * operator wrote down that C replaced B; it does not say C is trusted, or even that it
+ * exists. Nothing here is revocation, expiry, or a statement about time.
+ */
+export function describeSuccession(chain) {
+    const trail = (path) => path
+        .map((hop) => hop.keyid.slice(0, 8))
+        .concat(chain.state === "successor_not_listed" ? [chain.successor.slice(0, 8)] : [])
+        .join(" → ");
+    const last = (path) => path[path.length - 1].retirement;
+    switch (chain.state) {
+        case "not_retired":
+            return "not in this list. That is not a statement that it is trusted — only that nobody has recorded it as retired.";
+        case "retired_without_successor":
+            return chain.path.length === 1
+                ? `retired ${last(chain.path).retired_at} (${last(chain.path).reason}) and no successor was named. Nothing replaced this key.`
+                : `superseded along ${trail(chain.path)}, then retired ${last(chain.path).retired_at} (${last(chain.path).reason}) with no successor named. The chain ends here.`;
+        case "successor_not_listed":
+            return `superseded along ${trail(chain.path)}, pointing at a key that is not in this list — so whether it has itself been retired cannot be said. A successor is a note, not a proof: it does not say whether the successor key is trusted.`;
+        case "cycle":
+            return `the successor notes lead back to ${chain.repeated.slice(0, 8)} (${trail(chain.path)} → ${chain.repeated.slice(0, 8)}), so the chain has no end. This list was not written by the command in this repository.`;
+    }
+}
+/**
+ * One sentence per retirement state, in the words the docs use.
+ *
+ * Shared by the CLI and the API on purpose. Two copies would drift, and the drift would be
+ * invisible: an operator reading the terminal and a verifier reading the panel would be
+ * told subtly different things about the same record.
+ */
+export function describeVerdict(verdict) {
+    if (verdict === undefined) {
+        return "no signer was checked, so nothing can be said about whether this key was retired.";
+    }
+    switch (verdict.state) {
+        case "unchecked":
+            return "unchecked — no retirement list was supplied. That is not the same as checked and clear.";
+        case "not_listed":
+            return "key not in the list you supplied.";
+        case "retired_after_signing":
+            return `retired ${verdict.retirement.retired_at} (${verdict.retirement.reason}) — after this record was sealed, so it was signed while the key was trusted.`;
+        case "no_signing_time":
+            return `retired ${verdict.retirement.retired_at} (${verdict.retirement.reason}), but this record names no completed_at, so whether it predates the retirement cannot be decided.`;
+    }
+}
+/**
+ * Decides what the list says about a record signed by this keyid.
+ *
+ * **The signing moment is the whole record's, not one signature's.** An envelope does not
+ * carry a per-signature timestamp, and inventing one would be a claim the format does not
+ * make. So the question is asked of the record's *envelope* — the interval from the signed
+ * `created_at` to the signed `completed_at` — and the later end is what decides:
+ *
+ * - A record whose `completed_at` is at or after the retirement is `retired_before_signing`.
+ *   The key had been disowned by the time the record was sealed, so the signature claims
+ *   something its own operator had withdrawn.
+ * - A record whose `completed_at` is before the retirement is `retired_after_signing`: the
+ *   key was trusted throughout the job it describes.
+ *
+ * Using `completed_at` rather than `created_at` is deliberate. A long job that *started*
+ * before the retirement and finished after it was signed after the key was disowned. The
+ * earlier timestamp would launder exactly the case this feature exists to catch.
+ */
+export function judgeRetirement(list, keyid, signing) {
+    const retirement = list.retirements.find((entry) => entry.keyid === keyid);
+    if (retirement === undefined)
+        return { state: "not_listed" };
+    if (signing.completedAt === null || !isIsoDate(signing.completedAt)) {
+        return { state: "no_signing_time", retirement };
+    }
+    const completed = Date.parse(signing.completedAt);
+    const retired = Date.parse(retirement.retired_at);
+    return completed >= retired
+        ? { state: "retired_before_signing", retirement }
+        : { state: "retired_after_signing", retirement };
+}

package/statement.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 } from "./dsse.js";
+/** A subject digest: the algorithm and the hex digest of the exact bytes. */
+export interface SubjectDigest {
+    sha256: string;
+    [algorithm: string]: string;
+}
+export interface Subject {
+    /** What the record is about. For an approval: the artifact it approved. */
+    name: string;
+    digest: SubjectDigest;
+    /**
+     * The commit the patch was applied as, when it was applied.
+     *
+     * Absent otherwise, and never filled in by guesswork: a record that named a commit
+     * that does not exist would be a false statement in a document whose only value is
+     * that its statements are true.
+     */
+    gitCommit?: string;
+}
+export interface Statement<T> {
+    _type: typeof IN_TOTO_STATEMENT_TYPE;
+    subject: Subject[];
+    predicateType: typeof APPROVAL_PREDICATE_TYPE;
+    predicate: T;
+}
+/** Builds a statement around a predicate. The caller supplies the subject. */
+export declare function buildStatement<T>(subject: Subject, predicate: T): Statement<T>;
+/**
+ * Reads a statement back out of verified payload bytes.
+ *
+ * Returns a discriminated result rather than throwing, so the verify command can name
+ * the check that failed instead of printing a stack trace. The `_type` and
+ * `predicateType` checks are here and not in `verifyEnvelope` on purpose: the envelope
+ * is a generic container, and it is the *reader* that knows what it expects to find
+ * inside.
+ */
+export type StatementRead<T> = {
+    ok: true;
+    statement: Statement<T>;
+} | {
+    ok: false;
+    check: "statement_json" | "statement_type" | "predicate_type";
+    message: string;
+};
+export declare function readStatement<T>(payload: Buffer): StatementRead<T>;
+/** Re-exported so a caller needs one import for the whole format. */
+export { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE };

package/statement.js

@@ -0,0 +1,56 @@
+/**
+ * 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, } 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,
+    };
+}
+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),
+        });
+    }
+}