# pardnio/node-jwt-auth

> node-jwt-auth is a Node.js JWT authentication library for Express by Pardn Chiu, with refresh token rotation, device fingerprint binding, and Redis revocation.

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd, Taiwan · Infrastructure Engineering. Source: https://github.com/pardnio/node-jwt-auth

Full text in one file: [English](https://node-jwt-auth.pardn.io/llms-full.txt) · [中文](https://node-jwt-auth.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://node-jwt-auth.pardn.io/index.md): node-jwt-auth is a Node.js JWT authentication library for Express by Pardn Chiu, with refresh token rotation, device fingerprint binding, and Redis revocation.
- [Getting Started](https://node-jwt-auth.pardn.io/getting-started.md): Install @pardnchiu/jwt-auth, generate ES256 keys, and wire login, a protected route, and logout into an Express app with cookie-parser and Redis.

## Concepts

- [Architecture](https://node-jwt-auth.pardn.io/architecture.md): One-diagram overview of node-jwt-auth: the static JWTAuth class, fingerprint and refresh ID helpers, jsonwebtoken ES256, and Redis keys.
- [Refresh Token Rotation](https://node-jwt-auth.pardn.io/token-refresh.md): How VerifyJWT refreshes an expired JWT in the same request, when the refresh ID rotates (5 refreshes or half lifetime), and the 5-second grace window.
- [Device Fingerprint](https://node-jwt-auth.pardn.io/device-fingerprint.md): How node-jwt-auth binds tokens to a SHA-256 device fingerprint of OS, browser, device type, and X-Device-ID, and where mismatches are caught.
- [Token Revocation](https://node-jwt-auth.pardn.io/token-revocation.md): What RevokeJWT does at logout: clearing cookies, a Redis JWT blacklist with TTL, and the cases where the access token is not revoked.
- [Verification Results](https://node-jwt-auth.pardn.io/verify-results.md): The isAuth, isError, and isGuest flags returned by VerifyJWT, a scenario table for each outcome, and routing 401 versus 400 in Express.

## Guides

- [Token Transport](https://node-jwt-auth.pardn.io/token-transport.md): Where node-jwt-auth reads tokens (Bearer header, cookies, X-Refresh-ID), the X-New-* response headers, and cookie attributes per environment.
- [Client Integration](https://node-jwt-auth.pardn.io/client-integration.md): Integrating browsers with httpOnly cookies and mobile or CLI clients with Bearer and X-Refresh-ID headers, including CORS exposed headers.

## Reference

- [Configuration](https://node-jwt-auth.pardn.io/configuration.md): Every JWTAuth.init() config field with defaults: ES256 key paths, token lifetimes, isProd cookie behavior, Redis connection, and checkUserExists.
- [API Reference](https://node-jwt-auth.pardn.io/api-reference.md): Signatures and behavior of init, close, CreateJWT, VerifyJWT, RevokeJWT, and GetAuth on the static JWTAuth class, including thrown errors.
- [Types](https://node-jwt-auth.pardn.io/types.md): TypeScript interfaces exported by @pardnchiu/jwt-auth: AuthData, VerifyResult, TokenResult, RefreshData, JWTPayload, and Config.
- [Redis Keys](https://node-jwt-auth.pardn.io/redis-keys.md): The refresh: and revoke: Redis keys node-jwt-auth writes, their TTLs at each step, and redis-cli commands to inspect or end sessions.

## Symbols

Exported symbol -> page that documents it.

- `CreateFingerprint` (src): [Device Fingerprint](https://node-jwt-auth.pardn.io/device-fingerprint.md)
- `createRefreshId` (src): [Architecture](https://node-jwt-auth.pardn.io/architecture.md)
- `JWTAuth` (src): [API Reference](https://node-jwt-auth.pardn.io/api-reference.md), [Architecture](https://node-jwt-auth.pardn.io/architecture.md)

## 中文文件

- [首頁](https://node-jwt-auth.pardn.io/zh/index.md): 邱敬幃的 Node.js JWT 驗證函式庫 node-jwt-auth，支援 Express、Refresh Token 輪替、裝置指紋與 Redis 撤銷。
- [快速開始](https://node-jwt-auth.pardn.io/zh/getting-started.md): 安裝 @pardnchiu/jwt-auth、產生 ES256 金鑰，在 Express 中完成登入、受保護路由與登出。
- [架構](https://node-jwt-auth.pardn.io/zh/architecture.md): 一張圖看懂 node-jwt-auth：JWTAuth 類別、指紋與 Refresh ID、ES256 簽章與 Redis 鍵。
- [Refresh Token 輪替](https://node-jwt-auth.pardn.io/zh/token-refresh.md): VerifyJWT 如何在同一請求內續期過期 JWT，Refresh ID 何時輪替，以及 5 秒寬限期。
- [裝置指紋](https://node-jwt-auth.pardn.io/zh/device-fingerprint.md): Token 如何綁定 OS、瀏覽器、裝置類型與 X-Device-ID 組成的 SHA-256 裝置指紋。
- [Token 撤銷](https://node-jwt-auth.pardn.io/zh/token-revocation.md): RevokeJWT 登出時清除 cookie、寫入 Redis JWT 黑名單，以及不會撤銷的情況。
- [驗證結果](https://node-jwt-auth.pardn.io/zh/verify-results.md): VerifyJWT 回傳的 isAuth、isError、isGuest 旗標，各情境對照與 401／400 分流。
- [Token 傳遞](https://node-jwt-auth.pardn.io/zh/token-transport.md): Token 從 Bearer header、cookie、X-Refresh-ID 讀取，X-New-* 回寫與 cookie 屬性。
- [客戶端整合](https://node-jwt-auth.pardn.io/zh/client-integration.md): 瀏覽器以 httpOnly cookie、行動 App 以 Bearer 與 X-Refresh-ID header 串接，含 CORS 設定。
- [設定](https://node-jwt-auth.pardn.io/zh/configuration.md): JWTAuth.init() 每個設定欄位與預設值：ES256 金鑰、Token 壽命、isProd、Redis 與 checkUserExists。
- [API 參考](https://node-jwt-auth.pardn.io/zh/api-reference.md): JWTAuth 的 init、close、CreateJWT、VerifyJWT、RevokeJWT、GetAuth 簽章、行為與錯誤。
- [型別](https://node-jwt-auth.pardn.io/zh/types.md): @pardnchiu/jwt-auth 匯出的 TypeScript 介面：AuthData、VerifyResult、RefreshData 等。
- [Redis 鍵](https://node-jwt-auth.pardn.io/zh/redis-keys.md): node-jwt-auth 寫入的 refresh: 與 revoke: Redis 鍵、各階段 TTL 與 redis-cli 除錯指令。