eslint-plugin-jwt-security 2.3.0 → 2.3.1

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

@@ -1,98 +0,0 @@
-/**
- * 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;

package/src/__compatibility__/jwt-interface.spec.ts

@@ -1,192 +0,0 @@
-/**
- * JWT Ecosystem Interface Compatibility Tests
- *
- * Verifies that JWT-related packages export the interfaces our ESLint rules depend on.
- *
- * @sdk jsonwebtoken, jose, express-jwt, jwks-rsa, jwt-decode
- * @last-updated 2026-01-02
- */
-
-import { describe, it, expect, beforeAll } from 'vitest';
-
-// Use unknown types to avoid ESM/CJS type conflicts at compile time
-// Runtime checks handle the actual exports
-let jsonwebtokenModule: unknown;
-let joseModule: unknown;
-let jwtDecodeModule: unknown;
-
-// Helper to safely access properties on unknown types
-const getProp = (obj: unknown, key: string): unknown => {
-  if (obj && typeof obj === 'object' && key in obj) {
-    return (obj as Record<string, unknown>)[key];
-  }
-  return undefined;
-};
-
-beforeAll(async () => {
-  try {
-    jsonwebtokenModule = await import('jsonwebtoken');
-  } catch {
-    console.warn('jsonwebtoken not installed');
-  }
-  try {
-    joseModule = await import('jose');
-  } catch {
-    console.warn('jose not installed');
-  }
-  try {
-    jwtDecodeModule = await import('jwt-decode');
-  } catch {
-    console.warn('jwt-decode not installed');
-  }
-}, 30_000); // native-addon packages can take >10s to load cold
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// JSONWEBTOKEN INTERFACE
-// Primary package for JWT operations in Node.js
-// ═══════════════════════════════════════════════════════════════════════════════
-
-describe('jsonwebtoken Interface Compatibility', () => {
-  describe('Core Exports', () => {
-    it('exports sign function', () => {
-      const sign = getProp(jsonwebtokenModule, 'sign');
-      expect(sign).toBeDefined();
-      expect(typeof sign).toBe('function');
-    });
-
-    it('exports verify function', () => {
-      const verify = getProp(jsonwebtokenModule, 'verify');
-      expect(verify).toBeDefined();
-      expect(typeof verify).toBe('function');
-    });
-
-    it('exports decode function', () => {
-      const decode = getProp(jsonwebtokenModule, 'decode');
-      expect(decode).toBeDefined();
-      expect(typeof decode).toBe('function');
-    });
-  });
-
-  describe('Sign Options (Critical for Security Rules)', () => {
-    it('sign accepts algorithm option', () => {
-      // Rules check: no-algorithm-none, require-algorithm-whitelist
-      expect(getProp(jsonwebtokenModule, 'sign')).toBeDefined();
-    });
-
-    it('sign accepts expiresIn option', () => {
-      // Rules check: require-expiration
-      expect(getProp(jsonwebtokenModule, 'sign')).toBeDefined();
-    });
-
-    it('sign accepts audience option', () => {
-      // Rules check: require-audience
-      expect(getProp(jsonwebtokenModule, 'sign')).toBeDefined();
-    });
-
-    it('sign accepts issuer option', () => {
-      // Rules check: require-issuer
-      expect(getProp(jsonwebtokenModule, 'sign')).toBeDefined();
-    });
-  });
-
-  describe('Verify Options (Critical for Security Rules)', () => {
-    it('verify accepts algorithms option (array)', () => {
-      // Rules check: verify-algorithm-explicit
-      expect(getProp(jsonwebtokenModule, 'verify')).toBeDefined();
-    });
-
-    it('verify accepts complete option', () => {
-      // Returns full decoded token with header
-      expect(getProp(jsonwebtokenModule, 'verify')).toBeDefined();
-    });
-  });
-});
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// JOSE INTERFACE
-// Modern JWT library with async/await support
-// ═══════════════════════════════════════════════════════════════════════════════
-
-describe('jose Interface Compatibility', () => {
-  describe('Core Exports', () => {
-    it('exports SignJWT class', () => {
-      expect(getProp(joseModule, 'SignJWT')).toBeDefined();
-    });
-
-    it('exports jwtVerify function', () => {
-      const jwtVerify = getProp(joseModule, 'jwtVerify');
-      expect(jwtVerify).toBeDefined();
-      expect(typeof jwtVerify).toBe('function');
-    });
-
-    it('exports jwtDecrypt function', () => {
-      const jwtDecrypt = getProp(joseModule, 'jwtDecrypt');
-      expect(jwtDecrypt).toBeDefined();
-      expect(typeof jwtDecrypt).toBe('function');
-    });
-
-    it('exports createRemoteJWKSet function', () => {
-      // Used for JWKS validation
-      const createRemoteJWKSet = getProp(joseModule, 'createRemoteJWKSet');
-      expect(createRemoteJWKSet).toBeDefined();
-      expect(typeof createRemoteJWKSet).toBe('function');
-    });
-  });
-
-  describe('Key Generation', () => {
-    it('exports generateKeyPair function', () => {
-      expect(getProp(joseModule, 'generateKeyPair')).toBeDefined();
-    });
-
-    it('exports generateSecret function', () => {
-      expect(getProp(joseModule, 'generateSecret')).toBeDefined();
-    });
-  });
-});
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// JWT-DECODE INTERFACE
-// Client-side JWT decoding (no verification)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-describe('jwt-decode Interface Compatibility', () => {
-  describe('Core Exports', () => {
-    it('exports jwtDecode function', () => {
-      // Can be either named export or default export depending on version
-      const jwtDecode = getProp(jwtDecodeModule, 'jwtDecode') ?? getProp(jwtDecodeModule, 'default');
-      expect(jwtDecode).toBeDefined();
-    });
-
-    it('exports InvalidTokenError', () => {
-      expect(getProp(jwtDecodeModule, 'InvalidTokenError')).toBeDefined();
-    });
-  });
-});
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// PACKAGE METADATA
-// ═══════════════════════════════════════════════════════════════════════════════
-
-describe('Package Metadata', () => {
-  it('jsonwebtoken has discoverable version', async () => {
-    try {
-      const pkgPath = require.resolve('jsonwebtoken/package.json');
-      const pkg = await import(pkgPath, { with: { type: 'json' } }).then(m => m.default);
-      expect(pkg.version).toBeDefined();
-      console.log(`📦 jsonwebtoken version: ${pkg.version}`);
-    } catch {
-      console.log('📦 jsonwebtoken not installed');
-    }
-  });
-
-  it('jose has discoverable version', async () => {
-    try {
-      const pkgPath = require.resolve('jose/package.json');
-      const pkg = await import(pkgPath, { with: { type: 'json' } }).then(m => m.default);
-      expect(pkg.version).toBeDefined();
-      console.log(`📦 jose version: ${pkg.version}`);
-    } catch {
-      console.log('📦 jose not installed');
-    }
-  });
-});

package/src/index.test.ts

@@ -1,47 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import plugin from './index';
-import { rules, configs } from './index';
-
-describe('eslint-plugin-jwt-security plugin interface', () => {
-  it('should export correct meta information', () => {
-    expect(plugin.meta).toBeDefined();
-    expect(plugin.meta?.name).toBe('eslint-plugin-jwt-security');
-    expect(plugin.meta?.version).toBeDefined();
-  });
-
-  it('should export all JWT security rules', () => {
-    expect(plugin.rules).toBeDefined();
-    const ruleNames = Object.keys(plugin.rules || {});
-    expect(ruleNames).toContain('no-algorithm-none');
-    expect(ruleNames).toContain('no-algorithm-confusion');
-    expect(ruleNames).toContain('no-timestamp-manipulation');
-    expect(ruleNames.length).toBe(13);
-  });
-
-  describe('configurations', () => {
-    it('should provide recommended configuration', () => {
-      expect(configs.recommended).toBeDefined();
-      expect(configs.recommended.plugins?.jwt).toBeDefined();
-      
-      const recommendedRules = configs.recommended.rules || {};
-      Object.keys(recommendedRules).forEach(ruleName => {
-        expect(ruleName).toMatch(/^jwt\//);
-      });
-      
-      expect(recommendedRules['jwt/no-algorithm-none']).toBe('error');
-    });
-
-    it('should provide strict configuration', () => {
-      expect(configs.strict).toBeDefined();
-      expect(configs.strict.plugins?.jwt).toBeDefined();
-      
-      const strictRules = configs.strict.rules || {};
-      Object.keys(strictRules).forEach(ruleName => {
-        expect(ruleName).toMatch(/^jwt\//);
-      });
-      
-      expect(strictRules['jwt/no-algorithm-none']).toBe('error');
-      expect(Object.keys(strictRules).length).toBe(Object.keys(rules).length);
-    });
-  });
-});

package/src/index.ts

@@ -1,209 +0,0 @@
-/**
- * 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
- *
- * Comprehensive JWT security ESLint plugin for Node.js applications.
- * Detects vulnerabilities across jsonwebtoken, jose, express-jwt,
- * @nestjs/jwt, jwks-rsa, and jwt-decode libraries.
- *
- * Features:
- * - Algorithm confusion attack detection (CVE-2022-23540)
- * - "Back to the Future" replay attack prevention (LightSEC 2025)
- * - Signature verification enforcement
- * - Weak secret detection
- * - Expiration and claim validation
- * - AI-assisted fix guidance with CWE references
- *
- * @see https://tools.ietf.org/html/rfc8725
- * @see https://securitypattern.com/post/jwt-back-to-the-future
- */
-import type { TSESLint } from '@interlace/eslint-devkit';
-
-// Import rules - Core Security
-import { noAlgorithmNone } from './rules/no-algorithm-none';
-import { noAlgorithmConfusion } from './rules/no-algorithm-confusion';
-import { requireAlgorithmWhitelist } from './rules/require-algorithm-whitelist';
-import { noDecodeWithoutVerify } from './rules/no-decode-without-verify';
-import { noWeakSecret } from './rules/no-weak-secret';
-import { requireExpiration } from './rules/require-expiration';
-import { noHardcodedSecret } from './rules/no-hardcoded-secret';
-
-// Import rules - 2025 Vulnerability Research
-import { requireIssuedAt } from './rules/require-issued-at';
-import { requireIssuerValidation } from './rules/require-issuer-validation';
-import { requireAudienceValidation } from './rules/require-audience-validation';
-import { noTimestampManipulation } from './rules/no-timestamp-manipulation';
-import { requireMaxAge } from './rules/require-max-age';
-import { noSensitivePayload } from './rules/no-sensitive-payload';
-
-/**
- * Collection of all JWT security ESLint rules (13 rules)
- */
-export const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
-  // Core Security Rules
-  'no-algorithm-none': noAlgorithmNone,
-  'no-algorithm-confusion': noAlgorithmConfusion,
-  'require-algorithm-whitelist': requireAlgorithmWhitelist,
-  'no-decode-without-verify': noDecodeWithoutVerify,
-  'no-weak-secret': noWeakSecret,
-  'require-expiration': requireExpiration,
-  'no-hardcoded-secret': noHardcodedSecret,
-
-  // 2025 Vulnerability Research - "Back to the Future" & Replay Prevention
-  'require-issued-at': requireIssuedAt,
-  'require-issuer-validation': requireIssuerValidation,
-  'require-audience-validation': requireAudienceValidation,
-  'no-timestamp-manipulation': noTimestampManipulation,
-  'require-max-age': requireMaxAge,
-  'no-sensitive-payload': noSensitivePayload,
-} satisfies Record<string, TSESLint.RuleModule<string, readonly unknown[]>>;
-
-/**
- * ESLint Plugin object
- */
-export const plugin: TSESLint.FlatConfig.Plugin = {
-  meta: {
-    name: 'eslint-plugin-jwt-security',
-    version: '2.2.9',
-  },
-  rules,
-} satisfies TSESLint.FlatConfig.Plugin;
-
-/**
- * Recommended configuration - baseline security
- * Critical rules as errors, high as warnings
- */
-const recommendedRules: Record<string, TSESLint.FlatConfig.RuleEntry> = {
-  // CRITICAL - Algorithm attacks
-  'jwt/no-algorithm-none': 'error',
-  'jwt/no-algorithm-confusion': 'error',
-
-  // HIGH - Verification and secrets
-  'jwt/require-algorithm-whitelist': 'error',
-  'jwt/no-decode-without-verify': 'error',
-  'jwt/no-weak-secret': 'error',
-  'jwt/no-hardcoded-secret': 'error',
-  'jwt/no-timestamp-manipulation': 'error', // LightSEC 2025
-
-  // MEDIUM - Best practices
-  'jwt/require-expiration': 'error',
-  'jwt/no-sensitive-payload': 'warn',
-};
-
-/**
- * Strict configuration - maximum security (2025 research)
- * All rules as errors - includes replay attack prevention
- */
-const strictRules: Record<string, TSESLint.FlatConfig.RuleEntry> = {
-  // All core rules as errors
-  'jwt/no-algorithm-none': 'error',
-  'jwt/no-algorithm-confusion': 'error',
-  'jwt/require-algorithm-whitelist': 'error',
-  'jwt/no-decode-without-verify': 'error',
-  'jwt/no-weak-secret': 'error',
-  'jwt/no-hardcoded-secret': 'error',
-  'jwt/require-expiration': 'error',
-
-  // 2025 Research - Full replay attack prevention
-  'jwt/require-issued-at': 'error',
-  'jwt/require-issuer-validation': 'error',
-  'jwt/require-audience-validation': 'error',
-  'jwt/no-timestamp-manipulation': 'error',
-  'jwt/require-max-age': 'error',
-  'jwt/no-sensitive-payload': 'error',
-};
-
-/**
- * Legacy configuration - migration mode
- * Only critical rules enabled
- */
-const legacyRules: Record<string, TSESLint.FlatConfig.RuleEntry> = {
-  // Only most critical rules
-  'jwt/no-algorithm-none': 'error',
-  'jwt/no-algorithm-confusion': 'error',
-  'jwt/no-hardcoded-secret': 'warn',
-};
-
-/**
- * Configuration presets for flat config
- */
-export const configs = {
-  /**
-   * Flagship preset — the rule from this plugin in the ecosystem-wide
-   * flagship list (`.agent/flagship-rules.md`). Use this when you want
-   * the highest-signal JWT subset shippable in CI gates.
-   */
-  flagship: {
-    plugins: {
-      jwt: plugin,
-    },
-    rules: {
-      'jwt/no-algorithm-none': 'error',
-    },
-  } satisfies TSESLint.FlatConfig.Config,
-
-  /**
-   * Recommended preset - balanced security
-   */
-  recommended: {
-    plugins: {
-      jwt: plugin,
-    },
-    rules: recommendedRules,
-  } satisfies TSESLint.FlatConfig.Config,
-
-  /**
-   * Strict preset - maximum security (includes 2025 research)
-   */
-  strict: {
-    plugins: {
-      jwt: plugin,
-    },
-    rules: strictRules,
-  } satisfies TSESLint.FlatConfig.Config,
-
-  /**
-   * Legacy preset - migration mode
-   */
-  legacy: {
-    plugins: {
-      jwt: plugin,
-    },
-    rules: legacyRules,
-  } satisfies TSESLint.FlatConfig.Config,
-
-  /**
-   * All rules preset
-   */
-  all: {
-    plugins: {
-      jwt: plugin,
-    },
-    rules: strictRules,
-  } satisfies TSESLint.FlatConfig.Config,
-};
-
-// Default export for flat config usage
-export default plugin;
-
-// Named exports for flexibility
-export {
-  noAlgorithmNone,
-  noAlgorithmConfusion,
-  requireAlgorithmWhitelist,
-  noDecodeWithoutVerify,
-  noWeakSecret,
-  requireExpiration,
-  noHardcodedSecret,
-  requireIssuedAt,
-  requireIssuerValidation,
-  requireAudienceValidation,
-  noTimestampManipulation,
-  requireMaxAge,
-  noSensitivePayload,
-};

package/src/oxlint.test.ts

@@ -1,61 +0,0 @@
-/**
- * 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.
- */
-
-import { describe, it, expect } from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { plugin as mainPlugin } from './index';
-
-/**
- * Smoke test for the `./oxlint` sub-export.
- *
- * Runtime shape: `oxlint.ts` uses `export = plugin`, which compiles to
- * `module.exports = plugin`. From an ESM dynamic `import('./oxlint')` view,
- * Node's CJS interop surfaces that value at `.default`. From oxlint's
- * `require('eslint-plugin-jwt-security/oxlint')` view, it sits at the top of
- * `module.exports` — exactly the `{ meta, rules }` shape oxlint's JS plugin
- * loader expects.
- */
-
-type Plugin = typeof mainPlugin;
-
-describe('eslint-plugin-jwt-security/oxlint sub-export', () => {
-  it('declares the ./oxlint sub-export in package.json', () => {
-    const pkgJson = JSON.parse(
-      fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'),
-    );
-    expect(pkgJson.exports['./oxlint']).toEqual({
-      types: './src/oxlint.d.ts',
-      default: './src/oxlint.js',
-    });
-  });
-
-  it('re-exports the plugin object (meta + rules at top level)', async () => {
-    const oxlintModule = await import('./oxlint.js');
-    const oxlintPlugin = (oxlintModule as unknown as { default: Plugin }).default;
-    expect(oxlintPlugin).toBeDefined();
-    expect(oxlintPlugin.meta?.name).toBe('eslint-plugin-jwt-security');
-    expect(oxlintPlugin.rules).toBeDefined();
-  });
-
-  it('exposes the same rule names as the main entry (no rules dropped)', async () => {
-    const oxlintModule = await import('./oxlint.js');
-    const oxlintPlugin = (oxlintModule as unknown as { default: Plugin }).default;
-    expect(Object.keys(oxlintPlugin.rules || {}).toSorted()).toEqual(
-      Object.keys(mainPlugin.rules || {}).toSorted(),
-    );
-  });
-
-  it('exposes the same rule references (pass-through, not a copy)', async () => {
-    const oxlintModule = await import('./oxlint.js');
-    const oxlintPlugin = (oxlintModule as unknown as { default: Plugin }).default;
-    for (const ruleName of Object.keys(mainPlugin.rules || {})) {
-      expect(oxlintPlugin.rules?.[ruleName]).toBe(
-        (mainPlugin.rules as Record<string, unknown>)[ruleName],
-      );
-    }
-  });
-});

package/src/oxlint.ts

@@ -1,23 +0,0 @@
-/**
- * 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.
- */
-
-/**
- * oxlint sub-export.
- *
- * Consumers wire oxlint to this entry via:
- *   { "jsPlugins": ["eslint-plugin-jwt-security/oxlint"] }
- *
- * oxlint's JS plugin loader does `require('eslint-plugin-jwt-security/oxlint')` and reads
- * `.rules` off the result. The compiled output of `export = plugin` is
- * `module.exports = plugin`, which gives oxlint the plugin object directly
- * (`{ meta, rules }`) — no wrapper, no `.default` indirection.
- *
- * Generated by scripts/generate-oxlint-shims.mjs. Do not edit by hand.
- */
-
-import { plugin } from './index';
-
-export = plugin;