eslint-plugin-jwt-security 2.3.0

package/dist/src/rules/no-decode-without-verify/index.js

@@ -0,0 +1,131 @@
+"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.noDecodeWithoutVerify = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.noDecodeWithoutVerify = (0, eslint_devkit_1.createRule)({
+    name: 'no-decode-without-verify',
+    meta: {
+        type: 'problem',
+        docs: {
+            url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/no-decode-without-verify.md',
+            description: 'Disallow trusting decoded JWT payload without signature verification',
+            cwe: 'CWE-345',
+            cvss: 7.5,
+        },
+        fixable: undefined,
+        hasSuggestions: false,
+        messages: {
+            decodeWithoutVerify: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.SECURITY,
+                issueName: 'Decoded JWT Without Verification',
+                cwe: 'CWE-345',
+                description: 'jwt.decode() returns payload without verifying signature - data can be forged',
+                severity: 'HIGH',
+                fix: 'Use jwt.verify(token, secret) instead of jwt.decode(token)',
+                documentationLink: 'https://owasp.org/API-Security/0xa7-security-misconfiguration/',
+            }),
+            jwtDecodeLibrary: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.SECURITY,
+                issueName: 'jwt-decode Library Usage',
+                cwe: 'CWE-345',
+                description: 'jwt-decode library only decodes tokens, never verifies signatures',
+                severity: 'HIGH',
+                fix: 'Use jsonwebtoken.verify() or jose.jwtVerify() for verification',
+                documentationLink: 'https://www.npmjs.com/package/jwt-decode',
+            }),
+            useVerifyInstead: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Verify Instead',
+                description: 'Replace decode with verify to ensure authenticity',
+                severity: 'LOW',
+                fix: 'jwt.verify(token, secret, { algorithms: ["RS256"] })',
+                documentationLink: 'https://www.npmjs.com/package/jsonwebtoken',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allowHeaderInspection: {
+                        type: 'boolean',
+                        default: false,
+                        description: 'Allow decode() for reading header before verification',
+                    },
+                    trustedSanitizers: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                    trustedAnnotations: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: ['@decoded-header-only', '@verified-separately'],
+                    },
+                    strictMode: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            allowHeaderInspection: false,
+            trustedSanitizers: [],
+            trustedAnnotations: ['@decoded-header-only', '@verified-separately'],
+            strictMode: false,
+        },
+    ],
+    create(context) {
+        const options = context.options[0] ?? {};
+        const { trustedAnnotations = [] } = options;
+        /**
+         * Check if this is a jwt-decode import usage
+         */
+        // oxlint-disable-next-line consistent-function-scoping
+        const isJwtDecodeLibrary = (node) => {
+            // Direct call: jwtDecode(token)
+            if (node.callee.type === 'Identifier' &&
+                (node.callee.name === 'jwtDecode' || node.callee.name === 'jwt_decode')) {
+                return true;
+            }
+            return false;
+        };
+        return {
+            CallExpression(node) {
+                // Check for jwt.decode() pattern
+                if ((0, utils_1.isDecodeOperation)(node)) {
+                    // Check for safe annotations
+                    if ((0, eslint_devkit_1.hasSafeAnnotation)(node, context, trustedAnnotations)) {
+                        return;
+                    }
+                    context.report({
+                        node,
+                        messageId: 'decodeWithoutVerify',
+                    });
+                    return;
+                }
+                // Check for jwt-decode library usage
+                if (isJwtDecodeLibrary(node)) {
+                    // Check for safe annotations
+                    if ((0, eslint_devkit_1.hasSafeAnnotation)(node, context, trustedAnnotations)) {
+                        return;
+                    }
+                    context.report({
+                        node,
+                        messageId: 'jwtDecodeLibrary',
+                    });
+                }
+            },
+        };
+    },
+});
+exports.default = exports.noDecodeWithoutVerify;

package/dist/src/rules/no-hardcoded-secret/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: no-hardcoded-secret
+ *
+ * Detects hardcoded secrets in JWT sign/verify operations.
+ * Hardcoded secrets in source code are a critical security vulnerability.
+ *
+ * CWE-798: Use of Hard-coded Credentials
+ *
+ * @see https://cwe.mitre.org/data/definitions/798.html
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+import type { NoHardcodedSecretOptions } from '../../types';
+type MessageIds = 'hardcodedSecret' | 'useEnvVariable';
+type RuleOptions = [NoHardcodedSecretOptions?];
+export declare const noHardcodedSecret: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default noHardcodedSecret;

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

@@ -0,0 +1,189 @@
+"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.noHardcodedSecret = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.noHardcodedSecret = (0, eslint_devkit_1.createRule)({
+    name: 'no-hardcoded-secret',
+    meta: {
+        type: 'problem',
+        docs: {
+            url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/no-hardcoded-secret.md',
+            description: 'Disallow hardcoded secrets in JWT sign/verify operations',
+            cwe: 'CWE-798',
+            cvss: 9.8,
+        },
+        fixable: undefined,
+        hasSuggestions: false,
+        messages: {
+            hardcodedSecret: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.SECURITY,
+                issueName: 'Hardcoded JWT Secret',
+                cwe: 'CWE-798',
+                description: 'Secret key hardcoded in source code can be extracted from repositories',
+                severity: 'HIGH',
+                fix: 'Use process.env.JWT_SECRET or secure secret management',
+                documentationLink: 'https://cwe.mitre.org/data/definitions/798.html',
+            }),
+            useEnvVariable: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Environment Variable',
+                description: 'Replace hardcoded secret with environment variable',
+                severity: 'LOW',
+                fix: 'process.env.JWT_SECRET',
+                documentationLink: 'https://12factor.net/config',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    envPatterns: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                        description: 'Patterns that indicate safe environment variable usage',
+                    },
+                    trustedSanitizers: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                    trustedAnnotations: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                    strictMode: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            envPatterns: [],
+            trustedSanitizers: [],
+            trustedAnnotations: [],
+            strictMode: false,
+        },
+    ],
+    create(context) {
+        /**
+         * Check if a node is a hardcoded string literal
+         */
+        // oxlint-disable-next-line consistent-function-scoping
+        const isHardcodedString = (node) => {
+            // String literal
+            if (node.type === 'Literal' && typeof node.value === 'string') {
+                return true;
+            }
+            // Template literal without expressions
+            if (node.type === 'TemplateLiteral' &&
+                node.expressions.length === 0) {
+                return true;
+            }
+            return false;
+        };
+        /**
+         * Resolve an Identifier node to its initializer (one frame of indirection).
+         * Closes the audit FN where `const SECRET = 'x'; jwt.sign(p, SECRET)`
+         * was treated as safe — the literal-via-const pattern hides the
+         * hardcoded secret behind one declaration. See benchmarks/AUDIT_PATTERNS.md
+         * §3.2 ("Indirection through one level of variable").
+         */
+        const resolveConstLiteralValue = (node) => {
+            if (node.type !== 'Identifier')
+                return null;
+            const scope = context.sourceCode.getScope?.(node) ?? null;
+            if (!scope)
+                return null;
+            const variable = scope.references.find((r) => r.identifier === node)?.resolved;
+            const def = variable?.defs[0];
+            if (!def || def.type !== 'Variable')
+                return null;
+            const decl = def.parent;
+            if (decl?.type !== 'VariableDeclaration' || decl.kind !== 'const')
+                return null;
+            return def.node.init ?? null;
+        };
+        /**
+         * Check if node is a safe key source
+         */
+        const isSafeKeySource = (node) => {
+            // Environment variable
+            if ((0, utils_1.isEnvVariable)(node)) {
+                return true;
+            }
+            // Function call (getSecret(), loadKey(), etc.)
+            if (node.type === 'CallExpression') {
+                return true;
+            }
+            // await expression (async key loading)
+            if (node.type === 'AwaitExpression') {
+                return true;
+            }
+            // Variable reference: resolve `const X = ...` one level. If X is a
+            // hardcoded literal, treat as unsafe — fall through to the
+            // hardcoded check. Otherwise (env var, call, identifier chain)
+            // it's safe.
+            if (node.type === 'Identifier') {
+                const init = resolveConstLiteralValue(node);
+                if (init && isHardcodedString(init)) {
+                    // Unsafe — let the caller's `isHardcodedString` (with the
+                    // resolved init) flag it.
+                    return false;
+                }
+                return true;
+            }
+            // Member expression but not literal (config.secret, etc.)
+            if (node.type === 'MemberExpression' && !isHardcodedString(node)) {
+                return true;
+            }
+            return false;
+        };
+        /**
+         * Like isHardcodedString but resolves single-level `const X = '...'`
+         * indirection so the caller fires on `const SECRET = 'x'; jwt.sign(p, SECRET)`.
+         */
+        const isHardcodedStringOrResolvedConst = (node) => {
+            if (isHardcodedString(node))
+                return true;
+            const init = resolveConstLiteralValue(node);
+            return init ? isHardcodedString(init) : false;
+        };
+        return {
+            CallExpression(node) {
+                // Check both sign and verify operations
+                if (!(0, utils_1.isSignOperation)(node) && !(0, utils_1.isVerifyOperation)(node)) {
+                    return;
+                }
+                // Secret/key is the second argument
+                if (node.arguments.length < 2) {
+                    return;
+                }
+                const secretArg = node.arguments[1];
+                // Skip if safe source
+                if (isSafeKeySource(secretArg)) {
+                    return;
+                }
+                // Flag hardcoded strings (also follows single-frame `const X = '...'`).
+                if (isHardcodedStringOrResolvedConst(secretArg)) {
+                    context.report({
+                        node: secretArg,
+                        messageId: 'hardcodedSecret',
+                    });
+                }
+            },
+        };
+    },
+});
+exports.default = exports.noHardcodedSecret;

package/dist/src/rules/no-sensitive-payload/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: no-sensitive-payload
+ *
+ * Detects storage of sensitive data in JWT payload.
+ * JWT payloads are only base64-encoded, not encrypted.
+ *
+ * CWE-359: Exposure of Private Personal Information
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+import type { NoSensitivePayloadOptions } from '../../types';
+type RuleOptions = [NoSensitivePayloadOptions?];
+export declare const noSensitivePayload: TSESLint.RuleModule<"sensitivePayloadField", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default noSensitivePayload;

package/dist/src/rules/no-sensitive-payload/index.js

@@ -0,0 +1,103 @@
+"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.noSensitivePayload = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.noSensitivePayload = (0, eslint_devkit_1.createRule)({
+    name: 'no-sensitive-payload',
+    meta: {
+        type: 'problem',
+        docs: {
+            url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/no-sensitive-payload.md',
+            description: 'Prevent storing sensitive data in JWT payload which is only base64-encoded',
+            cwe: 'CWE-359',
+            cvss: 5,
+        },
+        fixable: undefined,
+        hasSuggestions: false,
+        messages: {
+            sensitivePayloadField: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.SECURITY,
+                issueName: 'Sensitive Data in JWT Payload',
+                cwe: 'CWE-359',
+                description: 'JWT payloads are not encrypted - sensitive data like "{{fieldName}}" can be read by anyone',
+                severity: 'MEDIUM',
+                fix: 'Store sensitive data server-side, reference by ID in token',
+                documentationLink: 'https://tools.ietf.org/html/rfc8725',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    additionalSensitiveFields: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                        description: 'Additional field names to flag as sensitive',
+                    },
+                    trustedSanitizers: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                    trustedAnnotations: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                    strictMode: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            additionalSensitiveFields: [],
+            trustedSanitizers: [],
+            trustedAnnotations: [],
+            strictMode: false,
+        },
+    ],
+    create(context) {
+        const options = context.options[0] ?? {};
+        const additionalFields = options.additionalSensitiveFields ?? [];
+        const allSensitiveFields = new Set([...utils_1.SENSITIVE_PAYLOAD_FIELDS, ...additionalFields]);
+        return {
+            CallExpression(node) {
+                if (!(0, utils_1.isSignOperation)(node)) {
+                    return;
+                }
+                if (node.arguments.length < 1) {
+                    return;
+                }
+                const payloadArg = node.arguments[0];
+                // Check object literal payload
+                if (payloadArg.type === 'ObjectExpression') {
+                    for (const prop of payloadArg.properties) {
+                        if (prop.type === 'Property' && prop.key.type === 'Identifier') {
+                            const fieldName = prop.key.name.toLowerCase();
+                            if (allSensitiveFields.has(fieldName)) {
+                                context.report({
+                                    node: prop,
+                                    messageId: 'sensitivePayloadField',
+                                    data: { fieldName: prop.key.name },
+                                });
+                            }
+                        }
+                    }
+                }
+            },
+        };
+    },
+});
+exports.default = exports.noSensitivePayload;

package/dist/src/rules/no-timestamp-manipulation/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: 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 } from '@interlace/eslint-devkit';
+import type { JwtRuleOptions } from '../../types';
+type MessageIds = 'timestampDisabled' | 'noTimestampTrue';
+type RuleOptions = [JwtRuleOptions?];
+export declare const noTimestampManipulation: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default noTimestampManipulation;

package/dist/src/rules/no-timestamp-manipulation/index.js

@@ -0,0 +1,97 @@
+"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.noTimestampManipulation = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.noTimestampManipulation = (0, eslint_devkit_1.createRule)({
+    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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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) {
+        return {
+            CallExpression(node) {
+                if (!(0, utils_1.isSignOperation)(node)) {
+                    return;
+                }
+                const optionsArg = (0, utils_1.getOptionsArgument)(node, 2);
+                if (!optionsArg) {
+                    return;
+                }
+                // Check for noTimestamp: true
+                if ((0, utils_1.hasOption)(optionsArg, 'noTimestamp')) {
+                    const value = (0, utils_1.getOptionValue)(optionsArg, 'noTimestamp');
+                    if (value?.type === 'Literal' && value.value === true) {
+                        context.report({
+                            node: value,
+                            messageId: 'noTimestampTrue',
+                        });
+                    }
+                }
+            },
+        };
+    },
+});
+exports.default = exports.noTimestampManipulation;

package/dist/src/rules/no-weak-secret/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: 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 } from '@interlace/eslint-devkit';
+import type { NoWeakSecretOptions } from '../../types';
+type MessageIds = 'weakSecret' | 'shortSecret' | 'useStrongSecret';
+type RuleOptions = [NoWeakSecretOptions?];
+export declare const noWeakSecret: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default noWeakSecret;