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
  1. graph TB
  2. Client[Client] -->|Cookie / Bearer / X-Refresh-ID / X-Device-ID| Route[Express Route]
  3. Route --> Auth[JWTAuth static class]
  4. Auth --> FP[CreateFingerprint]
  5. Auth --> RID[CreateRefreshId]
  6. Auth --> JWT[jsonwebtoken ES256]
  7. Auth --> Redis[(Redis refresh: / revoke:)]
  8. Auth --> Check[checkUserExists callback]
  9. 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


LayerFileResponsibility
Public APIsrc/JWTAuth.tsinit, close, CreateJWT, VerifyJWT, RevokeJWT, GetAuth; holds config and the Redis connection in static fields
Fingerprintsrc/CreateFingerprint.tsDerives a SHA-256 fingerprint from User-Agent and Device ID
Refresh IDsrc/CreateRefreshId.tscreateRefreshId() derives a SHA-256 identifier from user data, fingerprint, and issue time
Typessrc/type.tsConfig, AuthData, VerifyResult, and related interfaces
Exportssrc/index.tsNamed and default export of JWTAuth, plus all types

Cross-Cutting Principles


PrincipleImplementation
Single process-wide stateJWTAuth cannot be instantiated; one process holds one config and one Redis connection
Server state lives only in RedisRefresh data and the revocation blacklist are TTL-bound Redis keys that expire on their own
Tokens bound to devicesBoth the Access Token and refresh data store the fingerprint, checked on every verification
Verification rarely throwsVerifyJWT throws only when not initialized or when the revoke: blacklist lookup hits a Redis error; every other failure becomes a VerifyResult

Further Reading


中文