payment-kit 1.28.0 → 1.29.0

package/api/src/crons/index.ts

@@ -1,6 +1,7 @@
 import Cron from '@abtnode/cron';
 
 import { checkStakeRevokeTx } from '../integrations/arcblock/stake';
+import { runIapReconcile } from '../integrations/iap-reconcile';
 import {
   batchHandleStripeInvoices,
   batchHandleStripePayments,
@@ -9,7 +10,9 @@ import {
 import {
   creditConsumptionCronTime,
   depositVaultCronTime,
+  eventRetryCronTime,
   expiredSessionCleanupCronTime,
+  iapReconcileCronTime,
   notificationCronTime,
   overdueDetectionCronTime,
   paymentStatCronTime,
@@ -30,6 +33,7 @@ import { startVendorStatusCheckSchedule } from '../queues/vendors/status-check';
 import { CheckoutSession } from '../store/models';
 import { createOverdueDetection } from './overdue-detection';
 import { createPaymentStat } from './payment-stat';
+import { retryPendingEvents } from './retry-pending-events';
 import { SubscriptionTrialWillEndSchedule } from './subscription-trial-will-end';
 import { SubscriptionWillCanceledSchedule } from './subscription-will-canceled';
 import { SubscriptionWillRenewSchedule } from './subscription-will-renew';
@@ -128,6 +132,24 @@ function init() {
         fn: checkStakeRevokeTx,
         options: { runOnInit: false },
       },
+      {
+        // Backup for App Store / Google Play webhooks — pulls authoritative
+        // subscription state and patches local drift (refunds/renewals the
+        // webhook missed). See blocklets/core/api/src/integrations/iap-reconcile.ts.
+        name: 'iap.reconcile',
+        time: iapReconcileCronTime,
+        fn: () => runIapReconcile(),
+        options: { runOnInit: false },
+      },
+      {
+        // Backstop for the fire-and-forget event → webhook path. Rescans events
+        // with pending_webhooks>0 older than 60s and re-invokes handleEvent.
+        // See blocklets/core/api/src/crons/retry-pending-events.ts.
+        name: 'event.retry',
+        time: eventRetryCronTime,
+        fn: () => retryPendingEvents(),
+        options: { runOnInit: false },
+      },
       {
         name: 'payment.stat',
         time: paymentStatCronTime,

package/api/src/crons/retry-pending-events.ts

@@ -0,0 +1,58 @@
+// Backstop for the event → webhook fire-and-forget path.
+//
+// createEvent emits 'event.created' (sync) → an async listener calls
+// handleEvent → schedules HTTP webhook delivery. On CF Workers the listener's
+// microtask can lose the worker before its waitUntil registers if it fires
+// from the last line of an HTTP handler (e.g. ingestVerifiedGooglePlayPurchase
+// ends with `createEvent('subscription.started', ...).catch(...)` right before
+// returning — the response flushes and runtime may stop draining new
+// waitUntils). Result: events row exists with pending_webhooks>0 but no
+// webhook_attempt is ever written, so downstream apps silently miss the
+// notification.
+//
+// This cron rescans for pending events older than the realtime grace window
+// and re-invokes handleEvent. Stripe et al ship the same belt-and-suspenders.
+
+import { Op } from 'sequelize';
+
+import logger from '../libs/logger';
+import { eventQueue } from '../queues/event';
+import { Event } from '../store/models/event';
+
+const REALTIME_GRACE_SECONDS = 60;
+// Each cron tick only enqueues, does NOT inline await handleEvent. CF Workers
+// scheduled handler has a tight CPU budget (~30s) — inline handling N events
+// blew past it after ~7 iterations and was cut off mid-batch, so the tail
+// never got processed. Pushing to eventQueue lets the consumer (which has a
+// looser per-message budget) work through them asynchronously.
+//
+// BATCH_LIMIT must stay small: even push-only, the scheduled handler awaits
+// flushPendingJobs() at the end which await's each push's enqueue promise
+// (D1 addJob + CF Queue send). 50 was too many — pushes never finished
+// sending, jobs table never got rows, handleEvent never ran. 5 leaves
+// generous headroom and we still drain the backlog over a few minutes.
+const BATCH_LIMIT = 5;
+
+export async function retryPendingEvents(): Promise<void> {
+  const threshold = new Date(Date.now() - REALTIME_GRACE_SECONDS * 1000);
+  const docs = await Event.findAll({
+    where: {
+      pending_webhooks: { [Op.gt]: 0 },
+      created_at: { [Op.lt]: threshold },
+    },
+    attributes: ['id'],
+    order: [['created_at', 'ASC']],
+    limit: BATCH_LIMIT,
+  });
+
+  if (docs.length === 0) return;
+  logger.info(`event.retry: enqueuing ${docs.length} pending events older than ${REALTIME_GRACE_SECONDS}s`);
+
+  for (const doc of docs) {
+    try {
+      eventQueue.push({ id: doc.id, job: { eventId: doc.id }, persist: false });
+    } catch (err: any) {
+      logger.error('event.retry enqueue failed', { eventId: doc.id, error: err?.message });
+    }
+  }
+}

package/api/src/integrations/app-store/apple-root-certs.ts

@@ -0,0 +1,26 @@
+// Apple Root Certificates for App Store JWS verification.
+//
+// Vendored as base64 constants so `tsc` compiles cleanly without copying
+// non-ts assets into dist/. Source files (DER-encoded `.cer`) live under
+// `./certs/` and were downloaded from https://www.apple.com/certificateauthority/
+//
+// Apple's IAP JWS signing chain currently terminates at one of these roots.
+// Apple rotates roots roughly every 25 years — refresh when they do.
+//   - Apple Inc. Root Certificate (RSA 2048, valid 2006-04 → 2035-02)
+//   - Apple Root CA - G2          (RSA 4096, valid 2014-04 → 2039-04)
+//   - Apple Root CA - G3          (ECC P-384, valid 2014-04 → 2039-04)
+
+const APPLE_INC_ROOT_B64 =
+  'MIIEuzCCA6OgAwIBAgIBAjANBgkqhkiG9w0BAQUFADBiMQswCQYDVQQGEwJVUzETMBEGA1UEChMKQXBwbGUgSW5jLjEmMCQGA1UECxMdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxFjAUBgNVBAMTDUFwcGxlIFJvb3QgQ0EwHhcNMDYwNDI1MjE0MDM2WhcNMzUwMjA5MjE0MDM2WjBiMQswCQYDVQQGEwJVUzETMBEGA1UEChMKQXBwbGUgSW5jLjEmMCQGA1UECxMdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxFjAUBgNVBAMTDUFwcGxlIFJvb3QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDkkakJH5HbHkdQ6wXtXnmELes2oldMVeyLGYne+Uts9QerIjAC6Bg++FAJ039BqJj50cpmnCRrEdCju+QbKsMflZ56DKRHi1vUFjczy8QPTc4UadHJGXL1XQ7Vf1+b8iUDulWPTV0N8WQ1IxVLFVkds5T39pyez1C6wVhQZ48ItCD3y6wsIG9wtj8BMIy3Q88PnT3zK0koGsj+zrW5DtleHNbLPbU6rfQPDgCSC7EhFi501TwN22IWq6NxkkdTVcGvL0Gz+PvjcM3mo0xFfh9Ma1CWQYnEdGILEINBhzOKgbEwWOxaBDKMaLOPHd5lc/9nXmW8Sdh2nzMUZaF3lMktAgMBAAGjggF6MIIBdjAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUK9BpR5R2Cf70a40uQKb3R01/CF4wHwYDVR0jBBgwFoAUK9BpR5R2Cf70a40uQKb3R01/CF4wggERBgNVHSAEggEIMIIBBDCCAQAGCSqGSIb3Y2QFATCB8jAqBggrBgEFBQcCARYeaHR0cHM6Ly93d3cuYXBwbGUuY29tL2FwcGxlY2EvMIHDBggrBgEFBQcCAjCBthqBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMA0GCSqGSIb3DQEBBQUAA4IBAQBcNplMLXi37Yyb3PN3m/J20ncwT8EfhYOFG5k9RzfyqZtAjizUsZAS2L70c5vu0mQPy3lPNNiiPvl4/2vIB+x9OYOLUyDTOMSxv5pPCmv/K/xZpwUJfBdAVhEedNO3iyM7R6PVbyTi69G3cN8PReEnyvFteO3ntRcXqNx+IjXKJdXZD9Zr1KIkIxH3oayPc4FgxhtbCS+SsvhESPBgOJ4V9T0mZyCKM2r3DYLP3uujL/lTaltkwGMzd/c6ByxW69oPIQ7aunMZT7XZNn/Bh1XZp5m5MkL72NVxnn6hUrcbvZNCJBIqxw8dtk2cXmPIS4AXUKqK1drk/NAJBzewdXUh';
+
+const APPLE_ROOT_CA_G2_B64 =
+  'MIIFkjCCA3qgAwIBAgIIAeDltYNno+AwDQYJKoZIhvcNAQEMBQAwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEcyMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNDMwMTgxMDA5WhcNMzkwNDMwMTgxMDA5WjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzIxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANgREkhI2imKScUcx+xuM23+TfvgHN6sXuI2pyT5f1BrTM65MFQn5bPW7SXmMLYFN14UIhHF6Kob0vuy0gmVOKTvKkmMXT5xZgM4+xb1hYjkWpIMBDLyyED7Ul+f9sDx47pFoFDVEovy3d6RhiPw9bZyLgHaC/YuOQhfGaFjQQscp5TBhsRTL3b2CtcM0YM/GlMZ81fVJ3/8E7j4ko380yhDPLVoACVdJ2LT3VXdRCCQgzWTxb+4Gftr49wIQuavbfqeQMpOhYV4SbHXw8EwOTKrfl+q04tvny0aIWhwZ7Oj8ZhBbZF8+NfbqOdfIRqMM78xdLe40fTgIvS/cjTf94FNcX1RoeKz8NMoFnNvzcytN31O661A4T+B/fc9Cj6i8b0xlilZ3MIZgIxbdMYs0xBTJh0UT8TUgWY8h2czJxQI6bR3hDRSj4n4aJgXv8O7qhOTH11UL6jHfPsNFL4VPSQ08prcdUFmIrQB1guvkJ4M6mL4m1k8COKWNORj3rw31OsMiANDC1CvoDTdUE0V+1ok2Az6DGOeHwOx4e7hqkP0ZmUoNwIx7wHHHtHMn23KVDpA287PT0aLSmWaasZobNfMmRtHsHLDd4/E92GcdB/O/WuhwpyUgquUoue9G7q5cDmVF8Up8zlYNPXEpMZ7YLlmQ1A/bmH8DvmGqmAMQ0uVAgMBAAGjQjBAMB0GA1UdDgQWBBTEmRNsGAPCe8CjoA1/coB6HHcmjTAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBBjANBgkqhkiG9w0BAQwFAAOCAgEAUabz4vS4PZO/Lc4Pu1vhVRROTtHlznldgX/+tvCHM/jvlOV+3Gp5pxy+8JS3ptEwnMgNCnWefZKVfhidfsJxaXwU6s+DDuQUQp50DhDNqxq6EWGBeNjxtUVAeKuowM77fWM3aPbn+6/Gw0vsHzYmE1SGlHKy6gLti23kDKaQwFd1z4xCfVzmMX3zybKSaUYOiPjjLUKyOKimGY3xn83uamW8GrAlvacp/fQ+onVJv57byfenHmOZ4VxG/5IFjPoeIPmGlFYl5bRXOJ3riGQUIUkhOb9iZqmxospvPyFgxYnURTbImHy99v6ZSYA7LNKmp4gDBDEZt7Y6YUX6yfIjyGNzv1aJMbDZfGKnexWoiIqrOEDCzBL/FePwN983csvMmOa/orz6JopxVtfnJBtIRD6e/J/JzBrsQzwBvDR4yGn1xuZW7AYJNpDrFEobXsmII9oDMJELuDY++ee1KG++P+w8j2Ud5cAeh6Squpj9kuNsJnfdBrRkBof0Tta6SqoWqPQFZ2aWuuJVecMsXUmPgEkrihLHdoBR37q9ZV0+N0djMenl9MU/S60EinpxLK8JQzcPqOMyT/RFtm2XNuyE9QoB6he7hY1Ck3DDUOUUi78/w0EP3SIEIwiKum1xRKtzCTrJ+VKACd+66eYWyi4uTLLT3OUEVLLUNIAytbwPF+E=';
+
+const APPLE_ROOT_CA_G3_B64 =
+  'MIICQzCCAcmgAwIBAgIILcX8iNLFS5UwCgYIKoZIzj0EAwMwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNDMwMTgxOTA2WhcNMzkwNDMwMTgxOTA2WjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzB2MBAGByqGSM49AgEGBSuBBAAiA2IABJjpLz1AcqTtkyJygRMc3RCV8cWjTnHcFBbZDuWmBSp3ZHtfTjjTuxxEtX/1H7YyYl3J6YRbTzBPEVoA/VhYDKX1DyxNB0cTddqXl5dvMVztK517IDvYuVTZXpmkOlEKMaNCMEAwHQYDVR0OBBYEFLuw3qFYM4iapIqZ3r6966/ayySrMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2gAMGUCMQCD6cHEFl4aXTQY2e3v9GwOAEZLuN+yRhHFD/3meoyhpmvOwgPUnPWTxnS4at+qIxUCMG1mihDK1A3UT82NQz60imOlM27jbdoXt2QfyFMm+YhidDkLF1vLUagM6BgD56KyKA==';
+
+export const APPLE_ROOT_CERTS: Buffer[] = [
+  Buffer.from(APPLE_INC_ROOT_B64, 'base64'),
+  Buffer.from(APPLE_ROOT_CA_G2_B64, 'base64'),
+  Buffer.from(APPLE_ROOT_CA_G3_B64, 'base64'),
+];

package/api/src/integrations/app-store/client.ts

@@ -0,0 +1,369 @@
+// App Store integration client wrapper.
+//
+// Primary verify path is **client-side initiated** (mirrors A2 google_play):
+// the mobile client posts a `jws_signed_transaction` (StoreKit 2) right after a
+// purchase finishes. Apple's JWS carries a full self-attesting payload signed
+// by Apple — no shared secret, no server callback to Apple needed for the
+// happy path. We only hit App Store Server API when we need fresher state
+// (e.g. SUBSCRIPTION_STATUS at renewal time).
+//
+// A1 mock phase: `verifyJwsTransaction` decodes the JWT payload **without**
+// signature verification, so we can wire end-to-end with test fixtures. Real
+// signature verification (Apple Root CA → leaf cert → RS256) is gated behind
+// the same TODO marker as `google-play/verify.ts`.
+//
+// Write methods (cancel / refund) intentionally throw unless the
+// APP_STORE_WRITE_ENABLED env flag is set — same safety rail as google_play.
+//
+// Tests replace this class via jest mocks.
+
+import { config as configApple, validate as validateAppleReceipt } from 'node-apple-receipt-verify';
+
+import logger from '../../libs/logger';
+import {
+  AppStoreApiCredentials,
+  getAllSubscriptionStatuses,
+  verifySignedNotification,
+  verifySignedTransaction,
+} from './signed-data-verifier';
+
+/** App Store Server Notification V2 `notificationType` — Apple-defined string enum. */
+export type AppStoreNotificationType =
+  | 'SUBSCRIBED'
+  | 'DID_RENEW'
+  | 'EXPIRED'
+  | 'DID_FAIL_TO_RENEW'
+  | 'GRACE_PERIOD_EXPIRED'
+  | 'DID_CHANGE_RENEWAL_STATUS'
+  | 'DID_CHANGE_RENEWAL_PREF'
+  | 'OFFER_REDEEMED'
+  | 'PRICE_INCREASE'
+  | 'REFUND'
+  | 'REFUND_DECLINED'
+  | 'REFUND_REVERSED'
+  | 'REVOKE'
+  | 'CONSUMPTION_REQUEST'
+  | 'RENEWAL_EXTENDED'
+  | 'RENEWAL_EXTENSION'
+  | 'TEST';
+
+/** Decoded payload of the outer `signedPayload` JWS in an App Store Server Notification V2. */
+export type AppStoreNotificationPayload = {
+  notificationType: AppStoreNotificationType | string;
+  /** Optional subtype (e.g. INITIAL_BUY / RESUBSCRIBE / VOLUNTARY / AUTO_RENEW_DISABLED / GRACE_PERIOD). */
+  subtype?: string;
+  /** UUID Apple generates per notification — use this for idempotency. */
+  notificationUUID: string;
+  version: string;
+  signedDate: number;
+  data: {
+    appAppleId?: number;
+    bundleId: string;
+    bundleVersion?: string;
+    environment: 'Production' | 'Sandbox';
+    /** Inner JWS carrying the transaction details (decode with verifyJwsTransaction). */
+    signedTransactionInfo?: string;
+    /** Inner JWS carrying renewal info — auto-renew state, expiration intent, etc. */
+    signedRenewalInfo?: string;
+    /** Subscription status: 1=active, 2=expired, 3=billing-retry, 4=grace, 5=revoked. */
+    status?: 1 | 2 | 3 | 4 | 5;
+  };
+};
+
+/** Decoded payload of a StoreKit 2 `signedTransactionInfo` JWS. */
+export type AppStoreTransactionPayload = {
+  /** Apple's internal id for this specific charge */
+  transactionId: string;
+  /** Stable id across renewals (= subscription "thread") */
+  originalTransactionId: string;
+  /** Apple SKU (the Product Id configured in App Store Connect) */
+  productId: string;
+  /** RFC3339 millis (string in some SDK versions, number in others — normalize to number) */
+  purchaseDate?: number;
+  /** Subscription-only: expiry of this purchase */
+  expiresDate?: number;
+  /** UUID set by client via `Product.purchase(options:)` — our equivalent of obfuscatedExternalAccountId */
+  appAccountToken?: string;
+  /** "Production" | "Sandbox" */
+  environment: 'Production' | 'Sandbox';
+  /** When Apple signed this JWS */
+  signedDate?: number;
+  /** App bundle id, must match our configured one */
+  bundleId: string;
+  /** "AUTO_RENEWABLE" | "NON_RENEWABLE" | "CONSUMABLE" | "NON_CONSUMABLE" */
+  type?: string;
+  /** webOrderLineItemId — Apple-side line item id per renewal */
+  webOrderLineItemId?: string;
+  /** Set when Apple revokes the transaction (refund / family-sharing removal). Unix ms. */
+  revocationDate?: number;
+  /** Code why the transaction was revoked: 0=unknown, 1=app-issue. */
+  revocationReason?: number;
+};
+
+export type AppStoreSettings = {
+  bundle_id: string;
+  /** Constrained at runtime in `fromSettings`; widened here to align with PaymentMethodSettings (LiteralUnion). */
+  environment: string;
+  /** App-Specific Shared Secret — only needed for StoreKit 1 legacy receipts. */
+  shared_secret?: string;
+  /** App Store Server API credentials (only needed when calling Apple back for state refresh, NOT for JWS verify). */
+  issuer_id?: string;
+  key_id?: string;
+  private_key_pem?: string;
+};
+
+const WRITE_ENABLED = process.env.APP_STORE_WRITE_ENABLED === 'true';
+
+export class AppStoreClient {
+  declare readonly bundleId: string;
+
+  declare readonly environment: 'production' | 'sandbox';
+
+  private readonly sharedSecret?: string;
+
+  private readonly serverApiCredentials?: {
+    issuerId: string;
+    keyId: string;
+    privateKeyPem: string;
+  };
+
+  private constructor(settings: AppStoreSettings, environment: 'production' | 'sandbox') {
+    this.bundleId = settings.bundle_id;
+    this.environment = environment;
+    this.sharedSecret = settings.shared_secret;
+    if (settings.issuer_id && settings.key_id && settings.private_key_pem) {
+      this.serverApiCredentials = {
+        issuerId: settings.issuer_id,
+        keyId: settings.key_id,
+        privateKeyPem: settings.private_key_pem,
+      };
+    }
+  }
+
+  public static fromSettings(settings: AppStoreSettings): AppStoreClient {
+    if (!settings.bundle_id) {
+      throw new Error('AppStoreClient: bundle_id is required');
+    }
+    if (settings.environment !== 'production' && settings.environment !== 'sandbox') {
+      throw new Error(`AppStoreClient: environment must be production|sandbox, got ${settings.environment}`);
+    }
+    return new AppStoreClient(settings, settings.environment);
+  }
+
+  /**
+   * Verify + decode a StoreKit 2 signedTransactionInfo JWS.
+   *
+   * Delegates to Apple's official SignedDataVerifier:
+   *   1. Splits JWS, pulls leaf cert from header.x5c[0]
+   *   2. Verifies x5c chain against bundled Apple Root CAs
+   *   3. ES256 signature check on the payload
+   *
+   * Apple's verifyAndDecodeTransaction does NOT enforce bundleId — we layer
+   * that check here. Set `APP_STORE_SKIP_SIGNATURE_VERIFY=true` to bypass
+   * (decode only) for unit tests and emergency sandbox debugging.
+   */
+  public async verifyJwsTransaction(jws: string): Promise<AppStoreTransactionPayload> {
+    const decoded = await verifySignedTransaction(jws, this.bundleId, this.environment);
+
+    if (decoded.bundleId && decoded.bundleId !== this.bundleId) {
+      throw new Error(`AppStoreClient: bundleId mismatch — JWS says ${decoded.bundleId}, configured ${this.bundleId}`);
+    }
+    if (!decoded.transactionId || !decoded.productId) {
+      throw new Error('AppStoreClient: JWS payload missing transactionId or productId');
+    }
+
+    logger.debug('App Store JWS verified + decoded', {
+      transactionId: decoded.transactionId,
+      productId: decoded.productId,
+      environment: decoded.environment,
+    });
+
+    return {
+      transactionId: decoded.transactionId,
+      originalTransactionId: decoded.originalTransactionId ?? decoded.transactionId,
+      productId: decoded.productId,
+      purchaseDate: decoded.purchaseDate,
+      expiresDate: decoded.expiresDate,
+      appAccountToken: decoded.appAccountToken,
+      environment: (decoded.environment as 'Production' | 'Sandbox') ?? 'Sandbox',
+      signedDate: decoded.signedDate,
+      bundleId: decoded.bundleId ?? this.bundleId,
+      type: decoded.type,
+      webOrderLineItemId: decoded.webOrderLineItemId,
+      revocationDate: (decoded as any).revocationDate,
+      revocationReason: (decoded as any).revocationReason,
+    };
+  }
+
+  /**
+   * Verify + decode the outer signedPayload from an App Store Server
+   * Notification V2. Apple's SignedDataVerifier handles the cert chain +
+   * ES256 signature; we layer bundleId enforcement on top because the SDK
+   * trusts the configured bundleId but doesn't reject mismatching payloads.
+   */
+  public async verifyNotificationPayload(signedPayload: string): Promise<AppStoreNotificationPayload> {
+    const decoded = await verifySignedNotification(signedPayload, this.bundleId, this.environment);
+
+    if (decoded.data?.bundleId && decoded.data.bundleId !== this.bundleId) {
+      throw new Error(
+        `AppStoreClient: notification bundleId mismatch — JWS says ${decoded.data.bundleId}, configured ${this.bundleId}`
+      );
+    }
+    if (!decoded.notificationType || !decoded.notificationUUID) {
+      throw new Error('AppStoreClient: notification payload missing notificationType or notificationUUID');
+    }
+
+    logger.debug('App Store notification verified + decoded', {
+      notificationType: decoded.notificationType,
+      subtype: decoded.subtype,
+      notificationUUID: decoded.notificationUUID,
+    });
+
+    return {
+      notificationType: decoded.notificationType as string,
+      subtype: decoded.subtype as string | undefined,
+      notificationUUID: decoded.notificationUUID,
+      version: decoded.version ?? '2.0',
+      signedDate: decoded.signedDate ?? Date.now(),
+      data: {
+        appAppleId: decoded.data?.appAppleId,
+        bundleId: decoded.data?.bundleId ?? this.bundleId,
+        bundleVersion: decoded.data?.bundleVersion,
+        environment: (decoded.data?.environment as 'Production' | 'Sandbox') ?? 'Sandbox',
+        signedTransactionInfo: decoded.data?.signedTransactionInfo,
+        signedRenewalInfo: decoded.data?.signedRenewalInfo,
+        status: decoded.data?.status as 1 | 2 | 3 | 4 | 5 | undefined,
+      },
+    };
+  }
+
+  /**
+   * Verify a StoreKit 1 (legacy) base64 receipt via Apple's verifyReceipt endpoint.
+   *
+   * Calls `node-apple-receipt-verify` which POSTs to
+   *   https://buy.itunes.apple.com/verifyReceipt   (production)
+   *   https://sandbox.itunes.apple.com/verifyReceipt (sandbox, auto fallback)
+   *
+   * Returns a payload shaped like a StoreKit 2 transaction so downstream code
+   * (ingestVerifiedAppStorePurchase) can stay agnostic. Note: legacy receipts
+   * do NOT carry an appAccountToken — there's no client-set UUID for reverse
+   * lookup. Callers should rely on the customer's session identity instead.
+   *
+   * @param expectedProductIds — only items matching one of these productIds are kept.
+   *   If unset, all items are kept (receipt may contain multiple SKUs).
+   */
+  public async verifyLegacyReceipt(
+    receipt: string,
+    options: { expectedProductIds?: string[] } = {}
+  ): Promise<AppStoreTransactionPayload> {
+    if (!this.sharedSecret) {
+      throw new Error('AppStoreClient: shared_secret is required for legacy receipt verification');
+    }
+
+    // `node-apple-receipt-verify` uses a module-level config. We re-configure on
+    // every call so that multiple PaymentMethods (different secrets) don't
+    // shadow each other.
+    configApple({
+      secret: this.sharedSecret,
+      verbose: false,
+      environment: ['production', 'sandbox'],
+    });
+
+    const items = (await validateAppleReceipt({ receipt })) as Array<any>;
+    const filtered = options.expectedProductIds
+      ? items.filter((i) => options.expectedProductIds!.includes(i.productId))
+      : items;
+    if (!filtered.length) {
+      throw new Error('AppStoreClient: verifyReceipt returned no matching purchases');
+    }
+
+    // Pick the item with the latest expirationDate (subscription) or first one (non-subscription).
+    const latest = filtered.reduce((acc, cur) => {
+      const accExp = Number(acc.expirationDate ?? 0);
+      const curExp = Number(cur.expirationDate ?? 0);
+      return curExp > accExp ? cur : acc;
+    });
+
+    if (latest.bundleId && latest.bundleId !== this.bundleId) {
+      throw new Error(
+        `AppStoreClient: receipt bundleId mismatch — got ${latest.bundleId}, configured ${this.bundleId}`
+      );
+    }
+
+    logger.debug('App Store legacy receipt verified', {
+      productId: latest.productId,
+      transactionId: latest.transactionId,
+      expirationDate: latest.expirationDate,
+    });
+
+    return {
+      transactionId: String(latest.transactionId),
+      originalTransactionId: String(latest.originalTransactionId ?? latest.transactionId),
+      productId: latest.productId,
+      purchaseDate: latest.purchaseDate ? Number(latest.purchaseDate) : undefined,
+      expiresDate: latest.expirationDate ? Number(latest.expirationDate) : undefined,
+      // legacy receipts carry no client-set UUID
+      appAccountToken: undefined,
+      environment: this.environment === 'production' ? 'Production' : 'Sandbox',
+      bundleId: latest.bundleId ?? this.bundleId,
+      webOrderLineItemId: latest.webOrderLineItemId,
+    };
+  }
+
+  /**
+   * App Store Server API — pull latest subscription status by originalTransactionId.
+   *
+   * Returns the **decoded** latest `signedTransactionInfo` payload from
+   * Apple's StatusResponse (re-verified via SignedDataVerifier). Apple
+   * returns one transaction per `subscriptionGroupIdentifier`; we always
+   * pick the entry whose `originalTransactionId` matches the input.
+   *
+   * Requires issuer_id / key_id / private_key_pem in PaymentMethod settings.
+   */
+  public async getSubscriptionStatus(originalTransactionId: string): Promise<AppStoreTransactionPayload | null> {
+    if (!this.serverApiCredentials) {
+      throw new Error(
+        `AppStoreClient: getSubscriptionStatus(${originalTransactionId}) requires issuer_id/key_id/private_key_pem in settings`
+      );
+    }
+    const creds: AppStoreApiCredentials = {
+      issuerId: this.serverApiCredentials.issuerId,
+      keyId: this.serverApiCredentials.keyId,
+      privateKeyPem: this.serverApiCredentials.privateKeyPem,
+      bundleId: this.bundleId,
+      environment: this.environment,
+    };
+    const response = await getAllSubscriptionStatuses(originalTransactionId, creds);
+
+    // Apple groups by subscriptionGroupIdentifier — flatten + find the matching original txn.
+    const allTransactions = (response.data ?? []).flatMap((group) => group.lastTransactions ?? []);
+    const matched = allTransactions.find((t) => t.originalTransactionId === originalTransactionId);
+    if (!matched?.signedTransactionInfo) {
+      logger.warn('app_store getSubscriptionStatus: no matching transaction found', { originalTransactionId });
+      return null;
+    }
+    return this.verifyJwsTransaction(matched.signedTransactionInfo);
+  }
+
+  /** Refund — Apple actually doesn't let third parties refund subscriptions; this is here for symmetry with GooglePlayClient. */
+  // eslint-disable-next-line class-methods-use-this, require-await
+  public async refundSubscription(originalTransactionId: string): Promise<void> {
+    if (!WRITE_ENABLED) {
+      throw new Error(
+        `refundSubscription(${originalTransactionId}) is gated behind APP_STORE_WRITE_ENABLED env. Note: Apple Server API has no third-party refund endpoint — refunds must be requested by the end user via reportProblem.apple.com or by Apple support.`
+      );
+    }
+    throw new Error('refundSubscription not implementable — Apple does not expose a server-side refund API');
+  }
+
+  /** Cancel — same caveat as refund: Apple expects the user to cancel via App Store > Subscriptions. */
+  // eslint-disable-next-line class-methods-use-this, require-await
+  public async cancelSubscription(originalTransactionId: string): Promise<void> {
+    if (!WRITE_ENABLED) {
+      throw new Error(
+        `cancelSubscription(${originalTransactionId}) is gated behind APP_STORE_WRITE_ENABLED env. Apple does not expose a server-initiated cancel — the user must cancel from their device.`
+      );
+    }
+    throw new Error('cancelSubscription not implementable — Apple does not expose a server-side cancel API');
+  }
+}

package/api/src/integrations/app-store/handlers/index.ts

@@ -0,0 +1,46 @@
+// Top-level dispatch for an App Store Server Notification V2.
+//
+// Apple S2S envelope (already decoded by routes/integrations/app-store.ts):
+//   {
+//     notificationType: "DID_RENEW" | "EXPIRED" | ... ,
+//     subtype?: "INITIAL_BUY" | "VOLUNTARY" | ...,
+//     notificationUUID: "<uuid>",
+//     version: "2.0",
+//     signedDate: <unix ms>,
+//     data: {
+//       bundleId, environment,
+//       signedTransactionInfo, signedRenewalInfo,
+//       status (1=active, 2=expired, 3=billing-retry, 4=grace, 5=revoked)
+//     }
+//   }
+
+import logger from '../../../libs/logger';
+import { AppStoreClient, AppStoreNotificationPayload } from '../client';
+import { handleAppStoreSubscriptionEvent } from './subscription';
+
+export default async function handleAppStoreNotification(
+  notification: AppStoreNotificationPayload,
+  client: AppStoreClient
+): Promise<void> {
+  if (notification.notificationType === 'TEST') {
+    logger.info('app_store TEST notification received', {
+      notificationUUID: notification.notificationUUID,
+      bundleId: notification.data.bundleId,
+    });
+    return;
+  }
+
+  // Every actionable notification carries the inner transaction JWS — decode it
+  // here so the state machine can be tested with a pre-decoded payload.
+  if (!notification.data.signedTransactionInfo) {
+    logger.warn('app_store notification has no signedTransactionInfo — nothing to dispatch', {
+      notificationType: notification.notificationType,
+      notificationUUID: notification.notificationUUID,
+    });
+    return;
+  }
+
+  const transaction = await client.verifyJwsTransaction(notification.data.signedTransactionInfo);
+
+  await handleAppStoreSubscriptionEvent({ notification, transaction });
+}