eslint-plugin-jwt-security 2.3.0

package/src/index.ts

@@ -0,0 +1,209 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+
+/**
+ * eslint-plugin-jwt-security
+ *
+ * Comprehensive JWT security ESLint plugin for Node.js applications.
+ * Detects vulnerabilities across jsonwebtoken, jose, express-jwt,
+ * @nestjs/jwt, jwks-rsa, and jwt-decode libraries.
+ *
+ * Features:
+ * - Algorithm confusion attack detection (CVE-2022-23540)
+ * - "Back to the Future" replay attack prevention (LightSEC 2025)
+ * - Signature verification enforcement
+ * - Weak secret detection
+ * - Expiration and claim validation
+ * - AI-assisted fix guidance with CWE references
+ *
+ * @see https://tools.ietf.org/html/rfc8725
+ * @see https://securitypattern.com/post/jwt-back-to-the-future
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+
+// Import rules - Core Security
+import { noAlgorithmNone } from './rules/no-algorithm-none';
+import { noAlgorithmConfusion } from './rules/no-algorithm-confusion';
+import { requireAlgorithmWhitelist } from './rules/require-algorithm-whitelist';
+import { noDecodeWithoutVerify } from './rules/no-decode-without-verify';
+import { noWeakSecret } from './rules/no-weak-secret';
+import { requireExpiration } from './rules/require-expiration';
+import { noHardcodedSecret } from './rules/no-hardcoded-secret';
+
+// Import rules - 2025 Vulnerability Research
+import { requireIssuedAt } from './rules/require-issued-at';
+import { requireIssuerValidation } from './rules/require-issuer-validation';
+import { requireAudienceValidation } from './rules/require-audience-validation';
+import { noTimestampManipulation } from './rules/no-timestamp-manipulation';
+import { requireMaxAge } from './rules/require-max-age';
+import { noSensitivePayload } from './rules/no-sensitive-payload';
+
+/**
+ * Collection of all JWT security ESLint rules (13 rules)
+ */
+export const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  // Core Security Rules
+  'no-algorithm-none': noAlgorithmNone,
+  'no-algorithm-confusion': noAlgorithmConfusion,
+  'require-algorithm-whitelist': requireAlgorithmWhitelist,
+  'no-decode-without-verify': noDecodeWithoutVerify,
+  'no-weak-secret': noWeakSecret,
+  'require-expiration': requireExpiration,
+  'no-hardcoded-secret': noHardcodedSecret,
+
+  // 2025 Vulnerability Research - "Back to the Future" & Replay Prevention
+  'require-issued-at': requireIssuedAt,
+  'require-issuer-validation': requireIssuerValidation,
+  'require-audience-validation': requireAudienceValidation,
+  'no-timestamp-manipulation': noTimestampManipulation,
+  'require-max-age': requireMaxAge,
+  'no-sensitive-payload': noSensitivePayload,
+} satisfies Record<string, TSESLint.RuleModule<string, readonly unknown[]>>;
+
+/**
+ * ESLint Plugin object
+ */
+export const plugin: TSESLint.FlatConfig.Plugin = {
+  meta: {
+    name: 'eslint-plugin-jwt-security',
+    version: '2.2.9',
+  },
+  rules,
+} satisfies TSESLint.FlatConfig.Plugin;
+
+/**
+ * Recommended configuration - baseline security
+ * Critical rules as errors, high as warnings
+ */
+const recommendedRules: Record<string, TSESLint.FlatConfig.RuleEntry> = {
+  // CRITICAL - Algorithm attacks
+  'jwt/no-algorithm-none': 'error',
+  'jwt/no-algorithm-confusion': 'error',
+
+  // HIGH - Verification and secrets
+  'jwt/require-algorithm-whitelist': 'error',
+  'jwt/no-decode-without-verify': 'error',
+  'jwt/no-weak-secret': 'error',
+  'jwt/no-hardcoded-secret': 'error',
+  'jwt/no-timestamp-manipulation': 'error', // LightSEC 2025
+
+  // MEDIUM - Best practices
+  'jwt/require-expiration': 'error',
+  'jwt/no-sensitive-payload': 'warn',
+};
+
+/**
+ * Strict configuration - maximum security (2025 research)
+ * All rules as errors - includes replay attack prevention
+ */
+const strictRules: Record<string, TSESLint.FlatConfig.RuleEntry> = {
+  // All core rules as errors
+  'jwt/no-algorithm-none': 'error',
+  'jwt/no-algorithm-confusion': 'error',
+  'jwt/require-algorithm-whitelist': 'error',
+  'jwt/no-decode-without-verify': 'error',
+  'jwt/no-weak-secret': 'error',
+  'jwt/no-hardcoded-secret': 'error',
+  'jwt/require-expiration': 'error',
+
+  // 2025 Research - Full replay attack prevention
+  'jwt/require-issued-at': 'error',
+  'jwt/require-issuer-validation': 'error',
+  'jwt/require-audience-validation': 'error',
+  'jwt/no-timestamp-manipulation': 'error',
+  'jwt/require-max-age': 'error',
+  'jwt/no-sensitive-payload': 'error',
+};
+
+/**
+ * Legacy configuration - migration mode
+ * Only critical rules enabled
+ */
+const legacyRules: Record<string, TSESLint.FlatConfig.RuleEntry> = {
+  // Only most critical rules
+  'jwt/no-algorithm-none': 'error',
+  'jwt/no-algorithm-confusion': 'error',
+  'jwt/no-hardcoded-secret': 'warn',
+};
+
+/**
+ * Configuration presets for flat config
+ */
+export const configs = {
+  /**
+   * Flagship preset — the rule from this plugin in the ecosystem-wide
+   * flagship list (`.agent/flagship-rules.md`). Use this when you want
+   * the highest-signal JWT subset shippable in CI gates.
+   */
+  flagship: {
+    plugins: {
+      jwt: plugin,
+    },
+    rules: {
+      'jwt/no-algorithm-none': 'error',
+    },
+  } satisfies TSESLint.FlatConfig.Config,
+
+  /**
+   * Recommended preset - balanced security
+   */
+  recommended: {
+    plugins: {
+      jwt: plugin,
+    },
+    rules: recommendedRules,
+  } satisfies TSESLint.FlatConfig.Config,
+
+  /**
+   * Strict preset - maximum security (includes 2025 research)
+   */
+  strict: {
+    plugins: {
+      jwt: plugin,
+    },
+    rules: strictRules,
+  } satisfies TSESLint.FlatConfig.Config,
+
+  /**
+   * Legacy preset - migration mode
+   */
+  legacy: {
+    plugins: {
+      jwt: plugin,
+    },
+    rules: legacyRules,
+  } satisfies TSESLint.FlatConfig.Config,
+
+  /**
+   * All rules preset
+   */
+  all: {
+    plugins: {
+      jwt: plugin,
+    },
+    rules: strictRules,
+  } satisfies TSESLint.FlatConfig.Config,
+};
+
+// Default export for flat config usage
+export default plugin;
+
+// Named exports for flexibility
+export {
+  noAlgorithmNone,
+  noAlgorithmConfusion,
+  requireAlgorithmWhitelist,
+  noDecodeWithoutVerify,
+  noWeakSecret,
+  requireExpiration,
+  noHardcodedSecret,
+  requireIssuedAt,
+  requireIssuerValidation,
+  requireAudienceValidation,
+  noTimestampManipulation,
+  requireMaxAge,
+  noSensitivePayload,
+};

package/src/oxlint.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { plugin as mainPlugin } from './index';
+
+/**
+ * Smoke test for the `./oxlint` sub-export.
+ *
+ * Runtime shape: `oxlint.ts` uses `export = plugin`, which compiles to
+ * `module.exports = plugin`. From an ESM dynamic `import('./oxlint')` view,
+ * Node's CJS interop surfaces that value at `.default`. From oxlint's
+ * `require('eslint-plugin-jwt-security/oxlint')` view, it sits at the top of
+ * `module.exports` — exactly the `{ meta, rules }` shape oxlint's JS plugin
+ * loader expects.
+ */
+
+type Plugin = typeof mainPlugin;
+
+describe('eslint-plugin-jwt-security/oxlint sub-export', () => {
+  it('declares the ./oxlint sub-export in package.json', () => {
+    const pkgJson = JSON.parse(
+      fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'),
+    );
+    expect(pkgJson.exports['./oxlint']).toEqual({
+      types: './src/oxlint.d.ts',
+      default: './src/oxlint.js',
+    });
+  });
+
+  it('re-exports the plugin object (meta + rules at top level)', async () => {
+    const oxlintModule = await import('./oxlint.js');
+    const oxlintPlugin = (oxlintModule as unknown as { default: Plugin }).default;
+    expect(oxlintPlugin).toBeDefined();
+    expect(oxlintPlugin.meta?.name).toBe('eslint-plugin-jwt-security');
+    expect(oxlintPlugin.rules).toBeDefined();
+  });
+
+  it('exposes the same rule names as the main entry (no rules dropped)', async () => {
+    const oxlintModule = await import('./oxlint.js');
+    const oxlintPlugin = (oxlintModule as unknown as { default: Plugin }).default;
+    expect(Object.keys(oxlintPlugin.rules || {}).toSorted()).toEqual(
+      Object.keys(mainPlugin.rules || {}).toSorted(),
+    );
+  });
+
+  it('exposes the same rule references (pass-through, not a copy)', async () => {
+    const oxlintModule = await import('./oxlint.js');
+    const oxlintPlugin = (oxlintModule as unknown as { default: Plugin }).default;
+    for (const ruleName of Object.keys(mainPlugin.rules || {})) {
+      expect(oxlintPlugin.rules?.[ruleName]).toBe(
+        (mainPlugin.rules as Record<string, unknown>)[ruleName],
+      );
+    }
+  });
+});

package/src/oxlint.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+
+/**
+ * oxlint sub-export.
+ *
+ * Consumers wire oxlint to this entry via:
+ *   { "jsPlugins": ["eslint-plugin-jwt-security/oxlint"] }
+ *
+ * oxlint's JS plugin loader does `require('eslint-plugin-jwt-security/oxlint')` and reads
+ * `.rules` off the result. The compiled output of `export = plugin` is
+ * `module.exports = plugin`, which gives oxlint the plugin object directly
+ * (`{ meta, rules }`) — no wrapper, no `.default` indirection.
+ *
+ * Generated by scripts/generate-oxlint-shims.mjs. Do not edit by hand.
+ */
+
+import { plugin } from './index';
+
+export = plugin;

package/src/rules/no-algorithm-confusion/index.ts

@@ -0,0 +1,208 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+
+/**
+ * ESLint Rule: no-algorithm-confusion
+ *
+ * Detects algorithm confusion attacks where symmetric algorithms (HS256/384/512)
+ * are used with asymmetric keys (public keys). This allows attackers to sign
+ * tokens using the public key as an HMAC secret.
+ *
+ * CWE-347: Improper Verification of Cryptographic Signature
+ *
+ * @see https://portswigger.net/web-security/jwt/algorithm-confusion
+ */
+import type { TSESLint, TSESTree } from '@interlace/eslint-devkit';
+import { createRule, formatLLMMessage, MessageIcons } from '@interlace/eslint-devkit';
+import {
+  isVerifyOperation,
+  getOptionsArgument,
+  extractAlgorithms,
+} from '../../utils';
+import type { NoAlgorithmConfusionOptions } from '../../types';
+
+type MessageIds =
+  | 'algorithmConfusion'
+  | 'symmetricWithPublicKey'
+  | 'useAsymmetricAlgorithm';
+
+type RuleOptions = [NoAlgorithmConfusionOptions?];
+
+// Patterns that indicate a public key
+const PUBLIC_KEY_PATTERNS = [
+  /public/i,
+  /\.pub$/,
+  /\.pem$/,
+  /-----BEGIN PUBLIC KEY-----/,
+  /-----BEGIN RSA PUBLIC KEY-----/,
+  /-----BEGIN EC PUBLIC KEY-----/,
+  /getPublicKey/i,
+  /publicKey/i,
+  /jwks/i,
+];
+
+export const noAlgorithmConfusion = createRule<RuleOptions, MessageIds>({
+  name: 'no-algorithm-confusion',
+  meta: {
+    type: 'problem',
+    docs: {
+      url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/no-algorithm-confusion.md',
+      description:
+        'Prevent algorithm confusion attacks using symmetric algorithms with asymmetric keys',
+      cwe: 'CWE-347',
+      cvss: 9.5,
+    },
+    fixable: undefined,
+    hasSuggestions: false,
+    messages: {
+      algorithmConfusion: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'JWT Algorithm Confusion Attack',
+        cwe: 'CWE-347',
+        description:
+          'Symmetric algorithm (HS*) used with public key allows token forgery',
+        severity: 'CRITICAL',
+        fix: 'Use asymmetric algorithms (RS256, ES256) with public keys',
+        documentationLink:
+          'https://portswigger.net/web-security/jwt/algorithm-confusion',
+      }),
+      symmetricWithPublicKey: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Symmetric Algorithm with Public Key',
+        cwe: 'CWE-347',
+        description:
+          'HS256/384/512 should only be used with shared secrets, not public keys',
+        severity: 'CRITICAL',
+        fix: 'Switch to RS256 or ES256 for asymmetric key verification',
+        documentationLink:
+          'https://portswigger.net/web-security/jwt/algorithm-confusion',
+      }),
+      useAsymmetricAlgorithm: formatLLMMessage({
+        icon: MessageIcons.INFO,
+        issueName: 'Use Asymmetric Algorithm',
+        description: 'Replace HS* with RS* or ES* algorithm',
+        severity: 'LOW',
+        fix: 'Use RS256 or ES256 with public key verification',
+        documentationLink: 'https://tools.ietf.org/html/rfc8725',
+      }),
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          symmetricAlgorithms: {
+            type: 'array',
+            items: { type: 'string' },
+            default: ['HS256', 'HS384', 'HS512'],
+            description: 'Algorithms to flag when used with public keys',
+          },
+          trustedSanitizers: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          trustedAnnotations: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          strictMode: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      symmetricAlgorithms: ['HS256', 'HS384', 'HS512'],
+      trustedSanitizers: [],
+      trustedAnnotations: [],
+      strictMode: false,
+    },
+  ],
+  create(context: TSESLint.RuleContext<MessageIds, RuleOptions>) {
+    const options = context.options[0] ?? {};
+    const symmetricAlgSet = new Set(
+      options.symmetricAlgorithms ?? ['HS256', 'HS384', 'HS512']
+    );
+    const sourceCode = context.sourceCode;
+
+    /**
+     * Check if a node looks like a public key reference
+     */
+    const looksLikePublicKey = (node: TSESTree.Node): boolean => {
+      const text = sourceCode.getText(node);
+      return PUBLIC_KEY_PATTERNS.some((pattern) => pattern.test(text));
+    };
+
+    /**
+     * Check if algorithms include symmetric algorithms
+     */
+    const hasSymmetricAlgorithm = (algorithms: string[]): string | null => {
+      for (const alg of algorithms) {
+        if (symmetricAlgSet.has(alg)) {
+          return alg;
+        }
+      }
+      return null;
+    };
+
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        // Only check verify operations
+        if (!isVerifyOperation(node)) {
+          return;
+        }
+
+        // Need at least 2 arguments: token, key
+        if (node.arguments.length < 2) {
+          return;
+        }
+
+        const keyArg = node.arguments[1];
+        const optionsArg = getOptionsArgument(node, 2);
+
+        // Check if key looks like a public key
+        if (!looksLikePublicKey(keyArg)) {
+          return;
+        }
+
+        // If there are options, check the algorithms
+        if (optionsArg) {
+          const algorithms = extractAlgorithms(optionsArg);
+          const symmetricAlg = hasSymmetricAlgorithm(algorithms);
+
+          if (symmetricAlg) {
+            // Find the algorithm node for precise error location
+            for (const prop of optionsArg.properties) {
+              if (
+                prop.type === 'Property' &&
+                prop.key.type === 'Identifier' &&
+                ['algorithms', 'algorithm', 'alg'].includes(prop.key.name)
+              ) {
+                context.report({
+                  node: prop.value,
+                  messageId: 'algorithmConfusion',
+                  data: { algorithm: symmetricAlg },
+                });
+                return;
+              }
+            }
+          }
+        }
+
+        // If no options specified but key looks like public key,
+        // and we're in verify, flag as potential issue
+        // (verification without explicit algorithm with public key is risky)
+      },
+    };
+  },
+});
+
+export default noAlgorithmConfusion;

package/src/rules/no-algorithm-confusion/no-algorithm-confusion.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Tests for no-algorithm-confusion rule
+ * Security: CWE-347 (Algorithm Confusion Attack)
+ */
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { describe, it, afterAll } from 'vitest';
+import parser from '@typescript-eslint/parser';
+import { noAlgorithmConfusion } from './index';
+
+RuleTester.afterAll = afterAll;
+RuleTester.it = it;
+RuleTester.itOnly = it.only;
+RuleTester.describe = describe;
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser,
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+});
+
+describe('no-algorithm-confusion', () => {
+  describe('Valid Code - Safe Patterns', () => {
+    ruleTester.run('valid - asymmetric algorithms with public keys', noAlgorithmConfusion, {
+      valid: [
+        // RS256 with public key - SAFE
+        { code: `jwt.verify(token, publicKey, { algorithms: ['RS256'] });` },
+        // ES256 with public key - SAFE
+        { code: `jwt.verify(token, publicKey, { algorithms: ['ES256'] });` },
+        // Multiple asymmetric algorithms
+        { code: `jwt.verify(token, publicKey, { algorithms: ['RS256', 'ES256'] });` },
+        // HS256 with secret (not public key) - SAFE
+        { code: `jwt.verify(token, secret, { algorithms: ['HS256'] });` },
+        // HS256 with env var - SAFE
+        { code: `jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });` },
+        // No options specified
+        { code: `jwt.verify(token, publicKey);` },
+        // Sign operation (not verify)
+        { code: `jwt.sign(payload, privateKey, { algorithm: 'HS256' });` },
+        // Only 1 argument (edge case - line 157 coverage)
+        { code: `jwt.verify(token);` },
+        // No key that looks like public key
+        { code: `jwt.verify(token, sharedSecret, { algorithms: ['HS256'] });` },
+        // Empty options object with public key (no algorithms)
+        { code: `jwt.verify(token, publicKey, {});` },
+        // Options without algorithms property
+        { code: `jwt.verify(token, publicKey, { complete: true });` },
+      ],
+      invalid: [],
+    });
+  });
+
+  describe('Invalid Code - Algorithm Confusion', () => {
+    ruleTester.run('invalid - symmetric with public key', noAlgorithmConfusion, {
+      valid: [],
+      invalid: [
+        // HS256 with publicKey variable
+        {
+          code: `jwt.verify(token, publicKey, { algorithms: ['HS256'] });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // HS384 with public key
+        {
+          code: `jwt.verify(token, publicKey, { algorithms: ['HS384'] });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // HS512 with public key
+        {
+          code: `jwt.verify(token, publicKey, { algorithms: ['HS512'] });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // Single algorithm option
+        {
+          code: `jwt.verify(token, publicKey, { algorithm: 'HS256' });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // Mixed algorithms with symmetric
+        {
+          code: `jwt.verify(token, publicKey, { algorithms: ['RS256', 'HS256'] });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // getPublicKey() function
+        {
+          code: `jwt.verify(token, getPublicKey(), { algorithms: ['HS256'] });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // JWKS pattern
+        {
+          code: `jwt.verify(token, jwksKey, { algorithms: ['HS256'] });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // alg shorthand with public key
+        {
+          code: `jwt.verify(token, publicKey, { alg: 'HS256' });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+        // jwtVerify with public key
+        {
+          code: `jwtVerify(token, publicKey, { algorithms: ['HS256'] });`,
+          errors: [{ messageId: 'algorithmConfusion' }],
+        },
+      ],
+    });
+  });
+});