keel-verifier

Independent verifier for Permit-spec governance evidence and Keel audit exports.

Why this exists

Most AI platforms can tell you what they logged.

This verifier detects post-signing tampering of exported governance evidence. An auditor, customer, regulator, or security team can independently verify decisions, dispatched requests, returned responses, and lifecycle evidence integrity.

Verification runs locally and does not require access to Keel's systems.

What this verifier can and cannot prove

The verifier proves exported evidence has not been altered after signing. Like any signing system, the trust boundary includes the signer at signing-time. Defending against privileged signing-time manipulation requires a higher-assurance signing architecture beyond the scope of this verifier.

In practical terms:

• Post-signing tampering of any element in the permit lifecycle (input, dispatch, provider response, client response, closure record) is detected — see the Tampering Detection Matrix in the online documentation.
• Pre-signing manipulation by a privileged Keel operator at the moment evidence is created is NOT detected by this verifier. Defending against that threat model requires hardware-backed signing (TEE/HSM), a separate capability tier above what this verifier covers.

Quick Start

keel-verifier requires Python 3.10 or newer. Install the released package and inspect the command you intend to use:

python -m pip install keel-verifier
keel-verify export --help

From a checkout:

python -m pip install -e .
python -m keel_verifier --help

The v0.2.0 invocation pattern still works:

python -m keel_verifier sample/export.json --self-attested

Single-File Evidence Bundles

Keel evidence bundle v1 is intentionally one file, one command, no network. When a file has schema_version=keel.evidence_bundle/v1, the verifier reads the embedded body and signature_envelope, validates artifact_ref.v1, recomputes signature_envelope.content_hash over canonical body, verifies the Ed25519 signature, and checks RFC 3161 TSA receipt imprints against the bundled anchor when receipts are present.

The envelope's embedded public_key is only a claim about who signed. Since 3.29.0 the verifier resolves the signer through the trust root (purpose export_signing, matched by signature_envelope.public_key_id) and requires the embedded key to equal it. A bundle signed by any other key exits non-zero: BUNDLE_SIGNER_UNTRUSTED when the trust root has no matching key, and BUNDLE_SIGNER_KEY_MISMATCH when the key id names a trusted key but the embedded key differs. Bundles from a non-production Keel instance need --key-manifest or --trust-root; --self-attested checks internal consistency only and reports itself as such.

keel-verify export evidence_bundle.json
keel-verify checkpoint checkpoint_bundle.json

Legacy split-file exports still verify with keel-verify export export.json manifest.json, but the CLI emits a deprecation warning so operators migrate downloads to the single-file bundle.

Downloadable AI Permits

The default AI Permit-to-X download is one compact, signed, human-readable JSON file. Bare-path invocation is supported:

keel-verify AI-Permit-to-Pay.json \
  --expected-public-key ed25519:<out-of-band-public-key>

Compact contract pins contain identity, version, and SHA-256 rather than copies of every registry. The verifier resolves each pin only against its bundled, append-only allowlist and fails closed when a pin is unknown or mismatched. It then derives the Permit title, lifecycle state, and summary from verified signed evidence. Editing any signed field therefore produces a TAMPERED verdict.

Legacy .keelpermit ZIP packages remain supported. Their manifest is inventory, not authority: the verifier rejects unsafe paths, duplicate or unlisted members, digest/size divergence, ambiguous roles, and pointer substitution before it adjudicates the signed evidence.

Use --json for the structured verification report plus regenerated human artifact. Use --raw for the legacy technical evidence output. Raw signed evidence, canonical bytes, hex/Base64, signatures, digests, and contract pins remain advanced representations; they are not the default customer view.

This is the beginning of the README. Read the rest at the original. Read the full README ↗