Open specification for cryptographic governance receipts. When an AI agent acts, the Sanna Protocol evaluates the action against a constitution, enforces boundaries, and produces a signed receipt proving governance was applied. The receipt binds the policy document, the evaluation result, and the enforcement outcome into a single tamper-evident artifact using Ed25519 signatures and RFC 8785 JSON canonicalization.
| Path | Description |
|---|---|
spec/ |
Protocol specification v1.4 — receipt format, 20-field fingerprint (cv=9), tool identity, agent-model audit fields, multi-surface governance, canonicalization, signing, verification |
schemas/ |
JSON Schema (2020-12) for constitutions and receipts |
fixtures/ |
Golden test fixtures — test keypair, signed constitutions, 4 receipt variants, expected hashes, 1,296 canonicalization test vectors, 24 multi-surface (CLI/API) test vectors |
templates/ |
Starter constitutions: privacy-focused, developer, locked-down |
http/ |
HTTP header conventions (X-Sanna-Receipt, X-Sanna-Receipt-URL, X-Sanna-Verify, X-Sanna-Constitution) |
docs/ |
Implementers guide, protocol comparison (Sanna vs ORS v0.1) |
| Language | Package | Install |
|---|---|---|
| Python | sanna |
pip install sanna |
| TypeScript | @sanna-ai/core |
npm install @sanna-ai/core |
A conformant implementation must produce identical hashes and fingerprints for identical inputs. The fixtures/ directory contains everything needed to verify:
- Load the test keypair from
fixtures/keypairs/ - For each receipt in
fixtures/receipts/, recomputecontext_hash,output_hash, and the cv-appropriate fingerprint (20-field at cv=9, 16-field at cv=8, 14-field at cv=6/7, 12-field at cv=5) - Compare all computed values against
fixtures/golden-hashes.json - Verify Ed25519 signatures using the test public key
All hashes match → conformant. See docs/implementers-guide.md for the full algorithm and common pitfalls.
Every protocol PR is validated against both consumer SDK CI gates that touch
the spec submodule. The cross-sdk-smoke-python and cross-sdk-smoke-typescript
jobs in .github/workflows/ci.yml:
- Check out sanna-ai/sanna and sanna-ai/sanna-ts at their
mainbranches. - Override each consumer's
spec/submodule to point at the protocol PR's HEAD viagit fetch origin pull/<N>/head(works for fork PRs because GitHub mirrors all PRs on the upstream). - Run each consumer's spec-touching CI gates using the same commands and
environment that consumer's own CI uses:
- sanna-repo: schema parity diff,
python -m pytest tests/ -v, golden receipts verification (sanna-verify), example constitution verification (sanna-sign-constitution). All gated onSANNA_ALLOW_TEMP_DB=1. - sanna-ts:
npm run build, thennpm testwithSANNA_ALLOW_TEMP_DB=1.
- sanna-repo: schema parity diff,
- Fail the protocol PR if any gate fails.
The gate catches fixture-shape changes, schema breakage, signing or canonicalization divergence, and operational schema-mirror drift at protocol PR time -- before consumer SDKs bump the spec submodule.
Prior to this gate, protocol changes that broke fixture consumers were only detected when a consumer SDK's PR opened with the new submodule pin. The lag window was hours to days. The smoke gate moves detection to protocol PR time. Tradeoff: protocol PR CI duration increases from ~3 minutes to ~10-15 minutes.
If the smoke gate fails, the failing job's logs identify which consumer broke
and which gate. The protocol PR's content is the suspected cause. If a
consumer's main is itself broken (independent of the protocol PR), the smoke
fails as a side effect; fix the consumer's main first, then rerun the gate.
To reproduce the smoke check locally before opening a PR:
# In a temp clone of sanna-ai/sanna or sanna-ai/sanna-ts:
cd spec
git fetch origin <your-protocol-pr-sha>
git checkout <your-protocol-pr-sha>
cd ..
# Then run the consumer's test commands (python -m pytest tests/ -v;
# or npm run build && npm test).Protocol versions are independent of SDK versions. Patch versions (1.0.x) are clarifications and new test vectors. Minor versions (1.x.0) add backward-compatible fields. Major versions (x.0.0) are breaking changes to the receipt format, fingerprint algorithm, or signing protocol.