@pithy-sh/payments 0.1.0

package/src/rails/google/fixtures/play-product-purchased.json

@@ -0,0 +1,14 @@
+{
+  "kind": "androidpublisher#productPurchase",
+  "purchaseTimeMillis": "1768435200000",
+  "purchaseState": 0,
+  "consumptionState": 0,
+  "developerPayload": "",
+  "orderId": "GPA.3311-8452-9910-77304",
+  "acknowledgementState": 1,
+  "obfuscatedExternalAccountId": "b7e1c94f2a6d4c0e",
+  "regionCode": "US",
+  "quantity": 1,
+  "productId": "coins_100",
+  "purchaseToken": "ppgmhnokdjkfbicoloakhnli.AO-J1OyR4wKcTz8mHbXe1uQfLp"
+}

package/src/rails/google/fixtures/play-subscription-active.json

@@ -0,0 +1,23 @@
+{
+  "kind": "androidpublisher#subscriptionPurchaseV2",
+  "regionCode": "US",
+  "startTime": "2026-01-01T00:00:00Z",
+  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
+  "latestOrderId": "GPA.3311-8452-9910-77301..0",
+  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
+  "externalAccountIdentifiers": {
+    "obfuscatedExternalAccountId": "b7e1c94f2a6d4c0e"
+  },
+  "lineItems": [
+    {
+      "productId": "pro_monthly",
+      "expiryTime": "2026-02-01T00:00:00Z",
+      "autoRenewingPlan": {
+        "autoRenewEnabled": true
+      },
+      "offerDetails": {
+        "basePlanId": "monthly"
+      }
+    }
+  ]
+}

package/src/rails/google/fixtures/push.ts

@@ -0,0 +1,152 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { GoogleJwk } from "../oidc";
+
+/**
+ * Test material for Google's rail: a real RSA key, real RS256 signatures, and the Pub/Sub push envelope
+ * Google wraps a Real-time Developer Notification in.
+ *
+ * The OIDC token on a push is the authenticity boundary for the Google webhook, so its tests have to exercise
+ * genuine cryptography — a stubbed verifier proves only that a mock refuses when told to. And no test may
+ * reach Google. So the suites mint their own signing key here, publish it as a JWK the verifier is given, and
+ * sign real tokens with it: the same arrangement as the Apple rail's minted certificate chain, one layer
+ * simpler because Google publishes bare keys rather than a chain.
+ *
+ * That makes the negative cases real too. A token signed by the wrong key is a second minted key. An expired
+ * token is a real signature over a past `exp`. An algorithm-confused token is a genuine RSA signature under a
+ * header that lies about it. None of them is a refusal on command.
+ *
+ * This module signs and encodes; the shipped code only verifies and decodes. It lives under `fixtures/` for
+ * that reason, next to the recorded notification payloads.
+ */
+
+/** A minted signing key: the JWK a verifier is given, and the private half a test signs with. */
+export interface MintedOidcKey {
+  /** The key id, matched against a token header's `kid`. */
+  kid: string;
+  /** The public key as a JWK, in the shape Google's own key endpoint publishes. */
+  jwk: GoogleJwk;
+  /** The private half. What signs a token. */
+  privateKey: CryptoKey;
+}
+
+/** RS256, which is the only algorithm Google signs a Pub/Sub push token with. */
+const RS256 = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" } as const;
+
+/** Mint one RSA key pair and publish its public half as a JWK. */
+export async function mintOidcKey(kid = "pithy-test-1"): Promise<MintedOidcKey> {
+  // `generateKey`'s return type is the union of both its overloads; an RSA algorithm always yields a pair.
+  const pair = (await crypto.subtle.generateKey(
+    { ...RS256, modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]) },
+    true,
+    ["sign", "verify"],
+  )) as CryptoKeyPair;
+  // `exportKey`'s type is the union over every format; `jwk` always yields a JsonWebKey.
+  const exported = (await crypto.subtle.exportKey("jwk", pair.publicKey)) as JsonWebKey;
+  if (exported.kty === undefined || exported.n === undefined || exported.e === undefined) {
+    // Cannot happen for an RSA key, and a fixture that silently minted a key with an empty modulus would make
+    // every signature test pass against nothing.
+    throw new Error("WebCrypto exported an RSA public key with no kty, n, or e.");
+  }
+  return {
+    kid,
+    // `kty`, `n`, and `e` come from the export; `kid`, `alg`, and `use` are what a key endpoint adds.
+    jwk: { ...exported, kty: exported.kty, n: exported.n, e: exported.e, kid, alg: "RS256", use: "sig" },
+    privateKey: pair.privateKey,
+  };
+}
+
+/** A minted service-account key: the PEM a credential bundle carries, and the public half to check it with. */
+export interface MintedServiceAccountKey {
+  /** The PKCS#8 PEM, exactly as the `private_key` field of a downloaded Google key file holds it. */
+  pem: string;
+  /** The public half, so a test can verify the assertion the shipped code signed rather than trusting it. */
+  publicKey: CryptoKey;
+}
+
+/**
+ * Mint an RSA key pair and armour the private half as the PKCS#8 PEM a Google service-account key file carries.
+ *
+ * The public half comes back so a suite can **verify** the assertion the shipped signer produced. That is the
+ * difference between asserting we posted something to the token endpoint and asserting we posted a signature
+ * Google would accept.
+ */
+export async function mintServiceAccountKey(): Promise<MintedServiceAccountKey> {
+  const pair = (await crypto.subtle.generateKey(
+    { ...RS256, modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]) },
+    true,
+    ["sign", "verify"],
+  )) as CryptoKeyPair;
+  const pkcs8 = new Uint8Array((await crypto.subtle.exportKey("pkcs8", pair.privateKey)) as ArrayBuffer);
+  let binary = "";
+  for (const byte of pkcs8) binary += String.fromCharCode(byte);
+  const body = (btoa(binary).match(/.{1,64}/g) ?? []).join("\n");
+  return {
+    pem: `-----BEGIN PRIVATE KEY-----\n${body}\n-----END PRIVATE KEY-----\n`,
+    publicKey: pair.publicKey,
+  };
+}
+
+/** base64url without padding — how every segment of a JWS is encoded. */
+function base64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+/**
+ * Sign a compact JWT the way Google signs a push token: an `RS256` header naming the key, the claims, and an
+ * RSASSA-PKCS1-v1_5 signature over `header.payload`.
+ *
+ * `header` overrides let a test present a header Google never would — `alg: "none"`, `alg: "HS256"`, a `kid`
+ * nobody published — which is how algorithm confusion is proved rejected rather than assumed impossible.
+ */
+export async function signOidcToken(
+  claims: unknown,
+  key: MintedOidcKey,
+  header: Record<string, unknown> = {},
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const head = base64Url(encoder.encode(JSON.stringify({ alg: "RS256", typ: "JWT", kid: key.kid, ...header })));
+  const body = base64Url(encoder.encode(JSON.stringify(claims)));
+  const signature = new Uint8Array(
+    await crypto.subtle.sign(RS256.name, key.privateKey, encoder.encode(`${head}.${body}`)),
+  );
+  return `${head}.${body}.${base64Url(signature)}`;
+}
+
+/** A compact JWT with its claims swapped for others, keeping the original signature. The tamper case. */
+export function tamperClaims(token: string, claims: unknown): string {
+  const [head, , signature] = token.split(".");
+  return `${head}.${base64Url(new TextEncoder().encode(JSON.stringify(claims)))}.${signature}`;
+}
+
+/** What a test varies about the envelope around a notification. */
+export interface PushEnvelopeOptions {
+  /** Pub/Sub's own message id — the dedupe key, stable across redeliveries of one message. */
+  messageId?: string;
+  /** When Pub/Sub published it, RFC 3339. */
+  publishTime?: string;
+  /** The push subscription's resource name. Informational; nothing is decided from it. */
+  subscription?: string;
+}
+
+/**
+ * Wrap a decoded Developer Notification in the Pub/Sub push envelope Google POSTs.
+ *
+ * `data` is **standard** base64 with padding, which is what Pub/Sub emits — deliberately not base64url, so the
+ * decoder under test is exercised against the alphabet it will really receive.
+ */
+export function pushBody(notification: unknown, options: PushEnvelopeOptions = {}): string {
+  let binary = "";
+  for (const byte of new TextEncoder().encode(JSON.stringify(notification))) binary += String.fromCharCode(byte);
+  return JSON.stringify({
+    message: {
+      data: btoa(binary),
+      messageId: options.messageId ?? "6714080000000001",
+      publishTime: options.publishTime ?? "2026-01-15T00:00:00.000Z",
+    },
+    subscription: options.subscription ?? "projects/acme-42/subscriptions/pithy-payments-rtdn",
+  });
+}

package/src/rails/google/fixtures/rtdn-one-time-purchased.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0",
+  "packageName": "com.acme.app",
+  "eventTimeMillis": "1768435200000",
+  "oneTimeProductNotification": {
+    "version": "1.0",
+    "notificationType": 1,
+    "purchaseToken": "ppgmhnokdjkfbicoloakhnli.AO-J1OyR4wKcTz8mHbXe1uQfLp",
+    "sku": "coins_100"
+  }
+}

package/src/rails/google/fixtures/rtdn-subscription-renewed.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0",
+  "packageName": "com.acme.app",
+  "eventTimeMillis": "1768435200000",
+  "subscriptionNotification": {
+    "version": "1.0",
+    "notificationType": 2,
+    "purchaseToken": "gjdmnbkpaifcmlkgomhnpjbi.AO-J1OwXn3rM5pQe7vT2yLb0dK",
+    "subscriptionId": "pro_monthly"
+  }
+}

package/src/rails/google/fixtures/rtdn-subscription-revoked.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0",
+  "packageName": "com.acme.app",
+  "eventTimeMillis": "1768521600000",
+  "subscriptionNotification": {
+    "version": "1.0",
+    "notificationType": 12,
+    "purchaseToken": "gjdmnbkpaifcmlkgomhnpjbi.AO-J1OwXn3rM5pQe7vT2yLb0dK",
+    "subscriptionId": "pro_monthly"
+  }
+}

package/src/rails/google/fixtures/rtdn-test.json

@@ -0,0 +1,8 @@
+{
+  "version": "1.0",
+  "packageName": "com.acme.app",
+  "eventTimeMillis": "1768435200000",
+  "testNotification": {
+    "version": "1.0"
+  }
+}

package/src/rails/google/fixtures/rtdn-voided-purchase.json

@@ -0,0 +1,11 @@
+{
+  "version": "1.0",
+  "packageName": "com.acme.app",
+  "eventTimeMillis": "1768608000000",
+  "voidedPurchaseNotification": {
+    "purchaseToken": "ppgmhnokdjkfbicoloakhnli.AO-J1OyR4wKcTz8mHbXe1uQfLp",
+    "orderId": "GPA.3311-8452-9910-77304",
+    "productType": 2,
+    "refundType": 1
+  }
+}

package/src/rails/google/http.ts

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsProviderUnavailableError } from "../../error/errors";
+
+/**
+ * The one door out to Google, and the mapping from how it answered to what that means.
+ *
+ * **Why the Google rail reaches the network at all.** Apple hands us a signed transaction that verifies
+ * offline; Play hands us a purchase token, which is a pointer and nothing more. So Google's rail has two
+ * unavoidable round-trips — the JWKS that verifies a push token, and the Play Developer API that turns a
+ * pointer into a state — and every failure mode of those round-trips has to land somewhere deliberate.
+ *
+ * **Every failure but one is `payments/provider_unavailable` (503).** A timeout, a 5xx, a rate limit, a
+ * revoked service-account grant, an HTML error page from a proxy: from payments' side these are one
+ * statement — *we could not learn the state* — and the correct response to not knowing is to say so and let
+ * the caller retry. A silent skip would be the alternative, and a silent skip on a renewal notification
+ * revokes a paying subscriber. The webhook route rethrows a 503 so Pub/Sub redelivers, and the
+ * reconciliation Workflow repairs whatever redelivery never fixes.
+ *
+ * **The exception is a 404 the caller asked for.** Play has no "what kind of purchase is this token" call, so
+ * a 404 from the subscription endpoint is how a one-time purchase identifies itself. That is a fact about the
+ * purchase rather than a failure to reach the store, and only a caller that knows it is probing may treat it
+ * as one — hence `absentOn404` rather than a blanket rule.
+ *
+ * **No refusal carries the URL or the response body.** A Play request URL ends in the purchase token, and
+ * Google's error bodies quote the request. `detail` reaches an operator's logs, and a purchase token is a
+ * bearer artifact — the same rule as a receipt.
+ */
+
+/** One outbound request, narrowed to what Google's two endpoints need. */
+export interface GoogleHttpRequest {
+  /** The HTTP method. Defaults to GET. */
+  method?: string;
+  /** Request headers — the bearer token, or the token endpoint's form content type. */
+  headers?: Record<string, string>;
+  /** The request body, already encoded. */
+  body?: string;
+}
+
+/** The response shape this module reads. Structural, so a test's transport need not be a whole `Response`. */
+export interface GoogleHttpResponse {
+  /** Whether the status is 2xx. */
+  ok: boolean;
+  /** The status code, which is what decides the mapping. */
+  status: number;
+  /** The body as text. Read as text rather than JSON so a non-JSON answer is a diagnosis, not a throw. */
+  text(): Promise<string>;
+}
+
+/**
+ * The HTTP seam for Google's endpoints.
+ *
+ * Injectable for exactly one reason: **no test may reach a live store**, and a rail whose network call could
+ * not be substituted would have to be tested through a stub of itself, which proves nothing. One explicit
+ * parameter is better than reassigning a global — a global stub leaks between suites and hides which module
+ * was actually exercised.
+ */
+export type GoogleHttpFetch = (url: string, init?: GoogleHttpRequest) => Promise<GoogleHttpResponse>;
+
+/** The default transport: the runtime's own `fetch`. */
+export const googleHttpFetch: GoogleHttpFetch = (url, init) =>
+  fetch(url, init) as unknown as Promise<GoogleHttpResponse>;
+
+/** What one request is for, and how its answers should be read. */
+export interface GoogleJsonOptions {
+  /** What is being fetched, in a `detail` line: "the subscription", "an access token". Never the URL. */
+  what: string;
+  /** The HTTP method. Defaults to GET. */
+  method?: string;
+  /** Request headers. */
+  headers?: Record<string, string>;
+  /** The request body, already encoded. */
+  body?: string;
+  /**
+   * Whether a 404 means "no such purchase" rather than a failure. Set only by a caller that is deliberately
+   * probing — Play's subscription endpoint answering 404 is how a one-time purchase is recognized.
+   */
+  absentOn404?: boolean;
+}
+
+/**
+ * One request to Google, and its parsed JSON body — or `undefined` when a 404 was a legitimate answer.
+ *
+ * The body comes back as `unknown`. Reaching an endpoint proves who answered, never what they said, so every
+ * caller Zod-parses its own shape.
+ */
+export async function googleJson(
+  transport: GoogleHttpFetch,
+  url: string,
+  options: GoogleJsonOptions,
+): Promise<unknown | undefined> {
+  let response: GoogleHttpResponse;
+  try {
+    response = await transport(url, { method: options.method, headers: options.headers, body: options.body });
+  } catch (cause) {
+    throw unavailable(`Google did not answer when asked for ${options.what}.`, cause);
+  }
+
+  if (response.status === 404 && options.absentOn404) return undefined;
+
+  if (!response.ok) {
+    // 401 and 403 are the two an operator can actually fix, and they have one overwhelmingly common cause.
+    const hint =
+      response.status === 401 || response.status === 403
+        ? " Check that the service account is linked in the Play Console under Users and permissions with financial-data access, and that the Google Play Android Developer API is enabled for its project."
+        : "";
+    throw unavailable(`Google answered ${response.status} when asked for ${options.what}.${hint}`);
+  }
+
+  const text = await response.text();
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (cause) {
+    // An HTML error page behind a proxy is the realistic shape of this. Reading it as an absent purchase would
+    // revoke somebody's subscription, so it is a failure to reach the store like any other.
+    throw unavailable(`Google answered with a non-JSON body when asked for ${options.what}.`, cause);
+  }
+}
+
+/** The 503, with the operator's context in `detail` and nothing about the request in either field. */
+function unavailable(detail: string, cause?: unknown): PaymentsProviderUnavailableError {
+  return new PaymentsProviderUnavailableError({ detail }, cause === undefined ? undefined : { cause });
+}

package/src/rails/google/jwt.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsInvalidReceiptError, PaymentsRailNotConfiguredError } from "../../error/errors";
+
+/**
+ * The JWT primitives Google's two token jobs share.
+ *
+ * Google's rail is the only one that both **verifies** a JWT and **signs** one. It verifies the OIDC token a
+ * Pub/Sub push carries, which is what proves a notification came from Google; it signs a service-account
+ * assertion, which is what buys the access token the Play Developer API demands. Both are compact JWS, so
+ * both need base64url in both directions — and the shipped Apple modules need it in one direction only,
+ * because Apple hands us signed data and never asks us to sign any.
+ *
+ * That is why these live here rather than being taken from `rails/apple/der.ts`: that module is an ASN.1
+ * reader whose refusals carry DER offsets, it has no encoder, and a Google module reaching into an Apple one
+ * would make the rails depend on each other rather than on the shared contract. Small, local, and named for
+ * the rail that uses it.
+ *
+ * **Every input here is hostile.** A push token arrives in an unauthenticated request — verifying it is the
+ * whole point — so a malformed segment is refused rather than coerced, and no refusal echoes the bytes it
+ * refused. A token is a bearer artifact and `detail` reaches logs.
+ */
+
+/** Bytes from one base64url segment. `label` names the segment, so a refusal says which one failed. */
+export function base64UrlDecode(value: string, label: string): Uint8Array {
+  // Zero bytes is never a valid segment. An empty signature is `alg: none` expressed structurally, and
+  // decoding it to an empty buffer would hand a verifier something to compare against nothing.
+  if (value.length === 0) throw malformed(`${label} is empty; an unsigned token is not accepted.`);
+  const standard = value.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = standard.padEnd(standard.length + ((4 - (standard.length % 4)) % 4), "=");
+  let binary: string;
+  try {
+    binary = atob(padded);
+  } catch (cause) {
+    throw malformed(`${label} is not valid base64url.`, cause);
+  }
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+/** One base64url segment from bytes — the unpadded URL alphabet a JWS is assembled from. */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+/** The three segments of a compact JWT, as received. Kept as strings: a signature covers the exact bytes. */
+export interface JwtSegments {
+  /** The base64url header, still encoded. */
+  head: string;
+  /** The base64url claim set, still encoded. */
+  body: string;
+  /** The base64url signature, still encoded. */
+  mac: string;
+}
+
+/**
+ * Split a compact JWT, refusing anything that is not three non-empty segments.
+ *
+ * The empty-segment check is the structural half of the algorithm pin: `alg: none` produces a header, a
+ * payload, and nothing after the final dot, so it is refused here before any header is even decoded.
+ */
+export function splitJwt(token: string): JwtSegments {
+  const segments = token.split(".");
+  if (segments.length !== 3) throw malformed(`the token has ${segments.length} segments, expected 3.`);
+  const [head, body, mac] = segments as [string, string, string];
+  if (head.length === 0 || body.length === 0 || mac.length === 0) {
+    throw malformed("a token segment is empty; an unsigned token is not accepted.");
+  }
+  return { head, body, mac };
+}
+
+/** One base64url JSON segment. `unknown` out — decoded bytes are not yet a known shape. */
+export function decodeJwtJson(segment: string, label: string): unknown {
+  const text = new TextDecoder().decode(base64UrlDecode(segment, label));
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (cause) {
+    // Never echo the text. On the push path it is attacker-supplied, and `detail` reaches an operator's logs.
+    throw malformed(`${label} is not JSON.`, cause);
+  }
+}
+
+/** The PEM armour of a PKCS#8 private key — the only form `crypto.subtle.importKey("pkcs8", …)` reads. */
+const PKCS8_HEADER = "-----BEGIN PRIVATE KEY-----";
+
+/**
+ * PKCS#8 DER from the PEM a Google service-account key file carries.
+ *
+ * Two accommodations, both earned. Escaped `\n` sequences are honored because the key lives inside the
+ * downloaded JSON as a single line and arrives that way whenever a credential is moved by hand — refusing it
+ * would read as a bug in us. And a PKCS#1 body (`BEGIN RSA PRIVATE KEY`) is named rather than passed on,
+ * because WebCrypto's answer to one is an opaque `DataError` with nothing an operator can act on.
+ *
+ * A bad key is `payments/rail_not_configured`: from a caller's side the rail genuinely is not available, and
+ * a credential that cannot be read is a provisioning failure rather than a store outage.
+ */
+export function pemPrivateKey(pem: string): Uint8Array {
+  const text = pem.replaceAll("\\n", "\n");
+  if (!text.includes(PKCS8_HEADER)) {
+    throw new PaymentsRailNotConfiguredError({
+      detail: text.includes("PRIVATE KEY")
+        ? "Google: the service-account private key is not PKCS#8. Use the `private_key` field of the downloaded JSON key file, which begins `-----BEGIN PRIVATE KEY-----`."
+        : "Google: the service-account private key carries no PEM armour. Store the `private_key` field of the downloaded JSON key file verbatim.",
+    });
+  }
+  const body = text
+    .slice(text.indexOf(PKCS8_HEADER) + PKCS8_HEADER.length)
+    .replace(/-----END PRIVATE KEY-----[\s\S]*$/, "")
+    .replaceAll(/\s+/g, "");
+  try {
+    // The decoder maps `-`/`_` onto `+`/`/` and leaves the standard alphabet alone, so a PEM body — which is
+    // standard base64 — decodes through it unchanged. One decoder, one refusal path.
+    return base64UrlDecode(body, "the service-account private key");
+  } catch (cause) {
+    throw new PaymentsRailNotConfiguredError(
+      { detail: "Google: the service-account private key's PEM body is not valid base64." },
+      { cause },
+    );
+  }
+}
+
+/** A structural refusal. `Google:` prefixed so a log line says which rail failed to read something. */
+function malformed(detail: string, cause?: unknown): PaymentsInvalidReceiptError {
+  return new PaymentsInvalidReceiptError({ detail: `Google: ${detail}` }, cause === undefined ? undefined : { cause });
+}