hoangsonww / hoangsonww/JWT-Module
Feature: Support RS256/ES256 signing with JWKS endpoint and key rotation
- Dominant language
- TypeScript
- Stars
- 12
- Forks
- 6
- PR merge metrics
- No merged PRs in 30d
Description
## Why
Current HS256 shared-secret signing is simple but harder to operate securely across multiple services. Public/private key signing with JWKS enables safer verification and key rotation.
## Proposal
Add asymmetric signing modes with managed key lifecycle:
- Support `RS256` (required) and `ES256` (optional)
- Publish public keys via `/.well-known/jwks.json`
- Include `kid` in JWT headers
- Rotation strategy with active + grace-period keys
## Scope
- Configurable signing algorithm and key source
- Key manager abstraction (file/env/KMS-ready interface)
- Backward-compatible migration path from HS256
- Verification logic that supports previous keys during rollout window
## API/Behavior Changes
- New public JWKS endpoint
- Token headers include `kid`
- Internal verifier checks `alg` allowlist and key by `kid`
## Technical Notes
- Prevent alg confusion attacks (strict algorithm enforcement)
- Add clock-skew handling and key cache controls for consumers
- Provide operational docs for rotation playbook and emergency key revoke
## Acceptance Criteria
- Access/refresh tokens can be signed + verified with RS256
- JWKS endpoint returns active public keys with valid `kid`
- Rotated keys verify old tokens during grace window, then expire cleanly
- Security tests cover invalid `kid`, wrong `alg`, and revoked key cases
- Migration guide documents HS256 -> RS256 cutover steps
## Out of Scope
- Full OIDC provider implementation
- Dynamic client registration
Contributor guide
Assessment
This issue has not been assessed yet.