eslint-plugin-jwt-security 2.3.0

package/src/rules/require-audience-validation/index.ts

@@ -0,0 +1,120 @@
+/**
+ * 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-audience-validation
+ *
+ * Mandates audience (aud) claim validation in JWT verify operations.
+ * Without audience validation, tokens intended for other services are accepted.
+ *
+ * CWE-287: Improper Authentication
+ */
+import type { TSESLint, TSESTree } from '@interlace/eslint-devkit';
+import { createRule, formatLLMMessage, MessageIcons } from '@interlace/eslint-devkit';
+import { isVerifyOperation, getOptionsArgument, hasOption } from '../../utils';
+import type { RequireAudienceValidationOptions } from '../../types';
+
+type MessageIds = 'missingAudienceValidation';
+
+type RuleOptions = [RequireAudienceValidationOptions?];
+
+export const requireAudienceValidation = createRule<RuleOptions, MessageIds>({
+  name: 'require-audience-validation',
+  meta: {
+    type: 'problem',
+    docs: {
+      url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/require-audience-validation.md',
+      description:
+        'Require audience (aud) claim validation in JWT verify operations',
+      cwe: 'CWE-287',
+      cvss: 9.8,
+    },
+    fixable: undefined,
+    hasSuggestions: false,
+    messages: {
+      missingAudienceValidation: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Missing Audience Validation',
+        cwe: 'CWE-287',
+        description:
+          'JWT verification without audience validation accepts tokens intended for other services',
+        severity: 'MEDIUM',
+        fix: 'Add audience option: { audience: "https://api.example.com" }',
+        documentationLink: 'https://tools.ietf.org/html/rfc8725',
+      }),
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          knownAudiences: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+            description: 'Known valid audiences to suggest',
+          },
+          trustedSanitizers: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          trustedAnnotations: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          strictMode: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      knownAudiences: [],
+      trustedSanitizers: [],
+      trustedAnnotations: [],
+      strictMode: false,
+    },
+  ],
+  create(context: TSESLint.RuleContext<MessageIds, RuleOptions>) {
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        if (!isVerifyOperation(node)) {
+          return;
+        }
+
+        if (node.arguments.length < 2) {
+          return;
+        }
+
+        const optionsArg = getOptionsArgument(node, 2);
+
+        // No options at all
+        if (!optionsArg) {
+          context.report({
+            node,
+            messageId: 'missingAudienceValidation',
+          });
+          return;
+        }
+
+        // Check for audience option
+        if (!hasOption(optionsArg, 'audience') && !hasOption(optionsArg, 'aud')) {
+          context.report({
+            node: optionsArg,
+            messageId: 'missingAudienceValidation',
+          });
+        }
+      },
+    };
+  },
+});
+
+export default requireAudienceValidation;

package/src/rules/require-audience-validation/require-audience-validation.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Tests for require-audience-validation rule
+ */
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { describe, it, afterAll } from 'vitest';
+import parser from '@typescript-eslint/parser';
+import { requireAudienceValidation } 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-audience-validation', () => {
+  describe('Valid Code', () => {
+    ruleTester.run('valid - with audience', requireAudienceValidation, {
+      valid: [
+        { code: `jwt.verify(token, secret, { audience: 'https://api.example.com' });` },
+        { code: `jwt.verify(token, secret, { aud: 'api.example.com' });` },
+        { code: `jwt.verify(token, secret, { audience: ['api', 'web'] });` },
+        { code: `jwt.sign(payload, secret);` }, // sign not checked
+        // Only one argument - edge case
+        { code: `jwt.verify(token);` },
+        // jwtVerify with audience
+        { code: `jwtVerify(token, key, { audience: 'https://api.example.com' });` },
+      ],
+      invalid: [],
+    });
+  });
+
+  describe('Invalid Code', () => {
+    ruleTester.run('invalid - missing audience', requireAudienceValidation, {
+      valid: [],
+      invalid: [
+        {
+          code: `jwt.verify(token, secret);`,
+          errors: [{ messageId: 'missingAudienceValidation' }],
+        },
+        {
+          code: `jwt.verify(token, secret, {});`,
+          errors: [{ messageId: 'missingAudienceValidation' }],
+        },
+        {
+          code: `jwt.verify(token, secret, { issuer: 'auth.example.com' });`,
+          errors: [{ messageId: 'missingAudienceValidation' }],
+        },
+        // jwtVerify without audience
+        {
+          code: `jwtVerify(token, key);`,
+          errors: [{ messageId: 'missingAudienceValidation' }],
+        },
+        // jwtVerify with only issuer
+        {
+          code: `jwtVerify(token, key, { issuer: 'auth.example.com' });`,
+          errors: [{ messageId: 'missingAudienceValidation' }],
+        },
+      ],
+    });
+  });
+});

package/src/rules/require-expiration/index.ts

@@ -0,0 +1,170 @@
+/**
+ * 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-expiration
+ *
+ * Mandates expiration claim (exp) or expiresIn option in JWT sign operations.
+ * Tokens without expiration are valid forever, creating security risks.
+ *
+ * CWE-613: Insufficient Session Expiration
+ *
+ * @see https://tools.ietf.org/html/rfc8725
+ */
+import type { TSESLint, TSESTree } from '@interlace/eslint-devkit';
+import { AST_NODE_TYPES, createRule, formatLLMMessage, MessageIcons } from '@interlace/eslint-devkit';
+import {
+  isSignOperation,
+  getOptionsArgument,
+  hasOption,
+} from '../../utils';
+import type { RequireExpirationOptions } from '../../types';
+
+type MessageIds =
+  | 'missingExpiration'
+  | 'addExpiration';
+
+type RuleOptions = [RequireExpirationOptions?];
+
+export const requireExpiration = createRule<RuleOptions, MessageIds>({
+  name: 'require-expiration',
+  meta: {
+    type: 'problem',
+    docs: {
+      url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/require-expiration.md',
+      description:
+        'Require expiration claim (exp) or expiresIn option in JWT signing',
+      cwe: 'CWE-613',
+      cvss: 5.4,
+    },
+    hasSuggestions: true,
+    messages: {
+      missingExpiration: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Missing JWT Expiration',
+        cwe: 'CWE-613',
+        description:
+          'JWT without expiration is valid forever, increasing exposure window',
+        severity: 'MEDIUM',
+        fix: 'Add expiresIn: "1h" or exp claim to payload',
+        documentationLink: 'https://tools.ietf.org/html/rfc8725',
+      }),
+      addExpiration: formatLLMMessage({
+        icon: MessageIcons.INFO,
+        issueName: 'Add Expiration',
+        description: 'Add expiration to limit token lifetime',
+        severity: 'LOW',
+        fix: 'jwt.sign(payload, secret, { expiresIn: "1h" })',
+        documentationLink: 'https://www.npmjs.com/package/jsonwebtoken',
+      }),
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          maxExpirationSeconds: {
+            type: 'integer',
+            default: 86400,
+            description: 'Maximum allowed expiration time in seconds (24h default)',
+          },
+          trustedSanitizers: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          trustedAnnotations: {
+            type: 'array',
+            items: { type: 'string' },
+            default: [],
+          },
+          strictMode: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [
+    {
+      maxExpirationSeconds: 86400,
+      trustedSanitizers: [],
+      trustedAnnotations: [],
+      strictMode: false,
+    },
+  ],
+  create(context: TSESLint.RuleContext<MessageIds, RuleOptions>) {
+    /**
+     * Check if payload contains exp claim
+     */
+    // oxlint-disable-next-line consistent-function-scoping
+    const payloadHasExp = (payloadNode: TSESTree.Node): boolean => {
+      if (payloadNode.type !== 'ObjectExpression') {
+        return false;
+      }
+
+      return payloadNode.properties.some(
+        (prop) =>
+          prop.type === 'Property' &&
+          prop.key.type === 'Identifier' &&
+          prop.key.name === 'exp'
+      );
+    };
+
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        // Only check sign operations
+        if (!isSignOperation(node)) {
+          return;
+        }
+
+        // Need at least payload argument
+        if (node.arguments.length < 1) {
+          return;
+        }
+
+        const payloadArg = node.arguments[0];
+        const optionsArg = getOptionsArgument(node, 2);
+
+        // Check if payload has exp claim
+        if (payloadHasExp(payloadArg)) {
+          return;
+        }
+
+        // Check if options has expiresIn
+        if (optionsArg && hasOption(optionsArg, 'expiresIn')) {
+          return;
+        }
+
+        // Report missing expiration — suggest adding expiresIn to the options object
+        const optionsArg3 = node.arguments[2];
+        context.report({
+          node,
+          messageId: 'missingExpiration',
+          suggest: [
+            {
+              messageId: 'addExpiration',
+              fix(fixer) {
+                const sourceCode = context.sourceCode;
+                if (optionsArg3 && optionsArg3.type === AST_NODE_TYPES.ObjectExpression) {
+                  // Options object exists but lacks expiresIn — insert property
+                  const openBrace = sourceCode.getFirstToken(optionsArg3)!;
+                  return fixer.insertTextAfter(openBrace, ' expiresIn: \'1h\',');
+                }
+                // No options arg — insert { expiresIn: '1h' } as third argument
+                const lastArg = node.arguments[node.arguments.length - 1];
+                return fixer.insertTextAfter(lastArg, ', { expiresIn: \'1h\' }');
+              },
+            },
+          ],
+        });
+      },
+    };
+  },
+});
+
+export default requireExpiration;

package/src/rules/require-expiration/require-expiration.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for require-expiration rule
+ */
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { describe, it, afterAll } from 'vitest';
+import parser from '@typescript-eslint/parser';
+import { requireExpiration } 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-expiration', () => {
+  describe('Valid Code', () => {
+    ruleTester.run('valid - with expiration', requireExpiration, {
+      valid: [
+        // expiresIn option
+        { code: `jwt.sign(payload, secret, { expiresIn: '1h' });` },
+        { code: `jwt.sign(payload, secret, { expiresIn: 3600 });` },
+        // exp in payload
+        { code: `jwt.sign({ sub: 'user', exp: 1234567890 }, secret);` },
+        { code: `jwt.sign({ exp: Math.floor(Date.now()/1000) + 3600 }, secret);` },
+        // verify not checked
+        { code: `jwt.verify(token, secret);` },
+        // signJWT with expiresIn
+        { code: `signJWT(payload, key, { expiresIn: '1h' });` },
+        // Zero arguments - edge case (line 118 coverage)
+        { code: `jwt.sign();` },
+      ],
+      invalid: [],
+    });
+  });
+
+  describe('Invalid Code', () => {
+    ruleTester.run('invalid - no expiration', requireExpiration, {
+      valid: [],
+      invalid: [
+        {
+          code: `jwt.sign(payload, secret);`,
+          errors: [
+            {
+              messageId: 'missingExpiration',
+              suggestions: [
+                {
+                  messageId: 'addExpiration',
+                  output: `jwt.sign(payload, secret, { expiresIn: '1h' });`,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          code: `jwt.sign(payload, secret, {});`,
+          errors: [
+            {
+              messageId: 'missingExpiration',
+              suggestions: [
+                {
+                  messageId: 'addExpiration',
+                  output: `jwt.sign(payload, secret, { expiresIn: '1h',});`,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          code: `jwt.sign(payload, secret, { algorithm: 'RS256' });`,
+          errors: [
+            {
+              messageId: 'missingExpiration',
+              suggestions: [
+                {
+                  messageId: 'addExpiration',
+                  output: `jwt.sign(payload, secret, { expiresIn: '1h', algorithm: 'RS256' });`,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          code: `jwt.sign({ sub: 'user', iat: Date.now() }, secret);`,
+          errors: [
+            {
+              messageId: 'missingExpiration',
+              suggestions: [
+                {
+                  messageId: 'addExpiration',
+                  output: `jwt.sign({ sub: 'user', iat: Date.now() }, secret, { expiresIn: '1h' });`,
+                },
+              ],
+            },
+          ],
+        },
+        {
+          code: `sign(payload, key);`,
+          errors: [
+            {
+              messageId: 'missingExpiration',
+              suggestions: [
+                {
+                  messageId: 'addExpiration',
+                  output: `sign(payload, key, { expiresIn: '1h' });`,
+                },
+              ],
+            },
+          ],
+        },
+        // signJWT without expiration
+        {
+          code: `signJWT({ sub: 'user' }, key, { algorithm: 'RS256' });`,
+          errors: [
+            {
+              messageId: 'missingExpiration',
+              suggestions: [
+                {
+                  messageId: 'addExpiration',
+                  output: `signJWT({ sub: 'user' }, key, { expiresIn: '1h', algorithm: 'RS256' });`,
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+  });
+});

package/src/rules/require-issued-at/index.ts

@@ -0,0 +1,143 @@
+/**
+ * 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-issued-at
+ *
+ * Mandates the `iat` (issued at) claim in JWT tokens for freshness validation.
+ * Without `iat`, tokens cannot be validated for age, enabling 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 } from '../../utils';
+import type { JwtRuleOptions } from '../../types';
+
+type MessageIds = 'missingIssuedAt';
+
+type RuleOptions = [JwtRuleOptions?];
+
+export const requireIssuedAt = createRule<RuleOptions, MessageIds>({
+  name: 'require-issued-at',
+  meta: {
+    type: 'problem',
+    docs: {
+      url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/require-issued-at.md',
+      description:
+        'Require iat (issued at) claim for token freshness validation',
+      cwe: 'CWE-294',
+      cvss: 5,
+    },
+    fixable: undefined,
+    hasSuggestions: false,
+    messages: {
+      missingIssuedAt: formatLLMMessage({
+        icon: MessageIcons.SECURITY,
+        issueName: 'Missing Issued At Claim',
+        cwe: 'CWE-294',
+        description:
+          'JWT without iat claim cannot be validated for freshness, enabling replay attacks',
+        severity: 'MEDIUM',
+        fix: 'Add iat claim to payload or use library option that adds it automatically',
+        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>) {
+    /**
+     * Check if payload contains iat claim
+     */
+    // oxlint-disable-next-line consistent-function-scoping
+    const payloadHasIat = (payloadNode: TSESTree.Node): boolean => {
+      if (payloadNode.type !== 'ObjectExpression') {
+        return false;
+      }
+
+      return payloadNode.properties.some(
+        (prop) =>
+          prop.type === 'Property' &&
+          prop.key.type === 'Identifier' &&
+          prop.key.name === 'iat'
+      );
+    };
+
+    return {
+      CallExpression(node: TSESTree.CallExpression) {
+        // Only check sign operations
+        if (!isSignOperation(node)) {
+          return;
+        }
+
+        // Need at least payload argument
+        if (node.arguments.length < 1) {
+          return;
+        }
+
+        const payloadArg = node.arguments[0];
+        const optionsArg = getOptionsArgument(node, 2);
+
+        // Check if payload has iat claim
+        if (payloadHasIat(payloadArg)) {
+          return;
+        }
+
+        // Check if options has noTimestamp: false (meaning iat IS added)
+        // jsonwebtoken adds iat by default unless noTimestamp: true
+        if (optionsArg && hasOption(optionsArg, 'noTimestamp')) {
+          // If noTimestamp is explicitly set, we flag it (they're disabling iat)
+          context.report({
+            node: optionsArg,
+            messageId: 'missingIssuedAt',
+          });
+          return;
+        }
+
+        // For explicit payload objects without iat we intentionally do not
+        // report — jsonwebtoken adds iat by default. (A dead empty `if` that
+        // re-checked !payloadHasIat(payloadArg) — always true after the early
+        // return above — was removed as unreachable-by-construction.)
+
+        // Note: jsonwebtoken adds iat by default, so we don't flag by default
+        // This rule primarily catches explicit noTimestamp: true usage
+      },
+    };
+  },
+});
+
+export default requireIssuedAt;

package/src/rules/require-issued-at/require-issued-at.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Tests for require-issued-at rule
+ */
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { describe, it, afterAll } from 'vitest';
+import parser from '@typescript-eslint/parser';
+import { requireIssuedAt } 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-issued-at', () => {
+  describe('Valid Code', () => {
+    ruleTester.run('valid - with iat', requireIssuedAt, {
+      valid: [
+        // iat in payload
+        { code: `jwt.sign({ sub: 'user', iat: Date.now() }, secret);` },
+        // Default behavior (jsonwebtoken adds iat automatically)
+        { code: `jwt.sign(payload, secret);` },
+        { code: `jwt.sign(payload, secret, { expiresIn: '1h' });` },
+        // Verify not checked
+        { code: `jwt.verify(token, secret);` },
+        // No arguments - edge case
+        { code: `sign();` },
+        // Variable payload with iat
+        { code: `jwt.sign({ iat: Math.floor(Date.now() / 1000), sub: 'user' }, secret);` },
+      ],
+      invalid: [],
+    });
+  });
+
+  describe('Invalid Code', () => {
+    ruleTester.run('invalid - noTimestamp disables iat', requireIssuedAt, {
+      valid: [],
+      invalid: [
+        // noTimestamp: true explicitly disables iat
+        {
+          code: `jwt.sign({ sub: 'user' }, secret, { noTimestamp: true });`,
+          errors: [{ messageId: 'missingIssuedAt' }],
+        },
+        // noTimestamp with other options
+        {
+          code: `jwt.sign(payload, secret, { expiresIn: '1h', noTimestamp: true });`,
+          errors: [{ messageId: 'missingIssuedAt' }],
+        },
+        // SignJWT with noTimestamp
+        {
+          code: `signJWT(payload, key, { noTimestamp: true });`,
+          errors: [{ messageId: 'missingIssuedAt' }],
+        },
+      ],
+    });
+  });
+});