create-ailk 0.5.0 → 0.6.0

package/templates/apps/api/src/routes/webhooks/README.md

@@ -0,0 +1,265 @@
+# Webhooks — `apps/api/src/routes/webhooks/`
+
+Stripe webhook receiver at `POST /v1/webhooks/stripe`. Verifies
+signatures, dispatches events via a `switch`, and fires server-side
+telemetry. Handles `customer.created`, `checkout.session.completed`, and
+`checkout.session.expired` (the last two also stamp the recommender's
+buyer row — below).
+
+## Commerce claim — signature first, claim second (D-64, #5796)
+
+The receiver is a base-tree **primitive**: it registers on every build, with
+no `isModuleEnabled("commerce")` gate, and decides whether to act on the JWT
+`features[]` claim `commerce` (`lib/require-commerce-claim.ts`, read at call
+time through `checkLicense()`). The order inside `stripe.ts` is fixed and
+load-bearing: **the Stripe signature is verified BEFORE the claim is
+consulted.** An unsigned body therefore never reaches the claim check on its
+own merits, and the two unclaimed outcomes are:
+
+- **Signed, verifiable event, licence read and positively unclaimed** →
+  **200 `{received: true}`**, the event dropped with a structured `warn` log
+  line (`outcome: "dropped_no_commerce_claim"`). A 4xx here would have Stripe
+  retry the event for days against a site that turned commerce off. It is
+  logged at `warn`, not `info`: a discarded Stripe event is never routine.
+- **Missing secret / non-Buffer body / missing or invalid signature, licence
+  read and unclaimed** → the **module-disabled 404**, byte-identical to a
+  build that never carried the commerce module. A site without the claim is
+  indistinguishable from a site without the module, which is the point.
+
+With the claim, every mapping in the § above is exactly what it was before
+the gate existed.
+
+### The claim is a TRI-state, and `undetermined` is never a drop
+
+Security review (2026-09-16, High) against the first cut of this gate: a
+boolean `hasCommerceClaim()` returned one `false` both for "the licence says
+no" and for "the licence could not be read". On the second, a **live** commerce
+site whose read merely failed would ack a signed `checkout.session.completed`
+200 and lose it — Stripe records success, never redelivers, and the charge is
+never mapped to a customer. The pre-#5796 module flag was build-time and its
+off state 404'd, which Stripe retried; the runtime gate introduced the loss.
+
+So `resolveCommerceClaim()` answers `claimed | unclaimed | undetermined`, and
+**`undetermined` → 503 with `Retry-After: 300`**, which makes Stripe queue the
+event and redeliver it once the read succeeds — well inside Stripe's three-day
+redelivery window. The drop and the hold are both logged at `warn`
+(`outcome: "dropped_no_commerce_claim"` and `outcome: "license_undetermined"`):
+neither a discarded nor a held Stripe event is routine.
+
+`undetermined` covers every read that established no "no" (operator-disposed,
+round 2):
+
+- **`checkLicense()` threw.**
+- **A revoked licence** (`revoked === true`). It keeps verifying locally until
+  JWT `exp` (ADR 0014), so this is a paying commerce site mid-window whose
+  events are still real. Closing the gate is right; dropping the events is the
+  review's High under another label.
+- **A licence is configured yet resolves free** — the expired case, and any
+  other JWT that no longer verifies. `checkLicense()` returns the _same_
+  `FREE_RESULT` for expired, invalid and keyless alike, so the only signal that
+  separates them is whether a licence is CONFIGURED at all. The gate tests that
+  the same way `check-license.ts` resolves a token — `AILK_LICENSE_KEY`, else
+  the refresh storage file — for presence only: it parses no JWT and
+  re-implements no verification. Reading the storage file matters, because a
+  deployment can be fully licensed with no env key at all; an env-only test
+  read such a site as keyless, so its EXPIRED licence dropped already-charged
+  events.
+- **The licence storage file is UNREADABLE** (#5820) — EACCES, EIO, EMFILE, a
+  directory at its path, a filesystem that went away. See below.
+
+`unclaimed` is therefore reserved for a positively-established "no": a licence
+that reads successfully and simply lacks the claim, or a keyless deployment
+that configures no licence at all — where "no licence at all" now means the
+storage file was positively read as ABSENT, not merely that reading it failed.
+
+### `unreadable` is not `absent` (#5820)
+
+The gate reads the storage file through `readStoredJwtState()`
+(`packages/license/src/storage.ts`), which answers **`absent` · `unreadable` ·
+`present`**:
+
+- **`absent`** — ENOENT, or a file holding nothing but whitespace. The only
+  state that is evidence of an unlicensed site, and therefore the only one on
+  this path that may drop a signed event.
+- **`unreadable`** — every other read failure. Evidence of nothing, so it
+  resolves `undetermined` → **503 + `Retry-After: 300`**, logged with the
+  errno `code` (`outcome: "license_storage_unreadable"`).
+- **`present`** — the token; resolution continues exactly as for an env key.
+
+This closes the last gap in the tri-state. `readStoredJwt()` catches every read
+error and returns the same `null` it returns for "no file", so before this a
+transient EACCES on a storage-licensed site read as keyless: a signed
+`checkout.session.completed` in that window was acked 200, Stripe never
+redelivered it, and the charge was never mapped. `readStoredJwt()`'s own
+contract is unchanged — `checkLicense()` and every other caller still see one
+`null` for both states — so only the gate's resolution moved.
+
+**The checkout launcher does not hold.** It answers the module-disabled 404 on
+both `unclaimed` and `undetermined`: a checkout that cannot be started loses
+nothing, so there is no call to leak a "configured but unreadable" shape on it.
+The webhook holds because by the time an event arrives the buyer's money has
+already moved.
+
+## How to add a new event handler
+
+Add a `case` arm to the `switch` in `stripe.ts`:
+
+```ts
+case "invoice.payment_succeeded": {
+  const invoice = event.data.object as { ... };
+  await fireTelemetryWithTimeout(request, "invoice-paid", { ... });
+  break;
+}
+```
+
+Customer forks edit `stripe.ts` directly. v1 ships no pluggable handler
+registry — if multiple forks request one, file an issue.
+
+## Recommender purchase stamp (#4838)
+
+A Checkout Session the recommender opened (`POST /v1/flows/:slug/checkout`,
+#4841) carries `metadata.flowCheckoutId` — the `FlowCheckout` buyer row's
+id. On `checkout.session.completed` the handler stamps that row
+`status: "completed"` (+ `completedAt`, `stripeSessionId`,
+`stripeCustomerId`); on `checkout.session.expired` it stamps
+`status: "expired"`. Both are ONE guarded update —
+`updateMany({ where: { id, status: "created" } })` — so the stamp is
+at-most-once regardless of the in-memory store below: a replay, a restart
+between deliveries, or a late `expired` after a `completed` matches zero
+rows and logs `outcome: "stale_or_unknown"`. A charged `amount_total` that
+differs from the quoted `amountMinor` is logged (`expected` / `received`)
+and the row is still stamped — the quote is never overwritten. The stamp
+runs beside the telemetry + billing tasks, never instead of them, and an
+event without the key never touches `flowCheckout`. Always 200.
+
+## Dunning (#6034)
+
+Two arms record a per-subscriber lifecycle state so a failed renewal is no
+longer silent:
+
+- **`invoice.payment_failed`** — arms dunning for the `User` matched by the
+  invoice's Stripe customer id: the recorded state becomes `past_due`,
+  `dunningArmedAt` is stamped once (never moved while the subscription stays
+  failing), `accessState` stays `granted`. **This arm never revokes.**
+- **`customer.subscription.updated`** — maps the narrowed Stripe status
+  (`services/dunning-policy.ts`'s reuse of
+  `@working-theory/stripe-client`'s `toSubscriptionLifecycleStatus`) onto the
+  same record. `active`/`trialing` return the entry to a clean state
+  (`dunningArmedAt: null`, `accessRevokesAt: null`) so a recovered
+  subscriber's read shows nothing. `past_due`/`unpaid` arm exactly as
+  `invoice.payment_failed` does. `canceled` is the **only revoking
+  transition** — access is revoked once a per-tenant grace period, computed
+  from the FIRST failure, has already passed; if it hasn't, access is
+  retained and a revocation is scheduled.
+
+### The record
+
+One `UserData` row per subscriber (`userId_key` unique), reserved key
+`commerce.subscription_dunning`, holding a MAP keyed by Stripe subscription
+id — one customer can hold more than one subscription, and a flat blob would
+let a second subscription's `active` clobber the first's `past_due`:
+
+```jsonc
+{
+  "v": 1,
+  "subscriptions": {
+    "sub_1AbC…": {
+      "status": "past_due", // "past_due" | "active" | "canceled"
+      "accessState": "granted", // "granted" | "revoked"
+      "dunningArmedAt": "2026-09-18T04:12:00.000Z", // ISO-8601, or null
+      "accessRevokesAt": null, // ISO-8601, or null — set only on `canceled`
+      "lastEventAt": 1789000000, // Stripe event.created, seconds
+      "lastEventId": "evt_1XyZ…",
+    },
+  },
+}
+```
+
+Capped at 50 subscriptions per customer, evicting the oldest SETTLED entries
+(`status: "active"`, `accessState: "granted"`) first — an entry still being
+dunned is never evicted mid-decision.
+
+**No scheduler flips this.** `accessRevokesAt` is a lazily-evaluated
+deadline; nothing wakes up to act on it. Two exported read-side predicates
+(`services/dunning-policy.ts`) are the reader's contract instead:
+
+- `isSubscriberRevoked(entry, now?)` — access is gone: either already stamped
+  `revoked`, or `now` has passed the scheduled `accessRevokesAt`.
+- `isSubscriberActionRequired(entry, now?)` — the buyer must act (#6038's
+  banner predicate). Deliberately WIDER than `status === "past_due"`: a
+  subscription cancelled with its grace window still open
+  (`status: "canceled"`, `accessState: "granted"`, `accessRevokesAt`
+  non-null) is a buyer about to lose access who hasn't been told.
+
+**Ordering, ties, and durable replay.** Every write is a compare-and-swap
+whose `where` restates BOTH the observed `updatedAt` AND the observed
+`value` — a concurrent writer makes the predicate miss rather than silently
+overwrite. The SAME `event.id` replayed (even after a process restart, when
+the in-memory `hasSeen` map has forgotten it) is a no-op; a strictly OLDER
+event is stale; an EQUAL-timestamp write that would move the entry toward
+LESS restriction (setting `status` to `active`, clearing `accessRevokesAt`,
+or moving `accessState` from `revoked` to `granted`) is rejected as a stale
+tie — this is what stops a reordered delivery from permanently un-revoking a
+cancelled subscriber. A genuinely newer event is always admitted, including
+one that restores a terminal entry to `active`/`granted` (a real
+reactivation).
+
+### The grace policy
+
+`dunningPolicyFor(siteId)` reads a `SiteSetting` row keyed
+`commerce.dunning_policy:<siteId>` (`SiteSetting.key` has no `siteId`
+column of its own, so per-tenant scoping lives in the key string — never an
+unsuffixed fallback). Absent, malformed, non-numeric, negative, non-finite,
+or out-of-range (`> 90`) all resolve to a documented default (14 days) or a
+clamp, logged, never thrown. On a **multi-tenant** deployment this key is
+shared by every seller on the deployment (one process-wide `siteId`) — a
+one-time `warn` log names that on the first read.
+
+### The reserved key namespace
+
+The record above would be worthless if its own subject could rewrite it:
+`GET`/`PUT`/`DELETE /v1/user/data/:key` (`routes/auth/user.ts`) refuse a
+`commerce.`- or `system.`-prefixed key (case-insensitive) with `403
+{error: "reserved-key"}` before any Prisma call. `PUT` additionally bounds
+the body at 64 KiB. Every unreserved key's behavior is unchanged.
+
+## Idempotency caveat (load-bearing)
+
+Stripe uses **at-least-once delivery semantics** and occasionally
+double-delivers events. The in-memory store (`lib/webhook-idempotency.ts`)
+short-circuits a replayed `event.id` within one process; it is not durable
+across a restart or a second API instance. Telemetry-only side effects make
+that an acceptable counting drift.
+
+**A side effect with write semantics carries its own durable layer.** The
+recommender stamp above uses a guarded conditional update (the row's
+`status: "created"` is the key). A future write that cannot be expressed as
+a guarded update (confirmation email, refund processing) needs a
+`webhook_events` table keyed on `event.id` with an early-return for
+already-seen IDs — add it first.
+
+## Env contract
+
+Both vars are **server-only** — never use a `NEXT_PUBLIC_` prefix.
+
+| Var                     | Required                     | Notes                                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STRIPE_WEBHOOK_SECRET` | For the route to do anything | `whsec_*` from Stripe Dashboard                                                                                                                                                                                                                                                                                                                                                                |
+| `STRIPE_SECRET_KEY`     | For checkout + sandbox check | Must match an allow-listed test-mode prefix (`sk_test_*` / `pk_test_*` / `rk_test_*`); anything else — including live and restricted-live keys — is runtime-blocked by `assertSandboxKey`. The commit-time hook is a partial backstop only: it greps for `sk_live_` / `pk_live_` and does **not** catch restricted-live (`rk_live_`) keys, so the runtime allow-list is the load-bearing guard |
+
+Without `STRIPE_WEBHOOK_SECRET`, the route returns 503 on every request.
+
+## Deployment note
+
+Customer forks must:
+
+1. Configure a Stripe Dashboard webhook endpoint pointing at
+   `https://<your-host>/v1/webhooks/stripe`.
+2. Copy the endpoint's **Signing secret** (`whsec_*`) into
+   `STRIPE_WEBHOOK_SECRET` in their environment.
+
+Without both, telemetry will not fire and 503s will be logged.
+
+## Brief
+
+`docs/internal/decisions/ailk-stripe-webhook-receiver.md`