Rotating your e-signature key

Your company has one signing key for evidence: it seals the audit chain behind every signed agreement and every published report version. This page explains what that key covers, what happens to the old one when you replace it, and how to confirm that nothing you already signed was affected.

It is not the key that signs your login sessions. That one belongs to whoever operates the deployment and is documented with the engine, in docs/operate/rotate-jwt-keyring.md.

What this key signs

Every signature event — a client opening the agreement, typing their name, submitting it — is written as a row in an audit chain, and each row is sealed with your company's active Ed25519 key. Published report versions are sealed the same way. The seal is what lets anyone check later that the record was not edited after the fact.

Each sealed row records the fingerprint of the key that sealed it. That detail is the whole reason rotation is safe: verification never asks "what key does this company hold now", it asks "what key does this row name".

Why old keys are never deleted

When you rotate, the previous key is retired, not removed. It stays on file permanently.

Deleting a retired public key would invalidate every signature it ever verified — the evidence would still exist, but nothing could prove it. So the retired key is kept for as long as the signatures it covers are kept, which for signed agreements and published reports is indefinitely.

Nothing is re-signed during a rotation. Re-sealing old rows with the new key would manufacture a signing record that never happened, which is exactly what the chain exists to rule out.

When to rotate

Rotation is event-driven, not scheduled. There is no benefit to rotating on a calendar. Rotate when:

• you have reason to believe the key material was exposed;
• the person or entity holding signing authority for the company changes;
• an audit or compliance review asks you to.

How to rotate

Rotation is an owner-only action. Today it is performed through the API rather than from a settings screen — there is no button for it yet:

POST /api/admin/agreements/signing-key/rotate

Called with an owner session, it retires the current key, mints a replacement, and returns both fingerprints: the new active one and the one just retired (null if your company had no key yet).

Both fingerprints are written to your audit log as signing_key.rotate. That record is what lets a later reader say which key covers which stretch of your company's evidence.

Confirming that older signatures still verify

After rotating, check one agreement signed before the rotation and one signed after:

1. Open the signed agreement and use its verification link. It resolves the key by the fingerprint recorded on the row, so a pre-rotation signature verifies against the retired key.
2. An audit-trail export includes every key that chain used, so a chain that spans the rotation verifies as a whole — and can be checked by someone outside the system, with no access to your account.

If a pre-rotation signature fails to verify after a rotation, that is not expected behaviour: stop and report it rather than re-signing anything.