# Raven Cryptographic Agility & Long-Term Receipt Policy

Security-readiness document. Raven does NOT claim post-quantum security, and
quantum computers do NOT currently break Raven's signatures. This document
exists so receipts stay verifiable across key rotations and future algorithm
migrations — algorithm agility as a design principle.

## Current behavior (verified against the live verifier, 2026-06-05)

- Signing algorithm: **ed25519**, domain-separated
  (`"raven-official-attestation" || officialAttestationHash`).
- Current key id: **rvk_c2997e90215279c2**.
- Public key endpoint: `GET https://raven-hosted-verifier.onrender.com/pubkey`
  → `{ keys: [{ keyId, publicKeyBase64 (SPKI), alg }], domain, version: "v2" }`.
- Receipt fields ACTUALLY returned by `POST /verify` today:
  `ok, verdict, engineOutcome, reason, findingCodes, triggeringFindingCodes,
  findings, coverageGaps, replayable, rpc (incl. observedSlot), engineVersion,
  raven_version, replayHash, officialAttestationHash, keyId, issuedAt,
  signature, attestationPublicKey, signatureAlg, served_at`.

## What a verifying agent must check today

1. `keyId` matches a key served by `/pubkey` (today: rvk_c2997e90215279c2).
2. `signatureAlg` is the algorithm published for that key (today: ed25519).
3. Recompute `replayHash` from the response fields (canonical JSON; recipe in
   the repo) and compare.
4. Verify `signature` over `utf8(domain) || officialAttestationHash` using the
   published public key.
5. Treat `coverageGaps` as normative: listed surfaces were not evaluated.

## Why receipts are key-scoped and versioned

A receipt is a historical claim: "this key said this, then." Binding each
receipt to the keyId and engineVersion that produced it means rotation and
engine evolution never silently rewrite history.

## Key rotation principles
- Rotation is a deliberate operator action (see operator/skills/
  key-rotation-review.md) — never automated, always human-approved.
- A new key gets a new keyId; `/pubkey` may serve multiple keys.
- Old receipts remain verifiable against the key that signed them. Agents
  must NOT assume the newest key verifies old receipts.

## Retired keys
Retired = no longer signs new receipts; remains published (marked) so
historical receipts verify. Honoring old signatures is the point of receipts.

## Revoked keys
Revoked = compromise suspected. A revoked key blocks future trust; receipts
signed by it require case-by-case review (cross-check against the Quality
Ledger / re-run the request). Revocation semantics will be published in
/key-policy.json `keyStates` before any revocation event.

## Old receipt verification policy
Store the full receipt (all fields above). Verification of a stored receipt
needs only: the receipt + the historical public key for its keyId. Raven
keeps retired public keys published for this purpose.

## Future algorithm migration (future receipt-version plan — NOT current behavior)
If a stronger algorithm is adopted (including post-quantum candidates), Raven
will: add it under a NEW keyId and a NEW receipt/attestation version; publish
both algorithms in `/pubkey` and `/key-policy.json` during transition; never
re-sign or mutate historical receipts. Migration is additive.

## What this document does not claim
No post-quantum guarantee. No claim that current cryptography is broken. No
investment, market, or asset commentary of any kind.