eslint-plugin-jwt-security 2.3.0

package/AGENTS.md

@@ -0,0 +1,102 @@
+# AGENTS.md
+
+> Context for AI coding agents working on eslint-plugin-jwt-security
+
+## Setup Commands
+
+```bash
+# Install dependencies (from monorepo root)
+npm install
+
+# Build this package
+nx build eslint-plugin-jwt-security
+
+# Run tests
+nx test eslint-plugin-jwt-security
+
+# Run tests with coverage
+nx test eslint-plugin-jwt-security --coverage
+
+# Lint this package
+nx lint eslint-plugin-jwt-security
+```
+
+## Code Style
+
+- TypeScript strict mode with `@interlace/eslint-devkit` types
+- Use `AST_NODE_TYPES` constants, never string literals for node types
+- Use `formatLLMMessage()` for all rule error messages
+- Include CWE, CVSS, OWASP in every security message
+- Use `c8 ignore` comments with documented reasons for untestable code
+- Single-pass AST traversal patterns (O(n) complexity)
+
+## Testing Instructions
+
+- Tests use `@typescript-eslint/rule-tester` with Vitest
+- Each rule has `index.ts` (implementation) and `*.test.ts` (tests) in same directory
+- Run specific rule test: `nx test eslint-plugin-jwt-security --testPathPattern="no-algorithm-none"`
+- Coverage target: ≥90% lines, ≥95% functions
+- All tests must pass before committing
+
+## Project Structure
+
+```
+src/
+├── index.ts          # Plugin entry, exports rules and configs
+└── rules/            # 13 rule directories
+    └── [rule-name]/
+        ├── index.ts       # Rule implementation
+        └── *.test.ts      # Rule tests
+docs/rules/           # Markdown documentation per rule
+```
+
+## Plugin Purpose
+
+Comprehensive JWT security ESLint plugin with **13 rules** covering algorithm attacks, replay prevention, and claim validation. Targets 6 major Node.js JWT libraries.
+
+## Rule Categories
+
+| Category               | Rules                                                                                                                                            | CWEs               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
+| Algorithm Attacks      | `no-algorithm-none`, `no-algorithm-confusion`                                                                                                    | 347                |
+| Verification & Secrets | `require-algorithm-whitelist`, `no-decode-without-verify`, `no-weak-secret`, `no-hardcoded-secret`, `no-timestamp-manipulation`                  | 326, 345, 757, 798 |
+| Claims                 | `require-expiration`, `require-issued-at`, `require-issuer-validation`, `require-audience-validation`, `require-max-age`, `no-sensitive-payload` | 287, 294, 359, 613 |
+
+## Library Detection
+
+The plugin detects these method calls:
+
+- **Sign**: `jwt.sign()`, `signJWT()`, `SignJWT()`
+- **Verify**: `jwt.verify()`, `jwtVerify()`, `verifyJWT()`
+- **Decode**: `jwt.decode()`, `jwtDecode()`, `decodeJWT()`
+
+## Common Fix Patterns
+
+```typescript
+// Algorithm None Attack (CVE-2022-23540)
+// BAD: jwt.verify(token, secret, { algorithms: ['none'] })
+// GOOD: jwt.verify(token, secret, { algorithms: ['RS256'] })
+
+// Algorithm Confusion
+// BAD: jwt.verify(token, publicKey, { algorithms: ['HS256'] })
+// GOOD: jwt.verify(token, publicKey, { algorithms: ['RS256'] })
+
+// Hardcoded Secret
+// BAD: jwt.sign(payload, 'my-secret-key')
+// GOOD: jwt.sign(payload, process.env.JWT_SECRET)
+
+// Missing Expiration
+// BAD: jwt.sign({ sub: 'user' }, secret)
+// GOOD: jwt.sign({ sub: 'user' }, secret, { expiresIn: '1h' })
+
+// Replay Attack Prevention
+// BAD: jwt.sign(payload, secret, { noTimestamp: true })
+// GOOD: jwt.sign(payload, secret)
+// GOOD: jwt.verify(token, secret, { maxAge: '1h' })
+```
+
+## Security Considerations
+
+- CWE coverage: 287, 294, 326, 345, 347, 359, 613, 757, 798
+- Detects CVE-2022-23540 (Algorithm None attack)
+- Covers 6 major JWT libraries: jsonwebtoken, jose, jwt-decode, node-jose, jwt-simple, jsonwebtoken-esm

package/CHANGELOG.md

@@ -0,0 +1,161 @@
+## [2.2.3] - 2026-02-08
+
+## 2.2.9
+
+### Patch Changes
+
+- [#294](https://github.com/ofri-peretz/eslint/pull/294) [`659f6dc`](https://github.com/ofri-peretz/eslint/commit/659f6dc0181b03b675f72b5949fcf123dd066358) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Rewrite `description` and `keywords` on every published package for npm search discovery. npm ranks on name, description, and keywords, and the registry only picks up these fields at publish — so this is metadata-only and takes effect for each package on its next release.
+
+  **Descriptions now lead with the search phrase.** Every one starts `ESLint plugin for <the thing you'd search>` instead of a brand-first or category-first framing, and names the concrete vulnerabilities the plugin actually detects. Three were corrected while doing so:
+
+  - `eslint-plugin-import-next` claimed "100x faster no-cycle detection". No 100x measurement exists: `CLAIMS.md` records **3.1x end-to-end** (8x in pure rule execution) on a 5,483-file React codebase, and the highest number in any benchmark result is 54.9x on the synthetic corpus. The description now states the real-codebase figure.
+  - `eslint-plugin-secure-coding` claimed SQL injection, XSS and CSRF coverage — none of which are its rules. It now names what it does detect: LDAP, XPath, XXE, GraphQL and template injection, unsafe deserialization, ReDoS, missing authentication, and PII in logs.
+  - `eslint-plugin-secure-coding` ("89 rules") and `eslint-plugin-react-a11y` ("37 rules") hard-coded rule counts that had drifted from reality. Counts are generated into `interlace-numbers.json`; hand-typed copies are removed rather than corrected.
+
+  **Keywords now match the vocabulary of the plugins that rank.** `eslint-plugin-security`, `eslint-plugin-jsx-a11y`, `eslint-plugin-n` and `eslint-plugin-import` all carry the `eslint` / `eslintplugin` / `eslint-plugin` trio — six of our packages were missing `eslintplugin`, and every one now carries all three plus `static-analysis`, `linting` and `code-quality`. Security plugins add `sast`, `appsec` and `vulnerability`; `node-security` and `secure-coding` also carry `nodesecurity`, the exact keyword `eslint-plugin-security` ranks on. Each plugin gained the CWE identifiers and attack names for what it detects (`cwe-78` command injection, `cwe-22` path traversal, `cwe-89` SQL injection, `cwe-79` XSS, `cwe-347` JWT algorithm confusion, `cwe-352` CSRF, `cwe-943` NoSQL injection), and `node-security` gained the crypto vocabulary it had been missing entirely despite absorbing the crypto rule set (`crypto`, `cryptography`, `weak-hash`, `md5`, `sha1`, `timing-attack`).
+
+  No rule behavior, exports, or configuration changes.
+
+- Updated dependencies [[`e1cdf83`](https://github.com/ofri-peretz/eslint/commit/e1cdf83e3db761907f0ab06f7fc6c1f1da7513a5), [`659f6dc`](https://github.com/ofri-peretz/eslint/commit/659f6dc0181b03b675f72b5949fcf123dd066358)]:
+  - @interlace/eslint-devkit@1.4.3
+
+## 2.2.8
+
+### Patch Changes
+
+- [#269](https://github.com/ofri-peretz/eslint/pull/269) [`7028fe2`](https://github.com/ofri-peretz/eslint/commit/7028fe2668a42266d831014184dcef70e73101ad) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - docs: dual-logo README header (Interlace mark + ESLint mark side by side) and closing Interlace footer — refreshes the README rendered on npmjs.com. No runtime changes.
+
+- Updated dependencies [[`7028fe2`](https://github.com/ofri-peretz/eslint/commit/7028fe2668a42266d831014184dcef70e73101ad)]:
+  - @interlace/eslint-devkit@1.4.2
+
+## 2.2.7
+
+### Patch Changes
+
+- [#252](https://github.com/ofri-peretz/eslint/pull/252) [`d67e395`](https://github.com/ofri-peretz/eslint/commit/d67e3953c2748ad36e6aebe0f24b1d04e518b4d0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Fix Codecov badge showing "unknown" — switch from flag to component URL format
+
+## 2.2.6
+
+### Patch Changes
+
+- [#225](https://github.com/ofri-peretz/eslint/pull/225) [`34ff5a8`](https://github.com/ofri-peretz/eslint/commit/34ff5a8e6f5126c5d1c0a524759e0af2b5476b46) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - CI-only: pin all coverage thresholds at 100% (integration target, merges last).
+
+## 2.2.5
+
+### Patch Changes
+
+- [#213](https://github.com/ofri-peretz/eslint/pull/213) [`391dbe6`](https://github.com/ofri-peretz/eslint/commit/391dbe6b39f78d549379218567cb959649f8c614) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Align every security rule's `meta.docs.cvss` to the CVSS its finding actually
+  emits. The emitted machine-readable message sources its `CVSS:x` from
+  `CWE_MAPPING` via `formatLLMMessage` → `enrichFromCWE`, but the static
+  `meta.docs.cvss` documentation field had drifted on 45 rules across these 7
+  plugins — e.g. `no-hardcoded-credentials` documented `9.5` while emitting
+  `CVSS:9.8` (the value the published article and SARIF/LLM consumers already
+  read).
+
+  This corrects the **documentation metadata only** — no emitted finding changes.
+  Locked by `security-cvss-docs-consistency.lock.test.ts` (cross-plugin: every
+  security rule's `meta.docs.cvss` must equal the CVSS it emits), the
+  `no-hardcoded-credentials` rule lock (real ESLint `Linter` emission), and a
+  devkit `enrichFromCWE` contract test pinning `CWE-798 → 9.8`.
+
+  Follow-up (not in scope): 50 security rules document a CVSS that never appears
+  in any emitted message (their messages carry no CWE), and several rules emit the
+  generic CWE score where a rule-specific score may be warranted — both change
+  emitted output and are separate decisions.
+
+## 2.2.4
+
+### Patch Changes
+
+- [#143](https://github.com/ofri-peretz/eslint/pull/143) [`213cde1`](https://github.com/ofri-peretz/eslint/commit/213cde190ff2aea49ca7c1b533170940f879d9b4) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - fix(no-missing-null-checks): eliminate 53 false positives via three new narrowing patterns
+
+  Rules that were recognized as null guards are now correctly identified as safe:
+  1. **Truthy if guard** — `if (obj) { obj.prop }` — direct truthy check proves non-null. Also covers chains: `if (response)` protects `response.data.items`.
+  2. **Short-circuit AND** — `obj && obj.prop` — right side of `&&` only runs when left is truthy.
+  3. **Ternary consequent** — `obj ? obj.prop : fallback` — truthy test guards the consequent.
+
+  Also: bumped `beforeAll` timeout to 30 seconds in 7 compatibility test files (`__compatibility__/*.spec.ts`). Native-addon packages routinely exceed the previous 10-second default on a cold ESM load.
+
+- Updated dependencies [[`736a5fe`](https://github.com/ofri-peretz/eslint/commit/736a5fed47e673f6157ea900b29fe2a54e4bc7df)]:
+  - @interlace/eslint-devkit@1.4.1
+
+### Bug Fixes
+
+- align codecov component IDs with full package names ([2831b968](https://github.com/ofri-peretz/eslint/commit/2831b968))
+
+### Documentation
+
+- fix changelog header format across all packages ([c3a15082](https://github.com/ofri-peretz/eslint/commit/c3a15082))
+
+### ❤️ Thank You
+
+- Ofri Peretz
+
+## [2.2.2] - 2026-02-06
+
+### Bug Fixes
+
+- align codecov component names and update docs components ([0a59a86c](https://github.com/ofri-peretz/eslint/commit/0a59a86c))
+
+### ❤️ Thank You
+
+- Ofri Peretz
+
+## [2.2.1] - 2026-02-02
+
+This was a version bump only for eslint-plugin-jwt-security to align it with other projects, there were no code changes.
+
+# Changelog
+
+All notable changes to eslint-plugin-jwt-security will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-29
+
+### Added
+
+#### Core Security Rules (7)
+
+- `no-algorithm-none` - Prevent `alg:"none"` attack (CVE-2022-23540, CWE-347)
+- `no-algorithm-confusion` - Prevent RS256→HS256 key confusion (CWE-347)
+- `require-algorithm-whitelist` - Require explicit algorithm specification (CWE-757)
+- `no-decode-without-verify` - Prevent trusting decoded payloads (CWE-345)
+- `no-weak-secret` - Require 256-bit minimum secrets (CWE-326)
+- `no-hardcoded-secret` - Prevent secrets in source code (CWE-798)
+- `require-expiration` - Require `exp` claim or `expiresIn` (CWE-613)
+
+#### 2025 Research Rules (6)
+
+Based on LightSEC 2025 "Back to the Future" attack research:
+
+- `require-issued-at` - Require `iat` claim for freshness (CWE-294)
+- `require-issuer-validation` - Require issuer validation (CWE-287)
+- `require-audience-validation` - Require audience validation (CWE-287)
+- `no-timestamp-manipulation` - Prevent `noTimestamp: true` (CWE-294)
+- `require-max-age` - Require maxAge for replay prevention (CWE-294)
+- `no-sensitive-payload` - Prevent PII in token payload (CWE-359)
+
+#### Configuration Presets
+
+- `recommended` - Balanced security (critical=error, high=warn)
+- `strict` - Maximum security with all 13 rules enabled
+- `legacy` - Migration mode with only critical rules
+
+#### Library Support
+
+- jsonwebtoken
+- jose
+- express-jwt
+- @nestjs/jwt
+- jwks-rsa
+- jwt-decode
+
+### Features
+
+- AI-optimized error messages using `formatLLMMessage`
+- CWE references for all rules (9 CWEs covered)
+- OWASP Top 10 2021 coverage matrix (6 categories)
+- Full TypeScript support
+- Comprehensive test coverage (248 edge case tests)

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Ofri Peretz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/README.md

@@ -0,0 +1,158 @@
+<p align="center">
+  <a href="https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security" target="blank"><img src="https://eslint.interlace.tools/icon-light.svg" alt="Interlace" height="90" /></a>
+  &nbsp;&nbsp;
+  <a href="https://eslint.org" target="_blank"><img src="https://eslint.interlace.tools/eslint-logo.svg" alt="ESLint" height="90" /></a>
+  &nbsp;&nbsp;
+  <a href="https://oxc.rs" target="_blank"><img src="https://eslint.interlace.tools/oxlint-logo.svg" alt="oxlint" height="90" /></a>
+  &nbsp;&nbsp;
+  <a href="https://www.npmjs.com/package/jsonwebtoken" target="_blank"><img src="https://eslint.interlace.tools/jwt-logo.svg" alt="JSON Web Tokens" height="90" /></a>
+</p>
+
+<p align="center">
+  Security validation for JSON Web Tokens (JWT) implementation (signing, verification).
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/eslint-plugin-jwt-security" target="_blank"><img src="https://img.shields.io/npm/v/eslint-plugin-jwt-security.svg" alt="NPM Version" /></a>
+  <a href="https://www.npmjs.com/package/eslint-plugin-jwt-security" target="_blank"><img src="https://img.shields.io/npm/dm/eslint-plugin-jwt-security.svg" alt="NPM Downloads" /></a>
+  <a href="https://opensource.org/licenses/MIT" target="_blank"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="Package License" /></a>
+  <a href="https://app.codecov.io/gh/ofri-peretz/eslint/components?components%5B0%5D=eslint-plugin-jwt-security" target="_blank"><img src="https://codecov.io/gh/ofri-peretz/eslint/graph/badge.svg?component=eslint-plugin-jwt-security" alt="Codecov" /></a>
+  <a href="https://github.com/ofri-peretz/eslint" target="_blank"><img src="https://img.shields.io/badge/Since-Dec_2025-blue?logo=rocket&logoColor=white" alt="Since Dec 2025" /></a>
+</p>
+
+> ⭐ If this plugin caught a real bug for you, [**star the repo**](https://github.com/ofri-peretz/eslint) — it's the signal that keeps these rules maintained.
+
+## Description
+
+This plugin provides Security validation for JSON Web Tokens (JWT) implementation (signing, verification).
+
+## Philosophy
+
+**Interlace** fosters **strength through integration**. Instead of stacking isolated rules, we **interlace** security directly into your workflow to create a resilient fabric of code. We believe tools should **guide rather than gatekeep**, providing educational feedback that strengthens the developer with every interaction.
+
+## Getting Started
+
+- To check out the [guide](https://eslint.interlace.tools/docs/security/plugin-jwt?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security), visit [eslint.interlace.tools](https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security). 📚
+- 要查看中文 [指南](https://eslint.interlace.tools/docs/security/plugin-jwt?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security), 请访问 [eslint.interlace.tools](https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security). 📚
+- [가이드](https://eslint.interlace.tools/docs/security/plugin-jwt?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) 문서는 [eslint.interlace.tools](https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security)에서 확인하실 수 있습니다. 📚
+- [ガイド](https://eslint.interlace.tools/docs/security/plugin-jwt?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security)は [eslint.interlace.tools](https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security)でご確認ください。 📚
+- Para ver la [guía](https://eslint.interlace.tools/docs/security/plugin-jwt?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security), visita [eslint.interlace.tools](https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security). 📚
+- للاطلاع على [الدليل](https://eslint.interlace.tools/docs/security/plugin-jwt?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security)، قم بزيارة [eslint.interlace.tools](https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security). 📚
+
+```bash
+npm install eslint-plugin-jwt-security --save-dev
+```
+
+## ⚙️ Configuration Presets
+| Preset        | Description                                               |
+| :------------ | :-------------------------------------------------------- |
+| `recommended` | Recommended preset - balanced security                    |
+| `strict`      | Strict preset - maximum security (includes 2025 research) |
+| `legacy`      | Legacy preset - migration mode                            |
+| `all`         | All rules preset                                          |
+
+## 📚 Supported Libraries
+| Library        | npm                                                                                                                   | Downloads                                                                                                                    | Detection                       |
+| :------------- | :-------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |
+| `jsonwebtoken` | [![npm](https://img.shields.io/npm/v/jsonwebtoken.svg?style=flat-square)](https://www.npmjs.com/package/jsonwebtoken) | [![downloads](https://img.shields.io/npm/dt/jsonwebtoken.svg?style=flat-square)](https://www.npmjs.com/package/jsonwebtoken) | Signing, Verification, Decoding |
+| `jose`         | [![npm](https://img.shields.io/npm/v/jose.svg?style=flat-square)](https://www.npmjs.com/package/jose)                 | [![downloads](https://img.shields.io/npm/dt/jose.svg?style=flat-square)](https://www.npmjs.com/package/jose)                 | Verification (Fix Suggestion)   |
+| `jwt-decode`   | [![npm](https://img.shields.io/npm/v/jwt-decode.svg?style=flat-square)](https://www.npmjs.com/package/jwt-decode)     | [![downloads](https://img.shields.io/npm/dt/jwt-decode.svg?style=flat-square)](https://www.npmjs.com/package/jwt-decode)     | Unsafe Decoding                 |
+
+## 🤖 AI-Optimized Messages
+Every rule uses `formatLLMMessage` for structured output:
+
+```
+🔒 CWE-347 OWASP:A02-Crypto CVSS:9.8 | Using alg:"none" bypasses signature verification
+   Fix: Remove "none" and use RS256, ES256, or other secure algorithms
+   https://nvd.nist.gov/vuln/detail/CVE-2022-23540
+```
+
+By providing this structured context (CWE, OWASP, Fix), we enable AI tools to **reason** about the security flaw rather than hallucinating. This allows Copilot/Cursor to suggest the _exact_ correct fix immediately.
+
+By structuring errors with specific CWE codes, OWASP categories, and direct fix suggestions, this format allows AI coding assistants to autonomously identify, explain, and resolve security vulnerabilities with high confidence.
+
+## 💡 What You Get
+- **13 Security Rules** - Algorithm attacks, replay prevention, claim validation
+- **6 JWT Libraries** - jsonwebtoken, jose, express-jwt, @nestjs/jwt, jwks-rsa, jwt-decode
+- **2025 Research** - "Back to the Future" replay attack prevention (LightSEC 2025)
+- **AI-Optimized** - Structured messages for GitHub Copilot, Cursor, Claude assistance
+- **CWE References** - Every rule maps to Common Weakness Enumeration
+
+## 📦 Compatibility
+| Package | Version |
+| :--- | :--- |
+| ESLint | `^8.0.0 \|\| ^9.0.0 \|\| ^10.0.0` |
+| Node.js | `>=18.0.0` |
+
+See the [ESLint Version Support Policy](../../docs/ESLINT_VERSION_SUPPORT.md) — current ecosystem share data, the 20% gate, and the forward-looking exception that covers v10.
+
+## Rules
+
+**Legend**
+
+| Icon | Description |
+| :---: | :--- |
+| 💼 | **Recommended**: Included in the recommended preset. |
+| ⚠️ | **Warns**: Set to warn in recommended preset. |
+| 🔧 | **Auto-fixable**: Automatically fixable by the `--fix` CLI option. |
+| 💡 | **Suggestions**: Providing code suggestions in IDE. |
+| 🚫 | **Deprecated**: This rule is deprecated. |
+| 🟢 | **Type-unaware**: AST-only, runs in oxlint JS-plugin tier. |
+| 🟡 | **Type-aware (refining)**: pure-AST primary path; types refine precision. |
+| 🟠 | **Type-aware (graceful)**: requires TS program; silent without it. |
+
+<!-- AUTO-GENERATED:RULES_TABLE:START - Do not edit manually -->
+| Rule | CWE | OWASP | CVSS | Description | 🧠 | 💼 | ⚠️ | 🔧 | 💡 | 🚫 |
+| :--- | :---: | :---: | :---: | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
+| [no-algorithm-confusion](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/no-algorithm-confusion?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-347 |  |  | This rule detects algorithm confusion attacks where symmetric algorithms (HS256, HS384, HS512) are used wit… | 🟢 |  |  |  |  |  |
+| [no-algorithm-none](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/no-algorithm-none?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-347 |  |  | This rule detects attempts to use the none algorithm which completely bypasses JWT signature verification | 🟢 |  |  |  |  |  |
+| [no-decode-without-verify](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/no-decode-without-verify?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-345 |  |  | The rule provides LLM-optimized error messages (Compact 2-line format) with actionable security guidance: | 🟢 |  |  |  |  |  |
+| [no-hardcoded-secret](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/no-hardcoded-secret?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-798 |  |  | The rule provides LLM-optimized error messages (Compact 2-line format) with actionable security guidance: | 🟢 |  |  |  |  |  |
+| [no-sensitive-payload](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/no-sensitive-payload?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-359 |  |  | JWT payloads are NOT encrypted, only base64-encoded | 🟢 |  |  |  |  |  |
+| [no-timestamp-manipulation](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/no-timestamp-manipulation?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-294 |  |  | This rule detects noTimestamp: true which disables automatic iat (issued at) claim generation | 🟢 |  |  |  |  |  |
+| [no-weak-secret](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/no-weak-secret?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-326 |  |  | The rule provides LLM-optimized error messages (Compact 2-line format) with actionable security guidance: | 🟢 |  |  |  |  |  |
+| [require-algorithm-whitelist](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/require-algorithm-whitelist?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-757 |  |  | This rule enforces explicit algorithm specification in verify() calls | 🟢 |  |  |  |  |  |
+| [require-audience-validation](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/require-audience-validation?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-287 |  |  | The rule provides LLM-optimized error messages (Compact 2-line format) with actionable security guidance: | 🟢 |  |  |  |  |  |
+| [require-expiration](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/require-expiration?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-613 |  |  | The rule provides LLM-optimized error messages (Compact 2-line format) with actionable security guidance: | 🟢 |  |  |  |  |  |
+| [require-issued-at](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/require-issued-at?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-294 |  |  | This rule ensures tokens have the iat claim for freshness validation | 🟢 |  |  |  |  |  |
+| [require-issuer-validation](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/require-issuer-validation?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-287 |  |  | The rule provides LLM-optimized error messages (Compact 2-line format) with actionable security guidance: | 🟢 |  |  |  |  |  |
+| [require-max-age](https://eslint.interlace.tools/docs/security/plugin-jwt/rules/require-max-age?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security) | CWE-294 |  |  | This rule mandates maxAge in verify operations | 🟢 |  |  |  |  |  |
+<!-- AUTO-GENERATED:RULES_TABLE:END -->
+## 🔗 Related ESLint Plugins
+
+Part of the **Interlace ESLint Ecosystem** — AI-native security plugins with LLM-optimized error messages:
+
+| Plugin | Downloads | Description |
+| :--- | :---: | :--- |
+| [`eslint-plugin-secure-coding`](https://www.npmjs.com/package/eslint-plugin-secure-coding) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-secure-coding.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-secure-coding) | General security rules & OWASP guidelines. |
+| [`eslint-plugin-pg`](https://www.npmjs.com/package/eslint-plugin-pg) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-pg.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-pg) | PostgreSQL security & best practices. |
+| [`eslint-plugin-node-security`](https://www.npmjs.com/package/eslint-plugin-node-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-node-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-node-security) | Node.js core-module security (fs, child_process, vm, crypto, Buffer). |
+| [`eslint-plugin-jwt-security`](https://www.npmjs.com/package/eslint-plugin-jwt-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-jwt-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-jwt-security) | JWT security & best practices. |
+| [`eslint-plugin-browser-security`](https://www.npmjs.com/package/eslint-plugin-browser-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-browser-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-browser-security) | Browser-specific security & XSS prevention. |
+| [`eslint-plugin-express-security`](https://www.npmjs.com/package/eslint-plugin-express-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-express-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-express-security) | Express.js security hardening rules. |
+| [`eslint-plugin-lambda-security`](https://www.npmjs.com/package/eslint-plugin-lambda-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-lambda-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-lambda-security) | AWS Lambda security best practices. |
+| [`eslint-plugin-nestjs-security`](https://www.npmjs.com/package/eslint-plugin-nestjs-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-nestjs-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-nestjs-security) | NestJS security rules & patterns. |
+| [`eslint-plugin-mongodb-security`](https://www.npmjs.com/package/eslint-plugin-mongodb-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-mongodb-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-mongodb-security) | MongoDB security best practices. |
+| [`eslint-plugin-vercel-ai-security`](https://www.npmjs.com/package/eslint-plugin-vercel-ai-security) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-vercel-ai-security.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-vercel-ai-security) | Vercel AI SDK security hardening. |
+| [`eslint-plugin-import-next`](https://www.npmjs.com/package/eslint-plugin-import-next) | [![downloads](https://img.shields.io/npm/dt/eslint-plugin-import-next.svg?style=flat-square)](https://www.npmjs.com/package/eslint-plugin-import-next) | Next-gen import sorting & architecture. |
+
+<!-- INTERLACE:STAR_CTA:START -->
+## ⭐ Support & follow
+
+If this plugin caught a real bug for you, **[star the repo](https://github.com/ofri-peretz/eslint)** — stars are the signal that keeps the Interlace ESLint ecosystem maintained — and **[follow the writeups on Dev.to](https://dev.to/ofri-peretz)** for the benchmarks and security research behind these rules.
+
+[![GitHub stars](https://img.shields.io/github/stars/ofri-peretz/eslint?style=social)](https://github.com/ofri-peretz/eslint)
+
+<!-- INTERLACE:STAR_CTA:END -->
+
+## 📄 License
+
+MIT © [Ofri Peretz](https://github.com/ofri-peretz)
+
+<p align="center">
+  <a href="https://eslint.interlace.tools/docs/security/plugin-jwt?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security"><img src="https://eslint.interlace.tools/images/og-jwt.png" alt="ESLint Interlace Plugin" width="100%" /></a>
+</p>
+
+<p align="center">
+  <a href="https://eslint.interlace.tools/?utm_source=github&utm_medium=referral&utm_campaign=eslint-plugin-jwt-security" target="blank"><img src="https://eslint.interlace.tools/icon-light.svg" alt="Interlace" height="70" /></a>
+</p>

package/dist/AGENTS.md

@@ -0,0 +1,102 @@
+# AGENTS.md
+
+> Context for AI coding agents working on eslint-plugin-jwt-security
+
+## Setup Commands
+
+```bash
+# Install dependencies (from monorepo root)
+npm install
+
+# Build this package
+nx build eslint-plugin-jwt-security
+
+# Run tests
+nx test eslint-plugin-jwt-security
+
+# Run tests with coverage
+nx test eslint-plugin-jwt-security --coverage
+
+# Lint this package
+nx lint eslint-plugin-jwt-security
+```
+
+## Code Style
+
+- TypeScript strict mode with `@interlace/eslint-devkit` types
+- Use `AST_NODE_TYPES` constants, never string literals for node types
+- Use `formatLLMMessage()` for all rule error messages
+- Include CWE, CVSS, OWASP in every security message
+- Use `c8 ignore` comments with documented reasons for untestable code
+- Single-pass AST traversal patterns (O(n) complexity)
+
+## Testing Instructions
+
+- Tests use `@typescript-eslint/rule-tester` with Vitest
+- Each rule has `index.ts` (implementation) and `*.test.ts` (tests) in same directory
+- Run specific rule test: `nx test eslint-plugin-jwt-security --testPathPattern="no-algorithm-none"`
+- Coverage target: ≥90% lines, ≥95% functions
+- All tests must pass before committing
+
+## Project Structure
+
+```
+src/
+├── index.ts          # Plugin entry, exports rules and configs
+└── rules/            # 13 rule directories
+    └── [rule-name]/
+        ├── index.ts       # Rule implementation
+        └── *.test.ts      # Rule tests
+docs/rules/           # Markdown documentation per rule
+```
+
+## Plugin Purpose
+
+Comprehensive JWT security ESLint plugin with **13 rules** covering algorithm attacks, replay prevention, and claim validation. Targets 6 major Node.js JWT libraries.
+
+## Rule Categories
+
+| Category               | Rules                                                                                                                                            | CWEs               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
+| Algorithm Attacks      | `no-algorithm-none`, `no-algorithm-confusion`                                                                                                    | 347                |
+| Verification & Secrets | `require-algorithm-whitelist`, `no-decode-without-verify`, `no-weak-secret`, `no-hardcoded-secret`, `no-timestamp-manipulation`                  | 326, 345, 757, 798 |
+| Claims                 | `require-expiration`, `require-issued-at`, `require-issuer-validation`, `require-audience-validation`, `require-max-age`, `no-sensitive-payload` | 287, 294, 359, 613 |
+
+## Library Detection
+
+The plugin detects these method calls:
+
+- **Sign**: `jwt.sign()`, `signJWT()`, `SignJWT()`
+- **Verify**: `jwt.verify()`, `jwtVerify()`, `verifyJWT()`
+- **Decode**: `jwt.decode()`, `jwtDecode()`, `decodeJWT()`
+
+## Common Fix Patterns
+
+```typescript
+// Algorithm None Attack (CVE-2022-23540)
+// BAD: jwt.verify(token, secret, { algorithms: ['none'] })
+// GOOD: jwt.verify(token, secret, { algorithms: ['RS256'] })
+
+// Algorithm Confusion
+// BAD: jwt.verify(token, publicKey, { algorithms: ['HS256'] })
+// GOOD: jwt.verify(token, publicKey, { algorithms: ['RS256'] })
+
+// Hardcoded Secret
+// BAD: jwt.sign(payload, 'my-secret-key')
+// GOOD: jwt.sign(payload, process.env.JWT_SECRET)
+
+// Missing Expiration
+// BAD: jwt.sign({ sub: 'user' }, secret)
+// GOOD: jwt.sign({ sub: 'user' }, secret, { expiresIn: '1h' })
+
+// Replay Attack Prevention
+// BAD: jwt.sign(payload, secret, { noTimestamp: true })
+// GOOD: jwt.sign(payload, secret)
+// GOOD: jwt.verify(token, secret, { maxAge: '1h' })
+```
+
+## Security Considerations
+
+- CWE coverage: 287, 294, 326, 345, 347, 359, 613, 757, 798
+- Detects CVE-2022-23540 (Algorithm None attack)
+- Covers 6 major JWT libraries: jsonwebtoken, jose, jwt-decode, node-jose, jwt-simple, jsonwebtoken-esm