ainfera-verify

Offline audit chain verifier for Ainfera Routing. Trust no one — verify yourself.

Details

Visibility	PUBLIC
Primary Language	Python + TypeScript
Created	2026-05-14
Last Updated	2026-07-11

Quick Start

pip install ainfera-verify

Or with Homebrew:

brew install ainfera/tap/verify

Usage

Verify a full AuditChain by Agent ID (fetches from the public read endpoint, then verifies offline):

ainfera-verify chain manwe

Inspect a single AuditEvent:

ainfera-verify event manwe 1245

Verify an offline Annex IV bundle export (use this for air-gapped review):

ainfera-verify bundle ./manwe-2026-05-19.zip

Or verify the minimal JSON export from GET /v1/audit/{agent_id}/annex-iv:

ainfera-verify bundle ./export.json --pinned-key-fingerprint <sha256-hex>

Verify the baseline math on a savings receipt export:

ainfera-verify savings ./receipt.json

Verify a complete receipt-to-inference chain (pricing + audit linkage):

ainfera-verify receipt ./receipt.json --chain ./chain-export.json

What it verifies

For every AuditEvent in the chain:

1. Hash continuity — previous_hash matches the prior event's event_hash.
2. Event integrity — event_hash is the SHA-256 of canonical_json({agent_id, seq, event_type, payload, previous_hash}).
3. Sequence continuity — seq values are contiguous starting from 1 (no gaps, no duplicates).
4. Ed25519 signature — when sig_alg='ed25519', the signature validates against the platform public key published at /.well-known/ainfera-public-key.json.
5. HMAC signature — for legacy events (sig_alg='hmac'), the hmac_signature validates against the HMAC key published at /.well-known.
6. Sigstore signature — when present, validated against the Rekor transparency log.

If any check fails, the verifier reports the exact seq where the chain breaks.

For a savings receipt, the verifier fails closed when the receipt:

• has no audit event reference
• uses projected cost as the baseline
• omits the frozen baseline evidence
• reports arithmetic that does not match max(0, baseline - actual)

For receipt-to-inference verification, the verifier checks that:

• The receipt's audit_event_ref points to a real event in the chain
• The event's payload contains inference metadata (provider, model, cost)
• The receipt's actual_cost matches the event's cost_usd

For Merkle root anchoring, the verifier checks that:

• The chain tip hash matches an externally published anchor (e.g., in a transparency log or on-chain)
• The Merkle root computed from all event hashes matches the published root

Trust model

• The CLI ships under Apache 2.0. The verification logic is auditable.
• After events are fetched, verification is fully offline — no network calls, no Ainfera dependency.
• The key material is published at .well-known/ainfera-public-key.json and cached locally.
• For air-gapped verification, download the key once or use a bundle export (which embeds the key).

Ed25519 — shipped

Every audit event is now signed with Ed25519 (asymmetric). This means:

• Hash continuity (checks 1-3) is independent of who holds the signing key and is fully verifiable offline. A tampered chain breaks at the exact seq where the modification was introduced. This is the load-bearing security property.
• Ed25519 signature (check 4) is an asymmetric construction. Anyone with the public key published at /.well-known/ainfera-public-key.json can verify that Ainfera signed every event — no shared secret, no trust assumption beyond key authenticity.

AIN-205 (2026-05-21): migrated from HMAC-SHA256 to Ed25519 producer-side signing. Historical events with sig_alg='hmac' are still verifiable via HMAC; all new events sign with Ed25519. The hash chain itself is unchanged — tampering still breaks every subsequent event_hash regardless of signature algorithm.

If your threat model requires out-of-band key verification, pin the published key fingerprint and use ainfera-verify --pinned-key-fingerprint.

Historical trust epochs

See docs/trust-epochs.md for the full history of signature schemes and key rotations.

TypeScript / browser version

A browser-compatible TypeScript port lives in typescript/. It implements the same verification logic and can run entirely in the browser with no server dependency.

cd typescript && npm install && npm test

Test vectors

Canonical test vectors with known-good hashes are published in test-vectors/. Each vector includes the input payload, expected hash, expected signature, and a description. These allow independent reimplementers to verify their implementation matches.

EU AI Act Annex IV

Annex IV technical documentation requires verifiable evidence of system behavior. ainfera-verify bundle produces a pass/fail with the cryptographic chain of custody — sufficient evidence for a regulator's technical reviewer.

Web version

Don't want to install anything? Drop a bundle into verify.ainfera.ai. All verification runs in your browser.

License

This repository is part of the Ainfera project.

Status