hoangsonww / hoangsonww/JWT-Module

Feature: Support RS256/ES256 signing with JWKS endpoint and key rotation

Open
#6 0 comments 0 reactions 1 assignee Claimed by @hoangsonww View on GitHub
bug documentation enhancement good first issue help wanted question
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.