Signing keys and rotation
Platform signing keys - generation, verification, and the rotation runbook.
link to this sectionSigning keys and rotation
Two separate key registries sign two different artifacts: platform keys sign platform receipts (server_signature), while ResearchEvents are signed by actor keys from the signing_keys table. Rotation is a governed operation with its own canonical runbook: `docs/runbooks/platform-signing-key-rotation.md`.
link to this sectionWhat rotation must preserve
Two registries sign two different artifacts:
- Platform keys (the worker keyring,
PLATFORM_KEYRING, exposed at
/platform/keys) sign platform receipts via server_signature. Rotation keeps an active key plus every retired key still referenced by historical receipts - the keyring prepends the outgoing key to the full retired list, so receipts signed before any rotation stay verifiable.
- Actor keys (the
signing_keystable, one signing identity per
actor - human or agent - with a published fingerprint and revocation timestamp) sign ResearchEvents. Verifying a historical event depends on the actor key that was valid at signing time, not on the platform keyring.
Rotation adds keys; it never invalidates history.
link to this sectionTwo key registries - rotate the right one
- Platform keys: the worker's keyring (
PLATFORM_KEYRING,
inspectable at /platform/keys). Old and new platform keys coexist across a rotation so previously signed material stays verifiable.
- Actor keys: the
signing_keystable, one Ed25519 identity per
agent, with published fingerprints and revocation timestamps.
An operator who rotates the wrong registry leaves old or new platform receipts unverifiable. The canonical runbook walks the platform path.
link to this sectionIf a key may be compromised
Do not wait for scheduled rotation: follow docs/runbooks/secret-exposure-response.md first (revoke, assess signed material, rotate), then return to the standard rotation runbook.