proofbundle

AI eval results need receipts.

Turn an AI evaluation result, review, decision, or action outcome into a portable receipt that can be checked offline.

proofbundle lets a verifier check which key signed the exact bytes and whether those bytes changed. It does not prove that the result is true, that the signer is trustworthy, or that the evaluation was sound.

One file. No verification server. No network required.

Quick start · What it proves · New in 5.1.0 · Adoption review · Documentation

New in 5.1.0

proofbundle 5.1.0 adds a new receipt kind for disclosing AI agent involvement and review in pull requests and issues.

• Agent review receipts bind the reviewed GitHub object, the declared review runs, coverage, findings, limitations, and the human visible disclosure.
• Stronger subject and disclosure binding prevents a valid receipt from silently travelling to another object or a visible block from claiming more than the signed predicate.
• Clearer time and coverage semantics separate declared event time from witness observation time and reject ambiguous claims of complete coverage.
• Hardened correction chains prevent an untrusted receipt from taking over the current position in a correction or supersession chain.
• Executable conformance coverage now includes the agent review predicate and the receipt envelope profile.

One behaviour change deserves attention before upgrading. automation_summary now adds RECEIPT_NOT_OK to its blockers when a receipt is not ok. Read the 5.1.0 changelog before updating automation.

Release status

The closing audit verdict for 5.1.0 was PARTIAL_GATE_NO_WITHSTANDS, not WITHSTANDS_DEEPGATE. The declared residual risks are published in RESTRISIKO_510.md.

Quick start

Install the core verifier.

python -m pip install proofbundle

Requires Python 3.10 or newer. The core installs two dependencies, cryptography and rfc8785.

Download a real example receipt and verify it offline.

curl -fsSL \
  https://raw.githubusercontent.com/b7n0de/proofbundle/main/examples/example_bundle.json \
  -o receipt.json

proofbundle verify receipt.json

The command uses the local file only. Its exit code is part of the public contract.

0  verified
1  verification failed
2  malformed input or usage error
3  relying party policy not met

Run the tamper demo.

python -m pip install "proofbundle[eval]"
proofbundle demo

The demo checks an honest receipt, multiple tampered variants, and a sample swap. It exits nonzero if a tamper is accepted.

For a guided walkthrough, see docs/DEMO.md. For Inspect, see docs/INSPECT_HAPPY_PATH.md.

What a receipt proves

This boundary is the product. proofbundle makes a claim attributable and tamper evident without turning the claim into truth.

Read the full threat model and the project wide non claims.

Choose the path that matches your task

How it works

evaluation, review, decision, or action
                    │
                    ▼
      canonical statement and commitments
                    │
                    ▼
       signature and optional Merkle proofs
                    │
                    ▼
           one portable receipt file
                    │
                    ▼
        proofbundle verification offline
                    │
                    ▼
   separate verification axes and policy result

The verifier checks only the evidence supplied to it. Trust anchors, expected subjects, currentness information, and policy requirements come from the relying party.

Capabilities and maturity

proofbundle is a beta project. Shipped does not mean that every profile has the same maturity.

The full predicate inventory and maturity labels live in docs/predicates/README.md.

Security and trust

• The verifier uses cryptography for Ed25519 and rfc8785 for canonicalization. It does not implement its own cryptographic primitives.
• Correctness is checked against external RFC 6962 vectors and a real Sigstore Rekor proof, not only against the project's own receipts.
• The test suite sits behind a mutation gate and property based parser fuzzing.
• The receipt signature is Ed25519 and is not post quantum. Post quantum coverage today is limited to witness side ML-DSA-44 cosignatures. A post quantum payload signature is on the roadmap and not yet built. Detail in docs/ANCHORS.md.
• Releases are built once, carry SLSA build provenance, and are published through PyPI Trusted Publishing, where PyPI records PEP 740 attestations for the same bytes.
• The conformance corpus includes positive controls and counter proofs. Read what it does and does not establish in CONFORMANCE.md.
• The 30 minute adversarial adoption path is in docs/REVIEWERS.md.
• Security reports follow SECURITY.md.
• Release specific audit artefacts and residual risks remain visible rather than being folded into a single green status.

OpenSSF Scorecard

The aggregate score is a live heuristic, not a product verdict. Several checks score zero for reasons that are written down rather than hidden, one sentence per check, in docs/SCORECARD.md. The OpenSSF self assessment walks the Best Practices criteria honestly.

Standards and interoperability

proofbundle is a small offline receipt layer that complements, rather than replaces, systems such as in-toto, Sigstore, SCITT, transparency logs, trusted execution environments, and independent reproduction.

• INTEROP.md compares the boundaries tool by tool.
• docs/RECEIPT_ENVELOPE_PROFILE.md defines the portable envelope profile.
• docs/IN_TOTO_PROFILE.md describes the in-toto mapping.
• docs/SCITT_CPB_MAPPING.md records the SCITT mapping.
• docs/RELATED_WORK.md holds the research neighbourhood.

Documentation

Scope

proofbundle is not a hosted transparency service, a complete in-toto client, a trusted execution environment, a consensus system, or a compliance product by itself.

It is the portable, standards oriented receipt layer between an evidence producer and a relying party.

Roadmap, stated as not yet built. A post quantum payload signature, and a CLI flag to select the content root algorithm, jcs-sha256-v1 is the signed default today.

Citation

Machine readable citation metadata is in CITATION.cff.

The archival software record uses concept DOI 10.5281/zenodo.21110642. The Technical Note uses concept DOI 10.5281/zenodo.21230466.

Contributing

Read CONTRIBUTING.md and the Code of Conduct.

Good first issues use the good-first-issue label. Security findings follow SECURITY.md.

The verifier core aims to remain small, dependency light, and auditable.

License

MIT, see LICENSE.

_{proofbundle is part of b7n0de, Verified AI Work · b7n0de.com}