Token Revocation

Last updated


This page explains what RevokeJWT() does at logout, how the blacklist takes effect, and when nothing gets revoked.

Revocation Flow


StepAction
1Resolve the Refresh ID: refresh_id argument → X-Refresh-ID header → refresh cookie; return immediately if none
2Clear the access and refresh cookies
3Read refresh:<id>; stop if it does not exist
4Shorten the TTL of refresh:<id> to 5 seconds
5Write revoke:<access_token> with value "1" and TTL accessTokenExpires

How the Blacklist Takes Effect


The first thing VerifyJWT() does is look up revoke:<access_token>; on a hit it returns a guest (isError: false) without checking the signature. The blacklist TTL equals the Access Token lifetime, so the entry disappears once the token would have expired anyway.
When RevokeJWT() runs on a request that carries a Refresh ID but no Access Token, the blacklist key is written as revoke:null. VerifyJWT() builds the same key for every request without an Access Token, so for accessTokenExpires seconds afterwards, refresh-only requests from any client return a guest.

When Nothing Is Revoked


SituationResult
The request carries no Refresh IDReturns immediately: cookies are not cleared and nothing is blacklisted
The refresh data is already gone from RedisCookies are cleared, but the Access Token is not blacklisted and keeps passing verification until it expires
Redis errorLogged with console.error, not thrown

To guarantee revocation, clients should send both the Access Token and the Refresh ID.

Example


  1. import { Request, Response } from "express";
  2. import { JWTAuth } from "@pardnchiu/jwt-auth";
  3. export async function logout(req: Request, res: Response) {
  4. try {
  5. await JWTAuth.RevokeJWT(req, res);
  6. res.json({ message: "Successfully logged out" });
  7. } catch (err) {
  8. // Throws only when not initialized
  9. res.status(500).json({ error: (err as Error).message });
  10. }
  11. }

Related: Redis Keys, Verification Results
中文