@pithy-sh/payments 0.1.0

package/src/rails/stripe/portal.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PortalHandoff, PortalSessionInput } from "../contract";
+import { stripeHttpFetch, stripeJson } from "./api";
+import { hostedSession, type StripeCheckoutOptions } from "./checkout";
+
+/**
+ * The Billing Portal: Stripe's own page for managing a subscription, and the whole of Pithy's plan-management
+ * surface **on this rail**.
+ *
+ * Two parameters go out — which customer, and where to send them afterwards — and that is deliberate. Everything
+ * a subscriber may do in the portal (cancel, switch plan, update a card, download invoices) is configured in
+ * Stripe's dashboard, per environment, by the adopter. A parameter here that decided any of it would be this
+ * capability computing proration and tax, which #79's locked decision 2 still says it never does. It also means
+ * store rules and dunning copy stay Stripe's to keep current rather than ours to age.
+ *
+ * **"The whole of it on this rail" is a narrower claim than it was.** The decision's other half was amended on
+ * 2026-08-28 and the kit may now invoke a plan change from the server, passing the provider's figures through
+ * unmodified — `{base}/subscription/preview|change|cancel|keep`, behind {@link SubscriptionRail}. Only Paddle
+ * implements it. The amendment permits the seam rather than requiring one per rail, so Stripe's answer to
+ * "change my plan" is still this page, and `providers.test.ts` holds that to what the providers actually
+ * declare rather than to this sentence.
+ *
+ * The customer is resolved from the provider-account map, never from a request. That map is written from
+ * `client_reference_id` when a checkout completes, so the caller can only ever reach their own billing.
+ *
+ * The failure every adopter meets once is a Billing Portal with no configuration: Stripe answers 400 until one is
+ * created in the dashboard. `api.ts` maps that to `payments/rail_not_configured`, which reads to a caller as "not
+ * available here" — true — and carries Stripe's own sentence in `detail` for whoever can fix it.
+ */
+
+/** Create a hosted Billing Portal session for one customer, and return where to send the browser. */
+export async function createStripePortalSession(
+  input: PortalSessionInput,
+  options: StripeCheckoutOptions,
+): Promise<PortalHandoff> {
+  const created = await stripeJson(options.transport ?? stripeHttpFetch, "/billing_portal/sessions", {
+    what: "a Billing Portal session",
+    secretKey: options.credentials.secretKey,
+    form: { customer: input.providerAccountId, return_url: input.returnUrl },
+  });
+
+  return hostedSession(created, "a Billing Portal session");
+}

package/src/rails/stripe/pricing.ts

@@ -0,0 +1,123 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { SubscriptionPricing } from "../../data/discount";
+import type { PaymentsPurchase } from "../../data/purchase";
+import type { PaymentsStripeCredentials } from "../../secret/registry";
+import { type StripeHttpFetch, stripeHttpFetch, stripeJson } from "./api";
+
+/**
+ * What a Stripe subscription pays now, what it becomes, and when.
+ *
+ * Read from the store rather than computed. Stripe carries the discount on the subscription and the
+ * arithmetic on an upcoming invoice, so both are asked for and neither is derived: Pithy never multiplies a
+ * price by a percentage, here or anywhere.
+ *
+ * **`discountEndsAt` is the field this exists for.** Stripe reports a repeating discount's `end` on the
+ * subscription's discount object, and that date is what a customer must be told — a rate that lapses with
+ * nothing having said so is, from their seat, a billing error.
+ */
+
+/** What reading pricing needs. */
+export interface StripePricingOptions {
+  /** Stripe's credential block. Only `secretKey` is used here. */
+  credentials: PaymentsStripeCredentials;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: StripeHttpFetch;
+}
+
+/** A subscription, narrowed to the discount in force. */
+const DiscountedSubscription = z
+  .object({
+    currency: z.string().nullish(),
+    discount: z
+      .object({
+        end: z.number().nullish(),
+        promotion_code: z.unknown().nullish(),
+        coupon: z.object({ name: z.string().nullish() }).loose().nullish(),
+      })
+      .loose()
+      .nullish(),
+    items: z
+      .object({ data: z.array(z.object({ price: z.object({ unit_amount: z.number().nullish() }).loose() }).loose()) })
+      .loose()
+      .nullish(),
+  })
+  .loose();
+
+/** The upcoming invoice, which is Stripe's own answer to "what comes off and what is left". */
+const UpcomingInvoice = z
+  .object({ currency: z.string().nullish(), total: z.number().nullish(), subtotal: z.number().nullish() })
+  .loose();
+
+/** Read what this subscription pays, or `undefined` when Stripe has nothing to say. */
+export async function readStripePricing(
+  purchase: PaymentsPurchase,
+  options: StripePricingOptions,
+): Promise<SubscriptionPricing | undefined> {
+  // A Stripe subscription row's family key is the `sub_…` it belongs to; a one-off has none and has no
+  // renewal to price.
+  const subscriptionId = purchase.originalTransactionId;
+  if (subscriptionId === null || !subscriptionId.startsWith("sub_")) return undefined;
+
+  const transport = options.transport ?? stripeHttpFetch;
+  const found = await stripeJson(transport, `/subscriptions/${encodeURIComponent(subscriptionId)}`, {
+    what: `subscription ${subscriptionId} pricing`,
+    secretKey: options.credentials.secretKey,
+    absentOn404: true,
+  });
+  if (found === undefined) return undefined;
+
+  const parsed = DiscountedSubscription.safeParse(found);
+  if (!parsed.success) return undefined;
+  const subscription = parsed.data;
+
+  // `/v1/invoices/create_preview`, not `/v1/invoices/upcoming`. The latter is what every older integration
+  // guide shows and it is **gone** in the API version this rail pins (`2025-04-30.basil`) — so calling it
+  // 404s, `absentOn404` swallows the 404, and every amount below comes back null. A pricing read that
+  // silently reports nothing is worse than one that fails, because a screen renders the nothing.
+  const upcoming = await stripeJson(transport, "/invoices/create_preview", {
+    what: `subscription ${subscriptionId} next invoice`,
+    secretKey: options.credentials.secretKey,
+    form: { subscription: subscriptionId },
+    absentOn404: true,
+  });
+  const invoice = upcoming === undefined ? undefined : UpcomingInvoice.safeParse(upcoming);
+  const amounts = invoice?.success === true ? invoice.data : undefined;
+
+  // The list price falls back to the item's own unit amount when there is no upcoming invoice to read —
+  // a subscription canceled at period end has none, and its list price is still a fact.
+  const listed = subscription.items?.data[0]?.price.unit_amount ?? null;
+  const end = subscription.discount?.end;
+
+  return {
+    currency: amounts?.currency ?? subscription.currency ?? null,
+    currentAmountMinor: amounts?.total ?? null,
+    listAmountMinor: amounts?.subtotal ?? listed,
+    // The code a customer typed, never the `promo_…` id. `SubscriptionPricing.discountCode` is typed as a
+    // `DiscountCode` and is rendered on a billing screen; showing an opaque id there is showing the
+    // customer a value that is not theirs and that they cannot match to the code they entered. Stripe
+    // returns the id unless the discount is expanded, so an unexpanded one reports null rather than a lie.
+    discountCode: promotionCode(subscription.discount?.promotion_code),
+    // Seconds since the epoch on Stripe's side. Null means no discount, or one that runs forever — a screen
+    // must read it beside `discountCode` to know which, which `SubscriptionPricing` says out loud.
+    discountEndsAt: typeof end === "number" ? new Date(end * 1000) : null,
+  };
+}
+
+/**
+ * The customer-facing code off Stripe's `promotion_code` field, or null.
+ *
+ * Stripe returns either the id (`promo_…`) or, when expanded, the object carrying `code`. Only the second
+ * is a code a customer would recognize; a bare id is reported as null, because "no code shown" is honest
+ * and "PROMO_1QxYz" on a billing screen is not.
+ */
+function promotionCode(value: unknown): string | null {
+  if (typeof value === "string") return value.startsWith("promo_") ? null : value;
+  if (typeof value === "object" && value !== null) {
+    const code = (value as { code?: unknown }).code;
+    return typeof code === "string" && code !== "" ? code : null;
+  }
+  return null;
+}

package/src/rails/stripe/rail.ts

@@ -0,0 +1,139 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CreatedDiscount, DiscountTerms, SubscriptionPricing } from "../../data/discount";
+import type { PaymentsPurchase } from "../../data/purchase";
+import type { PaymentsStripeCredentials } from "../../secret/registry";
+import type {
+  CheckoutHandoff,
+  CheckoutRail,
+  CheckoutSessionInput,
+  DiscountRail,
+  ListedDiscount,
+  PaymentsRailProvider,
+  PortalHandoff,
+  PortalSessionInput,
+  PricingRail,
+  RailRequestContext,
+  UnboundProviderEvent,
+  VerifiedNotification,
+  VerifiedPurchase,
+  WebhookDelivery,
+} from "../contract";
+import type { StripeHttpFetch } from "./api";
+import { createStripeCheckoutSession } from "./checkout";
+import { createStripeDiscount, listStripeDiscounts } from "./discounts";
+import { mapStripeEvent, StripeEvent } from "./objects";
+import { createStripePortalSession } from "./portal";
+import { readStripePricing } from "./pricing";
+import { refreshStripeSubscription } from "./refresh";
+import { verifyStripeSession } from "./verify";
+import { parseStripeNotification } from "./webhook";
+
+/**
+ * The Stripe rail as one provider object — and the only rail that implements both halves of the contract.
+ *
+ * Apple and Google purchases have already happened inside a store SDK by the time the server hears of them. A
+ * Stripe purchase is one Pithy initiates: `/checkout` creates a hosted session and sends the browser to it. That
+ * asymmetry is why {@link CheckoutRail} is a separate interface rather than two methods Apple would have to stub,
+ * and this is the object that satisfies both.
+ *
+ * Built per request from credentials the caller resolved through the secrets store, rather than reading them
+ * itself. That keeps the rail a pure function of its inputs and keeps the secret read at the point of need.
+ *
+ * **Hosted only, and that is a decision rather than a stage.** No Payment Element, no card fields, no proration
+ * or plan-change logic — Stripe owns the payment page, SCA, tax, and every rule that changes underneath them.
+ * Nothing in this module would be a small edit away from owning any of that, which is the point.
+ */
+
+/** How the Stripe rail's transport and replay window may be varied. Both exist for the tests. */
+export interface StripeRailOptions {
+  /** The HTTP seam Stripe's API is reached through. Defaults to the runtime's `fetch`. */
+  transport?: StripeHttpFetch;
+  /** The signature freshness window, in seconds. Defaults to Stripe's own five minutes. */
+  toleranceSeconds?: number;
+}
+
+/** The Stripe rail. Verifies a returning Checkout Session, verifies webhooks, and creates hosted sessions. */
+export function stripeRail(
+  credentials: PaymentsStripeCredentials,
+  options: StripeRailOptions = {},
+): PaymentsRailProvider & CheckoutRail & DiscountRail & PricingRail {
+  return {
+    rail: "stripe",
+
+    async verify(receipt: string, context: RailRequestContext): Promise<VerifiedPurchase> {
+      // `return await`, not `return`. Returning a promise from an async function makes this frame *adopt* the
+      // rejection rather than raising it, and workerd then reports the adopted promise as an unhandled rejection
+      // even though Hono's `onError` answers the request correctly. A refused session is normal traffic.
+      return await verifyStripeSession(receipt, {
+        credentials,
+        now: context.now,
+        transport: options.transport,
+      });
+    },
+
+    async parseNotification(delivery: WebhookDelivery, context: RailRequestContext): Promise<VerifiedNotification> {
+      return await parseStripeNotification(delivery, {
+        credentials,
+        now: context.now,
+        toleranceSeconds: options.toleranceSeconds,
+      });
+    },
+
+    // The clock and the deployment travel with every rail call, and this one needs neither: the map reads
+    // the event's own `created` and Stripe stamps no deployment. Named `_context` so the signature still
+    // matches the contract rather than diverging from it.
+    async replay(
+      payload: Record<string, unknown>,
+      _context: RailRequestContext,
+    ): Promise<VerifiedNotification | undefined> {
+      // The recorded body is the whole Stripe event, and the map takes an event and reads nothing else — so
+      // this replay makes no call to Stripe at all. The signature is not re-checked: it covers a header this
+      // table never stored, and the row's authenticity was established when it was written.
+      const parsed = StripeEvent.safeParse(payload);
+      if (!parsed.success) return undefined;
+      const mapped = mapStripeEvent(parsed.data);
+      return {
+        providerEventId: parsed.data.id,
+        payload: parsed.data as Record<string, unknown>,
+        event: mapped.event,
+        providerAccountId: mapped.providerAccountId,
+        accountReference: mapped.accountReference,
+        note: mapped.note,
+      };
+    },
+
+    async refresh(purchase: PaymentsPurchase, context: RailRequestContext): Promise<UnboundProviderEvent | undefined> {
+      // `return await`, not `return` — see `verify` above for why the frame must raise rather than adopt.
+      return await refreshStripeSubscription(purchase, {
+        credentials,
+        now: context.now,
+        transport: options.transport,
+      });
+    },
+
+    async createCheckoutSession(input: CheckoutSessionInput): Promise<CheckoutHandoff> {
+      return await createStripeCheckoutSession(input, { credentials, transport: options.transport });
+    },
+
+    async createPortalSession(input: PortalSessionInput): Promise<PortalHandoff> {
+      return await createStripePortalSession(input, { credentials, transport: options.transport });
+    },
+
+    async readPricing(
+      purchase: PaymentsPurchase,
+      _context: RailRequestContext,
+    ): Promise<SubscriptionPricing | undefined> {
+      return await readStripePricing(purchase, { credentials, transport: options.transport });
+    },
+
+    async listDiscounts(): Promise<readonly ListedDiscount[]> {
+      return await listStripeDiscounts({ credentials, transport: options.transport });
+    },
+
+    async createDiscount(terms: DiscountTerms): Promise<CreatedDiscount> {
+      return await createStripeDiscount(terms, { credentials, transport: options.transport });
+    },
+  };
+}

package/src/rails/stripe/refresh.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaymentsPurchase } from "../../data/purchase";
+import { PaymentsVerificationFailedError } from "../../error/errors";
+import type { PaymentsStripeCredentials } from "../../secret/registry";
+import type { UnboundProviderEvent } from "../contract";
+import { type StripeHttpFetch, stripeHttpFetch, stripeJson } from "./api";
+import { mapStripeSubscription, StripeSubscription } from "./objects";
+
+/**
+ * Re-read one stored subscription at Stripe, normalized — the reconciliation path for this rail.
+ *
+ * **A subscription retrieve, not an invoice one, and that is the whole design.** A row is keyed on the invoice
+ * because each billing period is its own purchase; the *subscription* is what has a current state, and it is
+ * what `originalTransactionId` holds. So the retrieve is by `sub_…` and the mapping is the identical one the
+ * webhook path uses — `mapStripeSubscription`, not a second reading of Stripe's vocabulary that could drift
+ * from it. The invoice the answer names becomes the row's key, which means a period this deployment never
+ * heard a webhook for projects as its own new row rather than overwriting the last one it did hear about.
+ *
+ * **Subscriptions only.** A one-time Stripe purchase is a payment intent, and a payment intent does not change
+ * after it succeeds — the one thing that changes it is a refund, which arrives as `charge.refunded`. There is
+ * nothing for a periodic re-read to discover, so there is no call here to make.
+ *
+ * **Unlike Google there is nothing to batch.** Stripe authenticates every request with the secret key
+ * directly, so a hundred refreshes are a hundred round-trips and no token minting at all.
+ */
+
+/** What a Stripe refresh needs: the API key, the clock, and the transport. */
+export interface StripeRefreshOptions {
+  /** Stripe's credential block. Only `secretKey` is used here. */
+  credentials: PaymentsStripeCredentials;
+  /** The clock. A retrieve is a read of the state now, so this is the honest provider event time. */
+  now: Date;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: StripeHttpFetch;
+}
+
+/** Re-read a stored Stripe subscription, or `undefined` when there is nothing addressable to read. */
+export async function refreshStripeSubscription(
+  purchase: PaymentsPurchase,
+  options: StripeRefreshOptions,
+): Promise<UnboundProviderEvent | undefined> {
+  if (purchase.type !== "subscription") return undefined;
+
+  // The subscription id, which every invoice row of the family carries. A row written from a Checkout Session
+  // whose subscription was never expanded has none, and there is nothing to retrieve.
+  const subscriptionId = purchase.originalTransactionId;
+  if (subscriptionId === null) return undefined;
+
+  const retrieved = await stripeJson(
+    options.transport ?? stripeHttpFetch,
+    `/subscriptions/${encodeURIComponent(subscriptionId)}`,
+    {
+      what: "the subscription",
+      secretKey: options.credentials.secretKey,
+      absentOn404: true,
+    },
+  );
+  // Deleted at Stripe, or belonging to the other mode's account. Either way the row stays exactly as it stood:
+  // a subscription we cannot read is not evidence that anybody's access ended.
+  if (retrieved === undefined) return undefined;
+
+  const parsed = StripeSubscription.safeParse(retrieved);
+  if (!parsed.success) {
+    throw new PaymentsVerificationFailedError({
+      detail: `Stripe: the answer is not a Subscription — ${parsed.error.issues
+        .map((issue) => `${issue.path.join(".") || "<root>"}:${issue.code}`)
+        .join(", ")}.`,
+    });
+  }
+
+  // The clock as the provider event time. A retrieve has none of its own, and dating it by the subscription's
+  // `created` would put every repair behind every notification it is meant to correct.
+  //
+  // `?? undefined` rather than passing the null through: the mapper's `null` means "this object described no
+  // transaction", which is the same statement as "nothing to refresh" and must not read as a distinct outcome.
+  return mapStripeSubscription(parsed.data, options.now).event ?? undefined;
+}

package/src/rails/stripe/signature.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import {
+  checkSignedWebhook,
+  parseSignedWebhookHeader,
+  type SignedWebhookHeader,
+  type SignedWebhookRefusal,
+} from "@pithy-sh/core/src/http/signedWebhook";
+import { PaymentsVerificationFailedError } from "../../error/errors";
+
+/**
+ * Stripe's authenticity proof: an HMAC over the exact received bytes, dated, in one header.
+ *
+ * `Stripe-Signature: t=1768435200,v1=5257a8…` — the timestamp the delivery claims, then one hex HMAC-SHA256 per
+ * active signing secret, each computed over `<timestamp>.<body>` and keyed with the endpoint's `whsec_…`.
+ *
+ * ## Why the scheme itself is not here
+ *
+ * It is `@pithy-sh/core`'s `signed-webhook` primitive, and this module is one of its callers. Stripe's format is
+ * the one every other sender copied, so the kit implements it once — the freshness window in both directions, the
+ * timestamp inside the signed payload, `crypto.subtle.verify` instead of a hand-written compare, every listed
+ * signature tried, and a cap on how many. Each of those is a security property with a reason written down beside
+ * it, and a second copy here would be a second set of reasons to keep in step: a parser fix landing in one and
+ * not the other, with money on the side that missed it.
+ *
+ * What stays is what is Stripe's: the header name, the accepted scheme key, the tolerance, and the wording of a
+ * refusal.
+ *
+ * ## Why the window matters to this rail in particular
+ *
+ * A captured `customer.subscription.updated` replayed months later is a state claim about a subscription that has
+ * since lapsed. The projection's monotonic rule would correctly ignore it *only because* the stored event time is
+ * newer — and relying on that would make the window a happy accident of another rule. Five minutes is Stripe's own
+ * default and is generous against delivery latency and clock skew.
+ *
+ * Freshness is not uniqueness. Inside the window a captured delivery replays as often as it is sent, which is what
+ * the guard's `UNIQUE (rail, providerEventId)` insert is for.
+ *
+ * ## What a refusal says
+ *
+ * `payments/verification_failed`, with the reason in `detail` and nothing else. Never the secret, never the body,
+ * never the signature: `detail` reaches an operator's log, and the webhook guard maps this to
+ * `payments/webhook_unverified` (401) before anything reaches the sender — a forger learns only that it failed.
+ * That code is this rail's contract with its guard, which is why verification goes through the primitive's
+ * reporting seam rather than its throwing one.
+ */
+
+/** The header Stripe puts its proof in. Lower case, because that is how Hono presents a header name. */
+export const STRIPE_SIGNATURE_HEADER = "stripe-signature";
+
+/** How far a delivery's own timestamp may be from now. Stripe's default, and generous against clock skew. */
+export const STRIPE_SIGNATURE_TOLERANCE_SECONDS = 300;
+
+/** The one signature scheme this build accepts. `v0` is Stripe's thin-event variant and proves nothing here. */
+const ACCEPTED_SCHEME = "v1";
+
+/** The timestamp key Stripe writes. The primitive's default, named here so this file states its own format. */
+const TIMESTAMP_KEY = "t";
+
+/**
+ * A parsed `Stripe-Signature` header: when the delivery says it was signed, and with what. The primitive's
+ * shape under this rail's name — the format is Stripe's, the parser is the kit's.
+ */
+export type StripeSignatureHeader = SignedWebhookHeader;
+
+/** What verification needs beyond the bytes: the clock, and how wide the freshness window is. */
+export interface VerifyStripeSignatureOptions {
+  /** The clock. Injected so the replay window is deterministic in tests rather than wall-clock dependent. */
+  now: Date;
+  /** The freshness window, in seconds. Defaults to {@link STRIPE_SIGNATURE_TOLERANCE_SECONDS}. */
+  toleranceSeconds?: number;
+}
+
+/**
+ * Read a `Stripe-Signature` header, or `undefined` when it is not one.
+ *
+ * Undefined rather than a throw for every unreadable shape, because the caller turns them all into one refusal:
+ * distinguishing "no `t`" from "no `v1`" would describe our parser to a sender, and neither is actionable by
+ * anyone but an operator reading the endpoint's configuration.
+ *
+ * Unknown schemes are dropped rather than refused. Stripe already sends `v0` alongside `v1` for thin Connect
+ * events and may add another after this package shipped, and a delivery whose `v1` is good is authentic whatever
+ * else it carries. A header carrying *only* unknown schemes has proved nothing, so it yields undefined.
+ */
+export function parseStripeSignatureHeader(header: string): StripeSignatureHeader | undefined {
+  return parseSignedWebhookHeader(header, TIMESTAMP_KEY, ACCEPTED_SCHEME);
+}
+
+/**
+ * Verify one delivery's `Stripe-Signature`. Resolves when Stripe signed these exact bytes inside the window, and
+ * throws `payments/verification_failed` otherwise.
+ */
+export async function verifyStripeSignature(
+  body: string,
+  header: string | null,
+  secret: string,
+  options: VerifyStripeSignatureOptions,
+): Promise<void> {
+  const refusal = await checkSignedWebhook(body, header, {
+    header: STRIPE_SIGNATURE_HEADER,
+    timestampKey: TIMESTAMP_KEY,
+    signatureKey: ACCEPTED_SCHEME,
+    secret,
+    toleranceSeconds: options.toleranceSeconds ?? STRIPE_SIGNATURE_TOLERANCE_SECONDS,
+    now: options.now,
+  });
+  if (refusal === undefined) return;
+  throw new PaymentsVerificationFailedError({ detail: stripeRefusal(refusal) });
+}
+
+/**
+ * This rail's wording for the primitive's three refusals.
+ *
+ * Prefixed `Stripe:` because a payments Worker composes several rails and `detail` is what an operator reads to
+ * find out which one refused. The strings say what failed and what to check, and nothing the delivery carried.
+ */
+function stripeRefusal(refusal: SignedWebhookRefusal): string {
+  switch (refusal.reason) {
+    case "unreadable":
+      return "Stripe: the delivery carries no readable Stripe-Signature header with a t= timestamp and a v1= HMAC.";
+    case "stale":
+      return `Stripe: the delivery is dated ${refusal.skew}s from now, outside the ${refusal.tolerance}s tolerance. Check this Worker's clock, or a replayed delivery.`;
+    case "unmatched":
+      return "Stripe: no signature in the Stripe-Signature header matches these bytes under the configured signing secret. Check that the secret belongs to this endpoint and this environment.";
+  }
+}

package/src/rails/stripe/verify.ts

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors";
+import type { PaymentsStripeCredentials } from "../../secret/registry";
+import { noteText, type VerifiedPurchase } from "../contract";
+import { type StripeHttpFetch, stripeHttpFetch, stripeJson } from "./api";
+import { mapStripeSession, StripeCheckoutSession } from "./objects";
+
+/**
+ * The client-submission path for Stripe: the Checkout Session id a returning browser carries.
+ *
+ * Hosted Checkout sends the buyer back to `success_url`, and Stripe substitutes the session id into it wherever
+ * the adopter put `{CHECKOUT_SESSION_ID}`. Posting that id to `/payments/purchases` is the Stripe equivalent of
+ * submitting a StoreKit transaction: **nothing about correctness rests on it**, because the webhook produces the
+ * identical row through the same idempotent writer. What it buys is immediacy — the buyer sees their entitlement
+ * when they land on the thank-you page rather than when Stripe gets round to delivering.
+ *
+ * ## Why a session id is safe to accept, and where it stops
+ *
+ * A session id is not a bearer artifact the way a receipt is: it is not a secret, and it is not proof of anything
+ * on its own. What makes this path safe is that the session **names its own purchaser**. Pithy set
+ * `client_reference_id` from the authenticated caller when it created the session, and that value comes back on
+ * the retrieve — so a caller submitting somebody else's session id is refused by the route, before the projection
+ * writer's owner check ever has to catch it. The shape is checked here first, so an Apple receipt posted to the
+ * Stripe rail costs no round-trip.
+ *
+ * ## Why all three expansions
+ *
+ * `line_items` because a session's price is otherwise unknowable, and Stripe's own answer is better than the copy
+ * this deployment stamped into metadata. `subscription` because a subscription-mode session carries only an id,
+ * and expanding it turns one retrieve into the whole state — the same row the subscription's own webhook will
+ * later produce. And **`payment_intent.latest_charge` because a completed session is refund-blind**: its
+ * `payment_status` reads `paid` for ever, so without the charge this path would answer `active` on a purchase
+ * Stripe has already given back. The charge is the only object here that knows what became of the money.
+ */
+
+/** A Checkout Session id. Stripe's are `cs_` plus base62; the bound is generous and the shape is exact. */
+const SESSION_ID = /^cs_[A-Za-z0-9_]{1,255}$/;
+
+/** What verifying a submitted session needs: the API key, a clock, and the transport. */
+export interface StripeVerifyOptions {
+  /** Stripe's credential block. Only `secretKey` is used here. */
+  credentials: PaymentsStripeCredentials;
+  /** The clock. A retrieve is a read of the state now, so this is the honest provider event time. */
+  now: Date;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: StripeHttpFetch;
+}
+
+/** Verify a client-submitted Checkout Session and normalize it. The caller binds the authenticated purchaser. */
+export async function verifyStripeSession(receipt: string, options: StripeVerifyOptions): Promise<VerifiedPurchase> {
+  if (!SESSION_ID.test(receipt)) {
+    // Never echo the submitted value: it is caller-supplied and lands in an operator's log.
+    throw new PaymentsInvalidReceiptError({
+      detail: "Stripe: the submitted value is not a Checkout Session id. Submit the `cs_…` id from your success URL.",
+    });
+  }
+
+  const retrieved = await stripeJson(
+    options.transport ?? stripeHttpFetch,
+    `/checkout/sessions/${encodeURIComponent(receipt)}`,
+    {
+      what: "the Checkout Session",
+      secretKey: options.credentials.secretKey,
+      query: { expand: ["subscription", "line_items", "payment_intent.latest_charge"] },
+      absentOn404: true,
+    },
+  );
+
+  if (retrieved === undefined) {
+    throw new PaymentsVerificationFailedError({
+      detail: "Stripe: no Checkout Session exists under the submitted id in this environment.",
+    });
+  }
+
+  const parsed = StripeCheckoutSession.safeParse(retrieved);
+  if (!parsed.success) {
+    throw new PaymentsVerificationFailedError({
+      detail: `Stripe: the answer is not a Checkout Session — ${parsed.error.issues
+        .map((issue) => `${issue.path.join(".") || "<root>"}:${issue.code}`)
+        .join(", ")}.`,
+    });
+  }
+
+  // A retrieve is not an event: Stripe timed it with nothing, so `eventAt` is null and the mapping dates what it
+  // found. A live subscription it read is dated now; a frozen one-time snapshot is dated by Stripe's own clock,
+  // which is what stops a re-posted session id outranking the refund that followed it. See `objects.ts`.
+  const mapped = mapStripeSession(parsed.data, { eventAt: null, now: options.now });
+  if (mapped.event === null) {
+    // An abandoned session, one still awaiting a bank debit, or one whose subscription does not exist yet. The
+    // buyer is told rather than left with a 200 and no entitlement.
+    throw new PaymentsVerificationFailedError({
+      detail:
+        noteText(mapped.note) ??
+        "Stripe: that checkout has not completed into a purchase yet. It will project from the webhook when it does.",
+    });
+  }
+
+  return {
+    event: mapped.event,
+    providerAccountId: mapped.providerAccountId,
+    accountReference: mapped.accountReference,
+  };
+}