API 參考

最後更新


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

匯入


  1. import { JWTAuth } from "@pardnchiu/jwt-auth";
  2. // 或預設匯入
  3. import JWTAuth from "@pardnchiu/jwt-auth";

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

方法


方法簽章
initinit(config: Config): Promise<void>
closeclose(): Promise<void>
CreateJWTCreateJWT(req: Request, res: Response, user: AuthData): Promise<TokenResult>
VerifyJWTVerifyJWT(req: Request, res: Response): Promise<VerifyResult>
RevokeJWTRevokeJWT(req: Request, res: Response, refresh_id?: string): Promise<void>
GetAuthGetAuth(auth: AuthData | number)

init


載入金鑰、補上 cookie 名稱預設值並連線 Redis。錯誤見設定。

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.;Redis 寫入失敗時錯誤直接拋出,此時 access cookie 已設定。

VerifyJWT


驗證 Access Token,過期時自動續期並寫回 cookie 與 X-New-* header。未初始化,或第一步的 Redis 查詢(revoke: 黑名單檢查)失敗時拋出,其餘失敗皆以 VerifyResult 表示,對照見驗證結果;續期細節見 Refresh Token 輪替。

RevokeJWT


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

GetAuth


把舊版 VerifyJWT() 的回傳值(AuthData 或 400/401)轉成 { ...data, isAuth, isError, isGuest }。400/401 以外的數字會得到 isAuth: true。
相關:型別
EN