imbas-verify 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `imbas-verify`. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+`0.x` is deliberate: the record format is still settling, and a `1.0.0` would invite a consumer
+to build against it before it does.
+
+## [Unreleased]
+
+## [0.1.1]
+
+### Changed
+
+- **Verify-only build; no signing code shipped.** The package previously included
+  `signEnvelope`, `counterSignEnvelope` and every key-creation function, because the verifier
+  compiled the same source files the engine does. The tool that checks the evidence could also
+  manufacture it, which made "you do not have to trust us" false in the one way that matters.
+  Signing now lives in a module the verifier does not compile, and a test asserts that no
+  shipped file contains `createSign`, `generateKeyPair`, a private-key loader or a signing
+  entry point.
+
+  Nothing about verification changed: the same records verify, the same tampered ones are
+  refused, and the CLI surface is identical.
+
+## [0.1.0]
+
+### Added
+
+- First release. Verifies a signed Imbas approval record without the engine: DSSE envelope over
+  an in-toto Statement, ECDSA P-256, patch digest, provenance chain head, optional key-retirement
+  check.
+- `FORMAT.md` ships inside the package, so a record can be checked with `openssl` alone without
+  reaching anything else.
+- Zero runtime dependencies.

package/FORMAT.md

@@ -0,0 +1,155 @@
+# The Imbas approval record format
+
+This document is shipped inside the `imbas-verify` package so that you do not need to trust,
+reach, or have an account with Imbas to check a record. Everything below is enough to write
+an independent verifier. That is the point of publishing it.
+
+## 1. What a record is
+
+A record is a **DSSE envelope** (Dead Simple Signing Envelope, from the in-toto attestation
+specification) wrapping an **in-toto Statement v1**. Both formats are published, and `openssl`
+can verify the signature, so checking a record needs a public key and a shell — nothing else.
+
+Deliberately not Sigstore keyless signing. That flow publishes the signer's identity to a
+public transparency log, and an operator approving a change on their own machine should not
+have to announce that to the world. The key is local to the installation, and section 6 says
+plainly what that bounds.
+
+## 2. The envelope
+
+```json
+{
+  "payloadType": "application/vnd.in-toto+json",
+  "payload": "<base64 of the statement JSON>",
+  "signatures": [{ "keyid": "<sha256 hex>", "sig": "<base64 DER signature>" }]
+}
+```
+
+- **`payloadType`** is fixed at `application/vnd.in-toto+json`. Check it before anything else.
+- **`payload`** is the statement, base64-encoded. Decode **strictly**. `Buffer.from(x, "base64")`
+  silently skips characters it does not recognise, which can verify a tampered payload against
+  different bytes and then blame the cryptography for what is really bad encoding.
+- **`keyid`** is the lowercase hex `sha256` of the **DER SubjectPublicKeyInfo** — not of the PEM
+  text, and not of the private key.
+- **`sig`** is base64 of a **DER-encoded** ECDSA signature. Not IEEE-P1363 (the fixed `r||s`
+  form). Using the wrong one produces a signature that fails to verify for a reason that looks
+  like tampering, so if you are writing your own verifier, this is the first thing to check.
+- A record may carry **more than one signature**, for counter-signing. Every signature present
+  must be checked; the format's value is that there is more than one, so a verifier that checks
+  only `signatures[0]` throws away the reason counter-signing exists.
+
+## 3. PAE — the bytes that are actually signed
+
+You do not sign the JSON. You sign the **Pre-Authentication Encoding** of the payload, so that
+the type and the body cannot be swapped apart:
+
+```
+PAE(type, payload) = "DSSEv1" SP len(type) SP type SP len(payload) SP payload
+```
+
+where `SP` is a single space and `len()` is the **byte** length in ASCII decimal. The whole of
+it in JavaScript:
+
+```js
+const payload = Buffer.from(envelope.payload, "base64");
+const type = Buffer.from(envelope.payloadType, "utf8");
+const pae = Buffer.concat([
+  Buffer.from(`DSSEv1 ${type.length} `, "ascii"),
+  type,
+  Buffer.from(` ${payload.length} `, "ascii"),
+  payload,
+]);
+```
+
+`type.length` and `payload.length` are **byte** counts. Using `payload.toString("utf8").length`
+is wrong for any payload containing non-ASCII, and the error it produces is a signature failure
+that looks like an attack.
+
+## 4. The statement
+
+The decoded payload is an in-toto Statement:
+
+```json
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [{ "name": "changes.patch", "digest": { "sha256": "<hex>" } }],
+  "predicateType": "https://somernorth.co.uk/imbas/approval/v1",
+  "predicate": { "...": "the approval" }
+}
+```
+
+- **`subject[0].digest.sha256`** is over the **raw patch bytes**, exactly as stored. Do not
+  normalise line endings before hashing: that reports a mismatch for an honest file.
+- **`predicate`** carries the decision: which stage, which gate, who approved, the artifact, the
+  explainer shown, and the provenance chain head this approval continues from.
+
+The parsed statement must never be trusted before the envelope is known to hold what was
+signed. Otherwise a record can describe one thing and carry another, and both halves look
+individually valid.
+
+## 5. Verifying with `openssl` alone
+
+You need the record, the installation's public key PEM, and optionally the patch.
+
+```sh
+# 1. rebuild the signed bytes -> pae.bin, and extract signatures[0].sig -> sig.der
+#    (the fifteen lines in section 3, then base64 -d the sig field)
+
+# 2. verify
+openssl dgst -sha256 -verify imbas-pub.pem -signature sig.der pae.bin
+```
+
+`Verified OK` and exit 0, or `Verification failure` and exit 1.
+
+```sh
+# 3. the patch digest, if you have the patch
+sha256sum patch.diff     # compare with subject[0].digest.sha256
+```
+
+On Windows without coreutils, `sha256sum` ships with Git for Windows beside `openssl` at
+`C:\Program Files\Git\usr\bin\sha256sum.exe`. Any tool that hashes raw bytes agrees.
+
+If the `keyid` does not match the key you were given, you are verifying against the wrong key —
+check that before concluding the record was altered. "Wrong key" and "record tampered" are
+different problems with different fixes.
+
+## 6. What a record proves, and what it does not
+
+It proves:
+
+- **These exact bytes were signed** by the holder of the private key whose public half has the
+  quoted `keyid` — the signature is over the PAE bytes, so neither the payload nor the type can
+  change undetected.
+- **The patch is the one approved**, if the subject digest matches the file you hold.
+- **The chain head is intact**, if you check it: each record quotes the hash of the one before,
+  so an inserted or removed approval breaks the sequence.
+- **The decision that was recorded**, including who approved, at which gate, and what explainer
+  they were shown.
+
+It does not prove:
+
+- **That the change is good.** An approval records a decision, not a judgement about quality.
+  A careless approver produces a perfectly valid record.
+- **That the signer is who you think.** The key is local to one installation. Unless you obtained
+  the public key through a channel you already trust, a valid signature proves only that *some*
+  installation signed it. This is the honest limit of not using a transparency log, and it is
+  why the key must be pinned out of band.
+- **That a key was not revoked, unless you say so.** Pass `--retirements` to check. The three
+  answers stay distinct: `not listed` means the verifier looked and found nothing; `unchecked`
+  means you gave it nothing to look at. Only the first is a fact about the key.
+- **That the record is the only one.** Nothing here makes a record unique or non-repudiable
+  across installations.
+
+## 7. What the verifier does not do
+
+`imbas-verify` does not contact a network, apply a patch, read a configuration file, or open a
+data directory. It reads the files you name on the command line and nothing else. It has zero
+runtime dependencies: what you install is what is in the tarball.
+
+`--require-signer <keyid>` fails unless the named keyid has a valid signature — useful when you
+are given several keys and only some are acceptable for a given change.
+
+## 8. Licence and scope
+
+This document and the verifier are Apache-2.0. The engine that **produces** these records is a
+separate product; it is not included, not licensed here, and not required to check one.

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 Somer North Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/NOTICE

@@ -0,0 +1,21 @@
+Imbas Verifier
+Copyright 2026 Somer North Ltd
+
+This package is licensed under the Apache License, Version 2.0. See LICENSE.
+
+It contains only the modules needed to CHECK a signed Imbas approval record. The
+engine that produces records - the pipeline, the gates, the adapters, the apply
+control - is a separate proprietary product and is not part of this package, is
+not licensed by it, and is not required to use it.
+
+The attribution below covers the formats this verifier reads, both of which are
+public specifications implemented from their published descriptions rather than
+copied from another implementation:
+
+  DSSE (Dead Simple Signing Envelope)
+  https://github.com/secure-systems-lab/dsse
+
+  in-toto attestation framework
+  https://github.com/in-toto/attestation
+
+No third-party code is vendored. The package has no runtime dependencies.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# imbas-verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Check a signed Imbas approval record without Imbas.
+
+```sh
+npx imbas-verify approval.json --key installation-public.pem
+```
+
+```
+Verified OK
+  signed by  a1b2c3d4e5f60718
+  job        job_01HZX...
+  subject    changes.patch
+  sha256     9f2c... (full digest)
+  records    14
+  patch      matches the subject digest
+  retirement not listed
+```
+
+Exit code `0` means verified, `1` means a check failed and the first failing check is
+named, `2` means the arguments were wrong. Prose is for people; the exit code is the
+interface.
+
+## What it checks
+
+- **The signature** over the DSSE envelope, against the public keys you supply. Every
+  signature is checked, not the first one — a counter-signed record's value is that there
+  is more than one.
+- **The payload** is the signed bytes, byte for byte. The statement is parsed only after
+  the envelope is known to hold what was signed, so a record cannot describe one thing and
+  carry another.
+- **The patch digest**, if you pass `--patch`. It hashes the bytes, not a re-encoded
+  string.
+- **The provenance chain head** quoted in the record: that it is intact and ends at the
+  hash shown.
+- **Key retirement**, if you pass `--retirements`. The three answers are kept distinct:
+  `not listed` means the verifier looked and found nothing; `unchecked` means you gave it
+  nothing to look at. Only the first is a fact about the key.
+
+## What it does not do
+
+It does not contact a network, apply a patch, read a config file, or open a data
+directory. It reads the files you name on the command line and nothing else.
+
+It also does not tell you the change is good. An approval records a decision, and what a
+record proves and does not prove is written down in the statement itself.
+
+## Why you do not have to trust us
+
+The point of a verifier is that you can run it yourself. Two things make that true here:
+
+- **It is small.** Ten source files, all of them the record format. No pipeline, no
+  adapters, no gate logic, no configuration.
+- **It has no dependencies.** Zero. Not a smaller dependency tree — none at all. What you
+  install is what is in the tarball.
+
+The record format is public and implemented from its published specifications, so a
+record can also be checked with `openssl` alone. `FORMAT.md` in this package has the
+byte layout and the exact commands — it ships with the verifier precisely so that you do
+not need to reach anything else to check us.
+
+## Options
+
+```
+--key <file>              a public key PEM to verify against. May be repeated.
+--require-signer <keyid>  fail unless this keyid has a valid signature
+--retirements <file>      the retirement list this verifier holds
+--retirements-key <file>  the policy key's public half, to check the list's signature
+--patch <file>            also check the record's subject digest against this file
+--quiet                   print nothing but the failure, if any
+```
+
+## Licence
+
+Apache-2.0. See `LICENSE` and `NOTICE`.
+
+This package is the free half of Imbas. The engine that produces these records is a
+separate proprietary product; it is not included, not licensed here, and not needed.

package/args.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `Args` shape and the parser, shared by every command.
+ *
+ * Its own module so that `verify.ts` can type its argument without importing
+ * `attest.ts`, which would pull the engine back in and defeat the split.
+ *
+ * `VERIFY_USAGE` and `parseVerifyArgs` are the standalone command's half. They are
+ * separate from the engine's `parse` on purpose: the published package must not accept
+ * `attest`, `counter-sign` or `key retire`, because those need a signing key and a data
+ * dir, and a free verifier that advertises flags it cannot honour is worse than one with a
+ * smaller surface.
+ */
+export interface Args {
+    command: "attest" | "verify" | "counter-sign" | "key-retire" | "key-follow";
+    jobId: string | null;
+    file: string | null;
+    /** One or more public keys: verify checks against all, counter-sign against these. */
+    keys: string[];
+    signKey: string | null;
+    requireSigners: string[];
+    retirements: string | null;
+    retirementsKey: string | null;
+    retiredAt: string | null;
+    reason: string | null;
+    supersedes: string | null;
+    patch: string | null;
+    quiet: boolean;
+}
+/** The standalone command's help text. Only what `imbas-verify` can actually do. */
+export declare const VERIFY_USAGE = "Usage:\n  imbas-verify <record.json> --key <public.pem> [--key <public.pem> ...]\n                [--require-signer <keyid>] [--retirements <file>]\n                [--retirements-key <file>] [--patch <file>] [--quiet]\n\nChecks a signed Imbas approval record against one or more public keys.\n\nExit code 0 means verified, 1 means a check failed, 2 means the arguments were wrong.\nThe first check that failed is named, so a script does not have to parse prose.\n\nOptions:\n  --key <file>              a public key PEM to verify against. May be repeated.\n  --require-signer <keyid>  fail unless this keyid has a valid signature\n  --retirements <file>      the retirement list this verifier holds. Without it the answer\n                            is \"unchecked\", which is not the same as \"not retired\".\n  --retirements-key <file>  the policy key's public half. Without it a signed list is\n                            reported as unverified: present but unchecked.\n  --patch <file>            also check the record's subject digest against this file\n  --quiet                   print nothing but the failure, if any\n  -h, --help                this message\n\nWhat this does not do: it does not apply the patch, does not contact a network, and does\nnot read a config file or a data directory. It reads the files you name and nothing else.";
+export type ParseResult = {
+    ok: true;
+    args: Args;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Parses the standalone command's arguments.
+ *
+ * Returns a message rather than throwing, because every failure here is a usage failure
+ * and the caller's job is to print it. `Args.command` is always `"verify"` — the package
+ * has one command, and typing it that way keeps `runVerify` shared without the package
+ * needing the engine's parser.
+ */
+export declare function parseVerifyArgs(argv: readonly string[]): ParseResult;

package/args.js

@@ -0,0 +1,113 @@
+/**
+ * The `Args` shape and the parser, shared by every command.
+ *
+ * Its own module so that `verify.ts` can type its argument without importing
+ * `attest.ts`, which would pull the engine back in and defeat the split.
+ *
+ * `VERIFY_USAGE` and `parseVerifyArgs` are the standalone command's half. They are
+ * separate from the engine's `parse` on purpose: the published package must not accept
+ * `attest`, `counter-sign` or `key retire`, because those need a signing key and a data
+ * dir, and a free verifier that advertises flags it cannot honour is worse than one with a
+ * smaller surface.
+ */
+/** The standalone command's help text. Only what `imbas-verify` can actually do. */
+export const VERIFY_USAGE = `Usage:
+  imbas-verify <record.json> --key <public.pem> [--key <public.pem> ...]
+                [--require-signer <keyid>] [--retirements <file>]
+                [--retirements-key <file>] [--patch <file>] [--quiet]
+
+Checks a signed Imbas approval record against one or more public keys.
+
+Exit code 0 means verified, 1 means a check failed, 2 means the arguments were wrong.
+The first check that failed is named, so a script does not have to parse prose.
+
+Options:
+  --key <file>              a public key PEM to verify against. May be repeated.
+  --require-signer <keyid>  fail unless this keyid has a valid signature
+  --retirements <file>      the retirement list this verifier holds. Without it the answer
+                            is "unchecked", which is not the same as "not retired".
+  --retirements-key <file>  the policy key's public half. Without it a signed list is
+                            reported as unverified: present but unchecked.
+  --patch <file>            also check the record's subject digest against this file
+  --quiet                   print nothing but the failure, if any
+  -h, --help                this message
+
+What this does not do: it does not apply the patch, does not contact a network, and does
+not read a config file or a data directory. It reads the files you name and nothing else.`;
+/**
+ * Parses the standalone command's arguments.
+ *
+ * Returns a message rather than throwing, because every failure here is a usage failure
+ * and the caller's job is to print it. `Args.command` is always `"verify"` — the package
+ * has one command, and typing it that way keeps `runVerify` shared without the package
+ * needing the engine's parser.
+ */
+export function parseVerifyArgs(argv) {
+    const args = {
+        command: "verify",
+        jobId: null,
+        file: null,
+        keys: [],
+        signKey: null,
+        requireSigners: [],
+        retirements: null,
+        retirementsKey: null,
+        retiredAt: null,
+        reason: null,
+        supersedes: null,
+        patch: null,
+        quiet: false,
+    };
+    let index = 0;
+    /** Reads the value after a flag. Returns null when the flag had none. */
+    const takeValue = () => {
+        index += 1;
+        return argv[index] ?? null;
+    };
+    while (index < argv.length) {
+        const argument = argv[index] ?? "";
+        if (argument === "--key" ||
+            argument === "--require-signer" ||
+            argument === "--retirements" ||
+            argument === "--retirements-key" ||
+            argument === "--patch") {
+            const next = takeValue();
+            if (next === null)
+                return { ok: false, message: `${argument} needs a value.` };
+            if (argument === "--key")
+                args.keys.push(next);
+            else if (argument === "--require-signer")
+                args.requireSigners.push(next);
+            else if (argument === "--retirements")
+                args.retirements = next;
+            else if (argument === "--retirements-key")
+                args.retirementsKey = next;
+            else
+                args.patch = next;
+        }
+        else if (argument === "--quiet") {
+            args.quiet = true;
+        }
+        else if (argument.startsWith("-")) {
+            // Named rather than ignored. A mistyped flag that is silently dropped changes what
+            // was checked while still printing a verdict.
+            return { ok: false, message: `Unknown option ${argument}.` };
+        }
+        else if (args.file === null) {
+            args.file = argument;
+        }
+        else {
+            return { ok: false, message: `Unexpected argument ${argument}.` };
+        }
+        index += 1;
+    }
+    if (args.file === null)
+        return { ok: false, message: "No record file was given." };
+    if (args.keys.length === 0) {
+        // Refused rather than defaulted: verifying against no key cannot produce a verdict,
+        // and a "Verified OK" line printed without a key would be the worst output this tool
+        // could produce.
+        return { ok: false, message: "At least one --key is required." };
+    }
+    return { ok: true, args };
+}

package/attestation.d.ts

@@ -0,0 +1,178 @@
+import { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE, type DsseEnvelope } from "./dsse.js";
+import type { ApprovalPredicate } from "./record.js";
+import { type KeyRetirement, type RetirementList } from "./retirement.js";
+import { type Statement } from "./statement.js";
+/** A signed record as it is written to disk. */
+export interface AttestationFile {
+    /** The DSSE envelope. This is the signed thing; everything else is a convenience. */
+    envelope: DsseEnvelope;
+    /** The statement, decoded, so a reader need not base64-decode to see what it says. */
+    statement: Statement<ApprovalPredicate>;
+    /**
+     * Present once a second party has signed. Convenience metadata: the signatures that
+     * matter are on the envelope, and this field is not covered by any of them. A reader
+     * who needs proof of who signed must verify the envelope, never read this.
+     */
+    counter_signature?: CounterSignatureFile;
+}
+/** Writes an attestation as JSON. Two-space indent, so a human diff is readable. */
+/** A second party's signature, as it is written beside the envelope. */
+export interface CounterSignatureFile {
+    /**
+     * The keyids of every signature on the envelope, so a reader can see the shape without
+     * decoding it. Convenience only: what counts is the envelope's own signatures, and a
+     * reader who trusts this list instead of verifying would be trusting the file's prose.
+     */
+    signers: string[];
+    /** When the counter-signature was added. Not the record's time, and not signed. */
+    counter_signed_at: string;
+}
+/**
+ * Adds a counter-signature to an existing record.
+ *
+ * The order of operations is the security property, and it is not negotiable:
+ *
+ *   1. verify every existing signature over the payload, and refuse if any fails;
+ *   2. decode the payload those signatures actually cover;
+ *   3. sign *those bytes*, unchanged.
+ *
+ * A counter-signer who signed without step 1 would be endorsing a record they had not
+ * read, and their signature would add the appearance of a second opinion to a forged
+ * document. Step 2 rather than re-serialising the `statement` field is the same lesson as
+ * `attest`: the bytes that travel are the bytes that were signed, never a rebuild.
+ *
+ * Throws rather than returning a result. A caller who asked to counter-sign has already
+ * decided to vouch for a record, and a silent failure would leave them believing they had.
+ */
+/**
+ * Every check a verifier makes, in the order they run.
+ *
+ * The order is chosen so the *first* failure names the most specific fact: a record
+ * signed by a different installation fails at `keyid`, not at "signature", because
+ * "wrong key" and "tampered record" are different problems with different fixes.
+ */
+export type VerifyCheck = "file_json" | "key_not_public" | "envelope_shape" | "payload_type" | "payload_encoding" | "signature_present" | "keyid" | "signature" | "statement_json" | "statement_type" | "predicate_type" | "subject_digest"
+/**
+ * A signature the verifier has no key for. Distinct from `signature`, because "I hold
+ * no key for this signer" and "this signature is forged" send a reader to different
+ * places, and only one of them means the record was tampered with.
+ */
+ | "keyid_missing"
+/**
+ * The record carries fewer valid signers than the verifier required. This is the
+ * counter-signature check: it fails when one installation's word is all there is.
+ */
+ | "counter_signature_required"
+/**
+ * A signature was made by a key its own operator had already retired.
+ *
+ * Distinct from `signature`, which means the bytes were altered. This one means the
+ * bytes are intact and the *key* had been disowned when they were signed — so the record
+ * may be a forgery, or a genuine approval replayed by whoever held the retired key. Both
+ * are alarming and neither is "the file was edited".
+ */
+ | "key_retired_before_signing"
+/** A retirement list was supplied and could not be read. Says nothing about the record. */
+ | "retirements_unreadable";
+/** What the retirement list said about one verified signer. */
+export type SignerRetirement = {
+    keyid: string;
+    state: "unchecked";
+} | {
+    keyid: string;
+    state: "not_listed";
+} | {
+    keyid: string;
+    state: "retired_after_signing";
+    retirement: KeyRetirement;
+} | {
+    keyid: string;
+    state: "no_signing_time";
+    retirement: KeyRetirement;
+};
+export type VerifyOutcome = {
+    ok: true;
+    statement: Statement<ApprovalPredicate>;
+    /** The first supplied key that signed. Kept for callers that print one signer. */
+    keyid: string;
+    /** Every signer whose signature verified, in envelope order. */
+    signers: string[];
+    /**
+     * What the retirement list said about each signer, one entry per entry in `signers`.
+     *
+     * `unchecked` when no list was supplied — which is not the same as `not_listed`,
+     * and the difference is the whole reason this is a list of verdicts rather than a
+     * boolean. A verifier who was handed nothing must not read as a verifier who
+     * checked and found nothing.
+     */
+    retirements: SignerRetirement[];
+} | {
+    ok: false;
+    check: VerifyCheck;
+    message: string;
+};
+export interface VerifyInputs {
+    /** The attestation file's JSON, already read. */
+    file: unknown;
+    /**
+     * The verifier's public keys. Only public material reaches this function.
+     *
+     * A list rather than one PEM, because a counter-signed record carries more than one
+     * signature and a verifier has to be able to check all of them. Checking only the first
+     * would report "verified" for a record whose second signature is forged.
+     */
+    publicPem: string | readonly string[];
+    /** The patch file to check the subject digest against, when supplied. */
+    patch?: Buffer;
+    /**
+     * Keyids that must have signed. A verifier reading a record with a counter-signature
+     * passes the key they require here, so "one installation's word" fails rather than
+     * passing because *a* key signed it.
+     */
+    requireKeyids?: readonly string[];
+    /**
+     * The retirement list this verifier holds, if any.
+     *
+     * Absent means "nobody gave me one", which is reported as `unchecked` and never as
+     * "the key is fine". Present means a record signed at or after a retirement is refused
+     * at `key_retired_before_signing`; one signed before it still verifies, because the key
+     * was trusted when the record was made and saying otherwise would retroactively disown
+     * every honest approval the machine ever produced.
+     */
+    retirements?: RetirementList | null;
+}
+/**
+ * Verifies a signed record.
+ *
+ * The signature check comes before anything is read out of the payload, and that order
+ * is the whole security property: statement fields are parsed only after the bytes are
+ * known to be the bytes that were signed. Reading first would mean acting on
+ * unauthenticated input, which is how a "verify" function ends up trusting a tampered
+ * file for the length of one bug.
+ */
+export declare function verifyAttestation(inputs: VerifyInputs): VerifyOutcome;
+/**
+ * Reads an attestation file, refusing anything that is not JSON.
+ *
+ * Returns a result rather than throwing, and that is the whole point of the function.
+ * `verifyAttestation` already has a `file_json` check for "this is not an object", but
+ * a malformed file never reached it: `JSON.parse` threw first, and the operator got a
+ * `SyntaxError` stack trace from inside the tool. That is the failure mode this codebase
+ * refuses everywhere else — an unhandled exception says the tool is broken, when the
+ * truth is that a file is wrong. The same applies to a missing file and to a file that
+ * cannot be read at all.
+ *
+ * Path is included in the message but not the contents: a record could be large, and a
+ * verifier reading a wrong file usually needs to know *which* file, not what is in it.
+ */
+export type FileRead = {
+    ok: true;
+    file: unknown;
+} | {
+    ok: false;
+    check: "file_json" | "file_unreadable";
+    message: string;
+};
+export declare function readAttestationFile(path: string): FileRead;
+/** Re-exported so a caller needs one import for the whole flow. */
+export { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE, };