eslint-plugin-jwt-security 2.3.0

package/src/rules/no-timestamp-manipulation/index.ts

@@ -0,0 +1,118 @@
+/**
+ * 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-timestamp-manipulation
+ *
+ * Detects patterns that disable automatic timestamp (iat) generation.
+ * This enables the "Back to the Future" replay attack (LightSEC 2025).
+ *
+ * CWE-294: Authentication Bypass by Capture-replay
+ *
+ * @see https://securitypattern.com/post/jwt-back-to-the-future
+ */
+import type { TSESLint, TSESTree } from '@interlace/eslint-devkit';
+import { createRule, formatLLMMessage, MessageIcons } from '@interlace/eslint-devkit';
+import { isSignOperation, getOptionsArgument, hasOption, getOptionValue } from '../../utils';
+import type { JwtRuleOptions } from '../../types';
+
+type MessageIds = 'timestampDisabled' | 'noTimestampTrue';
+
+type RuleOptions = [JwtRuleOptions?];
+
+export const noTimestampManipulation = createRule<RuleOptions, MessageIds>({
+  name: 'no-timestamp-manipulation',
+  meta: {
+    type: 'problem',
+    docs: {
+      url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/no-timestamp-manipulation.md',
+      description:
+        'Prevent disabling automatic timestamp generation which enables replay attacks',
+      cwe: 'CWE-294',
+      cvss: 7.5,
+    },
+    fixable: undefined,
+    hasSuggestions: false,
+    messages: {
+      timestampDisabled: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Timestamp Generation Disabled',
+        cwe: 'CWE-294',
+        description:
+          'noTimestamp:true disables iat claim, enabling replay attacks',
+        severity: 'HIGH',
+        fix: 'Remove noTimestamp option or set to false',
+        documentationLink: 'https://securitypattern.com/post/jwt-back-to-the-future',
+      }),
+      noTimestampTrue: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Back to the Future Attack Vector',
+        cwe: 'CWE-294',
+        description:
+          'Disabling timestamps allows attackers to forge tokens valid in the future',
+        severity: 'HIGH',
+        fix: 'Always include iat claim for freshness validation',
+        documentationLink: 'https://securitypattern.com/post/jwt-back-to-the-future',
+      }),
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          trustedSanitizers: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          trustedAnnotations: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          strictMode: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      trustedSanitizers: [],
+      trustedAnnotations: [],
+      strictMode: false,
+    },
+  ],
+  create(context: TSESLint.RuleContext<MessageIds, RuleOptions>) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!isSignOperation(node)) {
+          return;
+        }
+
+        const optionsArg = getOptionsArgument(node, 2);
+        if (!optionsArg) {
+          return;
+        }
+
+        // Check for noTimestamp: true
+        if (hasOption(optionsArg, 'noTimestamp')) {
+          const value = getOptionValue(optionsArg, 'noTimestamp');
+          if (value?.type === 'Literal' && value.value === true) {
+            context.report({
+              node: value,
+              messageId: 'noTimestampTrue',
+            });
+          }
+        }
+      },
+    };
+  },
+});
+
+export default noTimestampManipulation;

package/src/rules/no-timestamp-manipulation/no-timestamp-manipulation.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Tests for no-timestamp-manipulation rule
+ * Security: LightSEC 2025 - "Back to the Future" Attack
+ */
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { describe, it, afterAll } from 'vitest';
+import parser from '@typescript-eslint/parser';
+import { noTimestampManipulation } 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-timestamp-manipulation', () => {
+  describe('Valid Code', () => {
+    ruleTester.run('valid - default timestamps', noTimestampManipulation, {
+      valid: [
+        'const x = 42;',
+        'const flag = true;',
+        { code: `jwt.sign(payload, secret);` },
+        { code: `jwt.sign(payload, secret, {});` },
+        { code: `jwt.sign(payload, secret, { expiresIn: '1h' });` },
+        { code: `jwt.sign(payload, secret, { noTimestamp: false });` },
+        { code: `jwt.verify(token, secret);` }, // verify not checked
+      ],
+      invalid: [],
+    });
+  });
+
+  describe('Invalid Code', () => {
+    ruleTester.run('invalid - noTimestamp true', noTimestampManipulation, {
+      valid: [],
+      invalid: [
+        {
+          code: `jwt.sign(payload, secret, { noTimestamp: true });`,
+          errors: [{ messageId: 'noTimestampTrue' }],
+        },
+        {
+          code: `jwt.sign(payload, secret, { algorithm: 'RS256', noTimestamp: true });`,
+          errors: [{ messageId: 'noTimestampTrue' }],
+        },
+      ],
+    });
+  });
+});

package/src/rules/no-weak-secret/index.ts

@@ -0,0 +1,204 @@
+/**
+ * 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-weak-secret
+ *
+ * Detects weak secrets used for HMAC-based JWT signing.
+ * Weak secrets can be brute-forced, allowing attackers to forge tokens.
+ *
+ * CWE-326: Inadequate Encryption Strength
+ *
+ * @see https://tools.ietf.org/html/rfc8725
+ */
+import type { TSESLint, TSESTree } from '@interlace/eslint-devkit';
+import { createRule, formatLLMMessage, MessageIcons } from '@interlace/eslint-devkit';
+import {
+  isSignOperation,
+  isVerifyOperation,
+  isEnvVariable,
+} from '../../utils';
+import type { NoWeakSecretOptions } from '../../types';
+
+type MessageIds =
+  | 'weakSecret'
+  | 'shortSecret'
+  | 'useStrongSecret';
+
+type RuleOptions = [NoWeakSecretOptions?];
+
+// Common weak secret patterns
+const WEAK_SECRET_PATTERNS = [
+  /^secret$/i,
+  /^password$/i,
+  /^123456/,
+  /^test/i,
+  /^demo/i,
+  /^example/i,
+  /^changeme/i,
+  /^default/i,
+];
+
+export const noWeakSecret = createRule<RuleOptions, MessageIds>({
+  name: 'no-weak-secret',
+  meta: {
+    type: 'problem',
+    docs: {
+      url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/no-weak-secret.md',
+      description:
+        'Require strong secrets (256+ bits) for HMAC-based JWT signing',
+      cwe: 'CWE-326',
+      cvss: 5.9,
+    },
+    fixable: undefined,
+    hasSuggestions: false,
+    messages: {
+      weakSecret: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Weak JWT Secret',
+        cwe: 'CWE-326',
+        description:
+          'JWT secret is too weak and can be brute-forced',
+        severity: 'HIGH',
+        fix: 'Use crypto.randomBytes(32).toString("hex") for secrets',
+        documentationLink: 'https://tools.ietf.org/html/rfc8725',
+      }),
+      shortSecret: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Short JWT Secret',
+        cwe: 'CWE-326',
+        description:
+          'JWT secret must be at least 32 characters (256 bits) for HS256',
+        severity: 'HIGH',
+        fix: 'Generate a secret with: crypto.randomBytes(32).toString("hex")',
+        documentationLink: 'https://tools.ietf.org/html/rfc8725',
+      }),
+      useStrongSecret: formatLLMMessage({
+        icon: MessageIcons.INFO,
+        issueName: 'Use Strong Secret',
+        description: 'Replace with cryptographically strong secret',
+        severity: 'LOW',
+        fix: 'Use process.env.JWT_SECRET with a 256-bit random value',
+        documentationLink: 'https://nodejs.org/api/crypto.html',
+      }),
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          minSecretLength: {
+            type: 'integer',
+            default: 32,
+            minimum: 16,
+            description: 'Minimum secret length in characters',
+          },
+          trustedSanitizers: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          trustedAnnotations: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          strictMode: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      minSecretLength: 32,
+      trustedSanitizers: [],
+      trustedAnnotations: [],
+      strictMode: false,
+    },
+  ],
+  create(context: TSESLint.RuleContext<MessageIds, RuleOptions>) {
+    const options = context.options[0] ?? {};
+    const { minSecretLength = 32 } = options;
+
+    /**
+     * Check if a value matches known weak patterns
+     */
+    const isKnownWeakPattern = (value: string): boolean => {
+      return WEAK_SECRET_PATTERNS.some((pattern) => pattern.test(value));
+    };
+
+    /**
+     * Check the secret argument for weakness
+     */
+    const checkSecret = (
+      secretNode: TSESTree.Node
+    ): void => {
+      // Environment variables are considered safe (configuration)
+      if (isEnvVariable(secretNode)) {
+        return;
+      }
+
+      // Check string literals
+      if (
+        secretNode.type === 'Literal' &&
+        typeof secretNode.value === 'string'
+      ) {
+        const secretValue = secretNode.value;
+
+        // Check for known weak patterns
+        if (isKnownWeakPattern(secretValue)) {
+          context.report({
+            node: secretNode,
+            messageId: 'weakSecret',
+          });
+          return;
+        }
+
+        // Check for short secrets
+        if (secretValue.length < minSecretLength) {
+          context.report({
+            node: secretNode,
+            messageId: 'shortSecret',
+            data: {
+              length: String(secretValue.length),
+              minLength: String(minSecretLength),
+            },
+          });
+        }
+      }
+
+      // Template literals with obvious weak values
+      if (secretNode.type === 'TemplateLiteral' && secretNode.quasis.length === 1) {
+        const rawValue = secretNode.quasis[0].value.raw;
+        if (isKnownWeakPattern(rawValue) || rawValue.length < minSecretLength) {
+          context.report({
+            node: secretNode,
+            messageId: 'weakSecret',
+          });
+        }
+      }
+    };
+
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        // Check both sign and verify operations
+        if (!isSignOperation(node) && !isVerifyOperation(node)) {
+          return;
+        }
+
+        // Secret is usually the second argument
+        if (node.arguments.length >= 2) {
+          checkSecret(node.arguments[1]);
+        }
+      },
+    };
+  },
+});
+
+export default noWeakSecret;

package/src/rules/no-weak-secret/no-weak-secret.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Tests for no-weak-secret rule
+ * Security: CWE-326 (Encryption Strength)
+ */
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { describe, it, afterAll } from 'vitest';
+import parser from '@typescript-eslint/parser';
+import { noWeakSecret } 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',
+  },
+});
+
+// 32+ character strong secret for testing
+const STRONG_SECRET = 'ThisIsAVeryStrongSecretThatIs32Ch+';
+
+describe('no-weak-secret', () => {
+  describe('Valid Code - Strong Secrets', () => {
+    ruleTester.run('valid - strong secrets', noWeakSecret, {
+      valid: [
+        // Environment variable
+        { code: `jwt.sign(payload, process.env.JWT_SECRET);` },
+        // Long secret (32+ chars)
+        { code: `jwt.sign(payload, '${STRONG_SECRET}');` },
+        // Non-literal (function call)
+        { code: `jwt.sign(payload, getSecret());` },
+        // Variable reference
+        { code: `jwt.sign(payload, secret);` },
+        // crypto.randomBytes
+        { code: `jwt.sign(payload, crypto.randomBytes(32).toString('hex'));` },
+        // Verify with env
+        { code: `jwt.verify(token, process.env.JWT_SECRET);` },
+      ],
+      invalid: [],
+    });
+  });
+
+  describe('Invalid Code - Weak Secrets', () => {
+    ruleTester.run('invalid - weak secrets', noWeakSecret, {
+      valid: [],
+      invalid: [
+        // Known weak pattern: "secret"
+        {
+          code: `jwt.sign(payload, 'secret');`,
+          errors: [{ messageId: 'weakSecret' }],
+        },
+        // Known weak pattern: "password"
+        {
+          code: `jwt.sign(payload, 'password');`,
+          errors: [{ messageId: 'weakSecret' }],
+        },
+        // Short secret
+        {
+          code: `jwt.sign(payload, 'short');`,
+          errors: [{ messageId: 'shortSecret' }],
+        },
+        // Just under minimum (31 chars)
+        {
+          code: `jwt.sign(payload, 'abcdefghijklmnopqrstuvwxyz12345');`,
+          errors: [{ messageId: 'shortSecret' }],
+        },
+        // Known weak: test
+        {
+          code: `jwt.sign(payload, 'testkey');`,
+          errors: [{ messageId: 'weakSecret' }],
+        },
+        // Known weak: demo
+        {
+          code: `jwt.verify(token, 'demo123');`,
+          errors: [{ messageId: 'weakSecret' }],
+        },
+        // Template literal with weak value
+        {
+          code: 'jwt.sign(payload, `secret`);',
+          errors: [{ messageId: 'weakSecret' }],
+        },
+        // Known weak: changeme
+        {
+          code: `jwt.sign(payload, 'changeme');`,
+          errors: [{ messageId: 'weakSecret' }],
+        },
+      ],
+    });
+  });
+
+  describe('Configuration Options', () => {
+    ruleTester.run('config - custom min length', noWeakSecret, {
+      valid: [
+        // 16 char secret with minSecretLength: 16
+        {
+          code: `jwt.sign(payload, 'sixteen_chars!!!');`,
+          options: [{ minSecretLength: 16 }],
+        },
+      ],
+      invalid: [
+        // 15 chars with minSecretLength: 16
+        {
+          code: `jwt.sign(payload, 'fifteen_chars!!');`,
+          options: [{ minSecretLength: 16 }],
+          errors: [{ messageId: 'shortSecret' }],
+        },
+      ],
+    });
+  });
+});

package/src/rules/require-algorithm-whitelist/index.ts

@@ -0,0 +1,145 @@
+/**
+ * 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: require-algorithm-whitelist
+ *
+ * Enforces explicit algorithm specification in JWT verify operations.
+ * Without explicit algorithms, the token's header algorithm is trusted,
+ * enabling algorithm substitution attacks.
+ *
+ * CWE-757: Selection of Less-Secure Algorithm During Negotiation
+ *
+ * @see https://tools.ietf.org/html/rfc8725
+ */
+import type { TSESLint, TSESTree } from '@interlace/eslint-devkit';
+import { createRule, formatLLMMessage, MessageIcons } from '@interlace/eslint-devkit';
+import {
+  isVerifyOperation,
+  getOptionsArgument,
+  hasOption,
+} from '../../utils';
+import type { RequireAlgorithmWhitelistOptions } from '../../types';
+
+type MessageIds =
+  | 'missingAlgorithmWhitelist'
+  | 'addAlgorithmWhitelist';
+
+type RuleOptions = [RequireAlgorithmWhitelistOptions?];
+
+export const requireAlgorithmWhitelist = createRule<RuleOptions, MessageIds>({
+  name: 'require-algorithm-whitelist',
+  meta: {
+    type: 'problem',
+    docs: {
+      url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/require-algorithm-whitelist.md',
+      description:
+        'Require explicit algorithm specification in JWT verify operations',
+      cwe: 'CWE-757',
+      cvss: 7.5,
+    },
+    fixable: undefined,
+    hasSuggestions: false,
+    messages: {
+      missingAlgorithmWhitelist: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Missing Algorithm Whitelist',
+        cwe: 'CWE-757',
+        description:
+          'JWT verification without explicit algorithms trusts the token header',
+        severity: 'HIGH',
+        fix: 'Add algorithms: ["RS256"] or algorithms: ["ES256"] to options',
+        documentationLink: 'https://tools.ietf.org/html/rfc8725',
+      }),
+      addAlgorithmWhitelist: formatLLMMessage({
+        icon: MessageIcons.INFO,
+        issueName: 'Add Algorithm Whitelist',
+        description: 'Specify allowed algorithms explicitly',
+        severity: 'LOW',
+        fix: 'jwt.verify(token, key, { algorithms: ["RS256"] })',
+        documentationLink: 'https://tools.ietf.org/html/rfc8725',
+      }),
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          recommendedAlgorithms: {
+            type: 'array',
+            items: { type: 'string' },
+            default: ['RS256', 'ES256'],
+            description: 'Algorithms to suggest in auto-fix',
+          },
+          trustedSanitizers: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          trustedAnnotations: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          strictMode: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      recommendedAlgorithms: ['RS256', 'ES256'],
+      trustedSanitizers: [],
+      trustedAnnotations: [],
+      strictMode: false,
+    },
+  ],
+  create(context: TSESLint.RuleContext<MessageIds, RuleOptions>) {
+
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        // Only check verify operations
+        if (!isVerifyOperation(node)) {
+          return;
+        }
+
+        // Need at least token and key arguments
+        if (node.arguments.length < 2) {
+          return;
+        }
+
+        const optionsArg = getOptionsArgument(node, 2);
+
+        // No options at all - definitely missing algorithms
+        if (!optionsArg) {
+          context.report({
+            node,
+            messageId: 'missingAlgorithmWhitelist',
+          });
+          return;
+        }
+
+        // Options exist but no algorithms property
+        const hasAlgorithms =
+          hasOption(optionsArg, 'algorithms') ||
+          hasOption(optionsArg, 'algorithm') ||
+          hasOption(optionsArg, 'alg');
+
+        if (!hasAlgorithms) {
+          context.report({
+            node: optionsArg,
+            messageId: 'missingAlgorithmWhitelist',
+          });
+        }
+      },
+    };
+  },
+});
+
+export default requireAlgorithmWhitelist;

package/src/rules/require-algorithm-whitelist/require-algorithm-whitelist.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Tests for require-algorithm-whitelist rule
+ */
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { describe, it, afterAll } from 'vitest';
+import parser from '@typescript-eslint/parser';
+import { requireAlgorithmWhitelist } 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('require-algorithm-whitelist', () => {
+  describe('Valid Code', () => {
+    ruleTester.run('valid - with algorithms', requireAlgorithmWhitelist, {
+      valid: [
+        { code: `jwt.verify(token, secret, { algorithms: ['RS256'] });` },
+        { code: `jwt.verify(token, secret, { algorithms: ['RS256', 'ES256'] });` },
+        { code: `jwt.verify(token, secret, { algorithm: 'RS256' });` },
+        { code: `jwt.verify(token, secret, { alg: 'RS256' });` },
+        { code: `jwt.sign(payload, secret);` }, // sign not checked
+        // Only one argument - edge case
+        { code: `jwt.verify(token);` },
+        // jwtVerify with algorithms
+        { code: `jwtVerify(token, key, { algorithms: ['RS256'] });` },
+      ],
+      invalid: [],
+    });
+  });
+
+  describe('Invalid Code', () => {
+    ruleTester.run('invalid - no algorithms', requireAlgorithmWhitelist, {
+      valid: [],
+      invalid: [
+        {
+          code: `jwt.verify(token, secret);`,
+          errors: [{ messageId: 'missingAlgorithmWhitelist' }],
+        },
+        {
+          code: `jwt.verify(token, secret, {});`,
+          errors: [{ messageId: 'missingAlgorithmWhitelist' }],
+        },
+        {
+          code: `jwt.verify(token, secret, { complete: true });`,
+          errors: [{ messageId: 'missingAlgorithmWhitelist' }],
+        },
+        {
+          code: `jwt.verify(token, secret, { issuer: 'auth.example.com' });`,
+          errors: [{ messageId: 'missingAlgorithmWhitelist' }],
+        },
+        {
+          code: `jwtVerify(token, key);`,
+          errors: [{ messageId: 'missingAlgorithmWhitelist' }],
+        },
+        // verifyJWT without algorithms
+        {
+          code: `verifyJWT(token, key, { issuer: 'auth.example.com' });`,
+          errors: [{ messageId: 'missingAlgorithmWhitelist' }],
+        },
+      ],
+    });
+  });
+});