jwt-redis-manager

A lightweight, type-safe JWT manager for Node.js using Upstash Redis for session revocation and refresh token blacklisting.

Ensures that even if a refresh token is physically valid (not expired), it can be remotely revoked via Redis.

Features

• ✅ Type-Safe: Built with TypeScript, supporting generic payloads.
• ✅ Redis-Backed: Uses Upstash Redis for high-performance session tracking.
• ✅ Security First: Implements a "Double-Gate" verification for refresh tokens (Signature + Redis existence).
• ✅ Short-lived Access / Long-lived Refresh: Standard security pattern out of the box.

Installation

npm install jwt-redis-manager @upstash/redis jsonwebtoken
# or
yarn add jwt-redis-manager @upstash/redis jsonwebtoken

Usage

1. Initialization

import { JwtRedisManager } from "jwt-redis-manager";

const authManager = new JwtRedisManager<{ id: string; role: string }>({
  redisUrl: process.env.REDIS_URL!,
  redisToken: process.env.REDIS_TOKEN!,
  accessSecret: process.env.ACCESS_SECRET!,
  refreshSecret: process.env.REFRESH_SECRET!,
});

2. Generating Tokens

const payload = { id: "user_123", role: "admin" };

// Access Token (Synchronous)
const accessToken = authManager.generateAccessToken(payload, {
  expiresIn: "15m",
});

// Refresh Token (Asynchronous - Stores in Redis)
const refreshToken = await authManager.generateRefreshToken(payload, {
  expiresIn: "7d",
});

3. Verification

// Verify Access Token
try {
  const user = authManager.verifyAccessToken(token);
  console.log(user.id);
} catch (err) {
  // Token expired or invalid signature
}

// Verify Refresh Token (Checks Redis)
try {
  const user = await authManager.verifyRefreshToken(refreshToken);
  // Only gets here if token is valid AND exists in Redis
} catch (err) {
  // Token was revoked or expired
}

4. Revocation (Logout)

// session clear
await authManager.revokeRefreshToken(userId);

Why Redis?

Standard JWTs are stateless, meaning you cannot "log out" a user until the token expires. By storing the refreshToken in Redis, this package allows you to:

1. Immediately invalidate a session when a user logs out.
2. Terminate all sessions for a compromised account.
3. Automatically clean up expired sessions using Redis TTL.

License

MIT