Architecture
Last updated
This page shows, in one diagram, how
@pardnchiu/jwt-auth is layered and what it depends on.System Overview
graph TB
Client[Client] -->|Cookie / Bearer / X-Refresh-ID / X-Device-ID| Route[Express Route]
Route --> Auth[JWTAuth static class]
Auth --> FP[CreateFingerprint]
Auth --> RID[CreateRefreshId]
Auth --> JWT[jsonwebtoken ES256]
Auth --> Redis[(Redis refresh: / revoke:)]
Auth --> Check[checkUserExists callback]
Auth -->|Set-Cookie / X-New-*| Client- graph TB
- Client[Client] -->|Cookie / Bearer / X-Refresh-ID / X-Device-ID| Route[Express Route]
- Route --> Auth[JWTAuth static class]
- Auth --> FP[CreateFingerprint]
- Auth --> RID[CreateRefreshId]
- Auth --> JWT[jsonwebtoken ES256]
- Auth --> Redis[(Redis refresh: / revoke:)]
- Auth --> Check[checkUserExists callback]
- Auth -->|Set-Cookie / X-New-*| Client
Signing and verification are delegated to
jsonwebtoken (auth0/node-jsonwebtoken); everything around them is handled in this package: issuing the Access Token and Refresh ID at login, refreshing an expired token inside the same request, rotating the Refresh ID, binding both to a device fingerprint, and revoking through Redis. That scope differs from other JWT libraries in the Node.js ecosystem. express-jwt is Express middleware that validates incoming JWTs and exposes the payload on req.auth, with revocation left to an isRevoked callback you implement. passport-jwt is a Passport strategy for authenticating endpoints with a JWT. jose provides JWA, JWS, JWE, JWT, and JWK primitives across Node.js, browsers, and edge runtimes. SuperTokens is an open-source user authentication product whose Node SDK talks to a separate SuperTokens core service; this package runs inside your Express process and keeps its only server state in your own Redis.Layers
| Layer | File | Responsibility |
|---|---|---|
| Public API | src/JWTAuth.ts | init, close, CreateJWT, VerifyJWT, RevokeJWT, GetAuth; holds config and the Redis connection in static fields |
| Fingerprint | src/CreateFingerprint.ts | Derives a SHA-256 fingerprint from User-Agent and Device ID |
| Refresh ID | src/CreateRefreshId.ts | createRefreshId() derives a SHA-256 identifier from user data, fingerprint, and issue time |
| Types | src/type.ts | Config, AuthData, VerifyResult, and related interfaces |
| Exports | src/index.ts | Named and default export of JWTAuth, plus all types |
Cross-Cutting Principles
| Principle | Implementation |
|---|---|
| Single process-wide state | JWTAuth cannot be instantiated; one process holds one config and one Redis connection |
| Server state lives only in Redis | Refresh data and the revocation blacklist are TTL-bound Redis keys that expire on their own |
| Tokens bound to devices | Both the Access Token and refresh data store the fingerprint, checked on every verification |
| Verification rarely throws | VerifyJWT throws only when not initialized or when the revoke: blacklist lookup hits a Redis error; every other failure becomes a VerifyResult |
Further Reading
- Full module diagrams, sequences, and state machines: doc/architecture.md
- Refresh flow: Refresh Token Rotation