Blacklisting and Forced Revocation in TypeScript REST API

Introduction to Token Blacklisting and Forced Revocation

Welcome to the Blacklisting and Forced Revocation in TypeScript REST API . In this lesson, we will focus on token blacklisting and forced revocation, two critical techniques for maintaining the security of your API.

What is Token Blacklisting?

Token blacklisting is a security mechanism where you maintain a list of tokens that are no longer considered valid, despite not being expired. When a token is added to this blacklist, the system will reject it even if it contains a valid signature and hasn't reached its expiration date.

What is Forced Revocation?

Forced revocation is the act of deliberately invalidating a token before its natural expiration. This is typically done through blacklisting and is essential for scenarios where you need to immediately terminate a user's session.

Approaches to Token Invalidation

There are several approaches to invalidating tokens: Blacklisting - Adding tokens to a "deny list" that is checked during validation Token Removal - Simply removing tokens from the database if you're storing them Direct Invalidation - Setting a "valid" flag to false in your token storage Each approach has its trade-offs. Token removal is simple but only works if you store tokens in the first place. Direct invalidation requires modifying your token storage schema. Blacklisting works universally but requires an additional database structure. For this course, we'll focus on the blacklisting approach as it provides a robust solution that works well with JWT-based authentication without requiring us to store valid tokens.

When to Use These Techniques

These techniques are particularly useful in several scenarios: When a user logs out and you want to invalidate their token immediately When a security breach is detected and you need to invalidate potentially compromised tokens When a user's account is deactivated or suspended When you need to enforce access policy changes immediately

Advantages and Disadvantages of Token Invalidation

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Understanding the TokenBlacklist Model

The TokenBlacklist model is the foundation of our implementation. It stores invalidated tokens and provides a way to check if a token has been revoked.

TypeScript

import { DataTypes, Model } from 'sequelize';
import { sequelize } from './index.js';

/**
 * Stores blacklisted tokens to prevent their use
 */
export class TokenBlacklist extends Model {
  declare token: string;     // The unique identifier (JWT token string)
  declare reason: string;    // Optional reason for blacklisting
  declare expiresAt: Date;   // When this blacklist entry should expire (matching token expiry)
}

TokenBlacklist.init({
  token: {
    type: DataTypes.STRING(1024), // Tokens can be long, especially JWTs
    primaryKey: true,
  },
  reason: {
    type: DataTypes.STRING,
    allowNull: true,
  },
  expiresAt: {
    type: DataTypes.DATE,
    allowNull: false,
  },
}, {
  sequelize,
  modelName: 'TokenBlacklist',
});

import { DataTypes, Model } from 'sequelize';
import { sequelize } from './index.js';

/**
 * Stores blacklisted tokens to prevent their use
 */
export class TokenBlacklist extends Model {
  declare token: string;     // The unique identifier (JWT token string)
  declare reason: string;    // Optional reason for blacklisting
  declare expiresAt: Date;   // When this blacklist entry should expire (matching token expiry)
}

TokenBlacklist.init({
  token: {
    type: DataTypes.STRING(1024), // Tokens can be long, especially JWTs
    primaryKey: true,
  },
  reason: {
    type: DataTypes.STRING,
    allowNull: true,
  },
  expiresAt: {
    type: DataTypes.DATE,
    allowNull: false,
  },
}, {
  sequelize,
  modelName: 'TokenBlacklist',
});

Key Concepts:

We store the complete token as a unique identifier, allowing quick lookups
We include a reason field to track why a token was blacklisted (useful for auditing)
The expiresAt field is critical for database maintenance - it matches the token's expiration so we can eventually clean up the blacklist

This model is optimized for quick lookups, which is essential as every authenticated request will check against this table.

Implementing Token Revocation Logic

The revokeAccessToken function handles the core functionality of adding tokens to the blacklist:

TypeScript

export async function revokeAccessToken(token: string, reason: string = 'Admin revocation') {
  console.log(`Revoking token: ${token.substring(0, 20)}...`);
  
  try {
    // Decode the token to get its expiration time (without verification)
    const decoded = jwt.decode(token) as any;
    
    // Calculate expiration time - if token has exp claim, use it, otherwise default to 24h
    const expiresAt = decoded && decoded.exp 
      ? new Date(decoded.exp * 1000)  // exp is in seconds
      : new Date(Date.now() + 24 * 60 * 60 * 1000); // 24h default
    
    // Create blacklist entry
    const blacklistEntry = await TokenBlacklist.create({
      token,
      reason,
      expiresAt
    });
    
    return blacklistEntry;
  } catch (error) {
    console.error('Error blacklisting token:', error);
    throw error;
  }
}

export async function revokeAccessToken(token: string, reason: string = 'Admin revocation') {
  console.log(`Revoking token: ${token.substring(0, 20)}...`);
  
  try {
    // Decode the token to get its expiration time (without verification)
    const decoded = jwt.decode(token) as any;
    
    // Calculate expiration time - if token has exp claim, use it, otherwise default to 24h
    const expiresAt = decoded && decoded.exp 
      ? new Date(decoded.exp * 1000)  // exp is in seconds
      : new Date(Date.now() + 24 * 60 * 60 * 1000); // 24h default
    
    // Create blacklist entry
    const blacklistEntry = await TokenBlacklist.create({
      token,
      reason,
      expiresAt
    });
    
    return blacklistEntry;
  } catch (error) {
    console.error('Error blacklisting token:', error);
    throw error;
  }
}

Key Logic:

The function decodes (not verifies) the token to extract its expiration time
We determine when the blacklist entry should expire based on the token's own expiration
If we can't determine the token's expiration, we default to 24 hours from now
We store the token information with a reason to create an audit trail

This approach ensures that the blacklist grows and shrinks naturally with token lifetimes, preventing it from becoming too large over time.

Middleware for Token Validation and Blacklist Checking

The authentication middleware is where token validation and blacklist checking come together:

TypeScript

export async function authRequired(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization || '';
  const token = authHeader.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({ error: 'Missing access token' });
  }

  try {
    // First check if token is blacklisted
    const blacklisted = await TokenBlacklist.findByPk(token);
    
    if (blacklisted) {
      console.log(`Blocked blacklisted token: ${token.substring(0, 20)}...`);
      return res.status(403).json({ 
        error: 'Access token has been revoked',
        reason: blacklisted.reason || 'Token revoked'
      });
    }
    
    // If not blacklisted, verify token
    const decoded = jwt.verify(token, JWT_SECRET_KEY);
    
    // Attach user info to request
    // @ts-ignore
    req.user = decoded;
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({ error: 'Token expired' });
    }
    return res.status(401).json({ error: 'Invalid token' });
  }
}

export async function authRequired(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization || '';
  const token = authHeader.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({ error: 'Missing access token' });
  }

  try {
    // First check if token is blacklisted
    const blacklisted = await TokenBlacklist.findByPk(token);
    
    if (blacklisted) {
      console.log(`Blocked blacklisted token: ${token.substring(0, 20)}...`);
      return res.status(403).json({ 
        error: 'Access token has been revoked',
        reason: blacklisted.reason || 'Token revoked'
      });
    }
    
    // If not blacklisted, verify token
    const decoded = jwt.verify(token, JWT_SECRET_KEY);
    
    // Attach user info to request
    // @ts-ignore
    req.user = decoded;
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({ error: 'Token expired' });
    }
    return res.status(401).json({ error: 'Invalid token' });
  }
}

Core Functionality:

Before verifying the token itself, we check if it exists in the blacklist
If the token is blacklisted, we immediately reject the request with a 403 status
The order of operations is important: we check the blacklist first, then verify the token
We include the revocation reason in the response to provide context to clients

This middleware creates a decision point where blacklisted tokens are filtered out before any protected resources are accessed.

Admin Endpoint for Token Revocation

To provide administrative control, we implement a dedicated endpoint for token revocation:

TypeScript

router.post('/revoke', authRequired, async (req, res) => {
  try {
    const { tokenToRevoke, reason } = req.body;
    if (!tokenToRevoke) {
      return res.status(400).json({ error: 'Must provide tokenToRevoke' });
    }

    // Check if user is admin - multiple formats supported
    const userRole = req.user?.role;
    const isAdmin = 
      userRole === Role.ADMIN.toString() || 
      userRole === 'ADMIN' || 
      userRole === '1';
    
    if (!req.user || !isAdmin) {
      return res.status(403).json({ error: 'Only admins can revoke tokens' });
    }

    // Revoke token - database implementation
    const blacklistEntry = await revokeAccessToken(
      tokenToRevoke, 
      reason || 'Admin revocation'
    );
    
    res.json({ 
      message: `Token revoked successfully.`,
      token: tokenToRevoke.substring(0, 20) + '...' // Show part of token for confirmation
    });
  } catch (error) {
    console.error('Error revoking token:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

router.post('/revoke', authRequired, async (req, res) => {
  try {
    const { tokenToRevoke, reason } = req.body;
    if (!tokenToRevoke) {
      return res.status(400).json({ error: 'Must provide tokenToRevoke' });
    }

    // Check if user is admin - multiple formats supported
    const userRole = req.user?.role;
    const isAdmin = 
      userRole === Role.ADMIN.toString() || 
      userRole === 'ADMIN' || 
      userRole === '1';
    
    if (!req.user || !isAdmin) {
      return res.status(403).json({ error: 'Only admins can revoke tokens' });
    }

    // Revoke token - database implementation
    const blacklistEntry = await revokeAccessToken(
      tokenToRevoke, 
      reason || 'Admin revocation'
    );
    
    res.json({ 
      message: `Token revoked successfully.`,
      token: tokenToRevoke.substring(0, 20) + '...' // Show part of token for confirmation
    });
  } catch (error) {
    console.error('Error revoking token:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

Essential Logic:

We implement proper authorization checks to ensure only admins can revoke tokens
The endpoint handles multiple admin role formats for flexibility
The endpoint requires both the token to revoke and optionally a reason
We use the revokeAccessToken function to add the token to the blacklist
For security, we only return a partial token in the response

This admin-controlled revocation creates a powerful security tool that can be used in response to security events or as part of normal administrative operations.

Blacklisting and Forced Revocation in TypeScript REST API

Introduction to Token Blacklisting and Forced Revocation

What is Token Blacklisting?

What is Forced Revocation?

Approaches to Token Invalidation

When to Use These Techniques

Advantages and Disadvantages of Token Invalidation

Join the 1M+ learners on CodeSignal

Understanding the TokenBlacklist Model

Implementing Token Revocation Logic

Middleware for Token Validation and Blacklist Checking

Admin Endpoint for Token Revocation

Summary and Preparation for Practice