Metadata-Version: 2.4
Name: aer1-verify
Version: 0.1.1
Summary: Verify any AER-1 verifiable execution receipt completely offline. Free, no network, no trusted server. Chain-head anchoring to Nostr and Bitcoin.
License: MIT
Project-URL: Homepage, https://zambo.dev
Project-URL: Documentation, https://datatracker.ietf.org/doc/draft-zambo-aer1/
Project-URL: Repository, https://gitlab.com/rambozambodotdev/zambo
Project-URL: Registry, https://rambozambodotdev.gitlab.io/registry.html
Keywords: aer-1,aer1,receipt,verification,ai-agents,ai-agent-receipt,execution-receipt,verifiable-receipt,audit,tamper-evident,agent-audit-trail,agent-accountability
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# aer1-verify

Verify an AER-1 verifiable execution receipt **completely offline**. No network, no API key, no trust in any server, including ours. Free forever. It also verifies receipt chain-head anchors on Nostr and Bitcoin, so a receipt recorded long ago can be rechecked against a public anchor.

> **Try it live:** [interactive demo](https://rambozambodotdev.gitlab.io/aer1-hub/try/) — mint a real verifiable receipt in your browser, no install, no signup.

## Why this exists

A verifiable receipt says: this AI did this work, and the record was not changed afterward. That claim should not require you to trust the company that issued it. `aer1-verify` rechecks the cryptography locally, from the receipt data alone. If the math holds, the receipt is intact. If it does not, the receipt is forged or corrupt.

The honest boundary, stated plainly: this tool proves the recorded result **was not changed**. It does not prove the recorded result **is correct**. Integrity, not truth. That is what AER-1 receipts claim, and it is all this tool checks.

## Install

Single file, standard library only. No dependencies.

```bash
# Option 1: copy the file, nothing else needed
curl -O https://gitlab.com/rambozambodotdev/zambo/-/raw/main/aer1-verifier/aer1_verify.py

# Option 2: pip install
pip install .
```

## Use

Get a receipt as JSON. From zambo.dev, the verify endpoint returns one:

```bash
curl -s "https://zambo.dev/api/v2/receipt/<receipt-id>/verify" -o receipt.json
```

Then verify it offline (unplug your network if you want to prove the point):

```bash
python3 aer1_verify.py receipt.json
```

Output:

```
aer1-verify 0.1.0
receipt: c5dadb0a-8f99-40f6-b30a-40852435b752
  [PASS] input shape recognized (envelope.receipt)
  [PASS] required fields present (id, canonical_bytes, output_hash)
  [PASS] canonical_bytes is strict base64 -- 740 bytes
  [PASS] decoded bytes are strict UTF-8 (fail closed)
  [PASS] canonical_byte_length matches decoded length -- field=740 actual=740
  [PASS] canonical JSON parses
  [PASS] canonical form re-encodes byte-exactly
  [PASS] output_hash is sha256: + 64 lowercase hex chars
  [PASS] hash_algorithm agrees with sha256 -- got: 'sha256'
  [PASS] sha256(canonical_bytes) equals output_hash
  [PASS] created_at/timestamp is a real calendar date
  [PASS] timestamp is not in the future
  [PASS] verification_status (server claim, informational only) -- server said: 'verified'; offline verdict rests on the math above
VERDICT: PASS: fingerprint matches, receipt intact
```

Machine-readable output for CI:

```bash
python3 aer1_verify.py receipt.json --json
```

Exit codes: `0` = PASS, `1` = FAIL, `2` = usage or input error.

## What it checks

1. **Required fields**: the receipt carries `id`, `canonical_bytes`, `output_hash`.
2. **Strict base64**: the committed bytes decode cleanly, no leniency.
3. **Strict UTF-8**: the bytes are valid UTF-8. Anything else fails closed.
4. **Byte length agreement**: the declared length matches the decoded bytes.
5. **Canonical round-trip**: the JSON re-encodes to byte-identical bytes (sorted keys, compact separators, UTF-8). The fingerprint covers exactly what you see; nothing hides outside it.
6. **Fingerprint shape**: `output_hash` is `sha256:` plus 64 lowercase hex chars.
7. **Algorithm agreement**: the declared hash algorithm is sha256.
8. **The core check**: `SHA-256(canonical_bytes)` equals the committed `output_hash`. This is the whole proof.
9. **Timestamp sanity**: the issue time is a real calendar date and not in the future.

The server's `verification_status` field is **reported, never trusted**. An offline verifier checks math, not the issuer's word. That is the point.

## Try breaking it

```bash
# Take a real receipt, change one character in the recorded result,
# keep the old fingerprint, and watch verification fail:
python3 - <<'EOF'
import json, base64
r = json.load(open('receipt.json'))['receipt']
raw = base64.b64decode(r['canonical_bytes']).decode('utf-8')
raw = raw.replace('164.00', '164.01', 1)  # one character
r['canonical_bytes'] = base64.b64encode(raw.encode()).decode()
r['canonical_byte_length'] = len(raw.encode())
json.dump({'receipt': r}, open('forged.json', 'w'))
EOF
python3 aer1_verify.py forged.json   # -> VERDICT: FAIL
```

One character. The fingerprint no longer matches. That is the security property, demonstrated negatively.

## Input shapes

Liberal on input, strict on math. Accepts:

- the bare receipt object (`canonical_bytes` / `output_hash` present),
- the `{"receipt": {...}}` envelope from the zambo.dev verify endpoint,
- the MCP `_receipt` shape returned with tool calls.

## Tests

```bash
python3 tests/test_verifier.py
```

Fixtures include real receipts issued by zambo.dev plus adversarial mutations (tampered bytes, bad base64, wrong digest, non-UTF-8 bytes). The real-receipt fixtures must keep passing: they pin this tool to production.

## Relation to AER-1

AER-1 is the AI Agent Execution Receipt specification (IETF Internet-Draft `draft-zambo-aer1`). This verifier implements the receipt-integrity checks from the draft's canonicalization and fingerprint rules. It is a verifier, not an issuer: it cannot create receipts, only judge them.

## License

Same as the parent repository.
