# 架構

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

## 系統概覽

```mermaid
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
```

## 分層

| 層 | 檔案 | 職責 |
|---|---|---|
| 公開 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` 只有在未初始化時拋出，其餘失敗皆轉為 `VerifyResult` |

## 延伸閱讀

- 模組圖、時序圖與狀態機完整版：[doc/architecture.zh.md](https://github.com/pardnio/node-jwt-auth/blob/main/doc/architecture.zh.md)
- 續期流程：[Refresh Token 輪替](/zh/token-refresh)