Key Rotation Plan

Planned rotation cadences and the implementation status of the rotation mechanism for each cryptographic key the Maelstrom AI ISMS tracks

Public

Key Rotation Plan

Owner: Cryptography Specialist Last Updated: 14 April 2026 Next Review: 14 July 2026 Relates to: Key Rotation Procedure, Key Rotation Log (maintained internally; available to auditors and enterprise customers on request), Cryptography Policy

This plan enumerates every key the ISMS tracks, the target rotation cadence, and the implementation status of the rotation mechanism. Maelstrom AI records the status of each key’s rotation mechanism in one place so a policy claim always sits beside an implementation status.

Status legend

SymbolMeaning
ImplementedRotation runbook exists, has been exercised at least once, and rotation is supported without user-visible breakage beyond the documented impact.
PlannedCadence is declared in policy. Runbook is drafted. Rotation would succeed but may invalidate sessions or credentials until the supporting dual-key flow lands.
Manual onlyNo automation. Rotation requires a human operator following the runbook end-to-end with downtime acceptance.

Key inventory and status

KeyTarget cadenceStatusDelivery vehicleNotes
Issuer signing key (RedJubjub) in provii-issuerAnnual or on compromiseImplemented, manual onlyOperator runbook at /operations/key-rotation-procedure#issuer-signing-key-rotationJWKS transition period holds old plus new key for seven days.
Verifier HMAC key in provii-verifier90 days recommendedImplemented, manual onlyOperator runbook at /operations/key-rotation-procedure#customer-api-key-rotation and analogous verifier pathDual-key acceptance not yet implemented; rotation invalidates in-flight verifier sessions.
Customer-facing API keys issued by provii-management90 days recommended, customer-drivenImplemented, customer-drivenAdmin Portal flow plus support pathCustomer chooses cut-over window.
Cloudflare account API tokenAnnualImplemented, manual onlyOperator runbook at /operations/key-rotation-procedure#cloudflare-api-token-rotationRequires GitHub Actions secret updates in every repo.
GitHub Actions secrets (derived from Cloudflare token)Triggered by Cloudflare token rotationImplemented, manual onlyOperator runbook with gh secret set commandsDownstream of the Cloudflare token rotation.
DOCS_SESSION_HMAC_KEY (docs interactive sandbox session HMAC)Planned 90 daysPlannedSecrets Store (internal reference); rotation currently re-writes Version N in the store.The docs session layer (demo-web-provii-agegate/src/docs/session.ts) runs a single-kid deployment. A rotation today invalidates all active __Host-docs_session cookies until users re-authenticate. Introducing a kid prefix on the bearer and dual-key acceptance will let rotation proceed without breaking in-flight sessions. Until that flow lands, the rotation cadence is a policy claim supported only by the single-kid emergency-rotate path.
DOCS_ATTESTATION_ED25519_SEED (docs sandbox issuer attestation seed)On compromise or scheduled rotationPlannedSecrets Store (internal reference); rotation re-writes Version N. The same kid-header flow planned for DOCS_SESSION_HMAC_KEY applies.Current rotation invalidates all in-flight sandbox attestations.
PII_HASH_KEY (HMAC-SHA-256 key for hashed-IP and other PII indexes)On compromise onlyImplemented, manual onlySecrets Store update followed by redeploy of consumer workersRotation invalidates all historical PII hash equality. Documented as a design property, not a defect.

Planned work to close the Planned items

  1. Implement the kid prefix on the __Host-docs_session bearer in demo-web-provii-agegate/src/docs/session.ts. Accept bearers minted under either the current or the previous generation of DOCS_SESSION_HMAC_KEY.
  2. Implement the kid prefix on sandbox attestations signed with DOCS_ATTESTATION_ED25519_SEED. Verifier-side acceptance reads the kid and selects the matching verification key from a two-slot keyring.
  3. Add a rotation cron entry (or documented quarterly calendar invite with runbook link) that exercises DOCS_SESSION_HMAC_KEY rotation on the 90-day target cadence. Populate the key rotation log on each exercise.
  4. After the first real rotation, advance the status of both planned entries above from Planned to Implemented.

Policy-to-implementation reconciliation

The 90-day rotation cadence for DOCS_SESSION_HMAC_KEY is a policy target. The implementation sits behind the planned work above. This plan is the ISMS artefact that audits the claim; the design proposals under internal docs are engineering artefacts, not ISMS artefacts.

If the dual-kid flow is not available by the first scheduled 90-day rotation window, Maelstrom AI will perform a single-kid rotation using the emergency path and accept the user-visible session invalidation as a planned downtime event. Letting the key age past 90 days is not acceptable under the declared cadence.

Change log

VersionDateSummary
1.02026-04-14Initial plan covering the DOCS_SESSION_HMAC_KEY rotation mechanism and the wider key inventory.