@pithy-sh/payments 0.1.0

package/src/rails/paddle/refresh.ts

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SubscriptionPricing } from "../../data/discount";
+import type { PaymentsPurchase } from "../../data/purchase";
+import type { PaymentsPaddleCredentials } from "../../secret/registry";
+import type { UnboundProviderEvent } from "../contract";
+import { type PaddleEnvironment, type PaddleHttpFetch, paddleHttpFetch, paddleJson } from "./api";
+import { currencyOf, minorAmount, subscriptionEvent, transactionEvent } from "./objects";
+import { readSubscription, readTransaction } from "./read";
+
+/**
+ * Re-read a Paddle purchase — the reconciliation path — and read what it pays.
+ *
+ * Webhooks are dropped, destinations 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
+ *
+ * Paddle's ids are globally prefixed, so the row's own key says what to ask: `sub_…` is a subscription,
+ * `txn_…` is a transaction. Both are addressable, so both are re-read — unlike Lemon Squeezy, where a
+ * money row records a closed period and has nothing to re-read.
+ *
+ * A **subscription** transaction's money row is born `expired`, which is in the Workflow's terminal set,
+ * so the pass never selects one. Should one reach here it is answered honestly rather than skipped: a
+ * refunded transaction is exactly the thing worth re-reading.
+ *
+ * ## 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 account, the clock, and the transport. */
+export interface RefreshPaddleOptions {
+  /** The rail's credentials. */
+  credentials: PaymentsPaddleCredentials;
+  /** Which Paddle account to read from. */
+  environment: PaddleEnvironment;
+  /** The clock. Stamped onto the returned event, per the contract. */
+  now: Date;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: PaddleHttpFetch;
+}
+
+/** Re-read one purchase, or `undefined` when Paddle has nothing to say about it. */
+export async function refreshPaddlePurchase(
+  purchase: PaymentsPurchase,
+  options: RefreshPaddleOptions,
+): Promise<UnboundProviderEvent | undefined> {
+  const read = {
+    credentials: options.credentials,
+    environment: options.environment,
+    transport: options.transport ?? paddleHttpFetch,
+  };
+  // **The row's own key, never the family's.** A money row's family key is `sub_…`, so falling back would
+  // re-read the subscription and answer with a state event keyed to a different row — which reconciliation
+  // would read as the row having been superseded.
+  const id = purchase.providerTransactionId;
+  const environment = options.environment === "production" ? "production" : "sandbox";
+
+  if (id.startsWith("sub_")) {
+    const subscription = await readSubscription(id, read);
+    if (subscription === undefined) return undefined;
+    return { ...subscriptionEvent(subscription, options.now, environment), providerEventAt: options.now };
+  }
+
+  if (id.startsWith("txn_")) {
+    const transaction = await readTransaction(id, read);
+    if (transaction === undefined) return undefined;
+    return { ...transactionEvent(transaction, options.now, environment), providerEventAt: options.now };
+  }
+
+  // A prefix a later build wrote. Nothing to re-read, which the contract defines as "the store has
+  // nothing to say about this purchase" and which leaves the row exactly as it stands.
+  return undefined;
+}
+
+/**
+ * What a Paddle subscription pays now, what it becomes, and when.
+ *
+ * Read from Paddle rather than computed. `include=next_transaction` carries what the next invoice comes
+ * to under any discount in force; `include=recurring_transaction_details` carries what it comes to at
+ * list price. Nothing here multiplies a price by a percentage — a second calculation would be a second
+ * answer to the one question a customer checks against their statement.
+ *
+ * Only a `sub_…` row can be asked. A transaction records one closed period and has no "next", so it
+ * answers `undefined` — the same "nothing to say about this purchase" the refresh path uses.
+ */
+export async function readPaddlePricing(
+  purchase: PaymentsPurchase,
+  options: RefreshPaddleOptions,
+): Promise<SubscriptionPricing | undefined> {
+  const id = purchase.providerTransactionId;
+  if (!id.startsWith("sub_")) return undefined;
+
+  const answer = await paddleJson(options.transport ?? paddleHttpFetch, `/subscriptions/${encodeURIComponent(id)}`, {
+    what: `subscription ${id}'s pricing`,
+    apiKey: options.credentials.apiKey,
+    environment: options.environment,
+    query: [["include", "next_transaction,recurring_transaction_details"]],
+    absentOn404: true,
+  });
+  if (answer === undefined) return undefined;
+
+  const data = answer.data as Record<string, unknown> | null;
+  if (data === null || typeof data !== "object") return undefined;
+
+  const next = totalsOf(data.next_transaction);
+  const recurring = totalsOf(data.recurring_transaction_details);
+  const discount = data.discount as Record<string, unknown> | null | undefined;
+  const endsAt = typeof discount?.ends_at === "string" ? new Date(discount.ends_at) : null;
+
+  return {
+    currency: next.currency ?? recurring.currency,
+    // What the next invoice actually comes to, under whatever is in force.
+    currentAmountMinor: next.total ?? recurring.total,
+    // What it comes to at list price. Equal to the current amount when no discount is in force, which is
+    // how a screen tells "this is your rate" from "this is your rate until March".
+    listAmountMinor: recurring.total ?? next.total,
+    // **Always null, and that is a stated limitation rather than a gap.** Paddle's subscription object
+    // carries `discount.id` and no code, so naming the code would mean a second round trip on every
+    // read of a screen a customer refreshes. `discountEndsAt` is the field that stops a bill changing
+    // unannounced, and it is here: a screen says "your rate changes on the 3rd" without naming the code
+    // that set it.
+    discountCode: null,
+    discountEndsAt: endsAt !== null && !Number.isNaN(endsAt.getTime()) ? endsAt : null,
+  };
+}
+
+/**
+ * Pull the total and its currency out of whichever include shape carried it.
+ *
+ * **The two includes are not the same shape**, and a reader that knew only one would silently answer null
+ * for the other — leaving a screen reporting no list price and a customer told nothing about the date
+ * their rate changes. `next_transaction` nests its figures under `details.totals`; `recurring_transaction
+ * _details` carries `totals` at the top. Both are checked, in that order.
+ */
+function totalsOf(value: unknown): { total: number | null; currency: string | null } {
+  if (value === null || typeof value !== "object") return { total: null, currency: null };
+  const bagged = value as Record<string, unknown>;
+  const details = bagged.details;
+  const nested = details !== null && typeof details === "object" ? (details as Record<string, unknown>).totals : null;
+  const totals = nested ?? bagged.totals ?? null;
+  if (totals === null || typeof totals !== "object") return { total: null, currency: null };
+  const bag = totals as Record<string, unknown>;
+  return {
+    total: minorAmount(typeof bag.total === "string" ? bag.total : (bag.grand_total as string | undefined)),
+    currency: currencyOf(typeof bag.currency_code === "string" ? bag.currency_code : null),
+  };
+}

package/src/rails/paddle/refund.ts

@@ -0,0 +1,297 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaymentsPurchase } from "../../data/purchase";
+import { RefundRequest, type RefundRequestOutcome, type RefundRequestStatus } from "../../data/subscription";
+import { PaymentsProviderUnavailableError, PaymentsSubscriptionChangeRefusedError } from "../../error/errors";
+import type { PaymentsPaddleCredentials } from "../../secret/registry";
+import type { RefundRequestInput } from "../contract";
+import { REVOKING_ACTIONS } from "./adjustments";
+import { type PaddleEnvironment, type PaddleHttpFetch, paddleHttpFetch, paddleJson, redactPaddleSecrets } from "./api";
+import { PaddleAdjustment, type PaddleTransaction } from "./objects";
+import { PADDLE_ADJUSTMENTS_INCLUDE, readTransaction } from "./read";
+
+/**
+ * Asking Paddle to give a subscriber's payments back — the fourth verb of #465.
+ *
+ * ## Three facts about Paddle shaped every line of this
+ *
+ * **1. It is a request, not a completion.** `POST /adjustments` creates an adjustment, and on a live
+ * account Paddle holds most refunds at `pending_approval` until a person there reviews them; the sandbox
+ * approves on its own, roughly ten minutes later. So nothing here says the money moved, nothing revokes an
+ * entitlement, and nothing writes a purchase row. An approved refund arrives as a webhook, and
+ * `adjustments.ts` and the projection writer already act on it — they are the only things that do.
+ * Revoking on the *request* would take access from a customer whose refund Paddle then rejects, leaving
+ * them with neither the money nor the product.
+ *
+ * **2. Refunds attach to a transaction, not to a subscription.** There is no endpoint that refunds a
+ * subscription, so this raises one adjustment per transaction and reports one outcome per transaction.
+ * The case is ordinary: a customer who joined on Solo at 6.00, upgraded to Team on day 10 for a 65.82
+ * proration and cancels on day 13 has paid twice, and a refund policy owes them both.
+ *
+ * **3. They do not stack.** Paddle: *"You can't create an adjustment for a transaction that has a refund
+ * that's pending approval."* Learning that from Paddle, mid-set, after other adjustments have already been
+ * raised, is the worst possible place to learn it — so it is decided here, from the transaction's own
+ * `include=adjustments`, before anything is sent.
+ *
+ * ## The guarantee, and the line it is split at
+ *
+ * All-or-nothing across the whole set **cannot be built**: Paddle offers no batch adjustment and no delete,
+ * so once the first one is at `pending_approval` nothing un-raises it. The guarantee is therefore split at
+ * the only line that is real — whether this call has written anything yet:
+ *
+ * - **Before the first write**, every transaction is read and checked, and anything that makes one
+ *   unrefundable refuses the *whole request* with `payments/subscription_change_refused` having sent
+ *   nothing. {@link MAX_PADDLE_REFUND_TRANSACTIONS} is enforced first, for the same reason.
+ * - **After the first write**, nothing throws. Every remaining failure becomes a `failed` outcome, because
+ *   an error raised over a state where money is already moving is precisely the silent partial this module
+ *   is designed against.
+ *
+ * A refund that is already standing is neither: it is reported as `already_requested` and no call is made.
+ * That is the per-payment form of the no-op rule the other four verbs follow — a retried write must not
+ * become a second refund, and a 409 for the state the caller asked for is simply wrong.
+ *
+ * ## The window is not here
+ *
+ * How long a customer has to ask for their money back is the **adopter's** policy, with a company's
+ * commercial decisions behind it. This module refunds what it is handed and hard-codes no window; the
+ * adopter's screen decides which button exists.
+ */
+
+/** What every call here needs: the credentials, which Paddle account, and the transport. */
+export interface PaddleRefundOptions {
+  /** The rail's credentials. The API key is read at the point of need and never cached. */
+  credentials: PaymentsPaddleCredentials;
+  /** Which Paddle account to reach. */
+  environment: PaddleEnvironment;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: PaddleHttpFetch;
+}
+
+/**
+ * The most transactions one request will refund.
+ *
+ * **A bound on subrequests, not a policy.** Each transaction costs two calls — a read and a create — and a
+ * Worker's subrequest budget is finite. A call that runs out of it half way through is a partial by
+ * another name, and the one thing this module will not produce. So the size is checked before anything is
+ * read, and a set that is too large is refused whole.
+ *
+ * Twelve, and the two ends of the range are what pick it. Any refund window an adopter would set holds one
+ * or two transactions on a monthly plan — the recorded upgrade case is two — so nothing legitimate comes
+ * near it. And twenty-four calls sits well inside the budget with room for everything else a request does.
+ * An adopter reversing a whole subscription history is doing something else, and the Paddle dashboard is
+ * the tool for it.
+ */
+export const MAX_PADDLE_REFUND_TRANSACTIONS = 12;
+
+/** What Paddle sends and what this module states. Anything else is `unknown` — see the enum's own doc. */
+const REFUND_STATUS: Readonly<Record<string, RefundRequestStatus>> = {
+  pending_approval: "awaiting_review",
+  approved: "approved",
+  rejected: "rejected",
+  reversed: "reversed",
+};
+
+/** The request cannot be honored, and nothing has been sent. 409, with the reason in `detail`. */
+function refuse(detail: string): never {
+  throw new PaymentsSubscriptionChangeRefusedError({
+    message: "That refund cannot be requested.",
+    action: "Re-read the subscription and the payments on it, then ask for a refund the present state allows.",
+    detail,
+  });
+}
+
+/** The transaction this purchase row names, or null when it names none. */
+function transactionIdOf(purchase: PaymentsPurchase): string | null {
+  const id = purchase.providerTransactionId;
+  return id.startsWith("txn_") ? id : null;
+}
+
+/**
+ * The adjustment already standing against this transaction, or undefined.
+ *
+ * **Two cases block, and one deliberately does not.** A `refund` awaiting review blocks because Paddle
+ * refuses a second one outright. An *approved* revoking adjustment — {@link REVOKING_ACTIONS}, so a
+ * chargeback counts — blocks because the money is already back and a second refund would send it twice.
+ *
+ * A **rejected** refund does not block. A reviewer at Paddle turning one down is not a permanent bar, and
+ * treating it as one would make somebody else's decision final over money the adopter has chosen to give
+ * back. Neither does a `credit` against a balance, which is not a revocation — the same line
+ * `adjustments.ts` draws, read from its set rather than restated here.
+ */
+function standingRefund(transaction: PaddleTransaction): PaddleAdjustment | undefined {
+  return (transaction.adjustments ?? []).find((one) => {
+    if (one.status === "pending_approval") return one.action === "refund";
+    return one.status === "approved" && REVOKING_ACTIONS.has(one.action);
+  });
+}
+
+/** One payment, checked at the store and ready to be acted on. */
+interface Checked {
+  /** The row the outcome is reported against. */
+  purchase: PaymentsPurchase;
+  /** The Paddle transaction to refund. */
+  transactionId: string;
+  /** The refund already standing on it, when one is. Present means nothing is sent for this payment. */
+  standing: PaddleAdjustment | undefined;
+}
+
+/**
+ * Read and check every payment, or refuse the whole request. **No write happens inside this.**
+ *
+ * A transaction Paddle does not know, or one it will not refund, refuses the request rather than becoming
+ * an outcome: it is knowable in advance, and everything knowable in advance is decided while refusing is
+ * still free. A store that cannot be *reached* raises `payments/provider_unavailable` from `paddleJson`
+ * and is left to propagate, because nothing about the subscription is wrong and telling a customer their
+ * refund was refused over a timeout is a true sentence about the wrong thing.
+ */
+async function check(purchases: readonly PaymentsPurchase[], options: PaddleRefundOptions): Promise<Checked[]> {
+  const read = {
+    credentials: options.credentials,
+    environment: options.environment,
+    transport: options.transport ?? paddleHttpFetch,
+  };
+  const checked: Checked[] = [];
+
+  for (const purchase of purchases) {
+    const transactionId = transactionIdOf(purchase);
+    if (transactionId === null) {
+      refuse(
+        `Purchase ${purchase.id} names ${JSON.stringify(purchase.providerTransactionId)}, which is not a Paddle transaction. A refund attaches to a transaction, and a subscription is not one.`,
+      );
+    }
+
+    const transaction = await readTransaction(transactionId, read, PADDLE_ADJUSTMENTS_INCLUDE);
+    if (transaction === undefined) {
+      refuse(`Paddle has no transaction ${transactionId}, so there is nothing on it to refund.`);
+    }
+    if (transaction.status !== "completed") {
+      refuse(
+        `Paddle reports transaction ${transactionId} as ${JSON.stringify(transaction.status)}, and only a completed transaction can be refunded. Nothing in this set was raised.`,
+      );
+    }
+
+    checked.push({ purchase, transactionId, standing: standingRefund(transaction) });
+  }
+
+  return checked;
+}
+
+/** Paddle's status, as this package states it. An unmapped one is `unknown` — never a throw. */
+function statusOf(stated: string | null | undefined): RefundRequestStatus {
+  return (typeof stated === "string" ? REFUND_STATUS[stated] : undefined) ?? "unknown";
+}
+
+/**
+ * Ask Paddle to refund these payments in full, and report what became of each.
+ *
+ * The report is **total** over the input — one outcome per purchase, in the order given — because a report
+ * shorter than the set is what a silent partial looks like. See {@link RefundRequest}.
+ */
+export async function requestPaddleRefunds(
+  input: RefundRequestInput,
+  options: PaddleRefundOptions,
+): Promise<RefundRequest> {
+  const { purchases, reason } = input;
+
+  if (purchases.length === 0) {
+    // Not an empty report. "Nothing to refund, all done" is a sentence about somebody's money that
+    // nobody asked for; a caller with nothing to refund has a refusal to render.
+    refuse("No payment was named, so there is nothing to refund.");
+  }
+  if (purchases.length > MAX_PADDLE_REFUND_TRANSACTIONS) {
+    refuse(
+      `${purchases.length} payments were named and one request refunds at most ${MAX_PADDLE_REFUND_TRANSACTIONS}. A call that runs out of budget half way through is a partial refund nobody asked for, so the whole set is refused before anything is read.`,
+    );
+  }
+
+  const checked = await check(purchases, options);
+  const transport = options.transport ?? paddleHttpFetch;
+  const outcomes: RefundRequestOutcome[] = [];
+  let raised = 0;
+
+  for (const one of checked) {
+    if (one.standing !== undefined) {
+      outcomes.push({
+        outcome: "already_requested",
+        purchaseId: one.purchase.id,
+        adjustmentId: one.standing.id,
+        status: statusOf(one.standing.status),
+      });
+      continue;
+    }
+
+    let answer: unknown;
+    try {
+      const response = await paddleJson(transport, "/adjustments", {
+        what: `a refund on transaction ${one.transactionId} (this key needs the adjustment.write permission)`,
+        apiKey: options.credentials.apiKey,
+        environment: options.environment,
+        method: "POST",
+        body: {
+          // The only action this module ever sends. `credit`, `chargeback` and the rest are Paddle's to
+          // raise; a value here would be a second verb wearing this one's name and its own audit row.
+          action: "refund",
+          // The transaction's whole total. `partial` needs `txnitm_` ids nothing here holds, and an
+          // amount on a bearer route is a self-service withdrawal.
+          type: "full",
+          transaction_id: one.transactionId,
+          reason,
+        },
+      });
+      answer = response?.data;
+    } catch (error) {
+      // **The line the whole design sits on.** With nothing raised, an error is the honest answer and the
+      // more useful one. With an adjustment already in flight, throwing would tell the caller the refund
+      // failed while the customer's money is on its way back — the silent partial, told backwards.
+      if (raised === 0) throw error;
+      outcomes.push({ outcome: "failed", purchaseId: one.purchase.id, reason: said(error, one.transactionId) });
+      continue;
+    }
+
+    const parsed = PaddleAdjustment.safeParse(answer);
+    if (!parsed.success) {
+      // Paddle answered 2xx, so an adjustment may well exist and this build simply cannot read it. Before
+      // the first write that is a shape change worth failing on; after it, losing the adjustment that
+      // definitely does exist is the worse outcome.
+      if (raised === 0) {
+        throw new PaymentsProviderUnavailableError({
+          detail: `Paddle answered the refund of transaction ${one.transactionId} in a shape this build cannot read.`,
+        });
+      }
+      outcomes.push({
+        outcome: "failed",
+        purchaseId: one.purchase.id,
+        reason: `Paddle answered the refund of transaction ${one.transactionId} in a shape this build cannot read, so whether one was raised is unknown. Check the transaction's adjustments at Paddle.`,
+      });
+      continue;
+    }
+
+    raised += 1;
+    outcomes.push({
+      outcome: "requested",
+      purchaseId: one.purchase.id,
+      adjustmentId: parsed.data.id,
+      status: statusOf(parsed.data.status),
+    });
+  }
+
+  // Parsed rather than returned raw: this crosses into a route that hands it to an audit trail and to a
+  // browser, and every boundary in this package is validated. It also refuses an outcome list that lost
+  // an entry, which is the one defect the shape exists to prevent.
+  return RefundRequest.parse({ outcomes });
+}
+
+/**
+ * What went wrong, in an operator's words, with anything key-shaped blanked.
+ *
+ * A reported reason lands in an audit trail and in a log, and the API key is in every request this module
+ * makes. `paddleJson` has already put Paddle's own sentence in `detail` and redacted it once; this redacts
+ * again rather than trusting that, because the cost of the second pass is nothing and the cost of the
+ * assumption being wrong is a credential in a long-lived queryable table.
+ */
+function said(error: unknown, transactionId: string): string {
+  const detail = (error as { payload?: { detail?: unknown } } | null)?.payload?.detail;
+  const stated = typeof detail === "string" && detail !== "" ? ` ${redactPaddleSecrets(detail)}` : "";
+  return `Paddle would not refund transaction ${transactionId}.${stated}`;
+}

package/src/rails/paddle/signature.ts

@@ -0,0 +1,225 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsVerificationFailedError } from "../../error/errors";
+
+/**
+ * Paddle's authenticity proof: a timestamp and one or more HMACs, in one header.
+ *
+ * `Paddle-Signature: ts=1770000000;h1=5257a8…` — elements split on `;`, key and value split on `=`, and
+ * the signed payload is the timestamp, **a colon**, and the exact received body. HMAC-SHA256, hex,
+ * keyed with the notification destination's `pdl_ntfset_…` secret.
+ *
+ * ## Why this is a second verifier and not a widened core primitive
+ *
+ * The issue that scoped this work said Paddle "fits the existing timestamped shape of
+ * `requireSignedWebhook` with no new scheme." It does not, and the difference is two characters that
+ * decide whether anything is verified at all. `packages/core/src/http/signedWebhook.ts` splits the header
+ * on `,` and builds its signed payload as `` `${timestamp}.${body}` `` — Stripe's format. Paddle uses `;`
+ * and `:`. Neither is a parameter, and the module doc there argues *deliberately* that the signed payload
+ * must never become a caller-supplied template, because a payload a caller can shape is a payload a caller
+ * can shape into one that matches.
+ *
+ * So there were two options, and this is the one taken out loud: generalize the core primitive — editing a
+ * package this issue does not scope, against its own written reasoning — or write the scheme here, as the
+ * Lemon Squeezy rail already did for its own. This is the sibling precedent, and it keeps the change inside
+ * `@pithy-sh/payments`.
+ *
+ * The cost is real and worth naming: two modules now know how to check an HMAC. What they do not share is
+ * a *format*, which is the part that would have had to become configurable, and a configurable format is
+ * how #125 shipped a `requireSignedWebhook("lemonSqueezy", …)` that structurally could not verify the
+ * signatures it claimed to.
+ *
+ * ## The freshness window, and why it is 300 seconds and not 5
+ *
+ * Paddle's own SDKs default to five seconds. This defaults to three hundred, and the reason is what
+ * replay protection actually rests on here: `UNIQUE (rail, providerEventId)` over `evt_…`, in the webhook
+ * guard, which is absolute. A captured delivery replayed a year later is refused because its event id is
+ * already recorded — no window is doing that work. What a five-second window *does* do is convert ordinary
+ * clock skew between a Cloudflare edge and Paddle into a dropped renewal.
+ *
+ * The window still earns its place, in both directions. It bounds how long a captured-but-never-delivered
+ * signature stays usable, and it refuses a far-future timestamp — either a broken clock or somebody trying
+ * to mint a delivery that never goes stale. Configurable, so an adopter who wants Paddle's number can set
+ * it.
+ *
+ * Paddle re-signs each retry attempt with a fresh `ts`, which is the only way a three-day retry window and
+ * a five-second SDK tolerance could both be coherent — so the window does not silently reject retries.
+ *
+ * ## 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. The webhook guard maps this to
+ * `payments/webhook_unverified` (401) before anything reaches the sender, so a forger learns only that it
+ * failed.
+ */
+
+/** The header Paddle puts its proof in. Lower case, because that is how Hono presents a header name. */
+export const PADDLE_SIGNATURE_HEADER = "paddle-signature";
+
+/** How long a delivery stays acceptable, by default. See the module doc for why this is not Paddle's 5. */
+export const PADDLE_DEFAULT_FRESHNESS_SECONDS = 300;
+
+/** 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;
+
+/**
+ * How many `h1` values a header may list.
+ *
+ * Paddle lists more than one only while a destination's secret is being rotated, which pairs the old and
+ * the new — so two is the real number and this is generous. It is bounded at all because each listed
+ * candidate costs an HMAC: unbounded, the header would be a free way to make this Worker do arbitrary
+ * work. Core's primitive caps its own list for the same reason.
+ */
+const MAX_SIGNATURES = 5;
+
+/** Why a delivery was refused. Three members: this scheme carries a timestamp, so `stale` is real here. */
+type PaddleRefusal = "unreadable" | "stale" | "unmatched";
+
+/** What the verifier needs beyond the bytes: the secret, the clock, and the window. */
+export interface VerifyPaddleSignatureOptions {
+  /** The notification destination's signing secret — `pdl_ntfset_…`. Never logged. */
+  secret: string;
+  /** The clock, for the freshness window. Injected so verification is deterministic. */
+  now: Date;
+  /** How many seconds either side of `now` a delivery may be dated. Undefined uses the default. */
+  toleranceSeconds?: number;
+}
+
+/** One parsed header: when Paddle says it signed, and every candidate MAC it listed. */
+interface ParsedSignature {
+  /** The `ts` value, as seconds since the epoch. */
+  timestamp: number;
+  /** Every `h1` value, decoded. */
+  candidates: Uint8Array[];
+}
+
+/** 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 Paddle would send for these bytes at this second — 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 signPaddleBody(timestamp: number, body: string, secret: string): Promise<string> {
+  const mac = await crypto.subtle.sign(
+    "HMAC",
+    await signingKey(secret, "sign"),
+    // The colon, and it is the whole difference from Stripe's scheme. A period here would produce a MAC
+    // that never matches, and a verifier that never matches is a rail that never receives a webhook.
+    new TextEncoder().encode(`${timestamp}:${body}`),
+  );
+  return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Parse the header into a timestamp and its candidate MACs, or `undefined` when it is not one.
+ *
+ * Strict about shape on purpose. Everything here is attacker-controlled text, and a lenient parse is how
+ * a verifier ends up comparing an empty candidate against an empty expectation and returning happily.
+ */
+function parse(header: string): ParsedSignature | undefined {
+  let timestamp: number | undefined;
+  const candidates: Uint8Array[] = [];
+
+  for (const element of header.split(";")) {
+    const at = element.indexOf("=");
+    if (at <= 0) continue;
+    const key = element.slice(0, at).trim();
+    const value = element.slice(at + 1).trim();
+    if (value === "") continue;
+
+    if (key === "ts") {
+      // The first `ts` wins, and a second one is not merged: a header listing two timestamps is not a
+      // shape Paddle produces, and picking either would be guessing at what was signed.
+      if (timestamp !== undefined) return undefined;
+      if (!/^\d+$/.test(value)) return undefined;
+      timestamp = Number.parseInt(value, 10);
+      if (!Number.isSafeInteger(timestamp)) return undefined;
+      continue;
+    }
+
+    if (key === "h1") {
+      // Refused rather than truncated. Silently taking the first five of a hundred would leave a header
+      // that costs bounded work and reads as accepted, which hides the abuse it exists to stop.
+      if (candidates.length >= MAX_SIGNATURES) return undefined;
+      const bytes = hexBytes(value);
+      if (bytes === undefined || bytes.length !== HMAC_SHA256_BYTES) return undefined;
+      candidates.push(bytes);
+    }
+  }
+
+  if (timestamp === undefined || candidates.length === 0) return undefined;
+  return { timestamp, candidates };
+}
+
+/**
+ * Verify one delivery's `Paddle-Signature`. Resolves when Paddle signed these exact bytes at a moment
+ * inside the window, 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.
+ *
+ * The freshness check runs **before** the MACs. A stale delivery is refused whatever it carries, and
+ * refusing it first means an expired capture does not buy an attacker even one HMAC of work.
+ */
+export async function verifyPaddleSignature(
+  body: string,
+  header: string | null,
+  options: VerifyPaddleSignatureOptions,
+): Promise<void> {
+  const parsed = header === null ? undefined : parse(header.trim());
+  if (parsed === undefined) throw new PaymentsVerificationFailedError({ detail: refusal("unreadable") });
+
+  const tolerance = options.toleranceSeconds ?? PADDLE_DEFAULT_FRESHNESS_SECONDS;
+  const drift = Math.abs(Math.floor(options.now.getTime() / 1000) - parsed.timestamp);
+  if (drift > tolerance) throw new PaymentsVerificationFailedError({ detail: refusal("stale") });
+
+  // The timestamp is inside the signed message, so a captured signature cannot be re-dated to slip
+  // through the window above: editing `ts` breaks the MAC checked here.
+  const key = await signingKey(options.secret, "verify");
+  const message = new TextEncoder().encode(`${parsed.timestamp}:${body}`);
+  for (const candidate of parsed.candidates) {
+    if (await crypto.subtle.verify("HMAC", key, candidate, message)) return;
+  }
+  throw new PaymentsVerificationFailedError({ detail: refusal("unmatched") });
+}
+
+/**
+ * This rail's wording for its three refusals.
+ *
+ * Prefixed `Paddle:` 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 — `detail` reaches a log, and a forger must not be able to write into one.
+ */
+function refusal(reason: PaddleRefusal): string {
+  switch (reason) {
+    case "unreadable":
+      return "Paddle: the delivery carries no Paddle-Signature header of the form ts=<seconds>;h1=<64 hex chars>.";
+    case "stale":
+      return "Paddle: the delivery's ts is outside the freshness window. Check this Worker's clock, or widen `paddle.webhookFreshnessSeconds`.";
+    case "unmatched":
+      return "Paddle: no h1 matches an HMAC-SHA256 of `ts:body` under the configured signing secret. Check that the secret belongs to this notification destination and this environment.";
+  }
+}