# CAIN signed records, version 1 An open description of how CAIN signs evidence, so anyone can verify a CAIN record with their own code. Test vectors: [`cain-signed-records-v1-vectors.json`](cain-signed-records-v1-vectors.json). Reference verifiers that import no CAIN code: `verify-record.html` (browser), `verify_proofloop_precision.py`, `verify_cain_jail.py`. ## 1. Shape A: `{body, sha256, signature, public_key}` Used by agent-jail run receipts, RewardGuard certificates, package-watch reports, AIUC-1 evidence maps, delegation grants, held-out results, eval records, redaction receipts and oversight approvals. ``` canonical = JSON(body) with keys sorted at every level, separators "," and ":" (no whitespace), non-ASCII characters written as-is (UTF-8), numbers written exactly as they appear in the record sha256 = lowercase hex SHA-256 of canonical signature = lowercase hex Ed25519 signature over canonical (not over the hash) public_key= lowercase hex of the 32-byte raw Ed25519 public key ``` Strings are escaped as Python's `json.dumps(ensure_ascii=False)` does: `\"`, `\\`, `\n`, `\r`, `\t`, `\b`, `\f`, other characters below U+0020 as `\u00XX`, everything else literal. A verifier MUST recompute `sha256` from `body`, check the signature against a public key it trusts (pinned), and, where the record type defines one, recompute the verdict from the recorded facts rather than trusting it (RewardGuard `verdict`, package-watch `verdict`, eval `status`). ## 2. Shape B: `{..., record_sha256, signature: {alg, public_key_b64, key_fingerprint, sig_b64}}` Used by PROOFLOOP evaluation, precision-ledger and self-audit records. ``` body = the record without record_sha256, signature and signed_payload_b64 canonical = JSON(body), sorted keys, compact separators, non-ASCII escaped as \uXXXX (ensure_ascii=True) record_sha256 = hex SHA-256 of canonical sig_b64 = base64 Ed25519 signature over canonical key_fingerprint = "SHA256:" + hex SHA-256 of the raw public key ``` The CAIN evidence key fingerprint is `SHA256:2232b4add9b35d4016e5be270df4ed56e0dc9b39a0530ac69891073253aae90d`. ## 3. Hash-chained ledgers Agent-jail ledgers are JSONL. Each row carries `seq` (0, 1, 2, …), `prev` (the previous row's `hash`; 64 zeros for the first) and `hash = SHA-256(prev_hex + canonical(row without "hash"))` with the Shape A canonical rules. Any edit, insertion, deletion or reordering breaks the chain from that row on. A run receipt binds the ledger by its head hash. ## 4. SCITT signed statements Any record above can be wrapped as a COSE_Sign1 (RFC 9052, CBOR tag 18): protected header `{1: -8 (EdDSA), 3: "application/json", 4: kid = first 16 bytes of SHA-256(raw public key), 15: {1: issuer, 2: subject, 6: iat}}`, empty unprotected header, payload = Shape A canonical bytes of the record. Registration is notarization of the statement's SHA-256 by the CAIN-42 PBFT validator quorum (N = 3f + 1, quorum 2f + 1). That registration is NOT an RFC 9942 COSE Receipt (it carries no Merkle inclusion proof). ## 5. What a valid signature does and does not prove It proves the record was not changed after it was signed by the holder of that key. It does not prove who holds the key unless you pinned the key from a source you trust, and it does not prove the content is true: each record type states its own scope and limits in its body.