Skip to content

Production JWKS key rotation is not implemented #175

Description

@Bccorb

Part of #155. Session 7.

Problem

The production branch of ensureKeys() is an empty function body with a comment
(src/scripts/keyManager.ts:52-53):

  // PRODUCTION MODE
  // Implement a first time JWKS rotation. See Seamless Auth docs for guides
}

There is no rotation mechanism, no rotation schedule and no rotation runbook step.
getSigningKey reads an active key id from the environment and caches it
(src/utils/signingKeyStore.ts), so rotation today is
a manual environment change with no tooling and no tested procedure.

Separately, getSecret reads process.env and nothing else
(src/utils/secretsStore.ts). There is no KMS or secrets
manager integration.

Why it matters

NIST 800-53 SC-12 and SC-17. SECURITY.md tells adopters to "rotate
signing and session keys periodically", which is advice the product does not
currently help them follow. The JWKS publication side already supports multiple
public keys by key id, so the hard part of rotation is designed and simply is not
driven by anything.

What to do

  • Implement key generation and rotation, including the overlap window where the old
    public key stays published while tokens signed with it are still valid
  • Add a documented, tested rotation procedure to
    docs/production-operations.md
  • Consider a pluggable secret store interface so a KMS or secrets manager can be
    used without patching the code

Acceptance

  • An operator can rotate the signing key without downtime, following a written
    procedure
  • Tokens signed with the previous key verify until they expire
  • The procedure is covered by a test

Freeze status

Anticipated GovRAMP finding (exception 2), and a gap between SECURITY.md guidance
and product capability.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestsecuritySecurity-sensitive: auth, tokens, OTP, sessions, crypto

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions