架構
最後更新
本頁以一張圖說明
@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- 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
簽章與驗證交給
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。分層
| 層 | 檔案 | 職責 |
|---|---|---|
| 公開 API | src/JWTAuth.ts | init、close、CreateJWT、VerifyJWT、RevokeJWT、GetAuth;以 static 欄位保存設定與 Redis 連線 |
| 指紋 | src/CreateFingerprint.ts | 由 User-Agent 與 Device ID 產生 SHA-256 指紋 |
| Refresh ID | src/CreateRefreshId.ts | createRefreshId() 由使用者資料、指紋與簽發時間產生 SHA-256 識別碼 |
| 型別 | src/type.ts | Config、AuthData、VerifyResult 等介面 |
| 匯出 | src/index.ts | 具名與預設匯出 JWTAuth,並匯出全部型別 |
跨切原則
| 原則 | 實作 |
|---|---|
| 單一行程狀態 | JWTAuth 不可實例化,同一行程只有一組設定與一條 Redis 連線 |
| 伺服器端狀態只放 Redis | Refresh 資料與撤銷黑名單皆為帶 TTL 的 Redis 鍵,過期自動清除 |
| Token 綁定裝置 | Access Token 與 Refresh 資料都存有指紋,每次驗證比對 |
| 驗證幾乎不拋錯 | VerifyJWT 只有在未初始化或 revoke: 黑名單查詢遇到 Redis 錯誤時拋出,其餘失敗皆轉為 VerifyResult |
延伸閱讀
- 模組圖、時序圖與狀態機完整版:doc/architecture.zh.md
- 續期流程:Refresh Token 輪替