@pithy-sh/payments 0.1.0

package/src/rails/google/rail.ts

@@ -0,0 +1,174 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaymentsPurchase } from "../../data/purchase";
+import { PaymentsVerificationFailedError } from "../../error/errors";
+import type { PaymentsGoogleCredentials } from "../../secret/registry";
+import type {
+  PaymentsRailProvider,
+  RailRequestContext,
+  UnboundProviderEvent,
+  VerifiedNotification,
+  VerifiedPurchase,
+  WebhookDelivery,
+} from "../contract";
+import type { GoogleHttpFetch } from "./http";
+import { type GoogleJwk, verifyGoogleOidcToken } from "./oidc";
+import { refreshPlayPurchase, resolvePlayPointer } from "./playApi";
+import { parseGoogleNotification } from "./rtdn";
+import { verifyGooglePurchase } from "./verify";
+
+/**
+ * The Google Play rail as one provider object — the two halves of the contract, closed over the app's identity.
+ *
+ * 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 it keeps the secret read at the point of need.
+ *
+ * ## Three checks, in this order, and each covers what the one before it cannot
+ *
+ * 1. **The OIDC token proves Google sent the delivery.** It arrives in the `Authorization` header rather than in
+ *    the body, because a Pub/Sub push is not signed — the token is the whole proof.
+ * 2. **The audience claim proves it was minted for *this* endpoint.** Google signs these tokens for every push
+ *    subscription in the world with the same keys, so the signature alone is worth nothing. See `oidc.ts`.
+ * 3. **The package name proves it concerns *this app*.** A token says who delivered it and nothing about what it
+ *    is about, so without this any Play developer who can reach the endpoint could name a SKU in our catalog.
+ *
+ * ## And then a fourth call, which is Google's own doing
+ *
+ * A Real-time Developer Notification is a pointer: a purchase token and a notification type, with no state. So
+ * every projectable notification costs a Play Developer API lookup. That is the shape of Play's API rather than
+ * a choice here, and it is why an unreachable Play API is `payments/provider_unavailable` (503) — the route
+ * rethrows that so Pub/Sub redelivers, because the alternative is projecting a guess.
+ *
+ * ## One gap, recorded rather than papered over
+ *
+ * A **voided one-time purchase** cannot be resolved on this path. Play's voided-purchase notification names an
+ * order id and no product, and Play's one-time lookup takes the product id as a path segment — so there is no
+ * call this module can make that turns that token into a state. The delivery is recorded with a note carrying
+ * the order id, which is the key the purchase row is already stored under, and the reconciliation Workflow
+ * resolves it with one query. Subscription refunds have no such gap: they arrive as `SUBSCRIPTION_REVOKED` and
+ * project immediately.
+ */
+
+/**
+ * How the Google rail's trust and transport may be widened, and the only callers with a reason to.
+ *
+ * `trustedKeys` is additive, so nothing can narrow production's trust: a token whose `kid` these do not cover is
+ * still resolved against Google's published set. It exists for the tests, which mint their own key so the
+ * signature check is exercised for real, and for a local **Pub/Sub emulator**, whose tokens are signed by a key
+ * Google never saw.
+ */
+export interface GoogleRailOptions {
+  /** Verification keys accepted in addition to Google's published set, matched by `kid`. */
+  trustedKeys?: readonly GoogleJwk[];
+  /** The HTTP seam Google's two endpoints are reached through. Defaults to the runtime's `fetch`. */
+  transport?: GoogleHttpFetch;
+  /**
+   * A Play access token already minted, so a batch of refreshes pays for one round-trip instead of one each.
+   * Passed down by the reconciliation Workflow; absent everywhere else, where one call mints its own.
+   */
+  accessToken?: string;
+}
+
+/** The `Authorization` scheme a Pub/Sub push uses for its OIDC token. */
+const BEARER = "bearer ";
+
+/** The Google Play rail. Verifies client submissions at Play, and Pub/Sub pushes on the webhook. */
+export function googleRail(
+  credentials: PaymentsGoogleCredentials,
+  options: GoogleRailOptions = {},
+): PaymentsRailProvider {
+  return {
+    rail: "google",
+
+    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 receipt is normal traffic — a
+      // stale token, a product the token is not for — so it must not read as a runtime fault in a log.
+      return await verifyGooglePurchase(receipt, {
+        credentials,
+        now: context.now,
+        transport: options.transport,
+      });
+    },
+
+    async parseNotification(delivery: WebhookDelivery, context: RailRequestContext): Promise<VerifiedNotification> {
+      // The header, not the body. A Pub/Sub push body carries no signature at all, so nothing about it is
+      // trustworthy until the token beside it verifies.
+      const authorization = delivery.headers.get("authorization") ?? "";
+      if (!authorization.toLowerCase().startsWith(BEARER)) {
+        throw new PaymentsVerificationFailedError({
+          detail:
+            "Google: the push carries no Authorization bearer token. Configure the Pub/Sub push subscription to authenticate with a service account.",
+        });
+      }
+      await verifyGoogleOidcToken(authorization.slice(BEARER.length).trim(), {
+        audience: credentials.pubsubAudience,
+        serviceAccountEmail: credentials.serviceAccountEmail,
+        now: context.now,
+        transport: options.transport,
+        trustedKeys: options.trustedKeys,
+      });
+
+      const parsed = parseGoogleNotification(delivery.body, { packageName: credentials.packageName });
+      if (parsed.pointer === null) {
+        return {
+          providerEventId: parsed.providerEventId,
+          payload: parsed.payload,
+          event: null,
+          providerAccountId: null,
+          // A void carries no state and needs none: the order id names the row, and the route owns the
+          // database that has it. See `VerifiedNotification.voidedOrderId`.
+          voidedOrderId: parsed.voidedOrderId,
+          // `stated`: `parseGoogleNotification` reads the delivered bytes and nothing else, so this note is
+          // what the notification says. The same bytes get the same answer for ever — terminal.
+          note: parsed.note === null ? null : { stated: parsed.note },
+        };
+      }
+
+      const state = await resolvePlayPointer(parsed.pointer, {
+        credentials,
+        now: context.now,
+        transport: options.transport,
+      });
+      if (state === undefined) {
+        // Authentic, and about a purchase Play will not show us — a token from a deleted app, or a
+        // notification that raced its own purchase.
+        //
+        // **`read`, not `stated`, and that is #341.** This sentence is the output of a call to Play, and the
+        // second reason above is a race by name: an RTDN is published before Play's own read-after-write has
+        // settled often enough that Google documents the retry. The note said "the answer will not change",
+        // which is true of the *bytes* and false of the *lookup* — so a note derived from it finished the row,
+        // and the redelivery Pub/Sub was already queuing was answered `duplicate`. Repairable.
+        return {
+          providerEventId: parsed.providerEventId,
+          payload: parsed.payload,
+          event: null,
+          providerAccountId: null,
+          note: {
+            read: `google: Play has no ${parsed.pointer.kind === "subscription" ? "subscription" : "one-time purchase"} under the token this notification points at.`,
+          },
+        };
+      }
+
+      return {
+        providerEventId: parsed.providerEventId,
+        payload: parsed.payload,
+        event: state.event,
+        providerAccountId: state.providerAccountId,
+        note: null,
+      };
+    },
+
+    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 refreshPlayPurchase(purchase, {
+        credentials,
+        now: context.now,
+        transport: options.transport,
+        accessToken: options.accessToken,
+      });
+    },
+  };
+}

package/src/rails/google/rtdn.ts

@@ -0,0 +1,331 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { PurchaseStatus } from "../../data/status";
+import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors";
+import { base64UrlDecode } from "./jwt";
+
+/**
+ * Play's Real-time Developer Notification, and the honest shape of what it tells us.
+ *
+ * **The payload is a pointer, not a state.** Apple and Stripe deliver the transaction inline; Play delivers a
+ * purchase token and a notification type, and nothing about the purchase's current condition. So this module
+ * produces a {@link GoogleNotificationPointer} — which purchase changed, and nothing more — and resolving it to
+ * a state is the *next* call, into the Play Developer API. That is modeled in the type rather than papered
+ * over: the pointer has no status field, so there is no place for a guess to hide.
+ *
+ * Guessing would be the alternative, and it fails in both directions. `SUBSCRIPTION_RENEWED` looks like
+ * "active", but the renewal it announces may already have been refunded by the time we read it; `EXPIRED` looks
+ * terminal, but Play sends it for a subscription the user has since restarted. Only the API knows, and it is
+ * the same API the reconciliation Workflow reads, so both paths converge on one answer.
+ *
+ * **One exception, and it is not a guess.** A revoked subscription reads as `EXPIRED` in the API once it is
+ * revoked, which loses the fact that money went back. The notification type is the only surviving record of
+ * that, so `SUBSCRIPTION_REVOKED` travels as an explicit `statusOverride` — a fact the API cannot report,
+ * carried in a field named for what it is.
+ *
+ * ## The envelope
+ *
+ * A notification does not arrive from Google Play. It arrives from **Pub/Sub**, as a push whose body wraps a
+ * base64 Developer Notification and whose `Authorization` header carries the OIDC token that proves it is
+ * Google's (see `oidc.ts`). Pub/Sub's `messageId` is stable across redeliveries of one message, which is what
+ * makes it the dedupe key `UNIQUE (rail, providerEventId)` needs.
+ */
+
+/** Play's `SUBSCRIPTION_REVOKED`. The one notification type whose meaning the API does not preserve. */
+const SUBSCRIPTION_REVOKED = 12;
+
+/** A string of milliseconds since the epoch — how Google writes a timestamp in an RTDN. */
+const GoogleEventMillis = z
+  .string()
+  .regex(/^\d+$/, "A Play event time is a string of milliseconds since the epoch.")
+  .describe(
+    "When Google recorded the event, as a decimal string of milliseconds. A string, not a number — Play's JSON encodes 64-bit integers that way, and parsing it loosely would yield an Invalid Date the monotonic write rule would silently lose to.",
+  );
+
+/** The Pub/Sub push envelope. `.loose()` so a new envelope field never refuses a real notification. */
+export const GooglePubSubPush = z
+  .object({
+    message: z
+      .object({
+        data: z
+          .string()
+          .min(1)
+          .describe("The Developer Notification, base64-encoded. Standard base64 with padding, as Pub/Sub emits."),
+        messageId: z
+          .string()
+          .min(1)
+          .describe(
+            "Pub/Sub's own id for this message. Stable across redeliveries, which is what makes it the dedupe key.",
+          ),
+        publishTime: z.string().min(1).optional().describe("When Pub/Sub published the message, RFC 3339."),
+      })
+      .loose()
+      .describe("The Pub/Sub message carrying one Developer Notification."),
+    subscription: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The push subscription's resource name. Recorded for diagnosis; nothing is decided from it."),
+  })
+  .loose()
+  .describe("The body Pub/Sub POSTs to a push endpoint.");
+export type GooglePubSubPush = z.infer<typeof GooglePubSubPush>;
+
+/** One Play Developer Notification. Exactly one of the four notification blocks is present. */
+export const GoogleDeveloperNotification = z
+  .object({
+    version: z.string().min(1).describe("The notification schema version Google sent — `1.0` throughout v1."),
+    packageName: z
+      .string()
+      .min(1)
+      .describe(
+        "The Android application id the event concerns. Checked against our own: a push token proves Google sent the delivery and says nothing about which app it is about.",
+      ),
+    eventTimeMillis: GoogleEventMillis.describe(
+      "When Google recorded the event. This is the provider event time the monotonic write rule compares against.",
+    ),
+    subscriptionNotification: z
+      .object({
+        version: z.string().min(1).describe("The block's schema version."),
+        notificationType: z
+          .number()
+          .int()
+          .describe(
+            "What happened, as Play's own integer. Recorded and reported, but not mapped to a status — the API is what says what the subscription is now.",
+          ),
+        purchaseToken: z
+          .string()
+          .min(1)
+          .describe("The subscription's purchase token. Stable across renewals, so it is the family's identity."),
+        subscriptionId: z.string().min(1).describe("The base subscription product id, as listed in the Play Console."),
+      })
+      .loose()
+      .optional()
+      .describe("Present when the event concerns a subscription."),
+    oneTimeProductNotification: z
+      .object({
+        version: z.string().min(1).describe("The block's schema version."),
+        notificationType: z.number().int().describe("1 for purchased, 2 for canceled."),
+        purchaseToken: z.string().min(1).describe("The purchase token for the one-time order."),
+        sku: z
+          .string()
+          .min(1)
+          .describe(
+            "The product id. Load-bearing here and nowhere else: Play's one-time lookup takes it as a path segment, so a pointer without it could not be resolved.",
+          ),
+      })
+      .loose()
+      .optional()
+      .describe("Present when the event concerns a one-time product."),
+    voidedPurchaseNotification: z
+      .object({
+        purchaseToken: z.string().min(1).describe("The voided purchase's token."),
+        orderId: z
+          .string()
+          .min(1)
+          .describe("The voided order — which, for a one-time purchase, is the id its purchase row is keyed by."),
+        productType: z.number().int().describe("1 for a subscription, 2 for a one-time product."),
+        refundType: z.number().int().optional().describe("1 for a full refund, 2 for a partial one."),
+      })
+      .loose()
+      .optional()
+      .describe("Present when a purchase was refunded or charged back."),
+    testNotification: z
+      .object({ version: z.string().min(1).describe("The block's schema version.") })
+      .loose()
+      .optional()
+      .describe("Present for the notification the Play Console's test button sends. Concerns no purchase."),
+  })
+  .loose()
+  .describe("One Play Real-time Developer Notification, decoded out of its Pub/Sub envelope.");
+export type GoogleDeveloperNotification = z.infer<typeof GoogleDeveloperNotification>;
+
+/** Which Play lookup resolves a pointer. The two take different endpoints and different path parameters. */
+export type GoogleNotificationKind = "subscription" | "one_time";
+
+/**
+ * Which purchase a notification is about. Deliberately carries no state — see the module doc.
+ */
+export interface GoogleNotificationPointer {
+  /** Which Play lookup resolves it. */
+  kind: GoogleNotificationKind;
+  /** The purchase token the lookup is keyed by. */
+  purchaseToken: string;
+  /** The product id, when the notification names one. Required for a one-time lookup, informational otherwise. */
+  productId: string | null;
+  /** Play's own notification type. Reported and audited; never mapped to a status. */
+  notificationType: number;
+  /**
+   * The one status the Play API cannot report and the notification can. `revoked` for a revoked subscription,
+   * which the API reports as merely expired, and null for everything else.
+   */
+  statusOverride: PurchaseStatus | null;
+  /** Google's own event time. What the monotonic write rule compares against. */
+  eventAt: Date;
+}
+
+/** A verified, decoded notification: what to record, and what to resolve. */
+export interface ParsedGoogleNotification {
+  /** Pub/Sub's message id — the dedupe key. */
+  providerEventId: string;
+  /** What to store on the webhook row: the decoded notification plus the envelope's own metadata. */
+  payload: Record<string, unknown>;
+  /** The app the notification concerns, already checked against ours. */
+  packageName: string;
+  /** Google's own event time. */
+  eventAt: Date;
+  /** Which purchase changed, or null when the notification concerns none. */
+  pointer: GoogleNotificationPointer | null;
+  /**
+   * Why a notification with no pointer had none, when that is worth recording. Null when there is nothing to
+   * say — a test notification needs no explanation.
+   */
+  note: string | null;
+  /**
+   * The order a voided-purchase notification refunded, or null. Reported rather than only described, because
+   * an order id is exactly what a Google purchase's `providerTransactionId` is — so the route can find the
+   * row this refund is about even though Play offers no lookup that would.
+   */
+  voidedOrderId: string | null;
+}
+
+/** What parsing needs: our own application id, and nothing else. */
+export interface ParseGoogleNotificationOptions {
+  /** Our Android application id. A notification for any other app is refused. */
+  packageName: string;
+}
+
+/**
+ * Decode one Pub/Sub push into a pointer.
+ *
+ * Authenticity is not established here — that is `verifyGoogleOidcToken`, and it runs first. What this adds is
+ * the check a token cannot make: Google signs a push token for every Pub/Sub subscription there is, so a valid
+ * token says nothing about which app a notification concerns. Without the package check, any Play developer who
+ * can reach our endpoint can send us a SKU that happens to match our catalog.
+ *
+ * @throws {@link PaymentsInvalidReceiptError} when the body cannot be read as a Pub/Sub push carrying a
+ *   Developer Notification.
+ * @throws {@link PaymentsVerificationFailedError} when it is readable and concerns another app.
+ */
+export function parseGoogleNotification(
+  body: string,
+  options: ParseGoogleNotificationOptions,
+): ParsedGoogleNotification {
+  let envelope: unknown;
+  try {
+    envelope = JSON.parse(body) as unknown;
+  } catch (cause) {
+    throw malformed("the push body is not JSON.", cause);
+  }
+
+  const push = GooglePubSubPush.safeParse(envelope);
+  if (!push.success) throw malformed(`the push body is not a Pub/Sub push — ${issues(push.error)}.`);
+
+  const decoded = new TextDecoder().decode(base64UrlDecode(push.data.message.data, "the push message data"));
+  let raw: unknown;
+  try {
+    raw = JSON.parse(decoded) as unknown;
+  } catch (cause) {
+    throw malformed("the push message data is not JSON.", cause);
+  }
+
+  const parsed = GoogleDeveloperNotification.safeParse(raw);
+  if (!parsed.success) {
+    throw malformed(`the push carries no Play developer notification — ${issues(parsed.error)}.`);
+  }
+  const notification = parsed.data;
+
+  if (notification.packageName !== options.packageName) {
+    throw new PaymentsVerificationFailedError({
+      message: "That notification is not for this app.",
+      action: "Check that the Play Console app and this deployment's package name are the same.",
+      detail: `Google: the notification is for "${notification.packageName}", this app is "${options.packageName}".`,
+    });
+  }
+
+  const eventAt = new Date(Number(notification.eventTimeMillis));
+  const common = {
+    providerEventId: push.data.message.messageId,
+    // The base64 `data` is deliberately dropped: keeping it would store the same bytes twice, and the decoded
+    // form is what a human reads and what a replay needs.
+    payload: {
+      subscription: push.data.subscription,
+      message: { messageId: push.data.message.messageId, publishTime: push.data.message.publishTime },
+      notification,
+    } as Record<string, unknown>,
+    packageName: notification.packageName,
+    eventAt,
+    // Only the voided branch overrides this; every other notification refunds nothing.
+    voidedOrderId: null as string | null,
+  };
+
+  if (notification.subscriptionNotification) {
+    const block = notification.subscriptionNotification;
+    return {
+      ...common,
+      pointer: {
+        kind: "subscription",
+        purchaseToken: block.purchaseToken,
+        productId: block.subscriptionId,
+        notificationType: block.notificationType,
+        statusOverride: block.notificationType === SUBSCRIPTION_REVOKED ? "revoked" : null,
+        eventAt,
+      },
+      note: null,
+    };
+  }
+
+  if (notification.oneTimeProductNotification) {
+    const block = notification.oneTimeProductNotification;
+    return {
+      ...common,
+      pointer: {
+        kind: "one_time",
+        purchaseToken: block.purchaseToken,
+        productId: block.sku,
+        notificationType: block.notificationType,
+        statusOverride: null,
+        eventAt,
+      },
+      note: null,
+    };
+  }
+
+  if (notification.voidedPurchaseNotification) {
+    // No pointer, and there cannot be one: a voided notification names no product, and Play's one-time lookup
+    // takes the product id as a path segment, so no call this module can make turns the token back into a
+    // state. But it does not need to. The notification is authentic and it says the order was refunded — the
+    // same statement Apple's `REFUND` makes — and the product it concerns is in our own row, which is keyed by
+    // this very order id. So the order travels out as `voidedOrderId` and the route resolves it.
+    const block = notification.voidedPurchaseNotification;
+    return {
+      ...common,
+      pointer: null,
+      voidedOrderId: block.orderId,
+      note: `google: purchase voided (order ${block.orderId}, productType ${block.productType}, refundType ${block.refundType ?? "unspecified"}).`,
+    };
+  }
+
+  if (notification.testNotification) return { ...common, pointer: null, note: null };
+
+  // Google adds notification kinds, and a type this build has never heard of must not be an error: answering
+  // non-2xx would make Pub/Sub redeliver it forever and read as a broken endpoint. Recorded, and the note is
+  // what makes it visible rather than silently dropped.
+  return {
+    ...common,
+    pointer: null,
+    note: "google: the notification carries no notification this build recognizes, so there is nothing to resolve.",
+  };
+}
+
+/** A structural refusal. The body is never echoed: a purchase token is a bearer artifact. */
+function malformed(detail: string, cause?: unknown): PaymentsInvalidReceiptError {
+  return new PaymentsInvalidReceiptError({ detail: `Google: ${detail}` }, cause === undefined ? undefined : { cause });
+}
+
+/** Zod issues as `path:code` pairs — never `message` or `received`, which would echo the payload. */
+function issues(error: z.ZodError): string {
+  return error.issues.map((issue) => `${issue.path.join(".") || "<root>"}:${issue.code}`).join(", ");
+}

package/src/rails/google/verify.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PaymentsInvalidReceiptError, PaymentsVerificationFailedError } from "../../error/errors";
+import type { VerifiedPurchase } from "../contract";
+import {
+  fetchPlayProduct,
+  fetchPlaySubscription,
+  type PlayApiOptions,
+  playProductEvent,
+  playSubscriptionEvent,
+} from "./playApi";
+
+/**
+ * The client-submission path for Google: a Play purchase token, verified at Google.
+ *
+ * **There is no offline verification here, and that is Play's design rather than ours.** Play Billing hands the
+ * app a purchase token and, optionally, a signature over the receipt JSON made with the app's licensing key —
+ * which is a key Google publishes per app in the Play Console and which is not in this rail's credential bundle
+ * on purpose. Checking it would prove the JSON came from Play; it would not prove the purchase still stands, and
+ * a refunded purchase's receipt keeps verifying forever. So the token is looked up. One round-trip buys the
+ * current state, which is the thing an entitlement should rest on.
+ *
+ * Nothing about correctness rests on this path in any case. The webhook produces the identical row through the
+ * same idempotent writer, so a dropped submission costs nothing and a replayed one changes nothing. What it buys
+ * is immediacy: the buyer sees their entitlement the moment they buy, rather than when Pub/Sub gets round to it.
+ *
+ * ## Why a client-declared product id is safe here
+ *
+ * `PurchaseSubmission` carries no product id, deliberately — a client-declared product would let a caller
+ * present a cheap receipt as an expensive one. What the receipt *does* carry, because Play Billing puts it
+ * there, is the product the app thinks it bought, and that value is used as **a lookup key and never as a
+ * claim**: Play's one-time endpoint takes the product id as a path segment and answers 404 when the token does
+ * not belong to it. So a lie fails at Google rather than being believed here, and the id that lands in the
+ * purchase row is the one Google confirmed by answering.
+ *
+ * ## Why the subscription lookup goes first
+ *
+ * Play has no call that says what kind of purchase a token is. The subscription endpoint takes a token alone, so
+ * it can answer without believing anything the client said; its 404 is then how a one-time purchase identifies
+ * itself, and only then is the declared product id used at all.
+ */
+
+/** The longest a product id may be, matching the catalog's own bound. */
+const MAX_SKU_LENGTH = 200;
+
+/** The longest a purchase token may be. Play's are around a hundred characters; this is generous. */
+const MAX_TOKEN_LENGTH = 4096;
+
+/**
+ * What a client submits for the Google rail: `Purchase.getOriginalJson()`, verbatim.
+ *
+ * `.loose()` because Play Billing's JSON carries more than this and its shape moves between library versions.
+ * Both product spellings are accepted: Play Billing 4 and earlier emit `productId`, 5 and later emit a
+ * `productIds` array, and which one arrives depends on the app's library version rather than on anything a
+ * server decides.
+ */
+export const GooglePlayReceipt = z
+  .object({
+    purchaseToken: z
+      .string()
+      .min(1)
+      .max(MAX_TOKEN_LENGTH)
+      .describe("Play's own token for the purchase. The only field this path cannot do without."),
+    productId: z
+      .string()
+      .min(1)
+      .max(MAX_SKU_LENGTH)
+      .optional()
+      .describe(
+        "What the app thinks it bought, as Play Billing 4 and earlier report it. A lookup key, never a claim — Play answers 404 when the token does not belong to it.",
+      ),
+    productIds: z
+      .array(z.string().min(1).max(MAX_SKU_LENGTH).describe("One product the order covers."))
+      .min(1)
+      .optional()
+      .describe("The same thing as Play Billing 5 and later report it. The first entry is the product looked up."),
+  })
+  .loose()
+  .describe("A Play purchase as the Billing Library's `getOriginalJson()` returns it.");
+export type GooglePlayReceipt = z.infer<typeof GooglePlayReceipt>;
+
+/** Verify a client-submitted Play purchase and normalize it. The caller binds the authenticated purchaser. */
+export async function verifyGooglePurchase(receipt: string, options: PlayApiOptions): Promise<VerifiedPurchase> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(receipt) as unknown;
+  } catch (cause) {
+    // Never echo the receipt: it is caller-supplied, and it is what a stolen one would look like in a log.
+    throw new PaymentsInvalidReceiptError({ detail: "Google: the submitted purchase is not JSON." }, { cause });
+  }
+
+  const parsed = GooglePlayReceipt.safeParse(raw);
+  if (!parsed.success) {
+    throw new PaymentsInvalidReceiptError({
+      detail: `Google: the submitted purchase is not a Play receipt — ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}:${issue.code}`).join(", ")}.`,
+    });
+  }
+  const { purchaseToken } = parsed.data;
+  const productId = parsed.data.productId ?? parsed.data.productIds?.[0];
+
+  // A client submission is a read of the current state, so the clock is the honest event time: there is no
+  // provider timestamp on a Play purchase, and inventing an older one would make a submission lose to a
+  // notification it is newer than.
+  const context = { purchaseToken, eventAt: options.now };
+
+  // The token alone. Nothing the client said is used yet.
+  const subscription = await fetchPlaySubscription(purchaseToken, options);
+  if (subscription !== undefined) return playSubscriptionEvent(subscription, context);
+
+  if (productId === undefined) {
+    throw new PaymentsVerificationFailedError({
+      detail:
+        "Google: the purchase is not a subscription and the receipt names no product id, so there is no one-time purchase to look up. Submit `Purchase.getOriginalJson()` unaltered.",
+    });
+  }
+
+  const product = await fetchPlayProduct(productId, purchaseToken, options);
+  if (product !== undefined) return playProductEvent(product, { ...context, productId });
+
+  // Play knows neither a subscription nor a one-time purchase under this token and product. Either the token is
+  // not ours, or it is not for the product it claims. Both are the same statement to a client.
+  throw new PaymentsVerificationFailedError({
+    detail: `Google: Play has no subscription under this token and no "${productId}" purchase under it either.`,
+  });
+}