Change JWT encryption from HMAC to RSA with rotating keys

[Vianpyro]

Brief Description of Changes

This pull request upgrades the JWT security model from HS256 (HMAC with SHA-256) to RS256 (RSA with SHA-256) and introduces support for rotating RSA keys using KIDs (Key IDs).

Detailed Changes

• Switched JWT algorithm from HS256 to RS256 to leverage asymmetric cryptography.
• Implemented support for JWT header kid to identify which public key to use during verification.
• RSA key rotation is now supported via cron jobs that:
  • Generate new RSA key pairs periodically.
  • Update the current active signing key.
  • Archive older public keys for continued verification of existing tokens.
• Updated environment/config handling to support multiple public keys mapped by KID.
• Refactored token generation to include the correct kid in the JWT header.
• Enhanced error handling when a kid is missing, invalid, or points to an unknown public key.

Objective of Changes/Issue Resolved (if applicable)

This change improves the security, maintainability, and scalability of our JWT authentication system. By using RS256:

• The private signing key remains secure and private.
• Public verification keys can be shared safely across services.

By adding KID-based rotation:

• We reduce the risk of long-term key compromise.
• Services can verify tokens issued with older keys during the rotation window.

Resolves the problem of shared-secret risks and improves future readiness for distributed and multi-tenant environments.

Screenshots (if applicable)

Not applicable.

Verification Steps

1. Generate an initial RSA key pair with a unique KID.
2. Export JWT_PRIVATE_KEY, JWT_PUBLIC_KEYS (map of KIDs to public keys), and JWT_ACTIVE_KID.
3. Start the API — ensure it initializes correctly and reads the correct key config.
4. Authenticate and verify that:
   • Tokens are signed with the current private key.
   • The JWT header includes the correct kid.
   • Token verification succeeds using the matching public key from the map.
5. Manually rotate the key (as cron would) and verify:
   • New tokens are signed with the new private key and updated kid.
   • Previously issued tokens still verify correctly using archived public keys.

Notes for Reviewer

• The cron logic for rotation is external to this PR, but the app is now compatible with externally managed key updates.
• Review the structure and loading logic for the public key map (JWT_PUBLIC_KEYS) and how JWT_ACTIVE_KID is injected into the JWTs.
• Let me know if you'd like helper scripts or documentation for key generation.

[Copilot]

Copilot reviewed 25 out of 28 changed files in this pull request and generated 1 comment.

Files not reviewed (3)

• .devcontainer/Dockerfile: Language not supported
• Dockerfile: Language not supported
• entrypoint.sh: Language not supported

Comments suppressed due to low confidence (1)

jwtoken/tokens.py:55

• [nitpick] Consider providing a more descriptive error message for token type mismatches to aid in debugging, such as including the expected type versus the received type.

raise jwt.InvalidTokenError("Invalid token type")