# ToolHost — Signing-Key Custody & Rotation (D8)

*Anchor: project-docs/03-engineering-design/01-identity-auth.md §7 (advisor-locked 2026-07-06);
00-FINAL-GOAL.md §5 #8.*

[Current implementation status, verified 2026-07-12] The 85-minute rotation mechanics and their
failure-mode tests exist for the local signing provider. KMS/HSM signing, persisted rotation
state, and a production custody boot gate are **not yet wired**. ToolHost therefore makes no
production KMS/HSM, crypto-custody, or HA signing claim today.

## Custody

The target production posture is a non-exportable KMS/HSM signing key (AWS KMS-class provider,
ECC NIST P-256 / ES256) with provider-audited sign operations. That provider interface is a
design seam, not a deployed capability: current signing is local/in-process and is suitable only
for development evaluation. A customer requiring KMS/HSM or BYOK custody should treat it as a
launch blocker until the provider, boot validation, and production conformance evidence ship.

## The 5-phase rotation state machine

`normal → published → switched → cleanup_scheduled → complete`

1. **published** — in the target KMS-backed deployment, a new key is generated and published to the JWKS *before* anything else
   references it; a key that is generated but not yet published cannot be selected for signing.
2. **switched** — new tokens are signed with the new key; the old key remains in JWKS so
   already-issued tokens still verify.
3. **cleanup_scheduled → complete** — the old key leaves JWKS only after
   `now ≥ switched_at + max_token_TTL + safety_margin`; the prior key is disabled (retained for
   audit), status moves to `retired`.

## The 85-minute overlap window

The safety margin applies at both transitions: `published → switched` waits
`cache_TTL + margin = 20 min`; `switched → complete` waits `token_TTL + margin = 65 min` — the old
key lives in JWKS for `20 + 65 = 85 minutes` total. The three inputs (JWKS cache TTL, token TTL,
safety margin) are config-coupled: raising token TTL lengthens the window automatically, and the
config validator refuses a rotation schedule tighter than the derived window.

Compliance-short token TTLs (5–15 minutes) shrink both the compromise blast radius and the
rotation window — the recommended enterprise posture.

## Compromise / emergency revocation

The documented target response is a platform-admin action that removes the affected key from
rotation, records the actor, and bounds the re-authentication blast radius by token TTL. The
platform-admin route itself remains behind its second advisor gate, so this is not an available
production operation or a sales claim today.