@pithy-sh/payments 0.1.0

package/src/rails/lemonSqueezy/pricing.ts

@@ -0,0 +1,124 @@
+// 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 { PaymentsLemonSqueezyCredentials } from "../../secret/registry";
+import { type LemonSqueezyHttpFetch, lemonSqueezyHttpFetch, lemonSqueezyJson } from "./api";
+
+/**
+ * What a Lemon Squeezy subscription pays now, what it becomes, and when.
+ *
+ * Read from the store rather than computed: the subscription object carries the discounted total for the
+ * next renewal, the list total, and the discount in force. Pithy multiplies nothing — a second calculation
+ * here would be a second answer to the one question a customer checks against their statement.
+ *
+ * Only a `subscription:` row can be asked. A money row records one closed period and has no "next", and an
+ * order has no renewal at all, so both answer `undefined` — the same "nothing to say about this purchase"
+ * the refresh path uses.
+ */
+
+/** What reading pricing needs. */
+export interface LemonSqueezyPricingOptions {
+  /** The rail's credentials. */
+  credentials: PaymentsLemonSqueezyCredentials;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: LemonSqueezyHttpFetch;
+}
+
+/** A subscription, narrowed to what pricing needs. `.loose()` — the store adds fields. */
+const PricedSubscription = z
+  .object({
+    data: z
+      .object({
+        attributes: z
+          .object({
+            first_subscription_item: z.object({ price_id: z.number().optional() }).loose().nullish(),
+          })
+          .loose(),
+      })
+      .loose(),
+  })
+  .loose();
+
+/**
+ * The subscription's invoices — a **collection**, which is what `/v1/subscription-invoices` returns.
+ *
+ * `data` is an array. Parsing it as a single resource is the defect this replaced: `safeParse` failed
+ * silently, every amount fell back to null, and `GET /payments/pricing` reported nothing for every Lemon
+ * Squeezy subscriber while looking like it had worked.
+ */
+const PricedInvoices = z
+  .object({
+    data: z.array(
+      z
+        .object({
+          attributes: z
+            .object({
+              currency: z.string().nullish(),
+              subtotal: z.number().nullish(),
+              total: z.number().nullish(),
+              discount_total: z.number().nullish(),
+              created_at: z.string().nullish(),
+            })
+            .loose(),
+        })
+        .loose(),
+    ),
+  })
+  .loose();
+
+/** Read what this subscription pays, or `undefined` when the store has nothing to say. */
+export async function readLemonSqueezyPricing(
+  purchase: PaymentsPurchase,
+  options: LemonSqueezyPricingOptions,
+): Promise<SubscriptionPricing | undefined> {
+  const key = purchase.providerTransactionId;
+  if (!key.startsWith("subscription:")) return undefined;
+  const id = key.slice("subscription:".length);
+
+  const transport = options.transport ?? lemonSqueezyHttpFetch;
+  const body = await lemonSqueezyJson(transport, `/subscriptions/${encodeURIComponent(id)}`, {
+    what: `subscription ${id} pricing`,
+    apiKey: options.credentials.apiKey,
+    absentOn404: true,
+  });
+  if (body === undefined) return undefined;
+
+  const subscription = PricedSubscription.safeParse(body);
+  if (!subscription.success) return undefined;
+
+  // The store's own figures, from its most recent invoice for this subscription. A filtered collection on
+  // `/v1/subscription-invoices` — there is no `/subscriptions/{id}/invoices` sub-resource, and asking for
+  // one 404s into a silently empty answer.
+  const invoices = await lemonSqueezyJson(transport, "/subscription-invoices", {
+    what: `subscription ${id} invoices`,
+    apiKey: options.credentials.apiKey,
+    query: { "filter[subscription_id]": id, "page[size]": "1", sort: "-created_at" },
+    absentOn404: true,
+  });
+  const priced = invoices === undefined ? undefined : PricedInvoices.safeParse(invoices);
+  const amounts = priced?.success === true ? priced.data.data[0]?.attributes : undefined;
+
+  return {
+    currency: amounts?.currency ?? null,
+    currentAmountMinor: amounts?.total ?? null,
+    // The list price is the subtotal before the discount came off. Where the store reports no discount the
+    // two coincide, which is exactly what `SubscriptionPricing` says an undiscounted subscription looks like.
+    listAmountMinor: amounts?.subtotal ?? amounts?.total ?? null,
+    discountCode: null,
+    // **Null, always, on this rail — and that is the honest answer rather than a gap.**
+    //
+    // `SubscriptionPricing.discountEndsAt` means "the date this rate stops". Lemon Squeezy expresses a
+    // repeating discount's remaining life in billing *periods* on the discount object, and does not publish
+    // the resulting date on the subscription. The previous code returned `renews_at` whenever the last
+    // invoice carried any discount at all, which reported the **next renewal** as the end date for a
+    // discount running for another eleven periods — telling a customer their bill changes next month when
+    // it does not, which is the same class of surprise this field exists to prevent, pointed the other way.
+    //
+    // Null is documented as "no discount, or one that runs forever". A screen reads it beside
+    // `discountCode`; both null on this rail means "we cannot say", which is true.
+    discountEndsAt: null,
+  };
+}

package/src/rails/lemonSqueezy/rail.ts

@@ -0,0 +1,137 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CreatedDiscount, DiscountTerms, SubscriptionPricing } from "../../data/discount";
+import type { PaymentsPurchase } from "../../data/purchase";
+import type { PaymentsLemonSqueezyCredentials } from "../../secret/registry";
+import type {
+  CheckoutHandoff,
+  CheckoutRail,
+  CheckoutSessionInput,
+  DiscountRail,
+  ListedDiscount,
+  PaymentsRailProvider,
+  PortalHandoff,
+  PortalSessionInput,
+  PricingRail,
+  RailRequestContext,
+  UnboundProviderEvent,
+  VerifiedNotification,
+  VerifiedPurchase,
+  WebhookDelivery,
+} from "../contract";
+import type { LemonSqueezyHttpFetch } from "./api";
+import { createLemonSqueezyCheckoutSession } from "./checkout";
+import { createLemonSqueezyDiscount, listLemonSqueezyDiscounts } from "./discounts";
+import { createLemonSqueezyPortalSession } from "./portal";
+import { readLemonSqueezyPricing } from "./pricing";
+import { refreshLemonSqueezyPurchase } from "./refresh";
+import { verifyLemonSqueezyOrder } from "./verify";
+import { parseLemonSqueezyNotification } from "./webhook";
+
+/**
+ * The Lemon Squeezy rail as one provider object — the second to implement both halves of the contract.
+ *
+ * Like Stripe, this rail *initiates* purchases: `/checkout` creates a hosted checkout and sends the browser
+ * to it, so it implements {@link CheckoutRail} as well as {@link PaymentsRailProvider}. Unlike Stripe, it
+ * refuses `verify` outright — there is no client-submittable receipt here that could be trusted, and
+ * `verify.ts` explains at length why the obvious candidates are not one.
+ *
+ * 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 merchant of record.** Lemon Squeezy owns the payment page, the sales tax, the VAT
+ * registration, the invoice, the dunning and the chargebacks. That is the entire reason an adopter reaches
+ * for this rail over Stripe, and nothing in this module is a small edit away from taking any of it back.
+ */
+
+/** How the Lemon Squeezy rail's transport is varied. One seam, for the tests and for the reconciliation pass. */
+export interface LemonSqueezyRailOptions {
+  /** The HTTP seam Lemon Squeezy's API is reached through. Defaults to the runtime's `fetch`. */
+  transport?: LemonSqueezyHttpFetch;
+  /**
+   * Whether a variant is sold as a subscription, answered from the adopter's catalog.
+   *
+   * Supplied by `resolveRailProvider`, which has the config. It decides whether an `order_created` is a
+   * one-off sale or the container a subscription arrived in — the second of which is not its own payment.
+   */
+  sellsSubscription?: (variantId: string) => boolean;
+  /**
+   * The currency this store prices in, when the project declared one.
+   *
+   * Only used to refuse a fixed discount in another currency before it reaches the store — see
+   * `discounts.ts` for why that refusal has to happen at creation rather than at redemption.
+   */
+  storeCurrency?: string;
+}
+
+/** The Lemon Squeezy rail. Parses webhooks, re-reads purchases, and creates hosted checkouts and portal links. */
+export function lemonSqueezyRail(
+  credentials: PaymentsLemonSqueezyCredentials,
+  options: LemonSqueezyRailOptions = {},
+): PaymentsRailProvider & CheckoutRail & DiscountRail & PricingRail {
+  return {
+    rail: "lemonSqueezy",
+
+    async verify(receipt: string): 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.
+      return await verifyLemonSqueezyOrder(receipt);
+    },
+
+    async parseNotification(delivery: WebhookDelivery, context: RailRequestContext): Promise<VerifiedNotification> {
+      return await parseLemonSqueezyNotification(delivery, {
+        credentials,
+        deployment: context.deployment,
+        transport: options.transport,
+        sellsSubscription: options.sellsSubscription,
+      });
+    },
+
+    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 refreshLemonSqueezyPurchase(purchase, {
+        credentials,
+        now: context.now,
+        transport: options.transport,
+      });
+    },
+
+    async createCheckoutSession(input: CheckoutSessionInput, context: RailRequestContext): Promise<CheckoutHandoff> {
+      return await createLemonSqueezyCheckoutSession(input, {
+        credentials,
+        deployment: context.deployment,
+        transport: options.transport,
+      });
+    },
+
+    async createPortalSession(input: PortalSessionInput): Promise<PortalHandoff> {
+      return await createLemonSqueezyPortalSession(input, { credentials, transport: options.transport });
+    },
+
+    async readPricing(
+      purchase: PaymentsPurchase,
+      _context: RailRequestContext,
+    ): Promise<SubscriptionPricing | undefined> {
+      return await readLemonSqueezyPricing(purchase, { credentials, transport: options.transport });
+    },
+
+    async listDiscounts(): Promise<readonly ListedDiscount[]> {
+      return await listLemonSqueezyDiscounts({
+        credentials,
+        storeCurrency: options.storeCurrency,
+        transport: options.transport,
+      });
+    },
+
+    async createDiscount(terms: DiscountTerms): Promise<CreatedDiscount> {
+      return await createLemonSqueezyDiscount(terms, {
+        credentials,
+        storeCurrency: options.storeCurrency,
+        transport: options.transport,
+      });
+    },
+  };
+}

package/src/rails/lemonSqueezy/read.ts

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PaymentsProviderUnavailableError } from "../../error/errors";
+import type { PaymentsLemonSqueezyCredentials } from "../../secret/registry";
+import { type LemonSqueezyHttpFetch, lemonSqueezyJson } from "./api";
+import { LemonSqueezyOrder, LemonSqueezySubscription } from "./objects";
+
+/**
+ * The reads this rail makes of Lemon Squeezy: a subscription, and an order.
+ *
+ * Both exist for two callers with different needs, which is why they return `undefined` rather than throwing
+ * on an absent object. The webhook parser reads a subscription to learn which variant an invoice bills; the
+ * reconciliation pass reads one to find out what a purchase looks like now. For the first, an absent
+ * subscription is a delivery that cannot be projected; for the second it is the contract's documented
+ * "the store no longer knows this purchase". Neither is a failure of the rail.
+ *
+ * A store that cannot be *reached* throws `payments/provider_unavailable`, which is what tells the
+ * reconciliation Workflow to fail the step and retry, and what makes the webhook guard answer non-2xx so
+ * Lemon Squeezy redelivers.
+ */
+
+/** What a read needs: the credentials, and the transport to make it through. */
+export interface LemonSqueezyReadOptions {
+  /** The rail's credentials. The API key is read at the point of need and never cached. */
+  credentials: PaymentsLemonSqueezyCredentials;
+  /** The HTTP seam. */
+  transport: LemonSqueezyHttpFetch;
+}
+
+/** A JSON:API single-resource answer, narrowed to the attributes the caller will parse. */
+const Envelope = z.object({
+  data: z.object({ id: z.string(), attributes: z.record(z.string(), z.unknown()) }).loose(),
+});
+
+/** Read one object, or `undefined` when the store has no such thing. */
+async function readObject(
+  path: string,
+  what: string,
+  options: LemonSqueezyReadOptions,
+): Promise<{ id: string; attributes: Record<string, unknown> } | undefined> {
+  const body = await lemonSqueezyJson(options.transport, path, {
+    what,
+    apiKey: options.credentials.apiKey,
+    absentOn404: true,
+  });
+  if (body === undefined) return undefined;
+
+  const envelope = Envelope.safeParse(body);
+  if (!envelope.success) {
+    throw new PaymentsProviderUnavailableError({
+      detail: `Lemon Squeezy answered for ${what} with a body that is not a JSON:API resource.`,
+    });
+  }
+  return { id: envelope.data.data.id, attributes: envelope.data.data.attributes };
+}
+
+/** The subscription with this id, or `undefined` when Lemon Squeezy has none. */
+export async function readSubscription(
+  id: string,
+  options: LemonSqueezyReadOptions,
+): Promise<LemonSqueezySubscription | undefined> {
+  const object = await readObject(`/subscriptions/${encodeURIComponent(id)}`, `subscription ${id}`, options);
+  return object === undefined ? undefined : LemonSqueezySubscription.parse(object.attributes);
+}
+
+/** The order with this id, or `undefined` when Lemon Squeezy has none. */
+export async function readOrder(id: string, options: LemonSqueezyReadOptions): Promise<LemonSqueezyOrder | undefined> {
+  const object = await readObject(`/orders/${encodeURIComponent(id)}`, `order ${id}`, options);
+  return object === undefined ? undefined : LemonSqueezyOrder.parse(object.attributes);
+}

package/src/rails/lemonSqueezy/refresh.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaymentsPurchase } from "../../data/purchase";
+import type { PaymentsLemonSqueezyCredentials } from "../../secret/registry";
+import type { UnboundProviderEvent } from "../contract";
+import type { LemonSqueezyHttpFetch } from "./api";
+import { lemonSqueezyHttpFetch } from "./api";
+import { orderEvent, subscriptionEvent } from "./objects";
+import { readOrder, readSubscription } from "./read";
+
+/**
+ * Re-read a Lemon Squeezy purchase — the reconciliation path.
+ *
+ * Webhooks are dropped, endpoints are misconfigured, and a subscription can lapse with no notification
+ * arriving at all. This is the question the reconciliation Workflow exists to ask, and this rail answers it
+ * for real.
+ *
+ * ## Which rows it can answer for
+ *
+ * **State rows.** `providerTransactionId` is `subscription:<id>`, which is exactly the object Lemon Squeezy
+ * can be asked about, and the answer is the subscription's standing now — the freshest fact anyone holds.
+ *
+ * **Order rows.** `order:<id>`, read back the same way.
+ *
+ * **Money rows are deliberately not refreshed.** A `subscription_invoice:` row records one closed billing
+ * period, and it is born `expired` — which is in the Workflow's terminal set, so the pass never selects one.
+ * Re-reading a closed invoice could only restate what it already says. Should one somehow reach here it
+ * answers `undefined`, which the contract defines as "the store has nothing to say about this purchase" and
+ * which leaves the row exactly as it stands.
+ *
+ * ## The clock is ours
+ *
+ * `providerEventAt` is `context.now`, not the object's `updated_at`, as the contract requires. A refresh is
+ * a read of the state *now*, so it is the freshest fact there is — dating it earlier would let the monotonic
+ * write rule discard the very repair this pass exists to make.
+ */
+
+/** What a refresh needs: the credentials, the clock, and the transport. */
+export interface RefreshLemonSqueezyOptions {
+  /** The rail's credentials. */
+  credentials: PaymentsLemonSqueezyCredentials;
+  /** The clock. Stamped onto the returned event, per the contract. */
+  now: Date;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: LemonSqueezyHttpFetch;
+}
+
+/** Split a namespaced id back into its type and its Lemon Squeezy id. */
+function split(providerTransactionId: string): { type: string; id: string } | undefined {
+  const at = providerTransactionId.indexOf(":");
+  if (at <= 0) return undefined;
+  return { type: providerTransactionId.slice(0, at), id: providerTransactionId.slice(at + 1) };
+}
+
+/** Re-read one purchase, or `undefined` when Lemon Squeezy has nothing to say about it. */
+export async function refreshLemonSqueezyPurchase(
+  purchase: PaymentsPurchase,
+  options: RefreshLemonSqueezyOptions,
+): Promise<UnboundProviderEvent | undefined> {
+  // **The row's own key, never the family's.** Other rails fall back to `originalTransactionId` because
+  // their store can only be asked about the family — Apple's `originalTransactionId`, Play's purchase token.
+  // Here the row's own key already names an addressable object, and falling back would be actively wrong: a
+  // money row's family key is `subscription:<id>`, so it would re-read the *subscription* and answer with a
+  // state event keyed to a different row. Reconciliation would then read that as the row having been
+  // superseded, mark the invoice expired, and project nothing in its place.
+  const key = split(purchase.providerTransactionId);
+  if (key === undefined) return undefined;
+
+  const read = { credentials: options.credentials, transport: options.transport ?? lemonSqueezyHttpFetch };
+
+  if (key.type === "subscription") {
+    const subscription = await readSubscription(key.id, read);
+    if (subscription === undefined) return undefined;
+    return { ...subscriptionEvent(key.id, subscription), providerEventAt: options.now };
+  }
+
+  if (key.type === "order") {
+    const order = await readOrder(key.id, read);
+    if (order === undefined) return undefined;
+    return { ...orderEvent(key.id, order), providerEventAt: options.now };
+  }
+
+  // A `subscription_invoice:` row, or a prefix a later build wrote. Nothing to re-read — see the module doc.
+  return undefined;
+}

package/src/rails/lemonSqueezy/signature.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsVerificationFailedError } from "../../error/errors";
+
+/**
+ * Lemon Squeezy's authenticity proof: a bare HMAC over the exact received bytes, in one header.
+ *
+ * `X-Signature: 5257a8…` — one hex HMAC-SHA256 of the body, keyed with the webhook's signing secret. No
+ * timestamp, no scheme prefix, no list.
+ *
+ * ## Why this does not go through core's `signed-webhook` primitive
+ *
+ * That primitive implements Stripe's format — `t=…,v1=…` — and every security property it enforces is a
+ * property *of that format*: the freshness window in both directions, the timestamp being inside the signed
+ * payload, a cap on how many signatures a header may list. Lemon Squeezy's scheme has none of them to
+ * enforce. Generalizing the primitive to carry a scheme would mean giving it a variant whose `now` and
+ * `toleranceSeconds` are accepted and ignored, and a parameter a caller can set that changes nothing is
+ * worse than no parameter: somebody eventually reads the call site and believes the window is there.
+ *
+ * So the absence is expressed in the type. {@link verifyLemonSqueezySignature} takes no options bag and no
+ * clock — there is nowhere to pass a tolerance, so no call site can claim a window this rail does not
+ * honor, and the refusal union below has two members where Stripe's has three. There is no `stale`.
+ *
+ * ## Where replay protection actually lives
+ *
+ * Entirely in the webhook guard's `UNIQUE (rail, providerEventId)` insert. A captured delivery replayed a
+ * year later carries a signature that is still valid — that is a true fact about this scheme, not a defect
+ * in this module — and is refused because its event id is already in `pithy_payments_webhook_events`. The
+ * projection's monotonic `providerEventAt` rule is the second line: a replayed state claim about a
+ * subscription that has since moved on is staler than the row and is ignored.
+ *
+ * Worth stating plainly because it is the one property an operator might assume from the other rails and
+ * not have here.
+ *
+ * ## What a refusal says
+ *
+ * `payments/verification_failed`, with the reason in `detail` and nothing the delivery carried — not the
+ * body, not the candidate signature, never the secret. `detail` reaches an operator's log, and the webhook
+ * guard maps this to `payments/webhook_unverified` (401) before anything reaches the sender, so a forger
+ * learns only that it failed. That code is this rail's contract with its guard.
+ */
+
+/** The header Lemon Squeezy puts its proof in. Lower case, because that is how Hono presents a header name. */
+export const LEMON_SQUEEZY_SIGNATURE_HEADER = "x-signature";
+
+/** How many bytes an HMAC-SHA256 is. A candidate of any other length cannot be one, whatever it decodes to. */
+const HMAC_SHA256_BYTES = 32;
+
+/** Why a delivery was refused. Two members, not Stripe's three — this scheme carries no timestamp to be stale. */
+type LemonSqueezyRefusal = "unreadable" | "unmatched";
+
+/** Decode lower- or upper-case hex, or `undefined` when it is not hex at all. */
+function hexBytes(value: string): Uint8Array | undefined {
+  if (value.length === 0 || value.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(value)) return undefined;
+  const bytes = new Uint8Array(value.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/** Import a signing secret for HMAC-SHA256. */
+async function signingKey(secret: string, usage: "sign" | "verify"): Promise<CryptoKey> {
+  return await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage],
+  );
+}
+
+/**
+ * The signature Lemon Squeezy would send for these bytes — lower-case hex.
+ *
+ * Exported for the tests and the fixtures, which mint their own so verification is exercised for real
+ * rather than stubbed. Nothing in the request path signs anything: this rail only ever verifies.
+ */
+export async function signLemonSqueezyBody(body: string, secret: string): Promise<string> {
+  const mac = await crypto.subtle.sign("HMAC", await signingKey(secret, "sign"), new TextEncoder().encode(body));
+  return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Verify one delivery's `X-Signature`. Resolves when Lemon Squeezy signed these exact bytes, and throws
+ * `payments/verification_failed` otherwise.
+ *
+ * The comparison is `crypto.subtle.verify`, never `===` on the hex and never a hand-written loop: the
+ * runtime's own compare is constant-time, and a string equality on a MAC leaks how many leading bytes an
+ * attacker got right.
+ */
+export async function verifyLemonSqueezySignature(body: string, header: string | null, secret: string): Promise<void> {
+  const candidate = header === null ? undefined : hexBytes(header.trim());
+  if (candidate === undefined || candidate.length !== HMAC_SHA256_BYTES) {
+    throw new PaymentsVerificationFailedError({ detail: refusal("unreadable") });
+  }
+
+  const matched = await crypto.subtle.verify(
+    "HMAC",
+    await signingKey(secret, "verify"),
+    candidate,
+    new TextEncoder().encode(body),
+  );
+  if (!matched) throw new PaymentsVerificationFailedError({ detail: refusal("unmatched") });
+}
+
+/**
+ * This rail's wording for its two refusals.
+ *
+ * Prefixed `Lemon Squeezy:` 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 refusal(reason: LemonSqueezyRefusal): string {
+  return reason === "unreadable"
+    ? "Lemon Squeezy: the delivery carries no X-Signature header holding 32 bytes of hex."
+    : "Lemon Squeezy: the X-Signature does not match these bytes under the configured signing secret. Check that the secret belongs to this webhook and this store.";
+}

package/src/rails/lemonSqueezy/verify.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsInvalidReceiptError } from "../../error/errors";
+import type { VerifiedPurchase } from "../contract";
+
+/**
+ * This rail has no client-submittable receipt, and says so.
+ *
+ * ## Why refusing is the secure answer
+ *
+ * `verify` exists so a buyer sees their entitlement without waiting for the webhook. Stripe can do that
+ * because a returning buyer carries a Checkout Session id that Stripe substituted into the success URL: an
+ * unguessable token this deployment's own server can trade for a session carrying `client_reference_id`.
+ *
+ * Lemon Squeezy has no equivalent. Its order ids are **sequential integers**, so a `verify` that trusted a
+ * submitted order id would let any authenticated caller claim any order in the store by counting — including
+ * one belonging to somebody who has not signed in yet, whose purchase would then be bound to the attacker
+ * forever, because `linkProviderAccount` never rebinds and the first pairing wins.
+ *
+ * The order's UUID `identifier` was the obvious repair and is not one. It is unguessable, but it is not a
+ * *credential*: it appears in the buyer's own receipt email and in the storefront's return URL, so it proves
+ * possession of a value that was never secret, and Lemon Squeezy does not return `custom_data` on the order
+ * object in a form this server could check against the caller. Binding on an unguessable-but-unauthenticated
+ * identifier is exactly the class of mistake the {@link VerifiedPurchase.accountReference} doc warns about:
+ * it lets a client's choice of value decide who a purchase belongs to.
+ *
+ * ## What it costs, stated plainly
+ *
+ * A Lemon Squeezy buyer's entitlement appears when the webhook lands rather than the moment they return —
+ * seconds, usually. The `successUrl` this rail's config asks for should therefore show a pending state and
+ * poll, not post a receipt. `docs/lemon-squeezy.md` says so, and the scaffolded return page does it.
+ *
+ * The webhook is authoritative on every rail anyway. Here it is simply the only path.
+ */
+
+/** Refuse a submitted Lemon Squeezy receipt. There is no shape of one that could be trusted. */
+export async function verifyLemonSqueezyOrder(_receipt: string): Promise<VerifiedPurchase> {
+  throw new PaymentsInvalidReceiptError({
+    message: "Lemon Squeezy purchases confirm themselves.",
+    action: "Nothing to submit. Your purchase appears as soon as Lemon Squeezy tells the server about it.",
+    detail:
+      "Lemon Squeezy has no client-submittable receipt: an order id is a sequential integer, and the order object carries no reference this server set, so accepting one would let any authenticated caller claim an unprojected order by counting. Purchases on this rail land through the webhook alone.",
+  });
+}