@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/webhooks/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: webhooks
+description: "Use when building the receiving end of a webhook — a provider-agnostic endpoint that proves pushed events are authentic and never processes one twice: raw-body HMAC, ~5-min replay window, idempotency on the event id, fast-ack-then-queue. NOT the Stripe-Signature scheme (that is stripe), NOT outbound clients you call (that is api-connector-builder)."
+tags: [webhooks, inbound-webhooks, hmac-verification, idempotency, signature-verification, queue, connectors]
+recommends: [stripe, email-connector, api-connector-builder, automation-flows, redis, secure-coding]
+profiles: []
+origin: ai-hub
+---
+
+# Webhooks — the inbound front door that survives retries and forgeries
+
+You are building the side of a webhook that *receives*. Some external system
+pushes an HTTP POST at your endpoint; your job is to prove it is real, refuse to
+act on it twice, and answer fast. That is the whole mandate.
+
+This skill is provider-agnostic — it teaches the mechanics every webhook source
+shares, not any one vendor's event catalog — and it ends at "enqueued." What
+happens to the event afterward is a different job:
+
+- The Stripe-specific scheme (`Stripe-Signature`, `t=,v1=`, `stripe listen`,
+  the event model) → `../stripe/SKILL.md`.
+- Email bounce/complaint webhooks where the point is suppression state →
+  `../email-connector/SKILL.md`.
+- The *outbound* client that calls someone else's API → `api-connector-builder`.
+- Multi-step orchestration after the event lands → `automation-flows`.
+- Broker/queue tuning (BullMQ concurrency, DLQ ops) → `redis`.
+- Constant-time compare, secret handling, supply-chain hygiene →
+  `../secure-coding/SKILL.md`.
+
+## The pipeline
+
+These five stages run in exactly this order. Each one exists to protect the one
+after it; reorder them and you either trust forged data or waste work.
+
+| # | Stage | Why it precedes the next |
+|---|-------|--------------------------|
+| 1 | Read the **raw body** | Parsing first destroys the bytes the signature was computed over. Capture the raw buffer before any JSON parse. |
+| 2 | **Verify the signature** | Until this passes, every field in the body is attacker-controlled. Verify before you read anything. |
+| 3 | Check the **timestamp window** | A cheap reject of replayed-but-valid payloads, before you touch a datastore. |
+| 4 | **Dedupe** on the event id | At-least-once delivery means duplicates are normal. Mark it seen before doing work, not after. |
+| 5 | **Persist/enqueue → `2xx`** | Hand the event to durable storage, then ack. The ack means "I own this now." |
+
+**Delivery is at-least-once, never exactly-once.** Every major provider retries
+on non-2xx or timeout, so duplicate deliveries are normal traffic and idempotency
+is required, not a nice-to-have.
+
+## Verify the signature
+
+**Verify over the raw bytes, never over re-serialized JSON.** Re-serializing a
+parsed object reorders keys and normalizes whitespace, so the HMAC you compute
+no longer matches the one the sender computed. This is the single most common
+cause of "signature fails even though the secret is right."
+
+```js
+// Bad — body was parsed, so the bytes are gone. HMAC will never match.
+app.post("/webhooks", express.json(), (req, res) => {
+  const expected = sign(JSON.stringify(req.body)); // reordered, re-spaced
+});
+
+// Good — keep the raw buffer for the HMAC; parse only after verifying.
+app.post("/webhooks", express.raw({ type: "*/*" }), (req, res) => {
+  const raw = req.body; // a Buffer, the exact bytes received
+  if (!verify(raw, req.headers)) return res.sendStatus(400);
+  const event = JSON.parse(raw.toString("utf8"));
+});
+```
+
+**Compare signatures in constant time.** A normal `===`/`==` short-circuits on
+the first differing byte, which leaks how much of the signature an attacker
+guessed correctly. Use `crypto.timingSafeEqual` (Node) or `hmac.compare_digest`
+(Python). The buffers must be equal length, so guard that first.
+
+The cross-vendor **Standard Webhooks** spec (adopted by Svix, Clerk, Resend,
+Brex and others) defines the scheme this skill defaults to: headers
+`webhook-id`, `webhook-timestamp`, `webhook-signature`; the signature is
+`base64(HMAC-SHA256(secret, "{id}.{timestamp}.{body}"))`, version-prefixed as
+`v1,<sig>`, and the header may carry **space-separated** signatures so a secret
+can be rotated without dropped deliveries — accept the request if **any** match.
+
+```js
+import crypto from "node:crypto";
+
+function verify(raw, headers) {
+  const id = headers["webhook-id"];
+  const ts = headers["webhook-timestamp"];
+  const secret = process.env.WEBHOOK_SECRET; // never a literal
+  const signed = `${id}.${ts}.${raw.toString("utf8")}`;
+  const expected = crypto
+    .createHmac("sha256", Buffer.from(secret, "base64"))
+    .update(signed)
+    .digest("base64");
+  // header is "v1,<sig> v1,<sig2>"; accept if any matches (secret rotation)
+  return String(headers["webhook-signature"] || "")
+    .split(" ")
+    .map((part) => part.split(",")[1])
+    .some((sig) => sameLength(sig, expected) &&
+      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));
+}
+const sameLength = (a = "", b = "") => a.length === b.length;
+```
+
+```python
+import hmac, hashlib, base64, os
+
+def verify(raw: bytes, headers) -> bool:
+    secret = base64.b64decode(os.environ["WEBHOOK_SECRET"])  # never a literal
+    signed = f'{headers["webhook-id"]}.{headers["webhook-timestamp"]}.'.encode() + raw
+    expected = base64.b64encode(hmac.new(secret, signed, hashlib.sha256).digest()).decode()
+    sent = headers.get("webhook-signature", "")
+    for part in sent.split(" "):          # space-separated for rotation
+        sig = part.split(",", 1)[-1]
+        if hmac.compare_digest(sig, expected):  # constant time
+            return True
+    return False
+```
+
+Per-provider header formats (Stripe `t=,v1=`, GitHub `X-Hub-Signature-256`,
+Shopify base64 HMAC, Slack `v0=`, Svix) all map onto the same primitive —
+mapping table and per-language verify primitives in
+`references/signature-schemes.md`.
+
+## Timestamp & replay
+
+A valid signature does not stop a replay: an attacker who captures one delivery
+can re-send the exact bytes, signature intact. Bound it with a timestamp.
+
+**Reject any event whose `webhook-timestamp` is more than ~5 minutes from now.**
+That five-minute window is the de-facto industry value (Benchling and others
+recommend it). The Standard Webhooks spec mandates that you perform *a*
+tolerance check but does not fix the number — pick a small one.
+
+```js
+const skewSeconds = Math.abs(Date.now() / 1000 - Number(ts));
+if (skewSeconds > 300) return res.sendStatus(400); // outside the 5-min window
+```
+
+The timestamp window bounds *how long* a captured payload is replayable; the
+idempotency check (next section) stops *exact* replays that arrive inside the
+window. You need both — neither alone is enough.
+
+## Idempotency
+
+**The idempotency key is the provider's stable event id** (`webhook-id`, or for
+Stripe `event.id`) — never a hash of the body or your own generated id. Mark it
+seen *before* doing the work, so a retry that arrives mid-processing is caught.
+
+Two stores, same idea:
+
+| Store | Mechanism | TTL / lifetime |
+|-------|-----------|----------------|
+| Relational DB | `INSERT` the event id into a table with a **UNIQUE** constraint; a duplicate insert throws → skip | Keep the row at least as long as the retry window |
+| Redis | `SET key val NX EX <ttl>` — `SETNX` returns false if already present → skip | TTL **≥ the provider's retry window** (hours to days) |
+
+**The dedupe TTL must outlive the provider's entire retry schedule.** Retries
+are exponential and capped — a provider may redeliver hours or days later. If
+your key expires first, that late retry looks brand-new and you process twice.
+
+```js
+// Insert-then-process: the UNIQUE insert is the gate. Do work only if we won it.
+try {
+  await db.query("INSERT INTO seen_events (id) VALUES ($1)", [id]);
+} catch (e) {
+  if (e.code === "23505") return res.sendStatus(200); // already seen → ack, skip
+  throw e;
+}
+await queue.add("process", { id, event });
+res.sendStatus(200);
+```
+
+Prefer **insert-then-process** over **process-then-mark**. Marking after the
+work leaves a window where two concurrent deliveries both pass the "have I seen
+it?" check and both run. Let the UNIQUE constraint (or `NX`) be the lock.
+
+## Fast-ack & queue
+
+Heavy synchronous work inside the handler causes provider timeouts and a storm
+of retries. Return `2xx` as soon as the event is durably stored or enqueued,
+then do the real work in a background worker. The status code is a contract with
+the sender:
+
+| You return | Meaning to the provider | Use it when |
+|------------|-------------------------|-------------|
+| `2xx` | "I own this now" | After enqueue/persist — **even if** downstream processing later fails. Recover failures from your own queue, not by asking for a redelivery. |
+| `4xx` | Permanent reject, do not retry | Bad/forged signature (`400`/`401`), or a payload you will never accept. A retry of a forged request is still forged. |
+| `5xx` / timeout | "Try again" | A genuine transient failure *before* you took ownership (e.g. the queue itself is down). |
+
+Once work is in the queue, handle failures there: bounded retries with backoff,
+then route exhausted jobs to a **dead-letter queue / poison shelf** for manual
+inspection. Do not let a poison event loop forever or block the queue head.
+Queue/broker tuning itself (concurrency, DLQ wiring) is `redis`'s job.
+
+## Framework raw-body recipes
+
+Capturing the raw body is framework-specific and is the usual culprit behind
+"mismatch though the secret is correct." One line each; full recipes in
+`references/framework-raw-body.md`:
+
+- **Express** — mount `express.raw({ type: "*/*" })` on the webhook route only;
+  do not let a global `express.json()` consume it first.
+- **Next.js App Router** — read `await req.text()` (or `req.arrayBuffer()`) in
+  the route handler; the App Router does not auto-parse, but `await req.json()`
+  discards the raw bytes, so verify off the text.
+- **FastAPI / Starlette** — `await request.body()` for the raw `bytes`; do not
+  type the handler param as a Pydantic model (that parses for you).
+- **Hono** — `await c.req.text()` before any `c.req.json()`.
+- **Serverless (Lambda/Vercel/Cloudflare)** — disable body parsing / read the
+  raw stream; base64-decode if the platform wraps the body.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|--------------|--------------|------------|
+| HMAC over parsed/re-serialized JSON | Key reorder + whitespace break the signature ("works with the right secret but still fails") | Verify over the raw bytes captured before parsing |
+| `===` / `==` on the signature | Timing side-channel leaks the secret byte by byte | `crypto.timingSafeEqual` / `hmac.compare_digest` |
+| Heavy synchronous work in the handler | Provider times out → retry storm → duplicate processing | Fast-ack: verify → dedupe → enqueue → `2xx`, work in a worker |
+| Ack before persisting/enqueueing | `2xx` means "I own it"; if you crash now the event is lost forever (provider won't retry a 2xx) | Persist or enqueue *first*, then return `2xx` |
+| No dedupe / dedupe on a body hash | At-least-once delivery double-processes; body hashes drift across redeliveries | UNIQUE-constraint or `SETNX` on the provider's stable event id |
+| Dedupe TTL shorter than the retry window | A late retry looks new and runs again | TTL ≥ the provider's full retry schedule (hours–days) |
+| Signing secret hard-coded in source | Leaks in git history; can't rotate | Read from env; accept space-separated sigs for rotation |
+| Returning `200` on a bad signature | Silently swallows forged traffic and masks misconfig | `400`/`401` on signature failure |
+| Skipping the timestamp check | Valid-but-replayed payloads sail through | Reject outside the ~5-min window |
+
+## Verify your handler
+
+`scripts/verify.sh` is a read-only heuristic linter. Run it from the root of the
+project that contains your handler; it scans candidate files and prints
+PASS/WARN/FAIL per invariant (raw-body verify, constant-time compare, timestamp
+check, secret-from-env, dedupe-on-event-id). A WARN means "I could not find
+evidence," which on a clean tree is expected and exits `0`.

package/skills/shared/webhooks/evals/README.md

@@ -0,0 +1,15 @@
+# Evals — webhooks
+
+These cases are descriptive routing/capability checks, not an automated test
+suite. To run them, feed each `should_trigger` prompt to the skill router and
+confirm `webhooks` is selected (the `why` explains the intent, including the
+non-obvious raw-body and fast-ack symptoms); feed each `should_not_trigger`
+prompt and confirm the router picks the named sibling in `route_to` instead
+(these guard the boundaries against `stripe`, `email-connector`,
+`api-connector-builder`, `automation-flows` and `redis`). The `capability` case
+is graded by generation: have the skill produce the Express handler and check
+the output against the `must_include` rubric — every line should be present
+(raw-body HMAC, constant-time compare, 5-min window, dedupe-on-event-id with a
+TTL that outlives retries, 2xx-after-enqueue, secret-from-env, 400/401 on a bad
+signature). `scripts/verify.sh` is a complementary static linter for those same
+invariants against real handler files; it is advisory, not part of this eval.

package/skills/shared/webhooks/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: webhooks
+
+should_trigger:
+  - prompt: "We need to receive webhooks from a provider and process them without dropping events or double-processing. Where do I start?"
+    why: "Core inbound flow: receive + dedupe + safe processing is the skill's whole mandate (verify → timestamp → dedupe → fast-ack)."
+  - prompt: "My webhook signature verification keeps failing even though the signing secret is definitely correct. What am I missing?"
+    why: "Non-obvious. The classic raw-body trap — verifying over re-serialized JSON instead of the raw bytes. The skill names this exact symptom."
+  - prompt: "The provider keeps retrying and our handler ends up running the same event twice. How do we make it idempotent?"
+    why: "At-least-once delivery + idempotency on the stable event id is a flagship section; phrased as a symptom, not jargon."
+  - prompt: "How do I do a constant-time signature compare and a timestamp/replay check on an incoming webhook?"
+    why: "Verify mechanics: timingSafeEqual / compare_digest plus the ~5-min tolerance window are core content."
+  - prompt: "Verificar la firma del webhook entrante y evitar procesar el mismo evento dos veces — ¿cómo lo monto en Express?"
+    why: "Spanish trigger covering signature verification + idempotency, the two central invariants."
+  - prompt: "Our webhook endpoint times out under load and the sender hammers it with retries. How do we ack fast and move the work off the request?"
+    why: "Non-obvious framing of the fast-ack-then-queue pattern; the timeout→retry-storm chain is the reason the pattern exists."
+  - prompt: "What status code should I return from a webhook handler when the signature is bad versus when my downstream save fails?"
+    why: "Status-code semantics (2xx = I own it, 4xx = forged/no-retry, 5xx = genuine retry) is a dedicated decision table."
+
+should_not_trigger:
+  - prompt: "Verify a Stripe webhook with the Stripe-Signature header and handle checkout.session.completed in my SaaS."
+    route_to: stripe
+    why: "Stripe's specific t=,v1= scheme, event model and stripe listen CLI belong to the specialized skill; webhooks covers only the generic case."
+  - prompt: "Handle Resend and SendGrid bounce and complaint webhooks so our suppression list stays clean."
+    route_to: email-connector
+    why: "The point is deliverability suppression state, not generic receive-and-verify mechanics."
+  - prompt: "Build a client that calls the GitHub REST API with auth, pagination and retries on the requests we initiate."
+    route_to: api-connector-builder
+    why: "That is the outbound client (we call them), the opposite direction from an inbound receiver."
+  - prompt: "After an order webhook lands, branch across Slack, the database and an email in a multi-step flow with conditions."
+    route_to: automation-flows
+    why: "Post-landing orchestration; webhooks ends at 'enqueued' and the flow engine takes over from there."
+  - prompt: "Tune our BullMQ worker concurrency and set up a dead-letter queue in Redis."
+    route_to: redis
+    why: "Broker/queue operations, not the front-door receiver; webhooks enqueues but does not own broker tuning."
+
+capability:
+  - scenario: "Implement an inbound webhook endpoint for a generic Standard-Webhooks provider in Node/Express that receives an event, proves it is authentic, refuses to process it twice, and acks fast — then describe where the real work runs."
+    must_include:
+      - "HMAC is computed over the RAW request body (raw buffer/text), not over JSON.parse(req.body) or a re-serialized object"
+      - "constant-time comparison via crypto.timingSafeEqual (not === / ==), with an equal-length guard"
+      - "timestamp tolerance check (~5 minutes) rejecting stale/replayed deliveries"
+      - "dedupe on the provider's stable event id (webhook-id) via a UNIQUE constraint or Redis SETNX, marked before processing"
+      - "dedupe TTL must outlive the provider's retry window (hours to days)"
+      - "returns 2xx only after the event is persisted/enqueued, then does the work in a background worker"
+      - "signing secret read from an environment variable, never a hard-coded literal"
+      - "bad/forged signature returns 400 or 401, not 200"

package/skills/shared/webhooks/references/framework-raw-body.md

@@ -0,0 +1,97 @@
+# Getting the raw body, per framework
+
+If your signature check fails but the secret is correct, you are almost always
+verifying over a **re-serialized** body instead of the raw bytes the sender
+signed. Each framework hides the raw body somewhere different. The rule is the
+same everywhere: **capture the raw bytes, verify, and only then parse.**
+
+## Express
+
+A global `express.json()` consumes the stream, so by the time your handler runs
+the original bytes are gone. Mount `express.raw()` on the webhook route only.
+
+```js
+import express from "express";
+const app = express();
+app.use(express.json()); // fine for the rest of the app
+
+// Webhook route gets RAW, mounted before/instead of the global parser for this path.
+app.post("/webhooks", express.raw({ type: "*/*" }), (req, res) => {
+  const raw = req.body; // Buffer — exact bytes
+  if (!verify(raw, req.headers)) return res.sendStatus(400);
+  const event = JSON.parse(raw.toString("utf8"));
+  // dedupe + enqueue + res.sendStatus(200)
+});
+```
+
+If a global parser already ran, recover the bytes with a `verify` callback:
+`express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } })`.
+
+## Next.js (App Router)
+
+Route handlers do **not** auto-parse, but `await req.json()` reads the stream and
+discards the raw bytes. Read the text instead and parse it yourself after
+verifying.
+
+```ts
+// app/api/webhooks/route.ts
+export async function POST(req: Request) {
+  const raw = await req.text(); // raw string; do NOT call req.json() first
+  const headers = Object.fromEntries(req.headers);
+  if (!verify(raw, headers)) return new Response("bad sig", { status: 400 });
+  const event = JSON.parse(raw);
+  // dedupe + enqueue
+  return new Response("ok", { status: 200 });
+}
+```
+
+(Pages Router differs: set `export const config = { api: { bodyParser: false } }`
+and read the stream — prefer the App Router handler above.)
+
+## FastAPI / Starlette
+
+Typing the parameter as a Pydantic model parses the body for you and throws away
+the bytes. Take the raw `bytes` from the `Request`.
+
+```python
+from fastapi import FastAPI, Request, Response
+app = FastAPI()
+
+@app.post("/webhooks")
+async def webhooks(request: Request):
+    raw = await request.body()  # bytes — do not declare a model param
+    if not verify(raw, request.headers):
+        return Response(status_code=400)
+    event = json.loads(raw)
+    # dedupe + enqueue
+    return Response(status_code=200)
+```
+
+## Hono
+
+```ts
+app.post("/webhooks", async (c) => {
+  const raw = await c.req.text(); // before any c.req.json()
+  if (!verify(raw, c.req.header())) return c.text("bad sig", 400);
+  const event = JSON.parse(raw);
+  return c.text("ok", 200);
+});
+```
+
+## Serverless (Lambda / Vercel / Cloudflare Workers)
+
+- **AWS Lambda (API Gateway / function URL):** the body arrives as a string in
+  `event.body`; if `event.isBase64Encoded` is true, `Buffer.from(event.body,
+  "base64")` first. Verify over that, never over a parsed object.
+- **Vercel Functions:** disable the body parser for the route and read the raw
+  stream (Edge runtime: `await req.text()`).
+- **Cloudflare Workers:** `await request.text()` / `await request.arrayBuffer()`
+  in the `fetch` handler; the body is unbuffered, so read it once.
+
+## Common traps
+
+- A reverse proxy or middleware that re-encodes the body (gzip, charset
+  normalization) changes the bytes after the sender signed them — verify before
+  any transform, and disable response/transit re-encoding on the webhook path.
+- Reading the body stream twice: many runtimes let you read it once. Capture the
+  raw bytes into a variable and reuse that variable for both verify and parse.

package/skills/shared/webhooks/references/signature-schemes.md

@@ -0,0 +1,66 @@
+# Per-provider signature schemes
+
+Every webhook signature is the same primitive — `HMAC-SHA256(secret, message)`
+compared in constant time — wrapped in a different header layout. Map the
+provider onto the generic verify routine in `SKILL.md` by answering three
+questions: **which headers carry the id/timestamp/signature**, **what string is
+signed**, and **how is the signature encoded**.
+
+## Comparison table
+
+| Provider | Signature header | Signed message | Encoding | Timestamp source |
+|----------|------------------|----------------|----------|------------------|
+| Standard Webhooks | `webhook-signature` (`v1,<sig> …` space-separated) | `{webhook-id}.{webhook-timestamp}.{raw-body}` | base64 | `webhook-timestamp` header (Unix seconds) |
+| Stripe | `Stripe-Signature` (`t=<ts>,v1=<sig>`) | `{t}.{raw-body}` | hex | `t` field inside the header |
+| GitHub | `X-Hub-Signature-256` (`sha256=<sig>`) | raw body only | hex | none — rely on TLS + secret; no replay window |
+| Shopify | `X-Shopify-Hmac-SHA256` | raw body only | base64 | none |
+| Slack | `X-Slack-Signature` (`v0=<sig>`) + `X-Slack-Request-Timestamp` | `v0:{timestamp}:{raw-body}` | hex | `X-Slack-Request-Timestamp` header |
+| Svix | same as Standard Webhooks (`svix-id/timestamp/signature` or `webhook-*`) | `{id}.{timestamp}.{raw-body}` | base64 | timestamp header |
+
+Notes that bite:
+
+- **Stripe and Standard Webhooks both prefix versions and both allow multiple
+  comma/space-separated signatures** for secret rotation — accept the request if
+  *any* candidate matches. Never `break` on the first mismatch.
+- **GitHub and Shopify sign the body alone** (no id/timestamp), so they have no
+  built-in replay window. Lean on HTTPS and the secret; if you need replay
+  protection, dedupe on a delivery id (`X-GitHub-Delivery`).
+- **Slack signs `v0:{ts}:{body}`** with a colon separator and a literal `v0:`
+  prefix — different layout from the dot-joined Standard Webhooks string.
+- For the **Stripe** scheme specifically (event model, `stripe listen`, the
+  billing flows) use `../../stripe/SKILL.md`; this table only covers verifying
+  the signature.
+
+## Verify primitives by language
+
+The two things that must be language-correct: feed the **raw bytes** to the HMAC,
+and use the **constant-time** comparator.
+
+| Language | HMAC-SHA256 | Constant-time compare |
+|----------|-------------|------------------------|
+| Node.js | `crypto.createHmac("sha256", key).update(raw).digest()` | `crypto.timingSafeEqual(a, b)` (equal-length Buffers) |
+| Python | `hmac.new(key, raw, hashlib.sha256).digest()` | `hmac.compare_digest(a, b)` |
+| Go | `hmac.New(sha256.New, key); mac.Write(raw)` | `hmac.Equal(expected, got)` |
+| Ruby | `OpenSSL::HMAC.digest("SHA256", key, raw)` | `Rack::Utils.secure_compare(a, b)` |
+| PHP | `hash_hmac("sha256", $raw, $key, true)` | `hash_equals($a, $b)` |
+
+```go
+// Go — Standard Webhooks verify, constant time, raw body in.
+func verify(raw []byte, id, ts, header, secretB64 string) bool {
+	key, _ := base64.StdEncoding.DecodeString(secretB64)
+	mac := hmac.New(sha256.New, key)
+	mac.Write([]byte(id + "." + ts + "."))
+	mac.Write(raw)
+	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
+	for _, part := range strings.Fields(header) { // space-separated for rotation
+		sig := strings.TrimPrefix(part, "v1,")
+		if hmac.Equal([]byte(sig), []byte(expected)) {
+			return true
+		}
+	}
+	return false
+}
+```
+
+Whatever the layout, the order from `SKILL.md` does not change: raw body →
+verify → timestamp window → dedupe → enqueue → `2xx`.

package/skills/shared/webhooks/scripts/verify.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — webhooks inbound-handler invariant linter
+#
+# USAGE
+#   ./verify.sh [PATH]
+#   Run from the ROOT of YOUR project (the repo containing your webhook
+#   handler), NOT from the skills repository. PATH defaults to the current
+#   directory. Read-only: it never writes, never fixes, never installs.
+#
+# WHAT IT DOES
+#   Heuristically scans candidate webhook-handler files for the five inbound
+#   invariants and prints PASS / WARN / FAIL per file:
+#     1. raw body is used for HMAC verification (flags parsed-body verify)
+#     2. a constant-time signature compare is present (flags ==/=== on a sig)
+#     3. a timestamp / tolerance check exists
+#     4. the signing secret comes from env, not a string literal
+#     5. a dedupe step references a stable event id
+#
+#   It is a HEURISTIC (grep-based), advisory not a compiler. A WARN means
+#   "no evidence found", which is not necessarily a bug.
+#
+# EXIT CODES
+#   0  no candidate files found (clean/empty tree), OR all candidates PASS
+#      every hard check. WARN never fails the run.
+#   1  a candidate file FAILS a hard check (parsed-body verify, ==/=== on a
+#      signature, or a hard-coded secret).
+# ============================================================================
+
+TARGET="${1:-.}"
+
+if [ ! -e "$TARGET" ]; then
+  echo "verify.sh: target not found: $TARGET" >&2
+  exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Find candidate handler files: source files that look like they touch
+# webhooks / HMAC signatures. Prune dependency + VCS dirs. NUL-delimited so
+# paths with spaces survive.
+# ----------------------------------------------------------------------------
+# Portable (bash 3.2 / macOS + GNU) NUL-safe array build — no mapfile, no
+# process substitution, and -name globs instead of -iregex (BSD/GNU agree on
+# globs). We stage the NUL-delimited find output in a temp file, then read it.
+LISTFILE="$(mktemp -t webhooks-verify.XXXXXX 2>/dev/null || mktemp)"
+trap 'rm -f "$LISTFILE"' EXIT
+
+find "$TARGET" \
+  \( -name node_modules -o -name .git -o -name dist -o -name build \
+     -o -name vendor -o -name .venv -o -name venv -o -name __pycache__ \) -prune \
+  -o -type f \( -name '*.js' -o -name '*.cjs' -o -name '*.mjs' \
+                -o -name '*.ts' -o -name '*.tsx' -o -name '*.py' \
+                -o -name '*.go' -o -name '*.rb' -o -name '*.php' \) \
+  -print0 > "$LISTFILE" 2>/dev/null || true
+
+CANDIDATES=()
+while IFS= read -r -d '' f; do
+  if grep -Eilq 'webhook|x-hub-signature|stripe-signature|x-slack-signature|hmac' "$f" 2>/dev/null; then
+    CANDIDATES+=("$f")
+  fi
+done < "$LISTFILE"
+
+if [ "${#CANDIDATES[@]}" -eq 0 ]; then
+  echo "PASS  no webhook-handler files found under '$TARGET' — nothing to lint."
+  exit 0
+fi
+
+C_RESET=$'\033[0m'; C_RED=$'\033[31m'; C_GRN=$'\033[32m'; C_YEL=$'\033[33m'
+say_pass() { printf '%sPASS%s  %s\n' "$C_GRN" "$C_RESET" "$1"; }
+say_warn() { printf '%sWARN%s  %s\n' "$C_YEL" "$C_RESET" "$1"; }
+say_fail() { printf '%sFAIL%s  %s\n' "$C_RED" "$C_RESET" "$1"; }
+
+# matches lines, case-insensitive, fixed cost
+has() { grep -Eiq "$1" "$2" 2>/dev/null; }
+
+exit_code=0
+
+for f in "${CANDIDATES[@]}"; do
+  echo "── $f"
+
+  # 1. raw body used / parsed-body verify NOT used --------------------------
+  #    Hard fail if we see a signature/HMAC built from an obviously parsed
+  #    body (JSON.stringify(req.body), JSON.parse(...) fed to the digest).
+  if has 'createHmac|hmac\.new|OpenSSL::HMAC|hash_hmac|hmac\.New' "$f"; then
+    if has 'JSON\.stringify\s*\(\s*req\.body|JSON\.stringify\s*\(\s*request\.body' "$f"; then
+      say_fail "(1) HMAC appears to run over re-serialized parsed body (JSON.stringify(req.body)) — verify over the raw bytes"
+      exit_code=1
+    elif has 'rawbody|raw_body|req\.text\(\)|request\.body\(\)|c\.req\.text\(\)|arraybuffer|express\.raw|isbase64encoded' "$f"; then
+      say_pass "(1) raw body captured for HMAC verification"
+    else
+      say_warn "(1) HMAC found but no clear raw-body capture — confirm you verify over the raw bytes, not parsed JSON"
+    fi
+  else
+    say_warn "(1) no HMAC call detected in this file"
+  fi
+
+  # 2. constant-time compare -----------------------------------------------
+  if has 'timingsafeequal|compare_digest|hmac\.equal|secure_compare|hash_equals' "$f"; then
+    say_pass "(2) constant-time signature compare present"
+  elif has 'signature\s*===|signature\s*==|sig\s*===|sig\s*==|=== *expectedsig|== *expectedsig' "$f"; then
+    say_fail "(2) signature compared with ==/=== — timing leak; use a constant-time comparator"
+    exit_code=1
+  else
+    say_warn "(2) no constant-time compare detected — confirm timingSafeEqual / compare_digest is used"
+  fi
+
+  # 3. timestamp / tolerance check -----------------------------------------
+  if has 'webhook-timestamp|x-slack-request-timestamp|timestamp' "$f" \
+     && has '300|5 *\* *60|tolerance|skew|maxage|max_age|window' "$f"; then
+    say_pass "(3) timestamp tolerance / replay window check present"
+  else
+    say_warn "(3) no timestamp tolerance check detected — reject events outside ~5 minutes"
+  fi
+
+  # 4. secret from env, not a literal --------------------------------------
+  if has 'webhook_secret\s*=\s*["'\''][a-z0-9_]{12,}|signing_secret\s*=\s*["'\''][a-z0-9_]{12,}|whsec_[a-z0-9]' "$f"; then
+    say_fail "(4) signing secret looks hard-coded — read it from an environment variable"
+    exit_code=1
+  elif has 'process\.env|os\.environ|os\.getenv|env\(|ENV\[' "$f"; then
+    say_pass "(4) signing secret sourced from environment"
+  else
+    say_warn "(4) no env lookup detected — confirm the signing secret comes from env"
+  fi
+
+  # 5. dedupe on event id ---------------------------------------------------
+  if has 'unique|setnx|set .* nx|already.processed|already.seen|seen_event|idempoten|webhook-id|event\.id|delivery.id' "$f"; then
+    say_pass "(5) dedupe / idempotency on an event id present"
+  else
+    say_warn "(5) no dedupe step detected — dedupe on the provider's stable event id (UNIQUE / SETNX)"
+  fi
+done
+
+echo
+if [ "$exit_code" -eq 0 ]; then
+  echo "${C_GRN}verify.sh: no hard failures.${C_RESET} WARN lines are advisory — review them."
+else
+  echo "${C_RED}verify.sh: hard failures found.${C_RESET} Fix the FAIL lines above."
+fi
+exit "$exit_code"