qf-verify

Independent, offline verifier for Query Fanout AI agent audit evidence bundles (.json) and evidence packs (.zip).

It is small and dependency-light (only cryptography; asn1crypto is optional and needed for RFC 3161 timestamps), so an auditor can read it and run it without trusting the Query Fanout service that produced the evidence. It makes no network calls.

Install

pip install "qf-verify[tsa]"       # from PyPI, with RFC 3161 timestamp support
pip install ./qf-verify            # or from a checkout of the Query Fanout repo
qf-verify --version

Python 3.10 or newer.

Use

# 1. Get the publisher's public keys from a source other than the evidence itself
curl -s "https://<host>/audit/keys" > keys.json          # public endpoint, no API key

# 2. Verify an evidence bundle or an evidence pack
curl -H "X-API-Key: $QF_API_KEY" "https://<host>/audit/export?run_id=r1" > bundle.json
qf-verify bundle.json --trusted-keys-file keys.json

curl -H "X-API-Key: $QF_API_KEY" "https://<host>/audit/evidence-pack?run_id=r1" -o pack.zip
qf-verify pack.zip --trusted-keys-file keys.json

# 3. Also check who issued the RFC 3161 timestamps: pass the timestamp
#    authority's CA certificate, downloaded from the authority itself
curl -s https://freetsa.org/files/cacert.pem > freetsa-ca.pem
qf-verify pack.zip --trusted-keys-file keys.json --tsa-ca freetsa-ca.pem

Exit codes: 0 verified, 1 verification failed, 2 unreadable input. Add --json for machine-readable output (it includes a timestamps list).

What it checks

See docs/audit-schema.md in the Query Fanout repository for the format.

Packs are read in memory and never extracted. Names containing paths, duplicate entries, and oversized archives are rejected.

Pin keys (--trusted-key / --trusted-keys-file) obtained out of band; without pinning, the verifier trusts the keys embedded in the bundle and says so. In the same way, without --tsa-ca or --pin-tsa-cert a timestamp's signature is checked but the identity of the authority is only reported, with a warning.

Limits: certificate revocation (CRL/OCSP) is not checked, because the verifier works offline. Chains are evaluated at the timestamp's generation time.

Changelog

• 0.3.0: --tsa-ca chain validation, timestamps on earlier checkpoints, anchors.json in packs, --version, keys file may be a plain list, PyPI metadata.
• 0.2.0: evidence packs (.zip).
• 0.1.0: evidence bundles.

License

Apache License 2.0, see LICENSE.