rsc-universal 0.1.1

package/skills/stripe/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: stripe
+description: "Use when wiring an app to Stripe for payments, subscriptions, Checkout, webhooks, or the billing portal — adding a paywall or Pro plan, charging recurring fees, or debugging why checkout.session.completed never fires or signature verification fails. Triggers: 'add Stripe Checkout', 'handle Stripe webhooks', 'let users cancel their subscription', 'No signatures found matching the expected signature', 'the webhook fires twice and duplicates the order', 'integrar pagos con Stripe', 'configurar el webhook de Stripe', 'portal de facturación del cliente'. NOT a generic non-Stripe inbound event receiver (that is webhooks), NOT the invoice document's legal form (that is invoicing), NOT deciding what to charge (that is pricing)."
+tags: [stripe, payments, subscriptions, checkout, webhooks, billing, saas]
+recommends: [webhooks, invoicing, pricing, secure-coding, nodejs]
+profiles: []
+origin: risco
+---
+
+# Stripe — Checkout, subscriptions, and webhooks that survive production
+
+Wire an app to Stripe for one-time payments and subscriptions: a Checkout
+Session to take money, a signature-verified webhook to learn the outcome, and
+the billing portal so customers manage themselves. Targets stripe-node v22.x
+(API version `2026-05-27.dahlia`).
+
+The one rule everything else hangs off:
+
+- **Stripe is the source of truth; your DB is a cache kept current by verified
+  webhooks.** A subscription's real state lives in Stripe. You mirror it locally
+  only so you can render a paywall without a round-trip. The webhook is what
+  keeps the mirror honest — never the client redirect, never polling.
+
+## When to use / When NOT to use
+
+**Use when:** adding Checkout or a paywall; taking a one-time or recurring
+charge; receiving Stripe webhooks; letting users cancel/upgrade via the portal;
+debugging `No signatures found matching`, double-fired events, or a
+`checkout.session.completed` that never arrives.
+
+**Do NOT use for:**
+
+- A **generic, non-Stripe inbound webhook receiver** (arbitrary HMAC, a
+  retry/queue consumer for any provider) → `webhooks`. This skill only covers
+  Stripe's `Stripe-Signature` scheme and event model.
+- The **invoice document's legal form** — what must appear on it, dunning copy,
+  payment-status as a business process → [invoicing](../invoicing/SKILL.md).
+- **Cash-flow forecasting, bank reconciliation, month-close** →
+  [finance-ops](../finance-ops/SKILL.md).
+- **What to charge / plan tiers / packaging** → [pricing](../pricing/SKILL.md).
+  This skill implements a price; it does not decide it.
+- A **typed client for some other REST API** → `api-connector-builder`.
+
+## Pick the surface
+
+| You need | Use | Why |
+|---|---|---|
+| A link to sell one product, zero code | Payment Link | No backend; Stripe hosts everything. Outgrow it fast. |
+| Hosted checkout, full control of session | **Checkout Session** | The default. Stripe hosts the page, handles SCA/3DS, PCI scope is minimal. |
+| Your own embedded payment form | Payment Element + Checkout Session | Custom UI, but you render the form. Use the Element *with* a Checkout Session, not raw PaymentIntents, unless you have a reason. |
+
+Default to **Checkout Session** unless a requirement forces otherwise.
+
+## Mental model
+
+```text
+Customer ──> Price (you defined it in Stripe) ──> Checkout Session
+   │                                                    │
+   │                                          customer pays (hosted)
+   ▼                                                    ▼
+your DB  <── webhook (verified) ── Event <── Subscription / Invoice
+(a cache)                                    (the real state, in Stripe)
+```
+
+Env vars used throughout — read from the environment, never hard-code:
+
+- `STRIPE_SECRET_KEY` — `sk_test_…` in dev, `sk_live_…` in prod.
+- `STRIPE_WEBHOOK_SECRET` — `whsec_…`, one per endpoint; differs in test vs live.
+
+## Construct the client (pin the API version)
+
+```ts
+import Stripe from "stripe";
+
+// Pin apiVersion explicitly so a dashboard-level version bump can never change
+// your API behavior under you. Match the version your SDK release ships with.
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: "2026-05-27.dahlia",
+});
+```
+
+## Create a Checkout Session
+
+```ts
+// Subscription mode — recurring price.
+const session = await stripe.checkout.sessions.create({
+  mode: "subscription",
+  line_items: [{ price: "price_123", quantity: 1 }], // a recurring Price ID
+  success_url: `${BASE}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${BASE}/pricing`,
+  // Tie the session to YOUR user so the webhook can find the right row.
+  client_reference_id: userId,
+  // 14-day trial; omit for immediate billing.
+  subscription_data: { trial_period_days: 14 },
+});
+// Redirect the browser to session.url.
+```
+
+```ts
+// Payment mode — one-time charge (e.g. a digital download).
+const session = await stripe.checkout.sessions.create({
+  mode: "payment",
+  line_items: [{ price: "price_onetime", quantity: 1 }],
+  success_url: `${BASE}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${BASE}/`,
+  client_reference_id: userId,
+});
+```
+
+`success_url` is a UX redirect, not proof of payment. The customer can close the
+tab before it loads, or hit the URL directly. **Grant access from the webhook,
+not the redirect.**
+
+## The webhook handler (load-bearing)
+
+This is where integrations break. Three non-negotiables:
+
+1. **Verify against the RAW body.** `constructEvent` recomputes the signature
+   over the exact bytes Stripe sent. Any middleware that parses/re-serializes
+   the body (e.g. `express.json()` on this route) changes those bytes and you
+   get `No signatures found matching the expected signature`.
+2. **Return 2xx before slow work.** Verify, record the event, return 200
+   immediately. Stripe treats a timeout as failure and retries — for up to 3
+   days in live mode — so slow handlers cause duplicate delivery.
+3. **Be idempotent.** Events are unordered and may arrive more than once.
+   Dedupe on `event.id`, persisting the idempotency record in the *same
+   transaction* as the business write. Default replay tolerance is 5 minutes.
+
+```ts
+// Express. The route gets the RAW body; do NOT mount express.json() here.
+app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      req.body,                          // raw Buffer, untouched
+      req.headers["stripe-signature"]!,  // header name is lowercase
+      process.env.STRIPE_WEBHOOK_SECRET!,
+    );
+  } catch (err) {
+    return res.status(400).send(`Webhook Error: ${(err as Error).message}`);
+  }
+
+  // Dedupe + record in one transaction; skip if we have seen this event.id.
+  const fresh = await recordEventOnce(event.id, event.type);
+  if (!fresh) return res.status(200).send(); // already processed; ack and stop
+
+  // Return 2xx FAST. Hand heavy work to a queue/background job if it is slow.
+  switch (event.type) {
+    case "checkout.session.completed": {
+      const s = event.data.object as Stripe.Checkout.Session;
+      await grantAccess(s.client_reference_id!, s.customer as string);
+      break;
+    }
+    case "customer.subscription.updated":
+    case "customer.subscription.deleted": {
+      const sub = event.data.object as Stripe.Subscription;
+      await syncSubscription(sub.customer as string, sub.status); // mirror state
+      break;
+    }
+    case "invoice.payment_failed":
+      // dunning lives here; see references/webhook-events.md
+      break;
+  }
+  res.status(200).send();
+});
+```
+
+See [`references/webhook-events.md`](references/webhook-events.md) for the full
+event catalog per flow (subscription lifecycle, one-time payment, dunning) and
+what each event should do to your DB.
+
+### Framework gotchas (raw body)
+
+```ts
+// Next.js App Router — read the raw text yourself; do not use req.json().
+// app/api/webhook/route.ts
+export async function POST(req: Request) {
+  const body = await req.text();                       // raw string
+  const sig = req.headers.get("stripe-signature")!;
+  const event = stripe.webhooks.constructEvent(body, sig, secret);
+  // ...handle, then:
+  return new Response(null, { status: 200 });
+}
+```
+
+```ts
+// Edge / Cloudflare Workers — synchronous crypto is unavailable. Use the async
+// API with the Web Crypto provider.
+const event = await stripe.webhooks.constructEventAsync(
+  body, sig, secret, undefined, Stripe.createSubtleCryptoProvider(),
+);
+```
+
+## Subscribe to only the events you need
+
+For a subscription paywall, listen to exactly these — listening to "all events"
+is discouraged and buries you in noise:
+
+`checkout.session.completed`, `customer.subscription.created`,
+`customer.subscription.updated`, `customer.subscription.deleted`,
+`invoice.paid`, `invoice.payment_failed`.
+
+## Billing portal (self-service)
+
+Do not build cancel/upgrade/update-card UI. Stripe hosts it.
+
+```ts
+const portal = await stripe.billingPortal.sessions.create({
+  customer: stripeCustomerId,             // the Customer you stored
+  return_url: `${BASE}/account`,
+});
+// Redirect to portal.url — it is short-lived; mint it on demand, never cache it.
+```
+
+## Idempotency on create calls
+
+A retried POST (network blip, double-click) can create two subscriptions.
+Pass an idempotency key derived from the operation, not a random one:
+
+```ts
+await stripe.checkout.sessions.create(params, {
+  idempotencyKey: `checkout:${userId}:${planId}`,
+});
+```
+
+## Local testing — Stripe CLI, never hand-crafted JSON
+
+```bash
+stripe login
+stripe listen --forward-to localhost:3000/api/webhook   # prints a whsec_… secret
+stripe trigger checkout.session.completed                # fire a real test event
+```
+
+Put the printed `whsec_…` in `STRIPE_WEBHOOK_SECRET` for local runs. Hand-built
+JSON will never pass signature verification — that is the point.
+
+## Going live
+
+Compact checklist; depth in [`references/going-live.md`](references/going-live.md):
+
+- [ ] `apiVersion` pinned explicitly in the client.
+- [ ] Swap `sk_test_`/`whsec_` (test) for live values via env, not code.
+- [ ] Create the live webhook endpoint; copy its **own** signing secret.
+- [ ] Restrict the event subscription to the allowlist above.
+- [ ] Use **restricted API keys** for the server, not the unrestricted secret.
+- [ ] Idempotency keys on all create calls.
+- [ ] Confirm SCA/3DS is handled (Checkout does this for you).
+
+## Anti-patterns
+
+| Bad | Good | Why |
+|---|---|---|
+| `express.json()` on the webhook route | `express.raw()` / `req.text()` | Re-serialized body breaks the signature → `No signatures found matching`. |
+| No `constructEvent` — trust the payload | Always verify the signature | Anyone can POST fake events to an unverified endpoint. |
+| Grant access on the `success_url` redirect | Grant on `checkout.session.completed` | The redirect is UX, not proof; it can be skipped or forged. |
+| DB writes, then return 200 | Return 200 fast, queue slow work | Timeouts make Stripe retry → duplicate delivery. |
+| Process every delivery | Dedupe on `event.id` in the write txn | Events are unordered and at-least-once. |
+| Hard-coded `sk_live_…` in source | `process.env.STRIPE_SECRET_KEY` | Leaked keys = drained account; never commit them. |
+| No `apiVersion` | Pin it explicitly | A dashboard version bump silently changes your API behavior. |
+| Poll the API for subscription state | React to webhooks | Polling is slow, rate-limited, and races real events. |
+| Listen to all event types | Subscribe to the allowlist | Noise, wasted handling, accidental side effects. |
+| Cache the portal/session URL | Mint per request | These URLs are short-lived and single-use. |
+
+## See also
+
+- `webhooks` — generic, non-Stripe inbound event receivers.
+- [invoicing](../invoicing/SKILL.md) — the invoice document and its legal form.
+- [pricing](../pricing/SKILL.md) — deciding tiers and amounts before you wire them.
+- [secure-coding](../secure-coding/SKILL.md) — secret handling, key restriction.

package/skills/stripe/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — stripe
+
+`cases.yaml` holds three groups scored by an LLM judge against the rendered
+skill. `should_trigger` and `should_not_trigger` check routing: each prompt is
+classified and we confirm Stripe owns it (or that it correctly defers to the
+named sibling — `route_to` ids are real skills). `capability` checks that the
+SKILL.md plus `references/` actually contain enough to satisfy the `must_include`
+rubric for a subscription-paywall build. Run these through the repo's eval runner
+(it discovers `evals/cases.yaml` under each skill); there is no standalone
+harness here. Treat a judge miss as a prompt to sharpen the description's
+triggers/boundary or to fill a gap in the body, not as noise.

package/skills/stripe/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: stripe
+
+should_trigger:
+  - prompt: "Add a Pro subscription tier with Stripe Checkout to my SaaS."
+    why: Core build — subscription-mode Checkout Session plus webhook to grant access.
+  - prompt: "My Stripe webhook returns 400 with 'No signatures found matching the expected signature'."
+    why: Non-obvious symptom of the raw-body/signature-verification bug this skill owns.
+  - prompt: "The Stripe webhook fires twice and creates the order twice."
+    why: Idempotency / dedupe on event.id — a core handler concern, not obvious from the word 'twice'.
+  - prompt: "Let customers cancel and upgrade their plan themselves without me building UI."
+    why: Customer billing portal session.
+  - prompt: "El webhook de Stripe se ejecuta dos veces y duplica el pedido."
+    why: Spanish phrasing of the idempotency problem; same skill.
+  - prompt: "Set up recurring billing with a 14-day free trial in Stripe."
+    why: Subscription mode with trial_period_days.
+  - prompt: "Charge a one-time payment for a digital download via Stripe."
+    why: payment-mode Checkout Session and fulfillment on checkout.session.completed.
+
+should_not_trigger:
+  - prompt: "Verify the HMAC on an incoming GitHub webhook and put it on a retry queue."
+    route_to: webhooks
+    why: Generic non-Stripe inbound receiver; not Stripe's Stripe-Signature scheme.
+  - prompt: "What must legally appear on the invoice I email the client, and what's the dunning copy?"
+    route_to: invoicing
+    why: The invoice document and its legal form, not Stripe API wiring.
+  - prompt: "Should our Pro plan be $29 or $49, and how many tiers should we offer?"
+    route_to: pricing
+    why: Packaging/amount decision, not implementation.
+  - prompt: "Build a 13-week cash-flow forecast and reconcile the bank statement."
+    route_to: finance-ops
+    why: Forecasting and reconciliation, not payment integration.
+  - prompt: "Build a typed client for the Acme REST API with retries and backoff."
+    route_to: api-connector-builder
+    why: Generic third-party API client, unrelated to Stripe.
+
+capability:
+  - scenario: "Add a subscription paywall to a Next.js app: a Checkout Session, a webhook handler, and a self-service billing portal."
+    must_include:
+      - "Checkout Session created with mode: 'subscription' and both success_url and cancel_url."
+      - "Webhook verifies the RAW body with stripe.webhooks.constructEvent using STRIPE_WEBHOOK_SECRET."
+      - "Returns a 2xx before slow work and dedupes on event.id."
+      - "Handles checkout.session.completed plus customer.subscription.updated/deleted."
+      - "Billing portal via stripe.billingPortal.sessions.create({ customer, return_url })."
+      - "Keys read from process.env, explicit apiVersion pin, no hard-coded sk_ literal."
+      - "Access granted from the webhook, not from the success_url redirect."

package/skills/stripe/references/going-live.md

@@ -0,0 +1,64 @@
+# Going live — production hardening
+
+The Checkout/webhook code is the easy part. These are the things that bite in
+production.
+
+## Test → live cutover
+
+- Test and live mode have **separate keys, separate webhook endpoints, separate
+  signing secrets, and separate data**. Nothing crosses over.
+- Create the live webhook endpoint in the dashboard; copy its **own**
+  `whsec_…`. The CLI secret from `stripe listen` is for local only.
+- Swap keys via environment/secret manager, never by editing code. A `sk_live_`
+  literal in source is a drainable credential.
+
+## Restricted API keys
+
+Do not run the server with the account's unrestricted secret key. Create a
+**restricted key** granting only the resources you touch (e.g. write on
+Checkout Sessions, Customers, Subscriptions; read on Prices). If it leaks, blast
+radius is bounded. Rotate it on suspicion of exposure.
+
+## Webhook secret rotation
+
+When rotating a webhook signing secret, Stripe lets you keep the old secret
+valid during a roll window. Verify against both during the overlap, then drop
+the old one. Never log the secret or the raw signature header.
+
+## Idempotency keys
+
+Every create call that a retry could duplicate (`checkout.sessions.create`,
+`subscriptions.create`, `customers.create`) takes an `idempotencyKey`. Derive it
+from the operation (`checkout:${userId}:${planId}`), not `Math.random()`, so a
+genuine retry collides and Stripe returns the original result instead of making
+a second object.
+
+## SCA / 3DS
+
+Strong Customer Authentication and 3D Secure are handled for you by Checkout and
+the Payment Element — that is a core reason to prefer them over hand-rolled
+PaymentIntents + cards. Don't reimplement the authentication dance.
+
+## Test clocks
+
+To exercise renewals, trials ending, and dunning without waiting real days,
+attach a Customer to a **test clock** and advance time. This is the only sane
+way to test the multi-day subscription lifecycle.
+
+## PCI scope
+
+With Checkout (Stripe-hosted) or the Payment Element, card data never touches
+your server, keeping you in the lightest PCI tier (SAQ A-class). Raw card
+numbers hitting your backend escalate scope dramatically — don't.
+
+## Pre-launch checklist
+
+- [ ] `apiVersion` pinned in the client.
+- [ ] Live keys/secret in env, not code; test literals gone.
+- [ ] Live webhook endpoint created; its own signing secret wired.
+- [ ] Event subscription restricted to the allowlist you actually handle.
+- [ ] Restricted API key in use on the server.
+- [ ] Idempotency keys on all create calls.
+- [ ] Webhook handler verifies signature, returns 2xx fast, dedupes on `event.id`.
+- [ ] Access gated on `subscription.status`, refreshed by webhooks.
+- [ ] Tested the renewal/dunning path against a test clock.

package/skills/stripe/references/webhook-events.md

@@ -0,0 +1,79 @@
+# Stripe webhook events — catalog per flow
+
+What to listen for and what each event should do to your DB. Subscribe to only
+the events a flow needs; "send all events" is discouraged.
+
+## Subscription paywall
+
+| Event | What it means | DB action |
+|---|---|---|
+| `checkout.session.completed` | Customer finished Checkout (paid or trial started) | Link `client_reference_id` (your user) to `session.customer`; mark provisional access. |
+| `customer.subscription.created` | Subscription now exists | Store `subscription.id`, `status`, `current_period_end`, price ID. |
+| `customer.subscription.updated` | Plan changed, renewed, trial→active, past_due, canceled-at-period-end | Re-sync `status` and `current_period_end`. This is the workhorse; gate access on `status`. |
+| `customer.subscription.deleted` | Subscription ended | Revoke access. |
+| `invoice.paid` | A billing cycle was paid | Confirm/extend access; optionally store the invoice ref. |
+| `invoice.payment_failed` | A charge failed | Enter dunning (below); do not revoke immediately. |
+
+Gate access on `subscription.status` (`active` or `trialing` = entitled;
+`past_due`/`unpaid`/`canceled` = not), not on a single "is_pro" boolean you
+set once at checkout.
+
+## One-time payment
+
+| Event | DB action |
+|---|---|
+| `checkout.session.completed` (mode `payment`) | Fulfill the order / unlock the download. The primary signal. |
+| `payment_intent.succeeded` | Optional confirmation if you also create PaymentIntents directly. |
+
+## Dunning (failed payment)
+
+`invoice.payment_failed` starts Stripe's automatic retry schedule (Smart
+Retries / your dunning settings). Do not revoke on the first failure — Stripe
+will retry. Mark the account `past_due` and surface a "update your card"
+prompt (link to the billing portal). Revoke only when
+`customer.subscription.deleted` fires.
+
+## Thin events vs snapshot events
+
+- **Snapshot events** (`event.data.object`) embed a full object snapshot at send
+  time. Convenient, but the object may already be stale by the time you process
+  it out of order.
+- **Thin events** carry only IDs; you fetch the current object yourself. They
+  are inherently fresher.
+
+Whichever you receive, for state that matters (subscription status), re-fetch
+or trust the latest `customer.subscription.updated` rather than reconstructing
+state from an ordered sequence — events are not ordered.
+
+## Raw-body recipes by framework
+
+```ts
+// Express — raw on this route only; keep express.json() for other routes.
+app.post("/webhook", express.raw({ type: "application/json" }), handler);
+```
+
+```ts
+// Next.js App Router — route segment runs on Node by default; read raw text.
+export async function POST(req: Request) {
+  const body = await req.text();
+  const sig = req.headers.get("stripe-signature")!;
+  const event = stripe.webhooks.constructEvent(body, sig, secret);
+  // ...
+  return new Response(null, { status: 200 });
+}
+```
+
+```ts
+// Next.js Pages Router — disable the body parser, read the raw stream.
+export const config = { api: { bodyParser: false } };
+```
+
+```ts
+// Edge / Workers — no Node crypto; use the async API + Web Crypto provider.
+const event = await stripe.webhooks.constructEventAsync(
+  body, sig, secret, undefined, Stripe.createSubtleCryptoProvider(),
+);
+```
+
+The header name is lowercase `stripe-signature`. Default replay tolerance is
+5 minutes; a clock skew larger than that rejects valid events.

package/skills/stripe/scripts/verify.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — stripe integration static linter
+#
+# USAGE
+#   ./verify.sh [TARGET]
+#   TARGET is a file or directory (default: current directory). Run it against
+#   the source that wires your app to Stripe. READ-ONLY: it never edits files.
+#
+# WHAT IT CHECKS (FAIL on any violation)
+#   1. Hard-coded sk_live_ / sk_test_ / whsec_ literals in source.
+#   2. A webhook handler (uses constructEvent / handles stripe-signature) that
+#      also applies JSON body parsing on that route — the raw-body violation
+#      that yields "No signatures found matching the expected signature".
+#   3. A webhook route present with NO signature verification at all.
+#   4. A Stripe client constructed with no explicit apiVersion pin.
+#
+# GUARANTEES
+#   - Read-only and idempotent; writes nothing to the target.
+#   - Exit 0 on a clean OR empty/no-Stripe target (never a false failure).
+#   - No network. Portable to stock macOS bash 3.2.
+#
+# EXIT CODES
+#   0  No violations (clean, or nothing Stripe-related found).
+#   1  At least one violation.
+# ============================================================================
+
+TARGET="${1:-.}"
+
+RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
+if [ -n "${NO_COLOR:-}" ]; then RED=""; YEL=""; GRN=""; RST=""; fi
+
+FAILED=0
+bad()  { printf '%s[FAIL]%s %s\n' "$RED" "$RST" "$*" >&2; FAILED=1; }
+ok()   { printf '%s[ok]%s %s\n'   "$GRN" "$RST" "$*"; }
+info() { printf '%s[info]%s %s\n' "$YEL" "$RST" "$*"; }
+
+if [ ! -e "$TARGET" ]; then
+  info "target '$TARGET' does not exist; nothing to check"
+  exit 0
+fi
+
+# Collect candidate source files (JS/TS family). Skip vendored/build dirs.
+FILES=""
+if [ -f "$TARGET" ]; then
+  FILES="$TARGET"
+else
+  FILES=$(find "$TARGET" \
+    \( -name node_modules -o -name .git -o -name dist -o -name build -o -name .next \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' \) -print 2>/dev/null || true)
+fi
+
+if [ -z "$FILES" ]; then
+  info "no JS/TS source files under '$TARGET'; nothing to check"
+  exit 0
+fi
+
+# --- 1. Hard-coded keys -----------------------------------------------------
+# Match real Stripe key prefixes followed by a body char. Documentation/example
+# placeholders like sk_test_... or sk_test_xxx are ignored.
+KEY_HITS=$(grep -REn "(sk_live|sk_test|whsec)_[A-Za-z0-9]{6,}" $FILES 2>/dev/null | grep -Ev "x{6,}|\.\.\.|YOUR_|<|placeholder" || true)
+if [ -n "$KEY_HITS" ]; then
+  bad "hard-coded Stripe key literal(s) — read from env instead:"
+  printf '%s\n' "$KEY_HITS" >&2
+else
+  ok "no hard-coded Stripe key literals"
+fi
+
+# --- Identify webhook-handling files ----------------------------------------
+# A file is "webhook-related" if it references the stripe-signature header or
+# the constructEvent API.
+WEBHOOK_FILES=""
+for f in $FILES; do
+  if grep -Eqi "stripe-signature|constructEvent" "$f" 2>/dev/null; then
+    WEBHOOK_FILES="$WEBHOOK_FILES $f"
+  fi
+done
+
+if [ -z "$WEBHOOK_FILES" ]; then
+  info "no Stripe webhook handler found; skipped webhook checks"
+else
+  for f in $WEBHOOK_FILES; do
+    # 2. raw-body violation: JSON parsing on a route that also verifies.
+    if grep -Eqi "express\.json|bodyParser\.json|req\.json\(\)|await\s+req\.json|res\.json" "$f" 2>/dev/null \
+       && grep -Eqi "express\.json\(\)|bodyParser\.json|req\.json\(\)|await\s+req\.json" "$f" 2>/dev/null; then
+      bad "$f: webhook handler parses JSON body (express.json/req.json) — breaks signature verification; use raw body (express.raw / await req.text())"
+    fi
+
+    # 3. signature verification present?
+    if grep -Eqi "constructEvent" "$f" 2>/dev/null; then
+      ok "$f: verifies webhook signature (constructEvent)"
+    else
+      bad "$f: handles stripe-signature but never calls constructEvent — unverified webhook"
+    fi
+  done
+fi
+
+# --- 4. apiVersion pin on the Stripe client ---------------------------------
+# For each file that constructs `new Stripe(`, require an apiVersion within the
+# same file.
+CLIENT_FILES=""
+for f in $FILES; do
+  if grep -Eq "new\s+Stripe\s*\(" "$f" 2>/dev/null; then
+    CLIENT_FILES="$CLIENT_FILES $f"
+  fi
+done
+
+if [ -z "$CLIENT_FILES" ]; then
+  info "no 'new Stripe(' client construction found; skipped apiVersion check"
+else
+  for f in $CLIENT_FILES; do
+    if grep -Eq "apiVersion" "$f" 2>/dev/null; then
+      ok "$f: Stripe client pins apiVersion"
+    else
+      bad "$f: 'new Stripe(' without an explicit apiVersion pin"
+    fi
+  done
+fi
+
+# --- Summary ----------------------------------------------------------------
+printf '\n'
+if [ "$FAILED" -eq 0 ]; then
+  ok "PASS — no Stripe integration violations"
+else
+  printf '%sFAIL — Stripe integration violations above%s\n' "$RED" "$RST" >&2
+fi
+exit "$FAILED"