> [!NOTE]
> 此 README 由 [SKILL](https://github.com/agenvoy/skill-readme-generate) 生成，英文版請參閱 [這裡](https://github.com/pardnio/node-jwt-auth/blob/main/README.md)。

***

<p align="center">
<strong>DUAL-TOKEN JWT AUTH BOUND TO EVERY DEVICE!</strong>
</p>

<p align="center">
<a href="https://www.npmjs.com/package/@pardnchiu/jwt-auth"><img src="https://img.shields.io/npm/v/@pardnchiu/jwt-auth?include_prereleases&style=for-the-badge" alt="npm"></a>
<a href="https://www.jsdelivr.com/package/npm/@pardnchiu/jwt-auth"><img src="https://img.shields.io/jsdelivr/npm/hm/@pardnchiu/jwt-auth?include_prereleases&style=for-the-badge" alt="Downloads"></a>
<a href="https://www.npmjs.com/package/@pardnchiu/jwt-auth"><img src="https://img.shields.io/npm/l/@pardnchiu/jwt-auth?include_prereleases&style=for-the-badge" alt="License"></a>
</p>

***

> Node.js JWT 驗證函式庫，支援 Refresh Token 輪替、裝置指紋綁定與 Redis 撤銷黑名單

## 目錄

- [功能特點](#功能特點)
- [架構](#架構)
- [授權](#授權)
- [Author](#author)

## 功能特點

> `npm install @pardnchiu/jwt-auth` · [完整文件](https://github.com/pardnio/node-jwt-auth/blob/main/doc/doc.zh.md)

- **雙 Token 無感續期** — Access Token 過期時在同一個請求內以 Refresh ID 重新簽發 ES256 Token 並回寫 cookie 與 header，使用者不必重新登入。
- **裝置指紋綁定** — Token 與 OS、瀏覽器、裝置類型及 Device ID 組成的 SHA-256 指紋綁定，被帶到其他裝置使用會直接判定為可疑請求。
- **Refresh ID 自動輪替** — 續期超過 5 次或剩餘壽命不足一半即換發新 Refresh ID，舊 ID 保留 5 秒寬限期避免併發請求失敗。
- **Redis 撤銷黑名單** — 登出時把 Access Token 寫入 Redis 黑名單，TTL 與 Token 壽命一致，過期紀錄自動清除。
- **三態驗證結果** — 驗證結果同時回報已登入、異常請求與訪客三種狀態，路由可直接分流 401 與 400 而不必解析錯誤字串。

## 架構

> [完整架構](https://github.com/pardnio/node-jwt-auth/blob/main/doc/architecture.zh.md)

```mermaid
graph TB
    Client[客戶端] -->|Cookie / Bearer / X-Refresh-ID| App[Express 路由]
    App --> Auth[JWTAuth]
    Auth --> FP[CreateFingerprint 裝置指紋]
    Auth --> RID[CreateRefreshId]
    Auth --> JWT[jsonwebtoken ES256]
    Auth --> Redis[(Redis refresh / revoke)]
    Auth --> Check[checkUserExists 回呼]
    Auth -->|Set-Cookie / X-New-*| Client
```

## 授權

本專案採用 [MIT LICENSE](https://github.com/pardnio/node-jwt-auth/blob/main/LICENSE)。

## Author

Just [open an issue](https://github.com/pardnio/node-jwt-auth/issues/new) to share an idea.

<a href="https://github.com/pardnio/node-jwt-auth/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=pardnio/node-jwt-auth&cache_bust=2026-10-07" alt="node-jwt-auth contributors" />
</a>

***

©️ 2025 [邱敬幃 Pardn Chiu](https://www.linkedin.com/in/pardnchiu)