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

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+import { Rule, Linter } from 'eslint';
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: Record<string, Rule.RuleModule>;
+    configs: {
+        recommended: Linter.Config & {
+            rules: Linter.RulesRecord;
+        };
+        strict: Linter.Config & {
+            rules: Linter.RulesRecord;
+        };
+        "legacy-recommended": {
+            plugins: string[];
+            rules: Linter.RulesRecord;
+        };
+        "legacy-strict": {
+            plugins: string[];
+            rules: Linter.RulesRecord;
+        };
+    };
+};
+
+export = plugin;

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { Rule, Linter } from 'eslint';
+
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: Record<string, Rule.RuleModule>;
+    configs: {
+        recommended: Linter.Config & {
+            rules: Linter.RulesRecord;
+        };
+        strict: Linter.Config & {
+            rules: Linter.RulesRecord;
+        };
+        "legacy-recommended": {
+            plugins: string[];
+            rules: Linter.RulesRecord;
+        };
+        "legacy-strict": {
+            plugins: string[];
+            rules: Linter.RulesRecord;
+        };
+    };
+};
+
+export { plugin as default };

package/dist/index.js

@@ -0,0 +1,572 @@
+// src/utils.ts
+var REPO = "https://github.com/Krrishkumar125/eslint-plugin-webhook-safety";
+var docsUrl = (name) => `${REPO}/blob/main/docs/rules/${name}.md`;
+var WEBHOOK_PATH = /webhook|\/hooks?(?:\/|$)/i;
+var CONSTRUCT_EVENT = /* @__PURE__ */ new Set(["constructEvent", "constructEventAsync"]);
+var ROUTE_METHODS = /* @__PURE__ */ new Set(["post", "put", "all"]);
+function isFunction(node) {
+  return !!node && (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression");
+}
+function walk(root, visit) {
+  const stack = [root];
+  while (stack.length) {
+    const node = stack.pop();
+    visit(node);
+    for (const key of Object.keys(node)) {
+      if (key === "parent") continue;
+      const value = node[key];
+      const children = Array.isArray(value) ? value : [value];
+      for (const child of children) {
+        if (child && typeof child === "object" && typeof child.type === "string") {
+          stack.push(child);
+        }
+      }
+    }
+  }
+}
+function calleeName(node) {
+  const callee = node.callee;
+  if (callee.type === "Identifier") return callee.name;
+  if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier") {
+    return callee.property.name;
+  }
+  return void 0;
+}
+function memberCall(node) {
+  if (node.type !== "CallExpression") return void 0;
+  const callee = node.callee;
+  if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.property.type === "Identifier") {
+    return [callee.object.name, callee.property.name];
+  }
+  return void 0;
+}
+var PARSER_OWNERS = /* @__PURE__ */ new Set(["express", "bodyParser", "bodyparser"]);
+function isJsonParser(node) {
+  const m = memberCall(node);
+  return !!m && PARSER_OWNERS.has(m[0]) && m[1] === "json";
+}
+function isRawParser(node) {
+  const m = memberCall(node);
+  return !!m && PARSER_OWNERS.has(m[0]) && (m[1] === "raw" || m[1] === "text");
+}
+function isBodyParser(node) {
+  const m = memberCall(node);
+  return !!m && PARSER_OWNERS.has(m[0]) && ["json", "raw", "text", "urlencoded"].includes(m[1]);
+}
+function isConstructEvent(node) {
+  if (node.type !== "CallExpression") return false;
+  const name = calleeName(node);
+  return !!name && CONSTRUCT_EVENT.has(name);
+}
+function findAll(root, test) {
+  const out = [];
+  walk(root, (n) => {
+    if (test(n)) out.push(n);
+  });
+  return out;
+}
+function enclosingFunction(node) {
+  let cur = node.parent;
+  while (cur) {
+    if (isFunction(cur)) return cur;
+    cur = cur.parent;
+  }
+  return void 0;
+}
+function literalString(node) {
+  if (!node) return void 0;
+  if (node.type === "Literal" && typeof node.value === "string") return node.value;
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+    return node.quasis[0]?.value.cooked ?? void 0;
+  }
+  return void 0;
+}
+function asRoute(node) {
+  if (node.type !== "CallExpression") return void 0;
+  const callee = node.callee;
+  if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") {
+    return void 0;
+  }
+  if (!ROUTE_METHODS.has(callee.property.name)) return void 0;
+  const args = node.arguments;
+  const path = literalString(args[0]);
+  const handler = args[args.length - 1];
+  if (path === void 0 || args.length < 2 || !isFunction(handler)) return void 0;
+  return {
+    call: node,
+    owner: callee.object.type === "Identifier" ? callee.object.name : void 0,
+    path,
+    middlewares: args.slice(1, -1),
+    handler
+  };
+}
+function isNextPostHandler(fn) {
+  const parent = fn.parent;
+  if (fn.type === "FunctionDeclaration") {
+    return fn.id?.name === "POST" && parent?.type === "ExportNamedDeclaration";
+  }
+  if (parent?.type === "VariableDeclarator") {
+    return parent.id.type === "Identifier" && parent.id.name === "POST" && parent.parent?.parent?.type === "ExportNamedDeclaration";
+  }
+  return false;
+}
+function isWebhookFile(context) {
+  return WEBHOOK_PATH.test(context.filename.replace(/\\/g, "/"));
+}
+function eventBinding(call) {
+  let cur = call.parent;
+  if (cur?.type === "AwaitExpression") cur = cur.parent;
+  let target;
+  if (cur?.type === "VariableDeclarator") target = cur.id;
+  else if (cur?.type === "AssignmentExpression") target = cur.left;
+  if (!target) return void 0;
+  if (target.type === "Identifier") return { kind: "identifier", name: target.name };
+  if (target.type === "ObjectPattern") {
+    const hasId = target.properties.some(
+      (p) => p.type === "RestElement" || p.key.type === "Identifier" && p.key.name === "id" || p.key.type === "Literal" && p.key.value === "id"
+    );
+    return { kind: "pattern", hasId };
+  }
+  return void 0;
+}
+
+// src/rules/bullmq-require-job-id.ts
+var QUEUE_NAME = /queue$/i;
+var rule = {
+  meta: {
+    type: "problem",
+    hasSuggestions: true,
+    docs: {
+      description: "Require a jobId (or deduplication id) when a webhook handler adds a BullMQ job, so retried deliveries do not enqueue duplicates",
+      recommended: true,
+      url: docsUrl("bullmq-require-job-id")
+    },
+    schema: [],
+    messages: {
+      missing: "Webhook deliveries are retried, so this queue.add() will enqueue the same work twice. Pass a stable jobId such as the event id.",
+      addJobId: "Add { jobId: {{name}}.id }"
+    }
+  },
+  create(context) {
+    const webhookFile = isWebhookFile(context);
+    const queues = /* @__PURE__ */ new Set();
+    function isWebhookFunction(fn) {
+      const parent = fn.parent;
+      if (parent) {
+        const route = asRoute(parent);
+        if (route && route.handler === fn && WEBHOOK_PATH.test(route.path)) return true;
+      }
+      if (webhookFile && isNextPostHandler(fn)) return true;
+      return findAll(fn, isConstructEvent).some((c) => enclosingFunction(c) === fn);
+    }
+    function eventName(fn) {
+      for (const c of findAll(fn, isConstructEvent)) {
+        const b = eventBinding(c);
+        if (b?.kind === "identifier") return b.name;
+      }
+      return void 0;
+    }
+    function isQueue(obj) {
+      if (obj.type === "Identifier") return queues.has(obj.name) || QUEUE_NAME.test(obj.name);
+      return obj.type === "MemberExpression" && !obj.computed && obj.property.type === "Identifier" && QUEUE_NAME.test(obj.property.name);
+    }
+    return {
+      VariableDeclarator(node) {
+        if (node.id.type === "Identifier" && node.init?.type === "NewExpression" && node.init.callee.type === "Identifier" && node.init.callee.name === "Queue") {
+          queues.add(node.id.name);
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee;
+        if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier" || callee.property.name !== "add" || node.arguments.length < 2 || node.arguments.length > 3 || !isQueue(callee.object)) {
+          return;
+        }
+        const opts = node.arguments[2];
+        if (opts && opts.type !== "ObjectExpression") return;
+        if (opts?.type === "ObjectExpression" && opts.properties.some(
+          (p) => p.type === "SpreadElement" || p.key.type === "Identifier" && ["jobId", "deduplication"].includes(p.key.name)
+        )) {
+          return;
+        }
+        let fn = enclosingFunction(node);
+        let webhookFn;
+        while (fn) {
+          if (isWebhookFunction(fn)) {
+            webhookFn = fn;
+            break;
+          }
+          fn = enclosingFunction(fn);
+        }
+        if (!webhookFn) return;
+        const name = eventName(webhookFn);
+        const suggest = [];
+        if (name) {
+          const prop = `jobId: ${name}.id`;
+          suggest.push({
+            messageId: "addJobId",
+            data: { name },
+            fix: (fixer) => {
+              if (!opts)
+                return fixer.insertTextAfter(node.arguments[1], `, { ${prop} }`);
+              const obj = opts;
+              const last = obj.properties[obj.properties.length - 1];
+              return last ? fixer.insertTextAfter(last, `, ${prop}`) : fixer.replaceText(obj, `{ ${prop} }`);
+            }
+          });
+        }
+        context.report({ node, messageId: "missing", suggest });
+      }
+    };
+  }
+};
+var bullmq_require_job_id_default = rule;
+
+// src/rules/require-idempotency.ts
+var DEFAULT_HELPERS = /idempot|dedup|processed|alreadyHandled|seenEvent/i;
+var SIDE_EFFECT_METHODS = /* @__PURE__ */ new Set([
+  "create",
+  "createMany",
+  "insert",
+  "insertOne",
+  "insertMany",
+  "update",
+  "updateOne",
+  "updateMany",
+  "upsert",
+  "delete",
+  "deleteMany",
+  "increment",
+  "decrement",
+  "save",
+  "add",
+  "addBulk",
+  "enqueue",
+  "publish",
+  "send",
+  "sendMail",
+  "sendEmail",
+  "charge",
+  "capture",
+  "refund",
+  "transfer"
+]);
+var NON_EFFECT_OBJECTS = /* @__PURE__ */ new Set([
+  "console",
+  "Response",
+  "NextResponse",
+  "JSON",
+  "res",
+  "Math",
+  "Object",
+  "Array"
+]);
+function rootObject(node) {
+  let cur = node;
+  while (cur.type === "MemberExpression" || cur.type === "CallExpression") {
+    cur = cur.type === "MemberExpression" ? cur.object : cur.callee;
+  }
+  return cur;
+}
+var rule2 = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Suggest a duplicate-event check (using event.id) before a webhook handler performs side effects directly",
+      recommended: true,
+      url: docsUrl("require-idempotency")
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          idempotencyFunctions: { type: "array", items: { type: "string" } },
+          strict: { type: "boolean" }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      missing: "Consider a duplicate-event check: Stripe can deliver `{{name}}` more than once, and this write runs without any use of `{{name}}.id`. Record processed event ids (unique insert) before side effects, or ignore if this write is idempotent. See {{url}}"
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const helpers = new Set(options.idempotencyFunctions ?? []);
+    const url = docsUrl("require-idempotency");
+    function isSideEffect(call) {
+      const callee = call.callee;
+      if (callee.type === "MemberExpression") {
+        const root = rootObject(callee);
+        if (root.type === "Identifier" && NON_EFFECT_OBJECTS.has(root.name)) return false;
+        const name = calleeName(call);
+        if (name && SIDE_EFFECT_METHODS.has(name)) return true;
+      }
+      return !!options.strict && !isConstructEvent(call) && call.arguments.length > 0;
+    }
+    return {
+      CallExpression(node) {
+        if (!isConstructEvent(node)) return;
+        const binding = eventBinding(node);
+        if (!binding) return;
+        if (binding.kind === "pattern" && binding.hasId) return;
+        const name = binding.kind === "identifier" ? binding.name : "event";
+        const fn = enclosingFunction(node);
+        if (!fn) return;
+        const after = node.range?.[1] ?? 0;
+        let handled = false;
+        let firstEffect;
+        walk(fn, (n) => {
+          if (handled) return;
+          if (n.type === "MemberExpression" && n.object.type === "Identifier" && n.object.name === name && !n.computed && n.property.type === "Identifier" && n.property.name === "id") {
+            handled = true;
+          } else if (n.type === "ReturnStatement" && n.argument?.type === "Identifier" && n.argument.name === name || n.type === "ArrowFunctionExpression" && n.body.type === "Identifier" && n.body.name === name) {
+            handled = true;
+          } else if (n.type === "CallExpression") {
+            const callee = calleeName(n);
+            if (callee && (helpers.has(callee) || DEFAULT_HELPERS.test(callee))) handled = true;
+            const isConsole = n.callee.type === "MemberExpression" && n.callee.object.type === "Identifier" && n.callee.object.name === "console";
+            if (!isConsole && n.arguments.some((a) => a.type === "Identifier" && a.name === name)) {
+              handled = true;
+            }
+            if ((n.range?.[0] ?? 0) >= after && isSideEffect(n) && (!firstEffect || (n.range?.[0] ?? 0) < (firstEffect.range?.[0] ?? 0))) {
+              firstEffect = n;
+            }
+          }
+        });
+        if (!handled && firstEffect) {
+          context.report({ node: firstEffect, messageId: "missing", data: { name, url } });
+        }
+      }
+    };
+  }
+};
+var require_idempotency_default = rule2;
+
+// src/rules/require-raw-body.ts
+function parsesAway(node) {
+  if (!isJsonParser(node)) return false;
+  const opts = node.arguments[0];
+  return !(opts?.type === "ObjectExpression" && opts.properties.some(
+    (p) => p.type === "Property" && p.key.type === "Identifier" && p.key.name === "verify"
+  ));
+}
+function usesParsedBody(fn) {
+  return findAll(fn, isConstructEvent).some((c) => {
+    const payload = c.arguments[0];
+    return payload?.type === "MemberExpression" && !payload.computed && payload.property.type === "Identifier" && payload.property.name === "body";
+  });
+}
+var rule3 = {
+  meta: {
+    type: "problem",
+    hasSuggestions: true,
+    docs: {
+      description: "Require the raw request body for Stripe signature verification (no JSON parsing before constructEvent)",
+      recommended: true,
+      url: docsUrl("require-raw-body")
+    },
+    schema: [],
+    messages: {
+      jsonMiddleware: "express.json() parses the body before the Stripe signature check, so constructEvent will always fail. Use express.raw() on this route.",
+      globalJson: "`{{owner}}.use(express.json())` on line {{line}} runs before this webhook route and parses the body, so constructEvent will fail. Register the webhook route first or give it express.raw().",
+      parsedJson: "The body is parsed with .json() before the Stripe signature check. Read the raw body with .text() and pass it to constructEvent.",
+      stringified: "JSON.stringify() of a parsed body is not byte-identical to what Stripe signed. Pass the raw body string or Buffer.",
+      useRaw: "Replace with express.raw({ type: 'application/json' })",
+      useText: "Read the body with .text() instead"
+    }
+  },
+  create(context) {
+    const globalParsers = [];
+    function handlerVerifies(fn) {
+      return findAll(fn, isConstructEvent).length > 0;
+    }
+    return {
+      CallExpression(node) {
+        const n = node;
+        const callee = n.callee;
+        if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "use" && callee.object.type === "Identifier") {
+          const args = n.arguments;
+          const first = args[0];
+          const pathless = !(first?.type === "Literal" && first.value !== "/");
+          if (pathless && args.some(parsesAway)) {
+            globalParsers.push({ owner: callee.object.name, node: n });
+          }
+        }
+        const route = asRoute(n);
+        if (route && handlerVerifies(route.handler) && usesParsedBody(route.handler)) {
+          const inlineJson = route.middlewares.filter(parsesAway);
+          for (const mw of inlineJson) {
+            context.report({
+              node: mw,
+              messageId: "jsonMiddleware",
+              suggest: [
+                {
+                  messageId: "useRaw",
+                  fix: (fixer) => fixer.replaceText(mw, "express.raw({ type: 'application/json' })")
+                }
+              ]
+            });
+          }
+          if (!inlineJson.length && !route.middlewares.some(isRawParser)) {
+            const earlier = globalParsers.find(
+              (p) => p.owner === route.owner && (p.node.range?.[0] ?? 0) < (n.range?.[0] ?? 0)
+            );
+            if (earlier) {
+              context.report({
+                node: n,
+                messageId: "globalJson",
+                data: { owner: earlier.owner, line: String(earlier.node.loc?.start.line) }
+              });
+            }
+          }
+        }
+        if (isConstructEvent(n)) {
+          const payload = n.arguments[0];
+          if (payload?.type === "CallExpression" && payload.callee.type === "MemberExpression" && payload.callee.object.type === "Identifier" && payload.callee.object.name === "JSON" && payload.callee.property.type === "Identifier" && payload.callee.property.name === "stringify") {
+            context.report({ node: payload, messageId: "stringified" });
+          }
+          const fn = enclosingFunction(n);
+          if (!fn) return;
+          const params = new Set(
+            fn.params.flatMap((p) => p.type === "Identifier" ? [p.name] : [])
+          );
+          const isRequest = (obj) => obj.type === "Identifier" && params.has(obj.name) || obj.type === "MemberExpression" && obj.object.type === "Identifier" && params.has(obj.object.name) && obj.property.type === "Identifier" && obj.property.name === "req";
+          walkSameFunction(fn, (c) => {
+            if (c.type === "CallExpression" && c.arguments.length === 0 && c.callee.type === "MemberExpression" && !c.callee.computed && c.callee.property.type === "Identifier" && c.callee.property.name === "json" && isRequest(c.callee.object) && (c.range?.[0] ?? 0) < (n.range?.[0] ?? 0)) {
+              const prop = c.callee.property;
+              context.report({
+                node: c,
+                messageId: "parsedJson",
+                suggest: [
+                  { messageId: "useText", fix: (fixer) => fixer.replaceText(prop, "text") }
+                ]
+              });
+            }
+          });
+        }
+      }
+    };
+  }
+};
+function walkSameFunction(fn, visit) {
+  const body = fn.body;
+  const stack = [body];
+  while (stack.length) {
+    const node = stack.pop();
+    visit(node);
+    for (const key of Object.keys(node)) {
+      if (key === "parent") continue;
+      const value = node[key];
+      for (const child of Array.isArray(value) ? value : [value]) {
+        if (child && typeof child === "object" && typeof child.type === "string") {
+          if (!isFunction(child)) stack.push(child);
+        }
+      }
+    }
+  }
+}
+var require_raw_body_default = rule3;
+
+// src/rules/require-signature-verification.ts
+var DEFAULT_VERIFY = /verif|signature|constructEvent|timingSafeEqual|unwrap/i;
+var AUTH_CALL = /auth|session|apiKey|permission|currentUser|requireUser/i;
+var rule4 = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require webhook handlers to verify the request signature",
+      recommended: true,
+      url: docsUrl("require-signature-verification")
+    },
+    schema: [
+      {
+        type: "object",
+        properties: { verifyFunctions: { type: "array", items: { type: "string" } } },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      missing: "This webhook handler never verifies the request signature, so anyone can forge events. Call stripe.webhooks.constructEvent() (or your provider\u2019s verify function) before trusting the body."
+    }
+  },
+  create(context) {
+    const extra = new Set(
+      context.options[0]?.verifyFunctions ?? []
+    );
+    const webhookFile = isWebhookFile(context);
+    function verifies(fn) {
+      let found = false;
+      const params = new Set(
+        fn.params.flatMap((p) => p.type === "Identifier" ? [p.name] : [])
+      );
+      const isRequest = (a) => a.type === "Identifier" && params.has(a.name) || a.type === "MemberExpression" && a.object.type === "Identifier" && params.has(a.object.name) && !a.computed && a.property.type === "Identifier" && a.property.name === "req";
+      walk(fn, (n) => {
+        if (found || n.type !== "CallExpression" && n.type !== "NewExpression") return;
+        const root = n.callee.type === "MemberExpression" ? n.callee.object : void 0;
+        const builtin = root?.type === "Identifier" && ["console", "JSON", "Response", "NextResponse", "res", "Object"].includes(root.name);
+        if (!builtin && n.arguments.some(isRequest)) {
+          found = true;
+          return;
+        }
+        const name = calleeName(n);
+        if (name && (extra.has(name) || DEFAULT_VERIFY.test(name) || AUTH_CALL.test(name)))
+          found = true;
+      });
+      return found;
+    }
+    function check(fn) {
+      if (!verifies(fn)) context.report({ node: fn, messageId: "missing" });
+    }
+    return {
+      CallExpression(node) {
+        const route = asRoute(node);
+        if (!route || !WEBHOOK_PATH.test(route.path)) return;
+        if (route.middlewares.some((m) => !isBodyParser(m))) return;
+        check(route.handler);
+      },
+      "FunctionDeclaration, FunctionExpression, ArrowFunctionExpression"(node) {
+        if (webhookFile && isNextPostHandler(node)) check(node);
+      }
+    };
+  }
+};
+var require_signature_verification_default = rule4;
+
+// src/index.ts
+var rules = {
+  "require-raw-body": require_raw_body_default,
+  "require-signature-verification": require_signature_verification_default,
+  "require-idempotency": require_idempotency_default,
+  "bullmq-require-job-id": bullmq_require_job_id_default
+};
+var recommendedRules = {
+  "webhook-safety/require-raw-body": "error",
+  "webhook-safety/require-signature-verification": "error",
+  "webhook-safety/require-idempotency": "warn",
+  "webhook-safety/bullmq-require-job-id": "warn"
+};
+var strictRules = Object.fromEntries(
+  Object.keys(recommendedRules).map((k) => [k, "error"])
+);
+var plugin = {
+  meta: { name: "eslint-plugin-webhook-safety", version: "0.2.0" },
+  rules,
+  configs: {}
+};
+plugin.configs.recommended = {
+  name: "webhook-safety/recommended",
+  plugins: { "webhook-safety": plugin },
+  rules: recommendedRules
+};
+plugin.configs.strict = {
+  name: "webhook-safety/strict",
+  plugins: { "webhook-safety": plugin },
+  rules: strictRules
+};
+plugin.configs["legacy-recommended"] = { plugins: ["webhook-safety"], rules: recommendedRules };
+plugin.configs["legacy-strict"] = { plugins: ["webhook-safety"], rules: strictRules };
+var index_default = plugin;
+export {
+  index_default as default
+};
+//# sourceMappingURL=index.js.map