pardnio/node-jwt-auth

Last updated 2026-10-07

[!NOTE] This README was generated by SKILL, get the ZH version from here.

DUAL-TOKEN JWT AUTH BOUND TO EVERY DEVICE!

A Node.js JWT authentication library for Express with refresh token rotation, device fingerprint binding, and Redis revocation

Table of Contents

• Features
• Architecture
• License
• Author

Features

npm install @pardnchiu/jwt-auth · Documentation

• Seamless Dual-Token Refresh — When the Access Token expires, the same request re-signs an ES256 token from the Refresh ID and writes it back through cookies and headers, so users never log in again.
• Device Fingerprint Binding — Tokens are bound to a SHA-256 fingerprint of OS, browser, device type, and Device ID, so a token replayed from another device is flagged as suspicious.
• Automatic Refresh ID Rotation — After 5 refreshes or once less than half its lifetime remains, the Refresh ID is reissued while the old one stays valid for a 5-second grace window to absorb concurrent requests.
• Redis Revocation Blacklist — Logout writes the Access Token to a Redis blacklist whose TTL matches the token lifetime, so stale entries clean themselves up.
• Three-State Verification — Every verification reports authenticated, erroneous, and guest states at once, letting routes split 401 from 400 without parsing error strings.

Architecture

Full Architecture

graph TB
    Client[Client] -->|Cookie / Bearer / X-Refresh-ID| App[Express Route]
    App --> Auth[JWTAuth]
    Auth --> FP[CreateFingerprint]
    Auth --> RID[CreateRefreshId]
    Auth --> JWT[jsonwebtoken ES256]
    Auth --> Redis[(Redis refresh / revoke)]
    Auth --> Check[checkUserExists callback]
    Auth -->|Set-Cookie / X-New-*| Client

License

This project is licensed under the MIT LICENSE.

Author

Just open an issue to share an idea.

©️ 2025 邱敬幃 Pardn Chiu