eslint-plugin-jwt-security 2.3.0

package/dist/src/rules/require-issued-at/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.requireIssuedAt = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.requireIssuedAt = (0, eslint_devkit_1.createRule)({
+    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: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.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) {
+        /**
+         * Check if payload contains iat claim
+         */
+        // oxlint-disable-next-line consistent-function-scoping
+        const payloadHasIat = (payloadNode) => {
+            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) {
+                // 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 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 && (0, utils_1.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
+            },
+        };
+    },
+});
+exports.default = exports.requireIssuedAt;

package/dist/src/rules/require-issuer-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-issuer-validation
+ *
+ * Mandates issuer (iss) claim validation in JWT verify operations.
+ * Without issuer validation, tokens from any issuer are accepted.
+ *
+ * CWE-287: Improper Authentication
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+import type { RequireIssuerValidationOptions } from '../../types';
+type RuleOptions = [RequireIssuerValidationOptions?];
+export declare const requireIssuerValidation: TSESLint.RuleModule<"missingIssuerValidation", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default requireIssuerValidation;

package/dist/src/rules/require-issuer-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.requireIssuerValidation = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.requireIssuerValidation = (0, eslint_devkit_1.createRule)({
+    name: 'require-issuer-validation',
+    meta: {
+        type: 'problem',
+        docs: {
+            url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/require-issuer-validation.md',
+            description: 'Require issuer (iss) claim validation in JWT verify operations',
+            cwe: 'CWE-287',
+            cvss: 9.8,
+        },
+        fixable: undefined,
+        hasSuggestions: false,
+        messages: {
+            missingIssuerValidation: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.SECURITY,
+                issueName: 'Missing Issuer Validation',
+                cwe: 'CWE-287',
+                description: 'JWT verification without issuer validation accepts tokens from any source',
+                severity: 'MEDIUM',
+                fix: 'Add issuer option: { issuer: "https://auth.example.com" }',
+                documentationLink: 'https://tools.ietf.org/html/rfc8725',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    knownIssuers: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                        description: 'Known valid issuers to suggest',
+                    },
+                    trustedSanitizers: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                    trustedAnnotations: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                    strictMode: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            knownIssuers: [],
+            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: 'missingIssuerValidation',
+                    });
+                    return;
+                }
+                // Check for issuer option
+                if (!(0, utils_1.hasOption)(optionsArg, 'issuer') && !(0, utils_1.hasOption)(optionsArg, 'iss')) {
+                    context.report({
+                        node: optionsArg,
+                        messageId: 'missingIssuerValidation',
+                    });
+                }
+            },
+        };
+    },
+});
+exports.default = exports.requireIssuerValidation;

package/dist/src/rules/require-max-age/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-max-age
+ *
+ * Mandates maxAge option in JWT verify operations to enforce token freshness.
+ * This prevents the "Back to the Future" replay attack where tokens are
+ * captured and replayed months or years later.
+ *
+ * CWE-294: Authentication Bypass by Capture-replay
+ *
+ * @see https://securitypattern.com/post/jwt-back-to-the-future
+ * @see LightSEC 2025 - "JWT Back to the future: On the (ab)use of JWTs"
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+import type { JwtRuleOptions } from '../../types';
+type RuleOptions = [JwtRuleOptions?];
+export declare const requireMaxAge: TSESLint.RuleModule<"missingMaxAge", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export default requireMaxAge;

package/dist/src/rules/require-max-age/index.js

@@ -0,0 +1,93 @@
+"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.requireMaxAge = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const utils_1 = require("../../utils");
+exports.requireMaxAge = (0, eslint_devkit_1.createRule)({
+    name: 'require-max-age',
+    meta: {
+        type: 'problem',
+        docs: {
+            url: 'https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-plugin-jwt-security/docs/rules/require-max-age.md',
+            description: 'Require maxAge option in verify operations to enforce token freshness',
+            cwe: 'CWE-294',
+            cvss: 5,
+        },
+        fixable: undefined,
+        hasSuggestions: false,
+        messages: {
+            missingMaxAge: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.SECURITY,
+                issueName: 'Missing Token Age Validation',
+                cwe: 'CWE-294',
+                description: 'Without maxAge, tokens can be replayed long after issuance (Back to the Future attack)',
+                severity: 'MEDIUM',
+                fix: 'Add maxAge option: { maxAge: "1h" } to limit token lifetime',
+                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.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: 'missingMaxAge',
+                    });
+                    return;
+                }
+                // Check for maxAge option
+                if (!(0, utils_1.hasOption)(optionsArg, 'maxAge') && !(0, utils_1.hasOption)(optionsArg, 'clockTolerance')) {
+                    context.report({
+                        node: optionsArg,
+                        messageId: 'missingMaxAge',
+                    });
+                }
+            },
+        };
+    },
+});
+exports.default = exports.requireMaxAge;

package/dist/src/types/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * eslint-plugin-jwt-security Type Exports
+ *
+ * Barrel file that exports all JWT security rule Options types.
+ */
+import type { SecurityRuleOptions } from '@interlace/eslint-devkit';
+export interface JwtRuleOptions extends SecurityRuleOptions {
+    /** JWT libraries to consider for detection. Default: all supported libraries */
+    targetLibraries?: Array<'jsonwebtoken' | 'jose' | 'express-jwt' | '@nestjs/jwt' | 'jwks-rsa' | 'jwt-decode'>;
+}
+export interface NoAlgorithmNoneOptions extends JwtRuleOptions {
+    /** Allow 'none' algorithm in test files. Default: false */
+    allowInTests?: boolean;
+}
+export interface NoAlgorithmConfusionOptions extends JwtRuleOptions {
+    /** Symmetric algorithms that should not be used with public keys */
+    symmetricAlgorithms?: string[];
+}
+export interface RequireAlgorithmWhitelistOptions extends JwtRuleOptions {
+    /** Recommended algorithms to suggest. Default: ['RS256', 'ES256'] */
+    recommendedAlgorithms?: string[];
+}
+export interface NoDecodeWithoutVerifyOptions extends JwtRuleOptions {
+    /** Allow decode() for header inspection before verify. Default: false */
+    allowHeaderInspection?: boolean;
+}
+export interface NoWeakSecretOptions extends JwtRuleOptions {
+    /** Minimum secret length in characters. Default: 32 (256 bits) */
+    minSecretLength?: number;
+}
+export interface RequireExpirationOptions extends JwtRuleOptions {
+    /** Maximum allowed expiration time in seconds. Default: 86400 (24 hours) */
+    maxExpirationSeconds?: number;
+}
+export interface RequireIssuerValidationOptions extends JwtRuleOptions {
+    /** Known valid issuers to suggest. Default: [] */
+    knownIssuers?: string[];
+}
+export interface RequireAudienceValidationOptions extends JwtRuleOptions {
+    /** Known valid audiences to suggest. Default: [] */
+    knownAudiences?: string[];
+}
+export interface NoSensitivePayloadOptions extends JwtRuleOptions {
+    /** Additional field names to flag as sensitive. Default: [] */
+    additionalSensitiveFields?: string[];
+}
+export interface NoHardcodedSecretOptions extends JwtRuleOptions {
+    /** Patterns that indicate environment variable usage (safe). Default: process.env */
+    envPatterns?: string[];
+}
+export interface RequireJwksValidationOptions extends JwtRuleOptions {
+    /** Require cache configuration. Default: true */
+    requireCache?: boolean;
+    /** Require rate limiting. Default: true */
+    requireRateLimit?: boolean;
+}
+export interface NoInsecureKidOptions extends JwtRuleOptions {
+    /** Allow custom KID validation functions. Default: [] */
+    trustedKidValidators?: string[];
+}
+/**
+ * Combined type for all JWT rule options
+ */
+export type AllJwtRulesOptions = {
+    'no-algorithm-none'?: NoAlgorithmNoneOptions;
+    'no-algorithm-confusion'?: NoAlgorithmConfusionOptions;
+    'require-algorithm-whitelist'?: RequireAlgorithmWhitelistOptions;
+    'no-decode-without-verify'?: NoDecodeWithoutVerifyOptions;
+    'no-weak-secret'?: NoWeakSecretOptions;
+    'require-expiration'?: RequireExpirationOptions;
+    'require-issuer-validation'?: RequireIssuerValidationOptions;
+    'require-audience-validation'?: RequireAudienceValidationOptions;
+    'no-sensitive-payload'?: NoSensitivePayloadOptions;
+    'no-hardcoded-secret'?: NoHardcodedSecretOptions;
+    'require-jwks-validation'?: RequireJwksValidationOptions;
+    'no-insecure-kid'?: NoInsecureKidOptions;
+};

package/dist/src/types/index.js

@@ -0,0 +1,7 @@
+"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 });

package/dist/src/utils/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * Shared utilities for JWT security rules
+ *
+ * Library detection, pattern matching, and common helpers.
+ */
+import type { TSESTree } from '@interlace/eslint-devkit';
+/**
+ * Supported JWT libraries
+ */
+export declare const JWT_LIBRARIES: {
+    readonly JSONWEBTOKEN: "jsonwebtoken";
+    readonly JOSE: "jose";
+    readonly EXPRESS_JWT: "express-jwt";
+    readonly NESTJS_JWT: "@nestjs/jwt";
+    readonly JWKS_RSA: "jwks-rsa";
+    readonly JWT_DECODE: "jwt-decode";
+};
+export type JwtLibrary = (typeof JWT_LIBRARIES)[keyof typeof JWT_LIBRARIES];
+/**
+ * Insecure algorithms that should be flagged
+ */
+export declare const INSECURE_ALGORITHMS: Set<string>;
+/**
+ * Algorithms vulnerable to confusion attacks when used with asymmetric keys
+ */
+export declare const SYMMETRIC_ALGORITHMS: Set<string>;
+/**
+ * Recommended secure algorithms
+ */
+export declare const SECURE_ALGORITHMS: Set<string>;
+/**
+ * Sensitive field names that should not be in JWT payload
+ * All lowercase for case-insensitive matching
+ */
+export declare const SENSITIVE_PAYLOAD_FIELDS: Set<string>;
+/**
+ * JWT method patterns for different operations
+ */
+export declare const JWT_METHODS: {
+    readonly SIGN: Set<string>;
+    readonly VERIFY: Set<string>;
+    readonly DECODE: Set<string>;
+};
+/**
+ * Check if a node represents a call to a JWT library method
+ */
+export declare function isJwtLibraryCall(node: TSESTree.CallExpression, targetMethods: Set<string>): boolean;
+/**
+ * Check if a node is a string literal with a specific value
+ */
+export declare function isStringLiteral(node: TSESTree.Node, value?: string): node is TSESTree.Literal;
+/**
+ * Extract algorithm from options object
+ */
+export declare function extractAlgorithms(optionsNode: TSESTree.ObjectExpression): string[];
+/**
+ * Check if options object has a specific property set
+ */
+export declare function hasOption(optionsNode: TSESTree.ObjectExpression, optionName: string): boolean;
+/**
+ * Get the value of a specific option from options object
+ */
+export declare function getOptionValue(optionsNode: TSESTree.ObjectExpression, optionName: string): TSESTree.Node | undefined;
+/**
+ * Check if a literal appears to be a weak secret (short string)
+ */
+export declare function isWeakSecret(node: TSESTree.Node, minLength?: number): boolean;
+/**
+ * Check if a node is an environment variable access (safe pattern)
+ */
+export declare function isEnvVariable(node: TSESTree.Node): boolean;
+/**
+ * Check if this call looks like a JWT sign operation
+ */
+export declare function isSignOperation(node: TSESTree.CallExpression): boolean;
+/**
+ * Check if this call looks like a JWT verify operation
+ */
+export declare function isVerifyOperation(node: TSESTree.CallExpression): boolean;
+/**
+ * Check if this call looks like a JWT decode operation (no verification)
+ */
+export declare function isDecodeOperation(node: TSESTree.CallExpression): boolean;
+/**
+ * Get the options argument from a JWT call
+ * For jwt.verify(token, secret, options) -> returns options
+ * For jwt.sign(payload, secret, options) -> returns options
+ */
+export declare function getOptionsArgument(node: TSESTree.CallExpression, optionsIndex?: number): TSESTree.ObjectExpression | undefined;
+/**
+ * Check if file is a test file
+ */
+export declare function isTestFile(filename: string): boolean;