create-ailk 0.23.0 → 0.25.1

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

@@ -1,398 +0,0 @@
-# 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.
-
-## Site filter (#7868)
-
-The hub's Stripe account is shared with its spoke sites, so this endpoint
-receives every site's events. A Checkout session says which site opened it
-through `metadata.site`.
-
-- **The stamp.** Every session the hub creates — `POST /v1/checkout/sessions`
-  and the recommender's quoted checkout (`POST /v1/flows/:slug/checkout`) —
-  carries `metadata.site` = `currentSiteId()`: `AILK_SITE_ID`, else
-  `"default"`. The key, the stamp and the foreign test are defined once in
-  `lib/site.ts` (`SITE_STAMP_KEY`, `siteStamp()`, `isForeignSiteStamp()`).
-  No request field can set or override it.
-- **The filter.** A `checkout.session.completed` or `checkout.session.expired`
-  whose `metadata.site` is a non-empty string other than `currentSiteId()` is
-  another site's. The handler takes no action — no telemetry, billing bind,
-  recommender stamp or request-paid stamp — logs `outcome: "foreign_site"`
-  with the foreign `stamp` (first 64 characters) and the hub's `ownSite`, and
-  answers 200. The comparison is exact and case-sensitive. The event is still
-  marked seen, so a redelivery is the usual duplicate short-circuit.
-- **Unstamped is own.** A session with no stamp, or an empty one, is the hub's
-  and is handled as before: hub Payment Links, hosted invoices, portal events
-  and sessions opened before the stamp shipped carry none, so strict equality
-  would stop hub checkout (roadmap D4).
-- **One alias per deployment.** Two deployments on one Stripe account that
-  both leave `AILK_SITE_ID` unset both stamp `"default"` and treat each
-  other's sessions as their own — give each a distinct `AILK_SITE_ID`. The
-  alias is a deployment-wide constant: every instance and environment on the
-  account must agree on it, and change it only while no Checkout session is
-  open (a session lives up to 24 hours). A session whose stamp no longer
-  matches is acked as foreign and never retried, so its hub side effects are
-  lost; the `stamp` / `ownSite` pair in the log line is how to spot that drift.
-  A subscription keeps its stamp for its whole life and each finalized
-  invoice keeps an immutable copy of it, so a slug collision or a mis-stamp
-  on those lasts as long as the subscription — not the 24 hours a session
-  lives.
-- **Billing events (#8024).** One gate before the event switch applies the
-  same test to every `customer.*`, `customer.subscription.*` and `invoice.*`
-  event, handled type or not. It reads the stamp from the event object's own
-  metadata — the Subscription's (where spoke-checkout writes `site` through
-  `subscription_data.metadata`) or the Customer's — and, for an invoice, from
-  its own metadata, then the subscription snapshot under
-  `parent.subscription_details.metadata` (the pinned API version), then the
-  top-level `subscription_details.metadata` (an endpoint on a pre-`basil`
-  version). Any foreign source makes the event foreign; the first is logged.
-  A source is read only when `data.object.object` is the family's own type
-  (`subscription`, `customer`, `invoice`), so a `customer.source.*` card or a
-  `customer.tax_id.*` object is never read. A foreign event answers 200,
-  logs `outcome: "foreign_site"` (the same five fields), writes nothing — no
-  billing bind, request-paid stamp or dunning record — and is marked seen.
-  The decision uses the payload alone: no Stripe call.
-- **What stays unstamped.** The filter cannot see a stamp nobody wrote, so
-  these are still handled as the hub's own, exactly as before: spoke
-  customers (Checkout cannot put metadata on a customer it creates); quoted
-  spoke subscriptions and their invoices (`createQuotedCheckoutSession`
-  sends no `subscription_data` yet); a fixed spoke subscription whose `site`
-  was later removed; spoke subscriptions created before the stamp shipped,
-  or through a Payment Link or the Dashboard; and the billing app's sessions
-  and subscriptions on the shared account. Where such a subscription sits on
-  a hub User's own Stripe customer (a known buyer reused by a spoke), its
-  events keep reaching that User's dunning record.
-- **A label, not a boundary.** The stamp is written by whoever holds the
-  account's secret key. It separates cooperating sites on one account, not
-  tenants. Whoever holds a write key on the account can also make the hub
-  skip one of its own objects' billing events by stamping it with another
-  site, which silences the hub's dunning record for that subscription — the
-  same key can already cancel or re-price it outright.
-
-## Per-Organization endpoint (#8932)
-
-`POST /v1/webhooks/stripe/:connectionToken` (`stripe-offerings.ts`) is the
-receiver for one Organization's own Stripe connection — the Offerings money
-path (spec `docs/specs/8932-the-per-organization-stripe-webhook-spec.md`,
-contract `docs/specs/8879-the-offerings-security-contract-key-spec.md` W1,
-W3–W11, G5, T8). The 43-character token selects one `StripeConnection` row
-(`findStripeConnectionByWebhookToken`, #8907); that row's decrypted secret
-verifies the signature through `verifyWebhookSignatureKeyless` (no env key),
-and its `organizationId` is the only Organization the event can act for.
-Registered beside the legacy route on every build, with its own 100/min
-per-IP bucket; the commerce claim is read at call time.
-
-**The ladder** — the first step that answers ends the request; every `200`
-body is `{ received: true }` and the outcome is the log line's only:
-
-| #    | Step                                                                                                                                                                                                                | Answer                                                                                     | Seen     |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------- |
-| 1    | the token resolves to no row (or is malformed)                                                                                                                                                                      | `404 not-found`, logs nothing                                                              | no       |
-| 1a   | the token lookup rejects                                                                                                                                                                                            | `503 webhook-unavailable`                                                                  | no       |
-| 2    | the row has no usable secret                                                                                                                                                                                        | `503 webhook-not-configured`                                                               | no       |
-| 3–6  | signature settled, then the claim (as the legacy route): `undetermined` → `503` + `Retry-After: 300`; `unclaimed` → signed `200 dropped_no_commerce_claim`, unsigned the module-disabled `404`; then the held `400` | as stated                                                                                  | no       |
-| 7    | `event.livemode` is not the row's mode                                                                                                                                                                              | `200 livemode_mismatch`                                                                    | no       |
-| 8    | not `checkout.session.completed` / `.async_payment_succeeded` on a session object                                                                                                                                   | `200 ignored_type`                                                                         | no       |
-| 9–11 | the hub's session record (#8930): rejects / unreadable / none                                                                                                                                                       | `503 record-unavailable` / `500 record-unreadable` / `200 unrecorded`                      | no       |
-| 12   | another Organization's record, or `metadata.site` is not the record's workspace                                                                                                                                     | `200 foreign_organization`                                                                 | no       |
-| 13   | the record's mode is not the row's                                                                                                                                                                                  | `200 livemode_mismatch`                                                                    | no       |
-| 14   | already seen for this Organization                                                                                                                                                                                  | `200 duplicate`                                                                            | —        |
-| 15   | a `completed` session neither `paid` nor `no_payment_required`                                                                                                                                                      | `200 unpaid`                                                                               | yes      |
-| 16   | the connection's client or its `listLineItems` call fails                                                                                                                                                           | `503 stripe-unavailable` (never the env key)                                               | no       |
-| 17   | not exactly one line item whose Price id is the record's                                                                                                                                                            | `200 offering_mismatch`                                                                    | yes      |
-| 18   | `routeLead` (below)                                                                                                                                                                                                 | `200 fulfilled` / `already_fulfilled` / `unfulfillable`, else `503 fulfilment-unavailable` | yes / no |
-
-**The lead.** One per session: `routeLead` with the idempotency key
-`"stripe-offerings " + sessionId` — a space, which no `Idempotency-Key`
-header can carry, so no anonymous lead can take the key first — and
-`offeringsCheckout: true`. Its offering is the record's FULL lookup key,
-never `metadata.ailk_offering`. A live session's lead is marked
-`spokeCheckout`, the hold #8793's `releaseHeldCheckoutPlan` releases at the
-buyer's verified first link; no path here writes `Person.planOffering`. A
-test-mode session's lead is written unmarked: no hold, purchase message,
-email or consent grant. A replay or a conflict on that key is
-`already_fulfilled`; a lead the database did not take is a `503`, so Stripe
-retries.
-
-**The legacy endpoint steps aside (W8).** `POST /v1/webhooks/stripe` acks
-any event carrying an `ailk_offering` key — in a session's metadata or any
-site-stamp source above — with `200 { received: true }` and
-`outcome: "offerings_path"`, **before** `markSeen`, and writes nothing.
-Every event without the key takes the legacy path unchanged.
-
-**Two dedup stores.** The legacy route keeps `hasSeen` / `markSeen`; the
-per-Organization route uses its own `hasSeenForOrganization` /
-`markSeenForOrganization`, keyed `<organizationId>:<eventId>`. Neither
-endpoint's store can swallow the other's event. Both are in-memory per
-instance; the per-Organization route's correctness rests on the lead's
-database key.
-
-**Logs.** Each line carries `organizationId`, `eventType`, an 8-character
-`eventIdPrefix` and `outcome` (fewer before an event is verified) — never
-the token, the secret, a full Stripe id, an email, a lookup key, a metadata
-value or Stripe product text. Request and error lines log the path with
-the token replaced whole by `:connectionToken` (`redactLogPath`).
-
-**W11.** No billing identity is bound from a connection's event.
-
-## 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`