eslint-plugin-webhook-safety 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.2.0 (2026-10-22)
+
+- `require-idempotency` is now conservative: it reports only **direct** writes in the handler (DB, queue, email,
+  payment calls) with no `event.id` use, and points at that write. Helper calls that receive event-derived data
+  are treated as possibly idempotent (false positive found on twentyhq/twenty). New `strict` option restores
+  the broader check. The message now reads as a suggestion and links the docs.
+- `require-signature-verification` no longer reports handlers that pass the request to a helper (verification in another file).
+- `require-raw-body` ignores `express.json({ verify })` and handlers that verify something other than `req.body` (e.g. `req.rawBody`).
+- README: correct example output and a TypeScript setup section.
+- Release smoke test now covers ESLint 8.57 (flat and legacy), 9, 10 and `@typescript-eslint/parser`. CI adds Windows.
+
+## 0.1.0 (2026-10-22)
+
+- Rules: `require-raw-body`, `require-signature-verification`, `require-idempotency`, `bullmq-require-job-id`.
+- Configs: `recommended`, `strict`, `legacy-recommended`, `legacy-strict`.
+- Tested on 8 open-source apps (Stripe/BullMQ users). False positives fixed before release:
+  - `require-signature-verification` ignores authenticated endpoints (e.g. CRUD APIs that manage webhook subscriptions).
+  - `require-idempotency` ignores verify-and-return wrappers that return the event to the caller.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krrish Kumar
+
+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

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# eslint-plugin-webhook-safety
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/Krrishkumar125/eslint-plugin-webhook-safety/actions/workflows/ci.yml/badge.svg)](https://github.com/Krrishkumar125/eslint-plugin-webhook-safety/actions/workflows/ci.yml)
+
+ESLint rules that catch the Stripe webhook bugs that only show up in production:
+
+- the body was parsed before the signature check, so every event fails;
+- the signature is never checked;
+- duplicate deliveries are processed twice;
+- retries enqueue the same BullMQ job twice.
+
+The static half of [webhook-crash-lab](https://github.com/Krrishkumar125/webhook-crash-lab).
+This plugin finds the bug in your editor, and crash-lab proves the fix against a running server.
+
+## 60-second start
+
+```sh
+npm i -D eslint eslint-plugin-webhook-safety
+```
+
+```js
+// eslint.config.js
+import webhookSafety from 'eslint-plugin-webhook-safety';
+
+export default [
+  webhookSafety.configs.recommended, // or .strict
+];
+```
+
+```js
+// server.js
+app.use(express.json());
+app.post('/webhooks/stripe', async (req, res) => {
+  const event = stripe.webhooks.constructEvent(req.body, sig, secret);
+  await emailQueue.add('receipt', { to: event.data.object.customer_email });
+});
+```
+
+```text
+$ npx eslint server.js
+  2:1  error    `app.use(express.json())` on line 1 runs before this webhook route and parses the body ...  webhook-safety/require-raw-body
+  4:9  warning  Consider a duplicate-event check: Stripe can deliver `event` more than once ...                 webhook-safety/require-idempotency
+  4:9  warning  Webhook deliveries are retried, so this queue.add() will enqueue the same work twice ...      webhook-safety/bullmq-require-job-id
+```
+
+## Rules
+
+| Rule                                                                           | What it catches                                                            | recommended | strict | 💡  |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------- | ------ | --- |
+| [require-raw-body](docs/rules/require-raw-body.md)                             | `express.json()` / `req.json()` / `JSON.stringify` before `constructEvent` | error       | error  | ✅  |
+| [require-signature-verification](docs/rules/require-signature-verification.md) | webhook route or Next.js `POST` with no signature check                    | error       | error  |     |
+| [require-idempotency](docs/rules/require-idempotency.md)                       | DB/queue/email/payment write in the handler with no `event.id` dedupe      | warn        | error  |     |
+| [bullmq-require-job-id](docs/rules/bullmq-require-job-id.md)                   | `queue.add()` in a webhook handler without `jobId`                         | warn        | error  | ✅  |
+
+The rules are tuned for **low false positives**. When in doubt (custom middleware, the event passed to a
+helper, options passed as a variable) they stay quiet. Each rule doc lists exactly what triggers it.
+
+Supports Express, Hono, Fastify-style routers and the Next.js App Router, in JavaScript and TypeScript.
+
+### TypeScript
+
+ESLint only lints `.ts` files that some config object matches, so pair the plugin with
+`typescript-eslint` (or at least its parser):
+
+```js
+// eslint.config.js
+import tseslint from 'typescript-eslint';
+import webhookSafety from 'eslint-plugin-webhook-safety';
+
+export default [...tseslint.configs.recommended, webhookSafety.configs.recommended];
+```
+
+### Legacy `.eslintrc` (ESLint 8)
+
+```json
+{ "extends": ["plugin:webhook-safety/legacy-recommended"] }
+```
+
+## Requirements
+
+ESLint 8.57+, 9 or 10 (flat config, or `.eslintrc` via the legacy configs) and Node ≥ 20. Every release is
+smoke-tested from the packed tarball against ESLint 8.57 (flat and legacy), 9, 10 and `@typescript-eslint/parser`.
+
+## License
+
+MIT © Krrish Kumar