Key rotation

Runbook

Entitlement signing secret rotation

Rotates the entitlement signing secret — the HMAC secret used to sign entitlement tokens and exported audit bundles. It is held in backend secrets; this page does not name the variable.

Scope — what this key does and does not touch

  • Affects: entitlement tokens (commercial state and capability grants) and the HMAC on exported audit bundles.
  • Does not affect: receipts, the receipt hash chain, or policy signatures. Those are signed with workspace Ed25519 authority keys — see the authority key rotation runbook.
  • Nothing on the governance path reads this secret. Policy evaluation and receipt writing continue unchanged during and after rotation.

When to rotate

  • Suspected exposure of the secret.
  • Scheduled hygiene rotation (recommended every 12 months).
  • Personnel change with access to the secret vault.

Expected impact

  • Tokens signed with the previous secret stop verifying at the moment of rotation. Clients silently re-issue on their next entitlement refresh, so the visible effect is a one-time refresh, not a loss of access.
  • Entitlement refresh happens outside the governance path. A stale token never blocks a decision from being evaluated or recorded.
  • Previously exported audit bundles keep their original HMAC. Re-verify them with the archived secret, or re-export.

Steps

  1. Generate a new high-entropy secret offline:
    openssl rand -base64 48
  2. Archive the current secret in cold storage before overwriting it — you need it to re-verify audit bundles exported under the old secret.
  3. Update the entitlement signing secret value in backend secrets.
  4. Redeploy so the server picks up the new secret. New token issuance uses it immediately.
  5. Confirm a signed-in workspace still resolves its capabilities after a refresh, and that an evaluation workspace still lands on its expected surfaces.

Rollback

If issuance misbehaves, restore the archived secret value and redeploy. Tokens issued under the new secret then stop verifying and clients refresh again — the same one-time refresh, in reverse.

Verification checklist

  • A signed-in workspace resolves its capability grants.
  • An audit bundle exported after rotation verifies cleanly.
  • avar verify still passes on receipts written before and after rotation — this secret is not in that path.
  • The receipt hash chain is continuous across the rotation.