# API 參考

本頁列出 `JWTAuth` 每個公開方法的簽章、行為與錯誤。

## 匯入

```typescript
import { JWTAuth } from "@pardnchiu/jwt-auth";
// 或預設匯入
import JWTAuth from "@pardnchiu/jwt-auth";
```

`JWTAuth` 只有 static 方法，建構子為 private，不可 `new`。

## 方法

| 方法 | 簽章 |
|---|---|
| `init` | `init(config: Config): Promise<void>` |
| `close` | `close(): Promise<void>` |
| `CreateJWT` | `CreateJWT(req: Request, res: Response, user: AuthData): Promise<TokenResult>` |
| `VerifyJWT` | `VerifyJWT(req: Request, res: Response): Promise<VerifyResult>` |
| `RevokeJWT` | `RevokeJWT(req: Request, res: Response, refresh_id?: string): Promise<void>` |
| `GetAuth` | `GetAuth(auth: AuthData \| number)` |

### init

載入金鑰、補上 cookie 名稱預設值並連線 Redis。錯誤見[設定](/zh/configuration)。

### close

中斷 Redis 連線並清空連線參考。中斷失敗時記錄並拋出。

### CreateJWT

| 步驟 | 行為 |
|---|---|
| 1 | 計算指紋，產生 Refresh ID |
| 2 | 以 ES256 簽發 Access Token，payload 為 `id`、`name`、`email`、`thumbnail`、`level`、`role`、`scope`（預設 `[]`）、`fp`、`refresh_id` |
| 3 | 寫入 `refresh:<id>`（`version: 1`），TTL 為 `refreshTokenExpires` |
| 4 | 設定 Access 與 Refresh cookie |

回傳 `{ token, refresh_id }`。未初始化時拋出 `JWTAuth not initialized. Call JWTAuth.init() first.`。

### VerifyJWT

驗證 Access Token，過期時自動續期並寫回 cookie 與 `X-New-*` header。除未初始化外不拋出，所有失敗以 `VerifyResult` 表示，對照見[驗證結果](/zh/verify-results)；續期細節見 [Refresh Token 輪替](/zh/token-refresh)。

### RevokeJWT

清除 cookie、縮短 Refresh 資料 TTL、把 Access Token 加入黑名單。`refresh_id` 參數優先於請求中的值。Redis 錯誤只記錄不拋出。不會撤銷的情況見 [Token 撤銷](/zh/token-revocation)。

### GetAuth

把舊版 `VerifyJWT()` 的回傳值（`AuthData` 或 `400`／`401`）轉成 `{ ...data, isAuth, isError, isGuest }`。

相關：[型別](/zh/types)