eslint-plugin-jwt

🔐 Security-focused ESLint plugin for JWT authentication. Detects algorithm confusion (CVE-2022-23540), replay attacks, weak secrets, and library-specific vulnerabilities with AI-optimized fix guidance.

💡 What You Get

• 13 Security Rules - Algorithm attacks, replay prevention, claim validation
• 6 JWT Libraries - jsonwebtoken, jose, express-jwt, @nestjs/jwt, jwks-rsa, jwt-decode
• 2025 Research - "Back to the Future" replay attack prevention (LightSEC 2025)
• AI-Optimized - Structured messages for GitHub Copilot, Cursor, Claude assistance
• CWE References - Every rule maps to Common Weakness Enumeration

📦 Installation

npm install --save-dev eslint-plugin-jwt
# or
pnpm add -D eslint-plugin-jwt

🚀 Quick Start

Flat Config (ESLint 9+)

// eslint.config.js
import jwt from 'eslint-plugin-jwt';

export default [
  jwt.configs.recommended,
  // or jwt.configs.strict for maximum security
];

Custom Configuration

import jwt from 'eslint-plugin-jwt';

export default [
  {
    plugins: { jwt },
    rules: {
      // Critical - Algorithm attacks
      'jwt/no-algorithm-none': 'error',
      'jwt/no-algorithm-confusion': 'error',

      // High - Verification and secrets
      'jwt/require-algorithm-whitelist': 'warn',
      'jwt/no-decode-without-verify': 'warn',
      'jwt/no-weak-secret': 'error',
      'jwt/no-hardcoded-secret': 'error',

      // Medium - Best practices
      'jwt/require-expiration': 'warn',
      'jwt/require-issuer-validation': 'warn',
      'jwt/require-audience-validation': 'warn',
    },
  },
];

🔐 Rules

💼 = Set in recommended | 🔧 = Auto-fixable | 💡 = Has suggestions

Critical Severity (Algorithm Attacks)

High Severity (Verification & Secrets)

Medium Severity (Claims & Best Practices)

🔐 OWASP Top 10 2021 Coverage

CWE Coverage Summary

🛡️ Security Research Coverage

CVE-2022-23540 (jsonwebtoken Algorithm None)

The no-algorithm-none rule detects attempts to use alg:"none" which bypasses signature verification entirely.

// ❌ Vulnerable - Accepts unsigned tokens
jwt.verify(token, secret, { algorithms: ['none'] });

// ✅ Safe - Explicit secure algorithm
jwt.verify(token, secret, { algorithms: ['RS256'] });

LightSEC 2025 "Back to the Future" Attack

The no-timestamp-manipulation and require-max-age rules prevent replay attacks where tokens are captured and replayed years later.

// ❌ Vulnerable - Disables timestamp, enables replay
jwt.sign(payload, secret, { noTimestamp: true });

// ✅ Safe - Automatic iat, maxAge validation
jwt.sign(payload, secret, { expiresIn: '1h' });
jwt.verify(token, secret, { maxAge: '1h' });

Algorithm Confusion Attack

The no-algorithm-confusion rule detects when symmetric algorithms (HS256) are used with asymmetric keys (public keys).

// ❌ Vulnerable - Public key as HMAC secret
jwt.verify(token, publicKey, { algorithms: ['HS256'] });

// ✅ Safe - Asymmetric algorithm with public key
jwt.verify(token, publicKey, { algorithms: ['RS256'] });

⚙️ Configuration Presets

📚 Supported Libraries

Library	npm	Detection
jsonwebtoken		✅ Full
jose		✅ Full
express-jwt		✅ Full
@nestjs/jwt		✅ Full
jwks-rsa		✅ Full
jwt-decode		✅ Full

🤖 AI-Optimized Messages

Every rule uses formatLLMMessage for structured output:

🔒 CWE-347 OWASP:A02-Crypto CVSS:9.8 | Using alg:"none" bypasses signature verification
   Fix: Remove "none" and use RS256, ES256, or other secure algorithms
   https://nvd.nist.gov/vuln/detail/CVE-2022-23540

📖 References

• RFC 8725 - JWT Best Current Practices
• CVE-2022-23540 - jsonwebtoken algorithm none
• CVE-2025-30204 - golang-jwt DoS
• LightSEC 2025 - "Back to the Future" Attack
• PortSwigger - JWT Algorithm Confusion
• OWASP JWT Security Cheat Sheet

🔗 Related ESLint Plugins

Part of the Interlace ESLint Ecosystem — AI-native security plugins with LLM-optimized error messages:

📄 License

MIT © Ofri Peretz