rsc-universal 0.1.1

package/skills/vue-nuxt/references/nitro-and-rendering.md

@@ -0,0 +1,117 @@
+# Nitro server routes & rendering strategy
+
+Companion to the SKILL "Nitro server routes" and "Rendering strategy" sections. Nitro is Nuxt's
+server engine; everything under `server/` runs there.
+
+## Server route handlers
+
+| File | Maps to |
+|---|---|
+| `server/api/users.get.ts` | `GET /api/users` |
+| `server/api/users.post.ts` | `POST /api/users` |
+| `server/api/users/[id].get.ts` | `GET /api/users/:id` |
+| `server/routes/sitemap.xml.ts` | `GET /sitemap.xml` (non-`/api` route) |
+| `server/middleware/auth.ts` | runs on every request before handlers |
+
+```ts
+// server/api/users.post.ts
+export default defineEventHandler(async (event) => {
+  const body = await readBody<{ email: string }>(event)
+  if (!body?.email?.includes('@')) {
+    throw createError({ statusCode: 422, statusMessage: 'invalid email' })
+  }
+  const config = useRuntimeConfig(event)            // pass event for request-scoped config
+  const created = await db.insert(body, config.dbUrl)
+  setResponseStatus(event, 201)
+  return created
+})
+```
+
+Useful helpers: `getQuery(event)`, `getRouterParam(event, 'id')`, `readBody(event)`,
+`getHeader(event, 'x-...')`, `setResponseHeader`, `setResponseStatus`, `sendRedirect`,
+`getCookie`/`setCookie`, `createError`.
+
+## Server middleware
+
+```ts
+// server/middleware/log.ts
+export default defineEventHandler((event) => {
+  // runs on every request; do not return a body unless you mean to short-circuit
+  console.log(`${event.method} ${getRequestURL(event).pathname}`)
+})
+```
+
+## Runtime config (private vs public)
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  runtimeConfig: {
+    apiSecret: '',                 // server-only; override via NUXT_API_SECRET
+    dbUrl: '',                     // server-only; NUXT_DB_URL
+    public: {
+      apiBase: '/api',             // shipped to the browser; NUXT_PUBLIC_API_BASE
+    },
+  },
+})
+```
+
+Rule: anything under `public` (or any `NUXT_PUBLIC_*` env) is bundled into client JS and readable
+by every visitor. Keep secrets at the top level and read them only in `server/` code via
+`useRuntimeConfig(event)`. Empty-string defaults force the env var to be set in production.
+
+## Route-rule recipes
+
+`routeRules` in `nuxt.config.ts` sets per-route rendering and caching at the Nitro layer.
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/':              { prerender: true },                 // SSG at build time
+    '/docs/**':       { prerender: true },
+    '/blog/**':       { swr: 600 },                        // stale-while-revalidate, 10 min
+    '/products/**':   { isr: true },                       // ISR — cache until next deploy/revalidate
+    '/products/[id]': { isr: 3600 },                       // ISR with 1h TTL
+    '/dashboard/**':  { ssr: false },                      // client-only SPA island
+    '/legacy':        { redirect: '/new' },
+    '/feed.xml':      { headers: { 'content-type': 'application/xml' } },
+    '/api/**':        { cors: true, headers: { 'cache-control': 's-maxage=60' } },
+  },
+})
+```
+
+| Rule | Meaning |
+|---|---|
+| `prerender: true` | rendered at build, served as static HTML |
+| `swr: <s>` | cached server render, revalidated in the background after `<s>` seconds |
+| `isr: true \| <s>` | incremental static regeneration (needs a supporting preset, e.g. Vercel) |
+| `ssr: false` | no server render; ship an SPA shell for this route |
+| `redirect` / `headers` / `cors` | edge-level redirect, response headers, CORS |
+
+## Cached event handlers
+
+Cache expensive server work with `defineCachedEventHandler` (or `cachedFunction`):
+
+```ts
+export default defineCachedEventHandler(async (event) => {
+  return await expensiveAggregate()
+}, { maxAge: 60, swr: true, name: 'aggregate' })
+```
+
+Backed by Nitro storage; pick a KV/Redis storage driver for multi-instance deployments so the cache
+is shared.
+
+## Build & preset selection
+
+- `nuxt build` → SSR/hybrid server output in `.output/`.
+- `nuxt generate` → fully prerendered static site (every route must be prerenderable).
+- The **Nitro preset** picks the deploy target. Auto-detected on most platforms; set explicitly via
+  `nitro.preset` or the `NITRO_PRESET` env: `node-server`, `vercel`, `netlify`,
+  `cloudflare-pages`/`cloudflare-module`, `bun`, `static`, and more.
+
+```ts
+export default defineNuxtConfig({ nitro: { preset: 'node-server' } })
+```
+
+Choose the preset here, then defer platform specifics (env, edge config, adapters, domains) to
+`../deployment/SKILL.md`, `../vercel/SKILL.md`, `../netlify/SKILL.md`, `../cloudflare/SKILL.md`.

package/skills/vue-nuxt/references/reactivity.md

@@ -0,0 +1,135 @@
+# Reactivity deep dive (Vue 3.5)
+
+Companion to the SKILL "Composition API & reactivity core" section. Read it when a binding stops
+updating, an async effect races, or you are extracting a non-trivial composable.
+
+## `ref` vs `reactive` — pick `ref`
+
+- `ref` boxes any value behind `.value`; survives destructuring (you carry the box), works for
+  primitives, and reads uniformly. Templates auto-unwrap top-level refs.
+- `reactive` returns a deep Proxy of an object. It cannot hold primitives, breaks on destructure,
+  and a whole-object reassignment (`state = {...}`) detaches every consumer.
+- Rule: default to `ref`; reach for `reactive` only for a grouped object you never destructure and
+  never reassign.
+
+## Reactivity caveats
+
+```ts
+import { reactive, toRefs, toRef, ref } from 'vue'
+
+const state = reactive({ a: 1, b: 2 })
+const { a } = state           // ✗ detached primitive
+const { a: aRef } = toRefs(state)  // ✓ aRef.value linked
+const bRef = toRef(state, 'b')     // ✓ single-key ref
+
+// Reassigning a reactive loses every existing reference:
+let s = reactive({ n: 1 })
+// s = reactive({ n: 2 })     // ✗ old consumers keep the stale proxy
+s.n = 2                        // ✓ mutate in place
+```
+
+A `ref` of an object is deeply reactive by default. For large structures use `shallowRef`
+(reactivity only on `.value` replacement) or `shallowReactive` (only top-level keys) and replace
+the whole value to trigger updates.
+
+## `watch` vs `watchEffect` + cleanup
+
+- `watch(src, cb)` — lazy, gives `(new, old)`, explicit source; pass `{ immediate: true }` to run
+  once eagerly, `{ deep: true }` to track nested mutations of a `ref<object>`, `{ flush: 'post' }`
+  to run after DOM update.
+- `watchEffect(fn)` — runs immediately, auto-tracks whatever it reads, re-runs on any change. No
+  old value.
+- Always cancel stale async work so an out-of-order response can't overwrite a newer one:
+
+```ts
+import { watch, onWatcherCleanup } from 'vue'
+
+watch(query, async (q) => {
+  const ctrl = new AbortController()
+  onWatcherCleanup(() => ctrl.abort())   // 3.5: works without the cb arg
+  const res = await fetch(`/api/search?q=${q}`, { signal: ctrl.signal })
+  results.value = await res.json()
+})
+```
+
+## Effect scope
+
+`effectScope()` groups computed/watch effects so you can dispose them together — useful inside a
+composable that must tear down on demand. Effects created in `setup`/`onMounted` are auto-scoped to
+the component; effects created in a detached context (a singleton, a timer callback) are NOT and
+will leak unless you own a scope.
+
+```ts
+import { effectScope } from 'vue'
+const scope = effectScope()
+scope.run(() => { watch(/* ... */) })
+// later:
+scope.stop()
+```
+
+## Composable patterns
+
+A composable is a function named `useX` that uses Composition API internals and returns refs.
+Rules:
+
+- Call composables synchronously at the top of `setup` (or inside another composable), never inside
+  conditionals/loops — the same lifecycle constraint as React hooks.
+- Return refs (or readonly refs), not unwrapped values, so callers keep reactivity.
+- Accept refs/getters as input and normalize with `toValue()` so the composable works whether the
+  caller passes a raw value, a `ref`, or a getter.
+- No top-level module side effects — that runs once per server process and leaks across requests.
+
+```ts
+// composables/useMouse.ts
+import { ref, onMounted, onUnmounted } from 'vue'
+export function useMouse() {
+  const x = ref(0), y = ref(0)
+  const update = (e: MouseEvent) => { x.value = e.pageX; y.value = e.pageY }
+  onMounted(() => window.addEventListener('mousemove', update))   // browser-only, safe in onMounted
+  onUnmounted(() => window.removeEventListener('mousemove', update))
+  return { x, y }
+}
+```
+
+Composable, not mixin: mixins merge option objects invisibly and collide on names; composables are
+explicit, typed, and tree-shakeable.
+
+## Typed provide / inject
+
+Use an `InjectionKey<T>` so both ends are typed and you avoid string drift.
+
+```ts
+// keys.ts
+import type { InjectionKey, Ref } from 'vue'
+export const ThemeKey: InjectionKey<Ref<'light' | 'dark'>> = Symbol('theme')
+
+// provider
+provide(ThemeKey, theme)
+// consumer
+const theme = inject(ThemeKey)              // Ref<'light'|'dark'> | undefined
+const theme2 = inject(ThemeKey, ref('light'))  // with default
+```
+
+Provide a readonly ref + a mutator function when consumers should not write directly.
+
+## `defineModel` advanced
+
+```vue
+<script setup lang="ts">
+const model = defineModel<string>()                       // v-model
+const count = defineModel<number>('count', { default: 0 })// named: v-model:count
+const [name, modifiers] = defineModel<string>('name', {   // access v-model modifiers
+  set: (v) => modifiers.capitalize ? v.toUpperCase() : v,
+})
+</script>
+```
+
+`defineModel` compiles to the prop + `update:` emit pair; reading/writing `.value` is the
+two-way binding. Multiple named models on one component are fine.
+
+## Render functions / JSX
+
+`<script setup>` covers nearly everything. Drop to `h()` render functions or JSX (`@vitejs/plugin-vue-jsx`)
+only for highly dynamic component shapes a template can't express cleanly — a table that builds
+columns from data, a recursive tree renderer. Prefer templates otherwise: they get better
+compiler optimization (static hoisting, patch flags) and, in 3.6, Vapor compilation.

package/skills/vue-nuxt/scripts/verify.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# verify.sh — Vue 3 + Nuxt 4 project gate.
+#
+# Usage:
+#   bash scripts/verify.sh            # run from the Vue/Nuxt project root
+#
+# What it does (in order): typecheck -> package `lint` script -> Vitest -> build.
+#   - Nuxt repo  (nuxt.config.{ts,js,mjs} present): nuxi typecheck (fallback vue-tsc
+#     --noEmit), lint, vitest run, nuxi build.
+#   - Plain Vue repo (no Nuxt config):              vue-tsc --noEmit, lint, vitest run,
+#     vite build.
+# Each tool is detected; if it is not installed/resolvable, it is SKIPped with a yellow
+# warning (NOT a failure). Exits non-zero only on a real tool failure.
+#
+# Side effects: typecheck / lint / test are read-only. The final build WRITES output
+# (`.nuxt/` + `.output/` for Nuxt, `dist/` for plain Vue). It performs no installs and no
+# network mutations. Safe to re-run. Exits 0 on a clean/empty target (everything skipped).
+#
+# Portability: targets stock macOS bash 3.2. No `mapfile`, no empty-array expansion under
+# `set -u`, graceful degradation when a tool is missing. `set -e` is intentionally NOT used.
+
+set -u
+
+# --- colors (only when stdout is a TTY) -----------------------------------
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+skips=""
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s\n' "${YELLOW}SKIP: $1${RESET}"; skips="${skips}${skips:+ }$2"; return 0; }
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- resolve a package runner from the lockfile ----------------------------
+RUN=""
+if [ -f pnpm-lock.yaml ] && have pnpm; then
+  RUN="pnpm exec"
+elif [ -f yarn.lock ] && have yarn; then
+  RUN="yarn"
+elif [ -f package-lock.json ] && have npm; then
+  RUN="npm exec --"
+elif have npx; then
+  RUN="npx --no-install"
+fi
+
+run_bin() {
+  # run_bin <bin-name> <args...> : true if the bin is resolvable and runs
+  bin="$1"; shift
+  if have "$bin"; then "$bin" "$@"; return $?; fi
+  if [ -x "node_modules/.bin/$bin" ]; then "node_modules/.bin/$bin" "$@"; return $?; fi
+  if [ -n "$RUN" ]; then $RUN "$bin" "$@"; return $?; fi
+  return 127
+}
+
+bin_available() {
+  bin="$1"
+  have "$bin" && return 0
+  [ -x "node_modules/.bin/$bin" ] && return 0
+  return 1
+}
+
+# --- detect Nuxt vs plain Vue ----------------------------------------------
+IS_NUXT=false
+if [ -f nuxt.config.ts ] || [ -f nuxt.config.js ] || [ -f nuxt.config.mjs ]; then
+  IS_NUXT=true
+fi
+
+# Does package.json declare a "lint" script? (bash-3.2 safe, no jq/node)
+has_lint_script() {
+  [ -f package.json ] || return 1
+  grep -q '"lint"[[:space:]]*:' package.json 2>/dev/null
+}
+
+# --- 1. typecheck ----------------------------------------------------------
+if [ "$IS_NUXT" = true ] && bin_available nuxi; then
+  printf '%s\n' "Running nuxi typecheck..."
+  if run_bin nuxi typecheck; then ok "nuxi typecheck"; else fail "nuxi typecheck"; fi
+elif bin_available vue-tsc && [ -f tsconfig.json ]; then
+  printf '%s\n' "Running vue-tsc --noEmit..."
+  if run_bin vue-tsc --noEmit; then ok "vue-tsc --noEmit"; else fail "vue-tsc --noEmit"; fi
+else
+  warn "nuxi/vue-tsc (or tsconfig.json) not resolvable — skipping type check" "typecheck"
+fi
+
+# --- 2. lint (package script: ESLint / oxlint) -----------------------------
+if has_lint_script && [ -n "$RUN" ]; then
+  printf '%s\n' "Running package lint script..."
+  case "$RUN" in
+    "pnpm exec") LINT_CMD="pnpm run lint" ;;
+    "yarn")      LINT_CMD="yarn lint" ;;
+    "npm exec --") LINT_CMD="npm run lint" ;;
+    *)           LINT_CMD="npm run lint" ;;
+  esac
+  if $LINT_CMD; then ok "lint"; else fail "lint"; fi
+else
+  warn "no package lint script (or no package runner) — skipping lint" "lint"
+fi
+
+# --- 3. Vitest -------------------------------------------------------------
+# Treat as having unit tests when a vitest config exists OR *.test.* / *.spec.*
+# files exist (Vue/Nuxt commonly use either for unit tests).
+has_tests=false
+if ls vitest.config.* vitest.workspace.* >/dev/null 2>&1; then
+  has_tests=true
+elif find . \( -name node_modules -o -name .nuxt -o -name .output -o -name dist \) -prune -o \
+       \( -name '*.test.*' -o -name '*.spec.*' \) -print 2>/dev/null | grep -q .; then
+  has_tests=true
+fi
+if bin_available vitest && [ "$has_tests" = true ]; then
+  printf '%s\n' "Running vitest run..."
+  if run_bin vitest run; then ok "vitest"; else fail "vitest"; fi
+else
+  warn "vitest or tests (vitest.config.* / *.test.* / *.spec.*) not present — skipping unit tests" "vitest"
+fi
+
+# --- 4. build (slow; WRITES output; run last) ------------------------------
+if [ "$IS_NUXT" = true ]; then
+  if bin_available nuxi; then
+    printf '%s\n' "Running nuxi build... (writes .nuxt/ and .output/)"
+    if run_bin nuxi build; then ok "nuxi build"; else fail "nuxi build"; fi
+  else
+    warn "nuxi not resolvable — skipping build" "build"
+  fi
+else
+  if bin_available vite; then
+    printf '%s\n' "Running vite build... (writes dist/)"
+    if run_bin vite build; then ok "vite build"; else fail "vite build"; fi
+  else
+    warn "vite not resolvable — skipping build" "build"
+  fi
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\n'
+if [ -n "$skips" ]; then
+  printf '%s\n' "${YELLOW}skipped: ${skips}${RESET}"
+fi
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}verify.sh: $failures check(s) failed${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}verify.sh: all runnable checks passed${RESET}"
+exit 0

package/skills/webhooks/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: webhooks
+description: "Use when building the inbound side of a webhook — the HTTP endpoint that receives events a system pushes you, proves they are authentic, refuses to process the same one twice, and acks fast. Covers the mechanics every source shares: raw-body HMAC verification, ~5-min timestamp/replay window, idempotency on a stable event id, fast-ack-then-queue, retry/poison handling. Triggers: 'receive webhooks and process them safely', 'verify an incoming webhook signature', 'my signature verification fails even though the secret is correct', 'provider keeps retrying and we process the same event twice', 'handler times out under load, ack fast and queue', 'recibir webhooks entrantes', 'verificar la firma del webhook entrante', 'evitar procesar el mismo evento dos veces'. NOT the Stripe-Signature scheme (that is stripe), NOT email bounce/suppression hooks (that is email-connector), NOT outbound clients calling a third-party API (that is api-connector-builder), NOT what runs after the event lands (that is automation-flows)."
+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: risco
+---
+
+# 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. The deliverable is secret-safe
+server code plus minimal config: a handler that reads the **raw** request body
+for HMAC verification, compares signatures in **constant time**, rejects events
+outside a **timestamp tolerance**, **dedupes** on a stable event id, then
+**persists-or-enqueues before returning `2xx`**.
+
+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`.
+
+## The pipeline — non-negotiable order
+
+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." |
+
+Two facts make this order non-negotiable:
+
+- **Delivery is at-least-once, never exactly-once.** Every major provider
+  retries on non-2xx or timeout, so duplicate deliveries are normal traffic.
+  Idempotency is required, not a nice-to-have.
+- **The handler must be fast.** Heavy synchronous work inside it causes provider
+  timeouts and a storm of retries. Verify, dedupe, enqueue, ack — then work.
+
+## 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
+
+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 for each invariant (raw-body verify, constant-time compare,
+timestamp check, secret-from-env, dedupe-on-event-id). It is advisory, not a
+compiler — a WARN means "I could not find evidence," which on a clean/empty tree
+is expected and exits `0`.
+
+## Cross-references
+
+- Stripe's exact scheme and event model → `../stripe/SKILL.md`
+- Email bounce/complaint suppression webhooks → `../email-connector/SKILL.md`
+- The outbound API client (auth, pagination, retries you initiate) →
+  `api-connector-builder`
+- Orchestrating what happens after the event lands → `automation-flows`
+- Queue/broker concurrency and DLQ operations → `redis`
+- Constant-time compare, secret handling, supply-chain hygiene →
+  `../secure-coding/SKILL.md`

package/skills/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.