架構

最後更新


本頁以一張圖說明 @pardnchiu/jwt-auth 的組成層級與外部相依。

系統概覽


graph TB
    Client[客戶端] -->|Cookie / Bearer / X-Refresh-ID / X-Device-ID| Route[Express 路由]
    Route --> Auth[JWTAuth static 類別]
    Auth --> FP[CreateFingerprint]
    Auth --> RID[CreateRefreshId]
    Auth --> JWT[jsonwebtoken ES256]
    Auth --> Redis[(Redis refresh: / revoke:)]
    Auth --> Check[checkUserExists 回呼]
    Auth -->|Set-Cookie / X-New-*| Client
  1. graph TB
  2. Client[客戶端] -->|Cookie / Bearer / X-Refresh-ID / X-Device-ID| Route[Express 路由]
  3. Route --> Auth[JWTAuth static 類別]
  4. Auth --> FP[CreateFingerprint]
  5. Auth --> RID[CreateRefreshId]
  6. Auth --> JWT[jsonwebtoken ES256]
  7. Auth --> Redis[(Redis refresh: / revoke:)]
  8. Auth --> Check[checkUserExists 回呼]
  9. Auth -->|Set-Cookie / X-New-*| Client

簽章與驗證交給 jsonwebtoken(auth0/node-jsonwebtoken),其餘流程由本套件處理:登入時簽發 Access Token 與 Refresh ID、在同一請求內續期過期的 Token、輪替 Refresh ID、將兩者綁定裝置指紋,以及透過 Redis 撤銷。這個範圍與 Node.js 生態中其他 JWT 函式庫不同:express-jwt 是驗證傳入 JWT 的 Express 中介層,把 payload 放在 req.auth,撤銷交給你自行實作的 isRevoked 回呼;passport-jwt 是以 JWT 驗證端點的 Passport 策略;jose 提供可在 Node.js、瀏覽器與邊緣執行環境使用的 JWA、JWS、JWE、JWT、JWK 基礎元件;SuperTokens 是開源使用者驗證產品,其 Node SDK 需連線獨立的 SuperTokens core 服務。本套件則直接在你的 Express 程序內執行,伺服器端狀態只存在你自己的 Redis。

分層


層檔案職責
公開 APIsrc/JWTAuth.tsinit、close、CreateJWT、VerifyJWT、RevokeJWT、GetAuth;以 static 欄位保存設定與 Redis 連線
指紋src/CreateFingerprint.ts由 User-Agent 與 Device ID 產生 SHA-256 指紋
Refresh IDsrc/CreateRefreshId.tscreateRefreshId() 由使用者資料、指紋與簽發時間產生 SHA-256 識別碼
型別src/type.tsConfig、AuthData、VerifyResult 等介面
匯出src/index.ts具名與預設匯出 JWTAuth,並匯出全部型別

跨切原則


原則實作
單一行程狀態JWTAuth 不可實例化,同一行程只有一組設定與一條 Redis 連線
伺服器端狀態只放 RedisRefresh 資料與撤銷黑名單皆為帶 TTL 的 Redis 鍵,過期自動清除
Token 綁定裝置Access Token 與 Refresh 資料都存有指紋,每次驗證比對
驗證幾乎不拋錯VerifyJWT 只有在未初始化或 revoke: 黑名單查詢遇到 Redis 錯誤時拋出,其餘失敗皆轉為 VerifyResult

延伸閱讀


EN