eslint-plugin-jwt-security 2.3.0

package/dist/src/rules/no-weak-secret/index.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noWeakSecret = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+// Common weak secret patterns
+const WEAK_SECRET_PATTERNS = [
+    /^secret$/i,
+    /^password$/i,
+    /^123456/,
+    /^test/i,
+    /^demo/i,
+    /^example/i,
+    /^changeme/i,
+    /^default/i,
+];
+exports.noWeakSecret = (0, eslint_devkit_1.createRule)({
+    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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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) {
+        const options = context.options[0] ?? {};
+        const { minSecretLength = 32 } = options;
+        /**
+         * Check if a value matches known weak patterns
+         */
+        const isKnownWeakPattern = (value) => {
+            return WEAK_SECRET_PATTERNS.some((pattern) => pattern.test(value));
+        };
+        /**
+         * Check the secret argument for weakness
+         */
+        const checkSecret = (secretNode) => {
+            // Environment variables are considered safe (configuration)
+            if ((0, utils_1.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) {
+                // Check both sign and verify operations
+                if (!(0, utils_1.isSignOperation)(node) && !(0, utils_1.isVerifyOperation)(node)) {
+                    return;
+                }
+                // Secret is usually the second argument
+                if (node.arguments.length >= 2) {
+                    checkSecret(node.arguments[1]);
+                }
+            },
+        };
+    },
+});
+exports.default = exports.noWeakSecret;

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

@@ -0,0 +1,24 @@
+/**
+ * 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 } from '@interlace/eslint-devkit';
+import type { RequireAlgorithmWhitelistOptions } from '../../types';
+type MessageIds = 'missingAlgorithmWhitelist' | 'addAlgorithmWhitelist';
+type RuleOptions = [RequireAlgorithmWhitelistOptions?];
+export declare const requireAlgorithmWhitelist: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default requireAlgorithmWhitelist;

package/dist/src/rules/require-algorithm-whitelist/index.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireAlgorithmWhitelist = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.requireAlgorithmWhitelist = (0, eslint_devkit_1.createRule)({
+    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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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) {
+        return {
+            CallExpression(node) {
+                // Only check verify operations
+                if (!(0, utils_1.isVerifyOperation)(node)) {
+                    return;
+                }
+                // Need at least token and key arguments
+                if (node.arguments.length < 2) {
+                    return;
+                }
+                const optionsArg = (0, utils_1.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 = (0, utils_1.hasOption)(optionsArg, 'algorithms') ||
+                    (0, utils_1.hasOption)(optionsArg, 'algorithm') ||
+                    (0, utils_1.hasOption)(optionsArg, 'alg');
+                if (!hasAlgorithms) {
+                    context.report({
+                        node: optionsArg,
+                        messageId: 'missingAlgorithmWhitelist',
+                    });
+                }
+            },
+        };
+    },
+});
+exports.default = exports.requireAlgorithmWhitelist;

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

@@ -0,0 +1,20 @@
+/**
+ * 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 } from '@interlace/eslint-devkit';
+import type { RequireAudienceValidationOptions } from '../../types';
+type RuleOptions = [RequireAudienceValidationOptions?];
+export declare const requireAudienceValidation: TSESLint.RuleModule<"missingAudienceValidation", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default requireAudienceValidation;

package/dist/src/rules/require-audience-validation/index.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireAudienceValidation = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.requireAudienceValidation = (0, eslint_devkit_1.createRule)({
+    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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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) {
+        return {
+            CallExpression(node) {
+                if (!(0, utils_1.isVerifyOperation)(node)) {
+                    return;
+                }
+                if (node.arguments.length < 2) {
+                    return;
+                }
+                const optionsArg = (0, utils_1.getOptionsArgument)(node, 2);
+                // No options at all
+                if (!optionsArg) {
+                    context.report({
+                        node,
+                        messageId: 'missingAudienceValidation',
+                    });
+                    return;
+                }
+                // Check for audience option
+                if (!(0, utils_1.hasOption)(optionsArg, 'audience') && !(0, utils_1.hasOption)(optionsArg, 'aud')) {
+                    context.report({
+                        node: optionsArg,
+                        messageId: 'missingAudienceValidation',
+                    });
+                }
+            },
+        };
+    },
+});
+exports.default = exports.requireAudienceValidation;

package/dist/src/rules/require-expiration/index.d.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.
+ */
+/**
+ * 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 } from '@interlace/eslint-devkit';
+import type { RequireExpirationOptions } from '../../types';
+type MessageIds = 'missingExpiration' | 'addExpiration';
+type RuleOptions = [RequireExpirationOptions?];
+export declare const requireExpiration: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default requireExpiration;

package/dist/src/rules/require-expiration/index.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireExpiration = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.requireExpiration = (0, eslint_devkit_1.createRule)({
+    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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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) {
+        /**
+         * Check if payload contains exp claim
+         */
+        // oxlint-disable-next-line consistent-function-scoping
+        const payloadHasExp = (payloadNode) => {
+            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) {
+                // Only check sign operations
+                if (!(0, utils_1.isSignOperation)(node)) {
+                    return;
+                }
+                // Need at least payload argument
+                if (node.arguments.length < 1) {
+                    return;
+                }
+                const payloadArg = node.arguments[0];
+                const optionsArg = (0, utils_1.getOptionsArgument)(node, 2);
+                // Check if payload has exp claim
+                if (payloadHasExp(payloadArg)) {
+                    return;
+                }
+                // Check if options has expiresIn
+                if (optionsArg && (0, utils_1.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 === eslint_devkit_1.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\' }');
+                            },
+                        },
+                    ],
+                });
+            },
+        };
+    },
+});
+exports.default = exports.requireExpiration;

package/dist/src/rules/require-issued-at/index.d.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.
+ */
+/**
+ * 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 } from '@interlace/eslint-devkit';
+import type { JwtRuleOptions } from '../../types';
+type RuleOptions = [JwtRuleOptions?];
+export declare const requireIssuedAt: TSESLint.RuleModule<"missingIssuedAt", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default requireIssuedAt;