# Cryptography: Governance Contract Fabric

No custom primitives. Hashing is SHA-256 (`hashlib`). Signatures are Ed25519 (`cryptography`, pyca). The
transition chain uses HMAC-SHA256 under a per-deployment key from `cain_secret_material`.

| Signature | Key | Message |
|---|---|---|
| Issuer authorization | deployment contract-authority key (`<key dir>/contract_authority_ed25519.pem`, 0600, created race-safe) | `"CAIN/contract/v1/issuer" 0x1F fp 0x1F authority_digest` |
| Subject consent | the agent's RIG-registered key (held by the agent) | `"CAIN/contract/v1/subject" 0x1F fp` |
| Invocation PoP | agent key | `"CAIN/contract/v1/invoke" 0x1F CJ1({fp, nonce, request_hash, ts_ms})` |
| Receipt | authority key | `"CAIN/contract/v1/receipt" 0x1F SHA-256(CJ1(receipt body))` |
| Revocation | authority key | `"CAIN/contract/v1/revocation" 0x1F CJ1(statement)` |

Design notes:

* **Domain separation.** Every signed message starts with a distinct purpose tag, so a signature made for one purpose
  never verifies as another (tested pairwise).
* **Structured fingerprint.** The fingerprint is a hash over a map of per-section digests. This gives two things:
  * diff classification and selective disclosure can work section by section;
  * a change to one field changes exactly one section digest (tested for every leaf of a real contract).
* **Canonical form.** Floats are excluded. RFC 8785's number serialization is the usual source of
  cross-implementation disagreement, and integers avoid it. Strings must be NFC rather than being normalized
  silently, because silent normalization would let visually identical NFC and NFD inputs map to one contract.
* **Replay protection.** Each invocation carries a random 128-bit nonce, which is stored per contract. Its timestamp
  must be within ±60 s, and its signature covers the exact request hash.
* **Authority snapshot digest.** The digest of the subject's full RIG chain (keys, actions, scopes, runtime digests,
  statuses) is bound into the issuer signature and into every decision receipt.

Known cryptographic limitations:

* The authority key is a software key on the gateway host. There is no HSM or TEE, and no rotation or key-transparency
  log yet.
* A host attacker who can write the SQLite file can change contract state. The signed transition and receipt chains
  then disagree with the edited state (tested), but nothing outside the host notices unless receipts are anchored. The
  SCITT logging gives a second place to check, but the same operator runs it.
* Ed25519 via pyca is not constant-time-audited by this project. The fabric relies on the library.
