Skip to content
SlashClone
DiscoverUse in ClaudeSubmit a link
Sign in
Made by@shipcheck

Stripe webhook hardening

@shipcheck/stripe-webhook-hardening

Find your Stripe webhook handlers and harden them: verify the Stripe-Signature header, use the raw body, keep the signing secret in env, process each event once, reject bad signatures with 400, and fulfill orders from the webhook rather than the success page. Reads your code and proposes diffs; never calls Stripe.

SkillDevOpsv1.0.0 (latest)Tested
Use in Claude Save Like Clone Comment
Activity
New: be the first to try it
  1. 1#!/usr/bin/env node
  2. 2// Find Stripe webhook handlers in a project and check the basics:
  3. 3// signature verified, raw body used, secret read from env, idempotent on event.id,
  4. 4// bad signatures rejected with 400, event types filtered, edge runtime handled.
  5. 5// This is a first pass that points Claude (and you) at the right lines. It reads code
  6. 6// only; it never calls Stripe. Node built-ins only.
  7. 7//
  8. 8// Usage: node scripts/webhook-scan.mjs [project-dir] [--json out/webhook-scan.json] [--md out/webhook-scan.md]
  9. 9
  10. 10import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
  11. 11import { dirname, join, relative, sep } from "node:path";
  12. 12
  13. 13const SKIP_DIRS = new Set([".git", "node_modules", ".next", ".nuxt", ".svelte-kit", ".vercel", ".netlify", "dist", "build", "coverage", "out", "vendor", ".venv", "venv", "__pycache__"]);
  14. 14const CODE = /\.(?:[cm]?[jt]sx?|py|rb|go|php)$/;
  15. 15const SKIP_SELF = /(?:^|\/)stripe-webhook-hardening\//;
  16. 16
  17. 17function parseArgs(argv) {
  18. 18 const args = { root: ".", json: null, md: null };
  19. 19 const rest = [];
  20. 20 for (let i = 0; i < argv.length; i++) {
  21. 21 const a = argv[i];
  22. 22 if (a === "--json") args.json = argv[++i];
  23. 23 else if (a === "--md") args.md = argv[++i];
  24. 24 else if (a === "-h" || a === "--help") {
  25. 25 console.log("Usage: node scripts/webhook-scan.mjs [project-dir] [--json file] [--md file]");
  26. 26 process.exit(0);
  27. 27 } else rest.push(a);
  28. 28 }
  29. 29 if (rest[0]) args.root = rest[0];
  30. 30 return args;
  31. 31}
  32. 32
  33. 33function walk(root, dir = root, out = []) {
  34. 34 for (const e of readdirSync(dir, { withFileTypes: true })) {
  35. 35 const full = join(dir, e.name);
  36. 36 if (e.isDirectory()) {
  37. 37 if (!SKIP_DIRS.has(e.name)) walk(root, full, out);
  38. 38 } else if (e.isFile() && CODE.test(e.name)) {
  39. 39 const rel = relative(root, full).split(sep).join("/");
  40. 40 if (!SKIP_SELF.test(rel) && statSync(full).size < 512 * 1024) out.push(rel);
  41. 41 }
  42. 42 }
  43. 43 return out;
  44. 44}
  45. 45
  46. 46const lineOf = (text, re) => {
  47. 47 const m = re.exec(text);
  48. 48 return m ? text.slice(0, m.index).split("\n").length : 0;
  49. 49};
  50. 50
  51. 51const VERIFY = /\bwebhooks\.constructEvent(?:Async)?\s*\(|\bWebhook\.construct_event\s*\(|\bWebhook\.construct_event\b|\bStripe::Webhook\.construct_event\b|\bwebhook\.ConstructEvent\s*\(|\bWebhook::constructEvent\s*\(/;
  52. 52const HANDLES_EVENTS =
  53. 53 /\b(?:checkout\.session\.completed|invoice\.(?:paid|payment_succeeded|payment_failed)|customer\.subscription\.(?:created|updated|deleted)|payment_intent\.succeeded|charge\.(?:succeeded|refunded))\b|stripe-signature|Stripe-Signature|HTTP_STRIPE_SIGNATURE/;
  54. 54const PARSED_BODY = /\bawait\s+(?:req|request)\.json\(\)|\brequest\.get_json\(|\brequest\.json\b(?!\s*\()|JSON\.stringify\(\s*req\.body\s*\)/;
  55. 55const RAW_BODY =
  56. 56 /\bawait\s+(?:req|request)\.text\(\)|\barrayBuffer\(\)|express\.raw\(|bodyParser\.raw\(|bodyParser\s*:\s*false|\bbuffer\(\s*req\s*\)|\brawBody\b|\brequest\.(?:data|get_data\(|body\.read)|\bio\.ReadAll\(|php:\/\/input|getRawBody|req\.body\s*,\s*sig/;
  57. 57const JSON_PARSER = /\bexpress\.json\(|\bbodyParser\.json\(|app\.use\(\s*json\(/;
  58. 58const HARDCODED_SECRET = /["'`]whsec_[A-Za-z0-9]+["'`]/;
  59. 59const ENV_SECRET = /\benv\.[A-Z0-9_]*WEBHOOK|os\.environ(?:\.get)?[[(]\s*["'][A-Z0-9_]*WEBHOOK|ENV\[\s*["'][A-Z0-9_]*WEBHOOK|Deno\.env\.get\(\s*["'][A-Z0-9_]*WEBHOOK|getenv\(\s*["'][A-Z0-9_]*WEBHOOK|env\(\s*["'][A-Z0-9_]*WEBHOOK/;
  60. 60const IDEMPOTENT =
  61. 61 /\bevent\.id\b[\s\S]{0,400}?\b(?:insert|upsert|create|exists|findUnique|findFirst|processed|unique|on\s*conflict|onConflict|ignoreDuplicates|setnx|SETNX|get_or_create)\b|\b(?:processed_events|stripe_events|webhook_events|processedEvents|stripeEvents|webhookEvents)\b|idempotenc/i;
  62. 62const REJECTS_400 = /\b400\b|status_code\s*=\s*400|BadRequest|bad_request|HTTP_400/;
  63. 63const TYPE_FILTER = /\bswitch\s*\(\s*event\.type\s*\)|\bevent\.type\s*===?|\bevent\[["']type["']\]\s*==|\bevent\.type\s*==|\bcase\s+["']checkout\.session\.completed["']/;
  64. 64const EDGE = /export\s+const\s+runtime\s*=\s*["']edge["']|Deno\.serve\(|\bserve\(\s*async/;
  65. 65const ASYNC_VERIFY = /constructEventAsync\s*\(/;
  66. 66const CRYPTO_PROVIDER = /createSubtleCryptoProvider\(/;
  67. 67
  68. 68function checkFile(file, text) {
  69. 69 const verifies = VERIFY.test(text);
  70. 70 const handles = verifies || HANDLES_EVENTS.test(text);
  71. 71 if (!handles) return null;
  72. 72 const checks = [];
  73. 73 const add = (id, status, severity, line, message, fix) => checks.push({ id, status, severity, line, message, fix });
  74. 74
  75. 75 if (verifies)
  76. 76 add("signature", "pass", null, lineOf(text, VERIFY), "Verifies the Stripe-Signature header.", null);
  77. 77 else
  78. 78 add(
  79. 79 "signature",
  80. 80 "fail",
  81. 81 "high",
  82. 82 lineOf(text, HANDLES_EVENTS),
  83. 83 "Handles Stripe events without verifying the signature. Anyone who finds this URL can post a fake checkout.session.completed and get your product free.",
  84. 84 "Call stripe.webhooks.constructEvent(rawBody, signature, secret) before reading the event, with the secret from your STRIPE_WEBHOOK_SECRET env var.",
  85. 85 );
  86. 86
  87. 87 const parsed = PARSED_BODY.test(text);
  88. 88 const raw = RAW_BODY.test(text);
  89. 89 if (parsed && !raw)
  90. 90 add(
  91. 91 "raw-body",
  92. 92 "fail",
  93. 93 "high",
  94. 94 lineOf(text, PARSED_BODY),
  95. 95 "Reads the body as parsed JSON. Signature checks need the exact raw bytes, so verification fails (or was removed to make it pass).",
  96. 96 "Next.js App Router: const body = await req.text(). Express: express.raw({ type: 'application/json' }) on this route only. Pages Router: export const config = { api: { bodyParser: false } }.",
  97. 97 );
  98. 98 else if (raw) add("raw-body", "pass", null, lineOf(text, RAW_BODY), "Uses the raw request body.", null);
  99. 99 else if (JSON_PARSER.test(text))
  100. 100 add(
  101. 101 "raw-body",
  102. 102 "warn",
  103. 103 "medium",
  104. 104 lineOf(text, JSON_PARSER),
  105. 105 "A JSON body parser is set up in this file. If it runs before the webhook route, the raw body is gone.",
  106. 106 "Mount the webhook route with express.raw() before app.use(express.json()).",
  107. 107 );
  108. 108 else add("raw-body", "warn", "low", 0, "Could not tell how the body is read. Check by hand.", null);
  109. 109
  110. 110 if (HARDCODED_SECRET.test(text))
  111. 111 add(
  112. 112 "secret-from-env",
  113. 113 "fail",
  114. 114 "high",
  115. 115 lineOf(text, HARDCODED_SECRET),
  116. 116 "The webhook signing secret is hardcoded.",
  117. 117 "Move it to STRIPE_WEBHOOK_SECRET in your env and roll the secret in the Stripe dashboard.",
  118. 118 );
  119. 119 else if (verifies && !ENV_SECRET.test(text))
  120. 120 add("secret-from-env", "warn", "low", 0, "Could not see the signing secret being read from an env var here. Check where it comes from.", null);
  121. 121 else if (verifies) add("secret-from-env", "pass", null, lineOf(text, ENV_SECRET), "Reads the signing secret from env.", null);
  122. 122
  123. 123 if (IDEMPOTENT.test(text)) add("idempotency", "pass", null, lineOf(text, IDEMPOTENT), "Looks idempotent on event.id.", null);
  124. 124 else
  125. 125 add(
  126. 126 "idempotency",
  127. 127 "fail",
  128. 128 "medium",
  129. 129 0,
  130. 130 "No sign of de-duplicating by event.id. Stripe retries and can deliver the same event twice, so orders, credits, or emails can double up.",
  131. 131 "Insert event.id into a processed_events table with a unique constraint first; if the insert conflicts, return 200 and stop.",
  132. 132 );
  133. 133
  134. 134 if (verifies) {
  135. 135 if (REJECTS_400.test(text)) add("reject-bad-signature", "pass", null, lineOf(text, REJECTS_400), "Returns 400 on failure.", null);
  136. 136 else
  137. 137 add(
  138. 138 "reject-bad-signature",
  139. 139 "warn",
  140. 140 "low",
  141. 141 0,
  142. 142 "No 400 response found. Wrap verification in try/catch and return 400 when it throws, so bad requests are rejected and real failures show in the Stripe dashboard.",
  143. 143 null,
  144. 144 );
  145. 145 }
  146. 146
  147. 147 if (TYPE_FILTER.test(text)) add("event-types", "pass", null, lineOf(text, TYPE_FILTER), "Branches on event.type.", null);
  148. 148 else
  149. 149 add(
  150. 150 "event-types",
  151. 151 "warn",
  152. 152 "low",
  153. 153 0,
  154. 154 "Does not branch on event.type. Handle only the events you subscribed to and return 200 for the rest.",
  155. 155 null,
  156. 156 );
  157. 157
  158. 158 if (EDGE.test(text) && verifies && !ASYNC_VERIFY.test(text))
  159. 159 add(
  160. 160 "edge-runtime",
  161. 161 "fail",
  162. 162 "medium",
  163. 163 lineOf(text, EDGE),
  164. 164 "Runs on an edge or Deno runtime with the sync constructEvent, which needs Node crypto.",
  165. 165 "Use await stripe.webhooks.constructEventAsync(body, sig, secret, undefined, Stripe.createSubtleCryptoProvider()).",
  166. 166 );
  167. 167 else if (EDGE.test(text) && ASYNC_VERIFY.test(text) && !CRYPTO_PROVIDER.test(text))
  168. 168 add("edge-runtime", "warn", "low", lineOf(text, EDGE), "Edge runtime: pass Stripe.createSubtleCryptoProvider() to constructEventAsync if verification throws.", null);
  169. 169
  170. 170 return { file, checks };
  171. 171}
  172. 172
  173. 173export function scan(root) {
  174. 174 const handlers = [];
  175. 175 for (const file of walk(root)) {
  176. 176 const text = readFileSync(join(root, file), "utf8");
  177. 177 const r = checkFile(file, text);
  178. 178 if (r) handlers.push(r);
  179. 179 }
  180. 180 const all = handlers.flatMap((h) => h.checks.filter((c) => c.status !== "pass"));
  181. 181 return {
  182. 182 summary: {
  183. 183 handlers: handlers.length,
  184. 184 high: all.filter((c) => c.severity === "high").length,
  185. 185 medium: all.filter((c) => c.severity === "medium").length,
  186. 186 low: all.filter((c) => c.severity === "low").length,
  187. 187 },
  188. 188 handlers,
  189. 189 };
  190. 190}
  191. 191
  192. 192function toMarkdown(report) {
  193. 193 const s = report.summary;
  194. 194 const lines = ["# Stripe webhook scan", "", `Handlers found: ${s.handlers} | High: ${s.high} | Medium: ${s.medium} | Low: ${s.low}`, ""];
  195. 195 if (s.handlers === 0)
  196. 196 lines.push("No Stripe webhook handler found. Search for the route Stripe posts to (often api/webhooks/stripe) and point the scan at that folder.", "");
  197. 197 for (const h of report.handlers) {
  198. 198 lines.push(`## ${h.file}`, "", "| Check | Result | Line | Note |", "| --- | --- | --- | --- |");
  199. 199 for (const c of h.checks) {
  200. 200 const result = c.status === "pass" ? "pass" : `**${c.status.toUpperCase()}** (${c.severity})`;
  201. 201 lines.push(`| ${c.id} | ${result} | ${c.line || ""} | ${c.message.replace(/\|/g, "/")} |`);
  202. 202 }
  203. 203 const fixes = h.checks.filter((c) => c.fix);
  204. 204 if (fixes.length) {
  205. 205 lines.push("", "Fixes:", "");
  206. 206 for (const c of fixes) lines.push(`- ${c.id}: ${c.fix}`);
  207. 207 }
  208. 208 lines.push("");
  209. 209 }
  210. 210 return lines.join("\n");
  211. 211}
  212. 212
  213. 213function write(path, text) {
  214. 214 mkdirSync(dirname(path), { recursive: true });
  215. 215 writeFileSync(path, text);
  216. 216}
  217. 217
  218. 218function main() {
  219. 219 const args = parseArgs(process.argv.slice(2));
  220. 220 if (!existsSync(args.root) || !statSync(args.root).isDirectory()) {
  221. 221 console.error(`No folder at ${args.root}.`);
  222. 222 process.exit(2);
  223. 223 }
  224. 224 const report = scan(args.root);
  225. 225 const md = toMarkdown(report);
  226. 226 if (args.json) write(args.json, JSON.stringify(report, null, 2) + "\n");
  227. 227 if (args.md) write(args.md, md);
  228. 228 if (!args.json && !args.md) console.log(md);
  229. 229 else console.log(`${report.summary.handlers} handlers. High ${report.summary.high}, medium ${report.summary.medium}, low ${report.summary.low}.`);
  230. 230}
  231. 231
  232. 232main();
Sign in to comment on a line