Validate JWT signing keys at startup and document key rotation

[priscaenoch]

Problem

src/auth/keys.ts loads an RS256 key pair from JWT_PRIVATE_KEY/JWT_PUBLIC_KEY (with JWT_KEY_ID) and src/auth/tokens.ts signs tokens with it. If those environment variables are absent or malformed, the failure surfaces later at token-signing/verification time rather than at boot, and it is not documented how to generate the keys, what JWT_KEY_ID is for, or how to rotate keys. A silent or insecure fallback in production would be a serious auth problem.

What needs to be done

• Validate at startup that the required JWT keys are present and parse as a valid RS256 key pair; fail fast with a clear message when they are missing or invalid in a production configuration.
• Ensure there is no insecure default/fallback key path in production.
• Document how to generate the key pair, the role of JWT_KEY_ID, and a rotation procedure (supporting multiple valid kids during rotation).
• Confirm keys are never logged.

Files

• src/auth/keys.ts, src/auth/tokens.ts
• .env.example, README.md

Acceptance deliverables

• Missing/invalid JWT keys fail at startup with an actionable message.
• Key generation and rotation are documented.
• All CI checks pass; the change cannot be merged until CI is green.

Tests to pass

• Test: startup validation rejects missing/malformed keys.
• Test: a token signed with the configured key verifies against the configured public key.

[jchinedu]

let me work on this issue i have good experience on this issue

[grantfox-oss]

🦊 GrantFox — @jchinedu has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #46)
2. Your PR will be reviewed by the octraban maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@jchinedu's PR #54 was approved and merged by @priscaenoch.

🏆 @jchinedu: You earned 35 FoxPoints for this contribution! Your current tier: Builder (1,006 total points). Track your full progress on GrantFox.

👏 Great work, @jchinedu! Keep contributing to octraban.