payment-kit 1.28.0 → 1.29.1

package/api/src/routes/integrations/google-play.ts

@@ -0,0 +1,324 @@
+// Google Play Real-Time Developer Notification webhook receiver.
+//
+// Pub/Sub Push body:
+//   {
+//     "message": { "data": "<base64 JSON>", "messageId": "...", "publishTime": "..." },
+//     "subscription": "projects/<project>/subscriptions/<sub>"
+//   }
+//
+// Auth: Pub/Sub puts a Google-signed JWT in `Authorization: Bearer <jwt>`.
+// We verify the JWT claims here (signature verification is TODO — see verify.ts).
+
+import { Request, Response, Router } from 'express';
+import Joi from 'joi';
+
+import handleGooglePlayEvent, { GooglePlayRtdnPayload } from '../../integrations/google-play/handlers';
+import { ingestVerifiedGooglePlayPurchase } from '../../integrations/google-play/handlers/subscription';
+import { decodePubSubMessage, verifyPubSubJwt } from '../../integrations/google-play/verify';
+import logger from '../../libs/logger';
+import { authenticate } from '../../libs/security';
+import { googlePlayEndpoint } from '../../libs/util';
+import { Customer, PaymentMethod } from '../../store/models';
+
+const router = Router();
+const userAuth = authenticate<Customer>({ component: false, ensureLogin: true });
+
+const verifyBodySchema = Joi.object<{
+  purchaseToken: string;
+  subscriptionId: string;
+}>({
+  purchaseToken: Joi.string().required(),
+  subscriptionId: Joi.string().required(),
+});
+
+/**
+ * Client-initiated verify (aistro-shape).
+ * Mobile client POSTs after StoreKit / BillingClient finishes the purchase.
+ */
+router.post('/verify', userAuth, async (req: Request, res: Response) => {
+  try {
+    const did = (req as any).user?.did;
+    if (!did) {
+      res.status(401).json({ error: 'unauthenticated' });
+      return;
+    }
+    const input = await verifyBodySchema.validateAsync(req.body, { stripUnknown: true });
+
+    // Resolve the Google Play PaymentMethod for THIS livemode. Without the
+    // livemode filter a testmode request would silently fall through to the
+    // production method (and vice versa), and its encrypted credentials may
+    // not even decrypt under the current process key.
+    const method = await PaymentMethod.findOne({
+      where: { type: 'google_play', active: true, livemode: !!req.livemode },
+    });
+    if (!method) {
+      res.status(503).json({ error: 'google_play PaymentMethod not configured' });
+      return;
+    }
+    const client = method.getGooglePlayClient();
+
+    const result = await ingestVerifiedGooglePlayPurchase({
+      customerDid: did,
+      paymentMethod: method,
+      client,
+      purchaseToken: input.purchaseToken,
+      subscriptionId: input.subscriptionId,
+    });
+
+    res.json({
+      success: true,
+      subscription_id: result.subscription.id,
+      isFirstSubscribe: result.isFirstSubscribe,
+      active: result.subscription.status === 'active',
+      expires_at: result.subscription.current_period_end,
+      purchase: {
+        order_id: result.purchase.orderId,
+        expiry_time_millis: result.purchase.expiryTimeMillis,
+        acknowledgement_state: result.purchase.acknowledgementState,
+      },
+    });
+  } catch (err: any) {
+    // google-play-billing-validator surfaces some failures via `errorMessage`
+    // rather than throwing with a populated message; fall back through both.
+    const message = err?.message || err?.errorMessage || (typeof err === 'string' ? err : null) || 'verify failed';
+    logger.error('google_play verify failed', {
+      message,
+      errKeys: err ? Object.keys(err) : [],
+      stack: err?.stack,
+    });
+    res.status(400).json({
+      success: false,
+      error: { message, raw: err?.errorMessage ?? null },
+    });
+  }
+});
+
+// Restore-side input caps. BillingClient `queryPurchases()` typically returns
+// 1-2 active subs per Play account; cap an order of magnitude higher to
+// tolerate misbehaving clients without blocking legitimate uses. Each
+// purchaseToken is a base64-ish blob (~150-200 chars); 2 KB is plenty.
+// Play subscription IDs are bounded to 40 chars by the console — give 256.
+const RESTORE_MAX_ITEMS = 50;
+const PURCHASE_TOKEN_MAX_LENGTH = 2 * 1024;
+const SUBSCRIPTION_ID_MAX_LENGTH = 256;
+// Verify pool size. Each restore item triggers a Google Developer API
+// purchases.subscriptions.get call + a DB upsert. Bound the pool so an
+// authenticated request can't fan out into many concurrent Google calls.
+const RESTORE_CONCURRENCY = 5;
+
+const restoreBodySchema = Joi.object<{
+  purchases: Array<{ purchaseToken: string; subscriptionId: string }>;
+}>({
+  purchases: Joi.array()
+    .items(
+      Joi.object({
+        purchaseToken: Joi.string().max(PURCHASE_TOKEN_MAX_LENGTH).required(),
+        subscriptionId: Joi.string().max(SUBSCRIPTION_ID_MAX_LENGTH).required(),
+      })
+    )
+    .min(1)
+    .max(RESTORE_MAX_ITEMS)
+    .required(),
+});
+
+/**
+ * Restore purchases for Google Play.
+ *
+ * BillingClient on Android exposes `queryPurchases()` which returns active
+ * purchases from the Play cache. The mobile client iterates that list and
+ * posts each {purchaseToken, subscriptionId} pair here. We re-verify and
+ * either return the existing local Subscription or create one. Partial
+ * success is reported per item.
+ */
+router.post('/restore', userAuth, async (req: Request, res: Response) => {
+  try {
+    const did = (req as any).user?.did;
+    if (!did) {
+      res.status(401).json({ error: 'unauthenticated' });
+      return;
+    }
+    const input = await restoreBodySchema.validateAsync(req.body, { stripUnknown: true });
+
+    const method = await PaymentMethod.findOne({
+      where: { type: 'google_play', active: true, livemode: !!req.livemode },
+    });
+    if (!method) {
+      res.status(503).json({ error: 'google_play PaymentMethod not configured' });
+      return;
+    }
+    const client = method.getGooglePlayClient();
+
+    // Dedupe by purchaseToken — a single token is unique to one Google
+    // Play purchase, so duplicates in the request would otherwise double-
+    // call Google's verifier and re-upsert the same Subscription row.
+    const seen = new Set<string>();
+    const purchases = input.purchases.filter((p) => {
+      if (seen.has(p.purchaseToken)) return false;
+      seen.add(p.purchaseToken);
+      return true;
+    });
+
+    // Bounded concurrency: process in fixed-size batches. Each item hits
+    // Google's Developer API + at least one DB write; Promise.all over
+    // an arbitrary list lets a single authenticated request fan out into
+    // many concurrent Google calls.
+    type ItemResult =
+      | {
+          ok: true;
+          subscription_id: string;
+          isFirstSubscribe: boolean;
+          product_id: string;
+        }
+      | { ok: false; error: string; product_id: string };
+    const results: ItemResult[] = [];
+    for (let i = 0; i < purchases.length; i += RESTORE_CONCURRENCY) {
+      const batch = purchases.slice(i, i + RESTORE_CONCURRENCY);
+      // eslint-disable-next-line no-await-in-loop -- intentional: batches must complete sequentially to bound concurrency
+      const batchResults = await Promise.all(
+        batch.map(async (p): Promise<ItemResult> => {
+          try {
+            const r = await ingestVerifiedGooglePlayPurchase({
+              customerDid: did,
+              paymentMethod: method,
+              client,
+              purchaseToken: p.purchaseToken,
+              subscriptionId: p.subscriptionId,
+            });
+            return {
+              ok: true,
+              subscription_id: r.subscription.id,
+              isFirstSubscribe: r.isFirstSubscribe,
+              product_id: p.subscriptionId,
+            };
+          } catch (err: any) {
+            return {
+              ok: false,
+              error: err?.message ?? 'restore failed',
+              product_id: p.subscriptionId,
+            };
+          }
+        })
+      );
+      results.push(...batchResults);
+    }
+
+    res.json({
+      restored: results.filter((r) => r.ok),
+      errors: results.filter((r) => !r.ok),
+    });
+  } catch (err: any) {
+    logger.error('google_play restore failed', { error: err?.message, stack: err?.stack });
+    res.status(400).json({ error: err?.message ?? 'restore failed' });
+  }
+});
+
+// In-process dedup of recently-seen Pub/Sub messageIds. Pub/Sub guarantees the
+// same messageId on retries, so if we've already started handling this exact
+// message we can skip duplicate delivery (Google retries even on 2xx if its
+// timer expires before our response). Map<messageId, expiryEpochMs>; we cap
+// the map to avoid unbounded growth.
+const seenMessageIds = new Map<string, number>();
+const MESSAGE_DEDUP_TTL_MS = 10 * 60 * 1000; // 10 min — Pub/Sub retries within
+// ack deadline (default 10s) but
+// can also redeliver on cron, so
+// keep a comfortable window.
+const MESSAGE_DEDUP_MAX_SIZE = 1000;
+
+/** True if this messageId was already processed SUCCESSFULLY within the TTL. */
+function wasHandled(messageId: string): boolean {
+  const exp = seenMessageIds.get(messageId);
+  return !!exp && exp > Date.now();
+}
+
+/**
+ * Mark a messageId as successfully handled. Called ONLY after processing
+ * succeeds — so a failed/transient attempt is NOT deduped away and Pub/Sub's
+ * retry is allowed to run (PR #1381 review P1). NOTE: in-memory, so it does not
+ * survive Worker restarts — durable idempotency is a follow-up.
+ */
+function markHandled(messageId: string): void {
+  const now = Date.now();
+  if (seenMessageIds.size > MESSAGE_DEDUP_MAX_SIZE) {
+    for (const [id, exp] of seenMessageIds) {
+      if (exp < now) seenMessageIds.delete(id);
+    }
+  }
+  seenMessageIds.set(messageId, now + MESSAGE_DEDUP_TTL_MS);
+}
+
+router.post('/webhook', async (req: Request, res: Response) => {
+  const expectedEmail = process.env.GOOGLE_PUBSUB_PUSH_SERVICE_ACCOUNT;
+  // Fail CLOSED: in production the push service account MUST be configured. A
+  // sandbox/test bypass has to be explicit (PR #1381 review P1).
+  const allowUnverifiedSender =
+    process.env.GOOGLE_PUBSUB_ALLOW_UNVERIFIED_SENDER === 'true' || process.env.NODE_ENV === 'test';
+
+  // --- Phase 1: authenticate + select. Failures here are rejections / not-for-us,
+  //     NOT processing failures. ---
+  let payload: GooglePlayRtdnPayload;
+  let client: ReturnType<PaymentMethod['getGooglePlayClient']>;
+  let messageId: string | undefined;
+  try {
+    if (!expectedEmail && !allowUnverifiedSender) {
+      logger.error(
+        'google_play webhook refusing: GOOGLE_PUBSUB_PUSH_SERVICE_ACCOUNT unset ' +
+          '(set GOOGLE_PUBSUB_ALLOW_UNVERIFIED_SENDER=true only for sandbox)'
+      );
+      res.status(403).json({ error: 'sender verification not configured' });
+      return;
+    }
+
+    const authHeader = req.get('authorization') || req.get('Authorization');
+    if (authHeader) {
+      const token = authHeader.replace(/^Bearer\s+/i, '');
+      await verifyPubSubJwt(token, { expectedAudience: googlePlayEndpoint(), expectedEmail });
+    } else if (!allowUnverifiedSender) {
+      logger.warn('google_play webhook missing Authorization header');
+      res.status(401).json({ error: 'missing authorization' });
+      return;
+    }
+
+    messageId = req.body?.message?.messageId;
+    // Skip only messages we already handled SUCCESSFULLY (mark happens post-success).
+    if (messageId && wasHandled(messageId)) {
+      logger.info('google_play webhook: duplicate Pub/Sub messageId, skipping', { messageId });
+      res.json({ deduped: true });
+      return;
+    }
+
+    payload = decodePubSubMessage<GooglePlayRtdnPayload>(req.body);
+
+    const methods = await PaymentMethod.findAll({ where: { type: 'google_play' } });
+    const method = methods.find((m) => {
+      const settings = PaymentMethod.decryptSettings(m.settings);
+      return settings.google_play?.package_name === payload.packageName;
+    });
+    if (!method) {
+      logger.warn('google_play webhook: no matching PaymentMethod for packageName', {
+        packageName: payload.packageName,
+      });
+      // Not for us → ack so Pub/Sub doesn't retry a misconfigured topic forever.
+      res.json({ skipped: true });
+      return;
+    }
+    client = method.getGooglePlayClient();
+  } catch (err: any) {
+    // Auth / decode / selection failure → forged or malformed; reject.
+    logger.warn('google_play webhook: auth/decode failed', { error: err?.message });
+    res.status(401).json({ error: 'unauthorized' });
+    return;
+  }
+
+  // --- Phase 2: process the verified event. Failure here is transient → 5xx so
+  //     Pub/Sub retries; mark the messageId handled ONLY after success. ---
+  try {
+    await handleGooglePlayEvent(payload, client);
+    if (messageId) markHandled(messageId);
+    res.json({ received: true });
+  } catch (err: any) {
+    logger.error('google_play webhook processing failed — will retry', { error: err?.message, stack: err?.stack });
+    res.status(500).json({ error: err?.message ?? 'processing failed' });
+  }
+});
+
+export default router;

package/api/src/routes/payment-methods.ts

@@ -183,6 +183,124 @@ router.post('/', auth, async (req, res) => {
     return res.json({ ...method.toJSON(), payment_currencies: [currency.toJSON()] });
   }
 
+  if (raw.type === 'google_play') {
+    if (!raw.settings.google_play?.package_name) {
+      return res.status(400).json({ error: 'google_play package_name is required' });
+    }
+    if (!raw.settings.google_play?.service_account_json) {
+      return res.status(400).json({ error: 'google_play service_account_json is required' });
+    }
+    try {
+      const parsed = JSON.parse(raw.settings.google_play.service_account_json);
+      if (!parsed.client_email || !parsed.private_key) {
+        return res.status(400).json({ error: 'service_account_json missing client_email or private_key' });
+      }
+    } catch {
+      return res.status(400).json({ error: 'service_account_json is not valid JSON' });
+    }
+
+    const exist = await PaymentMethod.findOne({
+      where: { type: 'google_play', livemode: raw.livemode },
+    });
+    if (exist) {
+      return res.status(400).json({ error: 'google_play payment method already exists for this livemode' });
+    }
+
+    raw.settings = pick(PaymentMethod.encryptSettings(raw.settings), ['google_play']) as PaymentMethodSettings;
+    raw.logo = raw.logo || getUrl('/methods/google-play.png');
+    raw.features = { recurring: true, refund: true, dispute: false };
+    raw.confirmation = { type: 'callback' };
+
+    const method = await PaymentMethod.create(raw as TPaymentMethod);
+
+    // Create a default USD currency for the PaymentMethod (mirrors stripe path).
+    const currency = await PaymentCurrency.create({
+      livemode: method.livemode,
+      active: method.active,
+      locked: true,
+      is_base_currency: false,
+      payment_method_id: method.id,
+      type: 'standard',
+      name: 'Dollar',
+      description: 'US Dollar (Google Play)',
+      logo: getUrl('/currencies/dollar.png'),
+      symbol: 'USD',
+      decimal: 2,
+      maximum_precision: 2,
+      minimum_payment_amount: '1',
+      maximum_payment_amount: '100000000000',
+      contract: '',
+      metadata: {},
+    });
+    await method.update({ default_currency_id: currency.id });
+
+    return res.json({ ...method.toJSON(), payment_currencies: [currency.toJSON()] });
+  }
+
+  if (raw.type === 'app_store') {
+    if (!raw.settings.app_store?.bundle_id) {
+      return res.status(400).json({ error: 'app_store bundle_id is required' });
+    }
+    const env = raw.settings.app_store?.environment;
+    if (env !== 'production' && env !== 'sandbox') {
+      return res.status(400).json({ error: 'app_store environment must be production or sandbox' });
+    }
+    // Server API credentials are optional — StoreKit 2 JWS verify doesn't need them.
+    // But if any of the three is set, all three must be set together.
+    const hasAnyServerCred = !!(
+      raw.settings.app_store?.issuer_id ||
+      raw.settings.app_store?.key_id ||
+      raw.settings.app_store?.private_key_pem
+    );
+    if (hasAnyServerCred) {
+      if (
+        !raw.settings.app_store?.issuer_id ||
+        !raw.settings.app_store?.key_id ||
+        !raw.settings.app_store?.private_key_pem
+      ) {
+        return res.status(400).json({
+          error: 'app_store Server API credentials must include all of issuer_id, key_id, private_key_pem',
+        });
+      }
+    }
+
+    const exist = await PaymentMethod.findOne({
+      where: { type: 'app_store', livemode: raw.livemode },
+    });
+    if (exist) {
+      return res.status(400).json({ error: 'app_store payment method already exists for this livemode' });
+    }
+
+    raw.settings = pick(PaymentMethod.encryptSettings(raw.settings), ['app_store']) as PaymentMethodSettings;
+    raw.logo = raw.logo || getUrl('/methods/app-store.png');
+    raw.features = { recurring: true, refund: false, dispute: false };
+    raw.confirmation = { type: 'callback' };
+
+    const method = await PaymentMethod.create(raw as TPaymentMethod);
+
+    const currency = await PaymentCurrency.create({
+      livemode: method.livemode,
+      active: method.active,
+      locked: true,
+      is_base_currency: false,
+      payment_method_id: method.id,
+      type: 'standard',
+      name: 'Dollar',
+      description: 'US Dollar (App Store)',
+      logo: getUrl('/currencies/dollar.png'),
+      symbol: 'USD',
+      decimal: 2,
+      maximum_precision: 2,
+      minimum_payment_amount: '1',
+      maximum_payment_amount: '100000000000',
+      contract: '',
+      metadata: {},
+    });
+    await method.update({ default_currency_id: currency.id });
+
+    return res.json({ ...method.toJSON(), payment_currencies: [currency.toJSON()] });
+  }
+
   // FIXME: support bitcoin payment methods
 
   return res.status(400).json({ error: 'payment method type is not supported' });
@@ -259,6 +377,18 @@ router.get('/types', auth, (_, res) => {
       description: 'Pay with base compatible chains',
       logo: getUrl('/methods/base.png'),
     },
+    {
+      type: 'google_play',
+      name: 'Google Play',
+      description: 'Subscriptions purchased via Google Play in-app billing',
+      logo: getUrl('/methods/google-play.png'),
+    },
+    {
+      type: 'app_store',
+      name: 'App Store',
+      description: 'Subscriptions purchased via Apple App Store StoreKit',
+      logo: getUrl('/methods/app-store.png'),
+    },
   ]);
 });
 

package/api/src/store/migrations/20260526-iap-foundation.ts

@@ -0,0 +1,105 @@
+import { DataTypes } from 'sequelize';
+import { createIndexIfNotExists, safeApplyColumnChanges, type Migration } from '../migrate';
+import models from '../models';
+
+export const up: Migration = async ({ context }) => {
+  // 1. Customer: per-channel UUID for IAP appAccountToken / obfuscatedAccountId mapping (D-004)
+  await safeApplyColumnChanges(context, {
+    customers: [
+      { name: 'app_store_uuid', field: { type: DataTypes.STRING(36), allowNull: true } },
+      { name: 'google_play_uuid', field: { type: DataTypes.STRING(36), allowNull: true } },
+    ],
+  });
+  // SQLite/D1 allows multiple NULLs in UNIQUE columns, so a plain UNIQUE index
+  // is functionally equivalent to a partial one (WHERE col IS NOT NULL).
+  await createIndexIfNotExists(context, 'customers', ['app_store_uuid'], 'idx_customers_app_store_uuid', {
+    unique: true,
+  });
+  await createIndexIfNotExists(context, 'customers', ['google_play_uuid'], 'idx_customers_google_play_uuid', {
+    unique: true,
+  });
+
+  // 2. Subscription: channel + environment (D-005)
+  await safeApplyColumnChanges(context, {
+    subscriptions: [
+      { name: 'channel', field: { type: DataTypes.STRING(20), allowNull: true } },
+      {
+        name: 'environment',
+        field: { type: DataTypes.STRING(20), allowNull: true, defaultValue: 'production' },
+      },
+    ],
+  });
+
+  // 3. Invoice: three-segment amounts for cross-channel accounting (D-001 A)
+  await safeApplyColumnChanges(context, {
+    invoices: [
+      { name: 'gross_amount', field: { type: DataTypes.STRING(32), allowNull: true } },
+      { name: 'platform_fee', field: { type: DataTypes.STRING(32), defaultValue: '0' } },
+      { name: 'net_amount', field: { type: DataTypes.STRING(32), allowNull: true } },
+    ],
+  });
+  // Backfill: existing Stripe / on-chain rows have no platform fee, so gross = net = total
+  await context.sequelize.query(
+    'UPDATE invoices SET gross_amount = total, net_amount = total WHERE gross_amount IS NULL'
+  );
+
+  // 4. Refund: source (merchant_initiated | platform_initiated)
+  await safeApplyColumnChanges(context, {
+    refunds: [
+      {
+        name: 'source',
+        field: { type: DataTypes.STRING(30), allowNull: true, defaultValue: 'merchant_initiated' },
+      },
+    ],
+  });
+
+  // 5. Entitlement tables (D-003 B)
+  await context.createTable('entitlements', models.Entitlement.GENESIS_ATTRIBUTES);
+  await createIndexIfNotExists(context, 'entitlements', ['key'], 'idx_entitlements_key', { unique: true });
+
+  await context.createTable('entitlement_products', models.EntitlementProduct.GENESIS_ATTRIBUTES);
+
+  await context.createTable('entitlement_grants', models.EntitlementGrant.GENESIS_ATTRIBUTES);
+  await createIndexIfNotExists(
+    context,
+    'entitlement_grants',
+    ['customer_id', 'entitlement_id', 'status'],
+    'idx_entitlement_grants_lookup'
+  );
+  await createIndexIfNotExists(
+    context,
+    'entitlement_grants',
+    ['source_subscription_id'],
+    'idx_entitlement_grants_source_sub'
+  );
+
+  // Note: PaymentMethod.type ENUM extension to include 'app_store' / 'google_play'
+  // is intentionally NOT changed at DB level — on D1/SQLite the column is already TEXT
+  // with no CHECK constraint, so any value is accepted. The model-level type union
+  // is updated in models/payment-method.ts when A1/A2 lands.
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeIndex('entitlement_grants', 'idx_entitlement_grants_source_sub');
+  await context.removeIndex('entitlement_grants', 'idx_entitlement_grants_lookup');
+  await context.dropTable('entitlement_grants');
+
+  await context.dropTable('entitlement_products');
+
+  await context.removeIndex('entitlements', 'idx_entitlements_key');
+  await context.dropTable('entitlements');
+
+  await context.removeColumn('refunds', 'source');
+
+  await context.removeColumn('invoices', 'net_amount');
+  await context.removeColumn('invoices', 'platform_fee');
+  await context.removeColumn('invoices', 'gross_amount');
+
+  await context.removeColumn('subscriptions', 'environment');
+  await context.removeColumn('subscriptions', 'channel');
+
+  await context.removeIndex('customers', 'idx_customers_google_play_uuid');
+  await context.removeIndex('customers', 'idx_customers_app_store_uuid');
+  await context.removeColumn('customers', 'google_play_uuid');
+  await context.removeColumn('customers', 'app_store_uuid');
+};

package/api/src/store/models/customer.ts

@@ -57,6 +57,10 @@ export class Customer extends Model<InferAttributes<Customer>, InferCreationAttr
   };
   declare next_invoice_sequence?: number;
 
+  // Per-channel UUID for IAP appAccountToken / obfuscatedAccountId mapping (D-004)
+  declare app_store_uuid?: string;
+  declare google_play_uuid?: string;
+
   // TODO: following fields not supported
   // declare preferred_locales?: string[];
   // declare tax_exempt?: LiteralUnion<'exempt' | 'none' | 'reverse', string>;
@@ -143,6 +147,16 @@ export class Customer extends Model<InferAttributes<Customer>, InferCreationAttr
       type: DataTypes.NUMBER,
       defaultValue: 1,
     },
+    app_store_uuid: {
+      type: DataTypes.STRING(36),
+      allowNull: true,
+      unique: true,
+    },
+    google_play_uuid: {
+      type: DataTypes.STRING(36),
+      allowNull: true,
+      unique: true,
+    },
     created_at: {
       type: DataTypes.DATE,
       defaultValue: DataTypes.NOW,