tools: receipt-signed decision logs for post-incident verification

[tomjwxf]

What

Adds an optional receipt signer for cereal decision events in `tools/lib/`. Each event (controlsState, lateralPlan, etc.) produces an HMAC-signed, hash-chained receipt. The chain is independently verifiable without trusting the device operator.

Zero new dependencies. Stdlib only (hashlib, hmac, json). Nothing touches selfdrive or cereal.

Why

Post-incident investigation. If a comma device is involved in an incident, the log files are mutable (stored on the device filesystem). Someone with access can edit them. A signed receipt chain means:

• Editing any log entry breaks its signature
• Deleting a receipt breaks the hash chain (the next receipt points to a hash that no longer exists)
• Inserting a receipt between two legitimate ones is detectable (the parent hashes don't match)
• Anyone with the verification key can confirm the chain offline, without trusting comma's servers

This matters for insurance claims, regulatory inquiries, and legal discovery where the question is "prove the log hasn't been altered since the drive."

How it works

```python
from tools.lib.receipt_signer import ReceiptChain

chain = ReceiptChain(device_id="comma-3x-abc123")

Sign any decision event

chain.sign_event("controlsState", {"enabled": True, "vEgo": 25.3})
chain.sign_event("lateralPlan", {"dPath": [0.0, 0.1, 0.3]})

Verify the chain

assert chain.verify_all() # True

Tamper with a receipt

chain._receipts[0].payload["event_type"] = "TAMPERED"
assert not chain.verify_all() # False, tampering detected

Export for offline verification

chain.export_jsonl("/data/receipts/route_abc.jsonl")
```

Privacy-preserving: receipts store `event_hash` (SHA-256 of the event data), not raw sensor values. The receipt proves the event existed with specific content without exposing the content in the receipt itself.

Integration sketch (not in this PR)

```python
chain = create_receipt_logger(device_id=Params().get("DongleId"))
sm = messaging.SubMaster(['controlsState', 'lateralPlan'])
while True:
sm.update()
if sm.updated['controlsState']:
chain.sign_event("controlsState", sm['controlsState'].to_dict())
```

This is deliberately a tools/lib utility, not wired into any control path. Integration into loggerd or a daemon would be a separate PR if there's interest.

Production upgrade path

This PR uses HMAC-SHA256 (symmetric key, zero deps). The receipt envelope format is designed for Ed25519 upgrade:

• Swap `"alg": "HS256"` to `"alg": "EdDSA"`
• Key moves to a secure element (e.g., ATECC608B in a future hardware revision)
• Verification becomes asymmetric (anyone verifies, only the device signs)

The envelope format follows IETF draft-farley-acta-signed-receipts. Offline verification CLI: `npx @veritasacta/verify`.

Tests

10 tests in `tools/lib/test_receipt_signer.py`:

```
PYTHONPATH=. python3 tools/lib/test_receipt_signer.py

All 10 tests passed.

```

Covers: JCS canonicalization, sign/verify, tamper detection, chain linking, chain break detection, JSONL export, sequence numbering, privacy (raw data not in receipt).

Files changed

File	Lines	What
`tools/lib/receipt_signer.py`	174	ReceiptChain class + create_receipt_logger
`tools/lib/test_receipt_signer.py`	119	10 tests

No existing files modified.

Context

Same receipt format used by Microsoft Agent Governance Toolkit and AWS Cedar for Agents for AI agent decision logging. This extends it to autonomous vehicle decisions. The format is standards-based (IETF draft) so receipts from any implementation verify with the same CLI.

@adeebshihadeh, happy to adjust scope or location if tools/lib isn't the right place.

[github-actions]

Process replay diff report

Replays driving segments through this PR and compares the behavior to master.
Please review any changes carefully to ensure they are expected.

✅ 0 changed, 66 passed, 0 errors