payment-kit 1.29.6 → 1.29.8

package/api/src/integrations/app-store/signed-data-verifier.ts

@@ -1,49 +1,30 @@
-// Real signature verification for App Store JWS payloads.
+// Signature verification for App Store JWS payloads — native (node:crypto +
+// crypto.subtle), no external dependency. The Apple JWS chain/signature logic
+// lives in native-jws.ts (verifyAppleJws); the App Store Server API client lives
+// in native-api.ts (nativeGetAllSubscriptionStatuses). The legacy
+// `@apple/app-store-server-library` path was removed once native became the only
+// path (design §10 Phase 3) — that evicts jsrsasign + the whole apple cluster
+// from both payment-core bundles.
 //
-// Wraps Apple's official `@apple/app-store-server-library` SignedDataVerifier:
-//   1. Loads bundled Apple Root CAs (vendored as base64 constants in
-//      apple-root-certs.ts so tsc compiles to dist without copying assets)
-//   2. Caches a per-(bundleId, environment) verifier instance — Apple SDK keeps
-//      a public-key cache inside each verifier, so reusing is much faster than
-//      constructing per-call
-//   3. Provides verifyTransaction / verifyNotification that throw on bad signatures
-//
-// Env var `APP_STORE_SKIP_SIGNATURE_VERIFY=true` bypasses the SDK entirely
-// (decode-only). Use for unit tests and sandbox debugging — never in production.
-
-// NOTE: @apple/app-store-server-library has top-level side-effects (jsrsasign
-// initializes RNG in global scope, see https://github.com/apple/app-store-server-library-node).
-// Cloudflare Workers forbid I/O / random / setTimeout in global scope, so we
-// **lazy-load** the SDK inside the first call to getVerifier. This keeps the
-// worker startup clean and lets non-Apple endpoints (Google Play, entitlements,
-// etc.) mount even when Apple SDK is present in the deps.
-import type {
-  AppStoreServerAPIClient,
-  JWSTransactionDecodedPayload,
-  ResponseBodyV2DecodedPayload,
-  SignedDataVerifier,
-  StatusResponse,
-} from '@apple/app-store-server-library';
+// Env var `APP_STORE_SKIP_SIGNATURE_VERIFY=true` bypasses verification
+// (decode-only) — for unit tests / sandbox debugging, fail-closed in production.
 
 import logger from '../../libs/logger';
 import { appStoreSkipSignatureVerify, isProduction } from '../../libs/env';
-import { APPLE_ROOT_CERTS } from './apple-root-certs';
-
-const verifierCache = new Map<string, SignedDataVerifier>();
+import { JwsNotificationPayload, JwsTransactionPayload, verifyAppleJws } from './native-jws';
+import { nativeGetAllSubscriptionStatuses } from './native-api';
 
-async function getVerifier(bundleId: string, environment: 'production' | 'sandbox'): Promise<SignedDataVerifier> {
-  const key = `${bundleId}:${environment}`;
-  const cached = verifierCache.get(key);
-  if (cached) return cached;
-  // Dynamic import — keeps the SDK out of the worker bundle's global scope.
-  const mod = await import('@apple/app-store-server-library');
-  const env = environment === 'production' ? mod.Environment.PRODUCTION : mod.Environment.SANDBOX;
-  // enableOnlineChecks=false — turning this on does OCSP revocation lookups on
-  // every verify, which adds latency + network dependency. Apple's published
-  // recommendation is to leave it off unless you specifically need it.
-  const verifier = new mod.SignedDataVerifier(APPLE_ROOT_CERTS, false, env, bundleId);
-  verifierCache.set(key, verifier);
-  return verifier;
+/**
+ * Minimal local shape of Apple's App Store Server API StatusResponse — only the
+ * fields `AppStoreClient.getSubscriptionStatus` reads (client.ts:337-339).
+ */
+export interface StatusResponse {
+  data?: Array<{
+    lastTransactions?: Array<{
+      originalTransactionId?: string;
+      signedTransactionInfo?: string;
+    }>;
+  }>;
 }
 
 export function isSignatureVerificationSkipped(): boolean {
@@ -64,28 +45,29 @@ export function isSignatureVerificationSkipped(): boolean {
 
 export async function verifySignedTransaction(
   signedTransaction: string,
-  bundleId: string,
-  environment: 'production' | 'sandbox'
-): Promise<JWSTransactionDecodedPayload> {
+  _bundleId: string,
+  _environment: 'production' | 'sandbox'
+): Promise<JwsTransactionPayload> {
   if (isSignatureVerificationSkipped()) {
     logger.warn('app_store: signature verification skipped via APP_STORE_SKIP_SIGNATURE_VERIFY');
-    return decodeUnsafe<JWSTransactionDecodedPayload>(signedTransaction);
+    return decodeUnsafe<JwsTransactionPayload>(signedTransaction);
   }
-  const verifier = await getVerifier(bundleId, environment);
-  return verifier.verifyAndDecodeTransaction(signedTransaction);
+  // Stateless native verify — anchors to vendored Apple roots, validates against
+  // the payload's signedDate. bundleId/environment stay in the signature for
+  // caller-layer enforcement (client.ts) + API parity.
+  return verifyAppleJws<JwsTransactionPayload>(signedTransaction);
 }
 
 export async function verifySignedNotification(
   signedPayload: string,
-  bundleId: string,
-  environment: 'production' | 'sandbox'
-): Promise<ResponseBodyV2DecodedPayload> {
+  _bundleId: string,
+  _environment: 'production' | 'sandbox'
+): Promise<JwsNotificationPayload> {
   if (isSignatureVerificationSkipped()) {
     logger.warn('app_store: signature verification skipped via APP_STORE_SKIP_SIGNATURE_VERIFY');
-    return decodeUnsafe<ResponseBodyV2DecodedPayload>(signedPayload);
+    return decodeUnsafe<JwsNotificationPayload>(signedPayload);
   }
-  const verifier = await getVerifier(bundleId, environment);
-  return verifier.verifyAndDecodeNotification(signedPayload);
+  return verifyAppleJws<JwsNotificationPayload>(signedPayload);
 }
 
 /** Decode-only fallback for when signature verification is intentionally bypassed. */
@@ -101,13 +83,6 @@ function decodeUnsafe<T>(jws: string): T {
   }
 }
 
-// Exposed for tests — reset module-level caches between tests.
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export function __resetVerifierCachesForTests(): void {
-  verifierCache.clear();
-  apiClientCache.clear();
-}
-
 // ============================================================================
 // App Store Server API client — for pulling fresh state (subscription status,
 // transaction history) when our local cache might be stale (e.g. at renewal,
@@ -123,29 +98,15 @@ export type AppStoreApiCredentials = {
   environment: 'production' | 'sandbox';
 };
 
-const apiClientCache = new Map<string, AppStoreServerAPIClient>();
-async function getApiClient(creds: AppStoreApiCredentials): Promise<AppStoreServerAPIClient> {
-  const key = `${creds.bundleId}:${creds.environment}:${creds.keyId}`;
-  const cached = apiClientCache.get(key);
-  if (cached) return cached;
-  // Lazy import — same reason as getVerifier (global-scope I/O ban in CF Workers).
-  const mod = await import('@apple/app-store-server-library');
-  const env = creds.environment === 'production' ? mod.Environment.PRODUCTION : mod.Environment.SANDBOX;
-  const client = new mod.AppStoreServerAPIClient(creds.privateKeyPem, creds.keyId, creds.issuerId, creds.bundleId, env);
-  apiClientCache.set(key, client);
-  return client;
-}
-
 /**
- * Fetch all subscription statuses for a given originalTransactionId.
- * Returns Apple's StatusResponse which contains `signedTransactionInfo` /
- * `signedRenewalInfo` JWS strings — verify those with the SignedDataVerifier
- * if you want decoded payloads.
+ * Fetch all subscription statuses for a given originalTransactionId via the
+ * native App Store Server API client (ES256 JWT bearer + fetch). Returns Apple's
+ * StatusResponse, whose `signedTransactionInfo` JWS strings are verified by the
+ * caller (client.ts) with verifyAppleJws.
  */
 export async function getAllSubscriptionStatuses(
   originalTransactionId: string,
   creds: AppStoreApiCredentials
 ): Promise<StatusResponse> {
-  const client = await getApiClient(creds);
-  return client.getAllSubscriptionStatuses(originalTransactionId);
+  return nativeGetAllSubscriptionStatuses(originalTransactionId, creds);
 }

package/api/src/libs/env.ts

@@ -57,6 +57,31 @@ const numConfig = (key: string, fallback: number): number => {
   return v ? +v : fallback;
 };
 
+// Unified boolean env parsing. Accepts 1/true/yes/on (truthy) and 0/false/no/off
+// (falsy), case-insensitive; unset / empty / unrecognized → `fallback`. Replaces
+// the ad-hoc `=== '1'` / `=== 'true'` / `!== 'false'` conventions that used to be
+// scattered across these accessors, so operators no longer have to guess whether a
+// flag wants `1` or `true`.
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+const FALSY = new Set(['0', 'false', 'no', 'off']);
+const parseBool = (value: string | undefined, fallback = false): boolean => {
+  if (value === undefined || value === '') return fallback;
+  const v = value.trim().toLowerCase();
+  if (TRUTHY.has(v)) return true;
+  if (FALSY.has(v)) return false;
+  return fallback;
+};
+
+// First non-empty value among keys — used to honor a renamed key while still
+// reading the deprecated alias (new name wins, old name kept as fallback).
+const readConfigAny = (...keys: string[]): string | undefined => {
+  for (const key of keys) {
+    const v = readConfig(key);
+    if (v !== undefined && v !== '') return v;
+  }
+  return undefined;
+};
+
 export const paymentStatCronTime = (): string => '0 1 0 * * *'; // 默认每天一次，计算前一天的
 export const subscriptionCronTime = (): string => readConfig('SUBSCRIPTION_CRON_TIME') || '0 */30 * * * *';
 export const notificationCronTime = (): string => readConfig('NOTIFICATION_CRON_TIME') || '0 5 */6 * * *';
@@ -67,7 +92,6 @@ export const stripeInvoiceCronTime = (): string => readConfig('STRIPE_INVOICE_CR
 export const stripePaymentCronTime = (): string => readConfig('STRIPE_PAYMENT_CRON_TIME') || '0 */20 * * * *';
 export const stripeSubscriptionCronTime = (): string => readConfig('STRIPE_SUBSCRIPTION_CRON_TIME') || '0 10 */8 * * *';
 export const revokeStakeCronTime = (): string => readConfig('REVOKE_STAKE_CRON_TIME') || '0 */5 * * * *';
-export const daysUntilCancel = (): string | undefined => readConfig('DAYS_UNTIL_CANCEL');
 export const meteringSubscriptionDetectionCronTime = (): string =>
   readConfig('METERING_SUBSCRIPTION_DETECTION_CRON_TIME') || '0 0 10 * * *';
 export const overdueDetectionCronTime = (): string => readConfig('OVERDUE_DETECTION_CRON_TIME') || '0 0 10 * * *';
@@ -93,20 +117,26 @@ export const sequelizeOptionsPoolIdle = (): number => numConfig('SEQUELIZE_OPTIO
 
 export const updateDataConcurrency = (): number => numConfig('UPDATE_DATA_CONCURRENCY', 5);
 
-// When set to 'true' or '1', the system stops accepting new orders.
-// Existing checkout sessions can still be viewed but new submissions will be rejected.
+// When truthy, the system stops accepting new orders. Existing checkout sessions
+// can still be viewed but new submissions will be rejected.
+// Renamed PAYMENT_KIT_STOP_ACCEPTING_ORDERS → PAYMENT_STOP_ACCEPTING_ORDERS; the
+// old name is still honored as a deprecated alias.
 export const stopAcceptingOrders = (): boolean =>
-  readConfig('PAYMENT_KIT_STOP_ACCEPTING_ORDERS') === 'true' || readConfig('PAYMENT_KIT_STOP_ACCEPTING_ORDERS') === '1';
+  parseBool(readConfigAny('PAYMENT_STOP_ACCEPTING_ORDERS', 'PAYMENT_KIT_STOP_ACCEPTING_ORDERS'));
 
 export const exchangeRateCacheTTLSeconds = (): number => numConfig('EXCHANGE_RATE_CACHE_TTL_SECONDS', 10 * 60);
 
-// System-level maximum pending amount limit (in token format, e.g., "10")
-// Default is 0 (disabled). Set PAYMENT_KIT_MAX_PENDING_AMOUNT to enable this limit.
-export const systemMaxPendingAmount = (): number => numConfig('PAYMENT_KIT_MAX_PENDING_AMOUNT', 5);
+// System-level maximum pending amount limit (in token format, e.g., "10"). Default 5.
+// Renamed PAYMENT_KIT_MAX_PENDING_AMOUNT → PAYMENT_MAX_PENDING_AMOUNT; the old name
+// is still honored as a deprecated alias.
+export const systemMaxPendingAmount = (): number => {
+  const v = readConfigAny('PAYMENT_MAX_PENDING_AMOUNT', 'PAYMENT_KIT_MAX_PENDING_AMOUNT');
+  return v ? +v : 5;
+};
 
 // Whether a locked price may still be edited. Lazy (reads injected config via
 // the boundary at call time) like every other Phase 8 accessor.
-export const allowChangeLockedPrice = (): boolean => readConfig('PAYMENT_CHANGE_LOCKED_PRICE') === '1';
+export const allowChangeLockedPrice = (): boolean => parseBool(readConfig('PAYMENT_CHANGE_LOCKED_PRICE'));
 
 // ──────────────────────────────────────────────────────────────────────────
 // Phase 8 (W2′): converged accessors. Every read below used to live inline in
@@ -122,7 +152,7 @@ export const isProduction = (): boolean => blockletMode() === 'production';
 export const nodeEnv = (): string | undefined => readConfig('NODE_ENV');
 export const isTestEnv = (): boolean => nodeEnv() === 'test';
 export const isDevelopmentEnv = (): boolean => nodeEnv() === 'development';
-export const enableDevFakeAuth = (): boolean => readConfig('ENABLE_DEV_FAKE_AUTH') === '1';
+export const enableDevFakeAuth = (): boolean => parseBool(readConfig('ENABLE_DEV_FAKE_AUTH'));
 
 // -- tenant mode-source (getTenantMode / getDefaultInstanceDid read these) --
 export const tenantModeRaw = (): string | undefined => readConfig('PAYMENT_TENANT_MODE');
@@ -138,14 +168,14 @@ export const blockletPort = (): string | undefined => readConfig('BLOCKLET_PORT'
 export const blockletMountPoints = (): string | undefined => readConfig('BLOCKLET_MOUNT_POINTS');
 
 // -- integrations --
-export const appStoreWriteEnabled = (): boolean => readConfig('APP_STORE_WRITE_ENABLED') === 'true';
-export const appStoreSkipSignatureVerify = (): boolean => readConfig('APP_STORE_SKIP_SIGNATURE_VERIFY') === 'true';
+export const appStoreWriteEnabled = (): boolean => parseBool(readConfig('APP_STORE_WRITE_ENABLED'));
+export const appStoreSkipSignatureVerify = (): boolean => parseBool(readConfig('APP_STORE_SKIP_SIGNATURE_VERIFY'));
 export const googlePubsubSkipSignatureVerify = (): boolean =>
-  readConfig('GOOGLE_PUBSUB_SKIP_SIGNATURE_VERIFY') === 'true';
+  parseBool(readConfig('GOOGLE_PUBSUB_SKIP_SIGNATURE_VERIFY'));
 export const googlePubsubPushServiceAccount = (): string | undefined =>
   readConfig('GOOGLE_PUBSUB_PUSH_SERVICE_ACCOUNT');
 export const googlePubsubAllowUnverifiedSender = (): boolean =>
-  readConfig('GOOGLE_PUBSUB_ALLOW_UNVERIFIED_SENDER') === 'true';
+  parseBool(readConfig('GOOGLE_PUBSUB_ALLOW_UNVERIFIED_SENDER'));
 export const googlePlayWebhookUrl = (): string | undefined => readConfig('GOOGLE_PLAY_WEBHOOK_URL');
 export const stripeWebhookSecret = (): string | undefined => readConfig('STRIPE_WEBHOOK_SECRET');
 export const iapReconcileBatchSize = (): number => Number(readConfig('IAP_RECONCILE_BATCH_SIZE') ?? '100');
@@ -155,9 +185,12 @@ export const paymentBillingThreshold = (): number => +(readConfig('PAYMENT_BILLI
 export const paymentMinStakeAmount = (): number => +(readConfig('PAYMENT_MIN_STAKE_AMOUNT') as string);
 export const paymentDaysUntilDue = (): string | undefined => readConfig('PAYMENT_DAYS_UNTIL_DUE');
 export const paymentDaysUntilCancel = (): string | undefined => readConfig('PAYMENT_DAYS_UNTIL_CANCEL');
-export const paymentReloadSubscriptionJobs = (): boolean => readConfig('PAYMENT_RELOAD_SUBSCRIPTION_JOBS') === '1';
+export const paymentReloadSubscriptionJobs = (): boolean => parseBool(readConfig('PAYMENT_RELOAD_SUBSCRIPTION_JOBS'));
 export const paymentRateVolatilityThreshold = (): string | undefined => readConfig('PAYMENT_RATE_VOLATILITY_THRESHOLD');
-export const paymentLivemode = (): boolean => readConfig('PAYMENT_LIVEMODE') !== 'false';
+// Defaults to livemode (true) when unset. NOTE: with the unified parser, an
+// explicit falsy value (false/0/no/off) now means testmode — previously ONLY the
+// literal string 'false' did, so PAYMENT_LIVEMODE=0 used to (mis)read as livemode.
+export const paymentLivemode = (): boolean => parseBool(readConfig('PAYMENT_LIVEMODE'), true);
 
 // -- credit queue --
 export const creditLowBalanceThresholdPercentage = (): number =>
@@ -172,8 +205,8 @@ export const creditQueueConcurrency = (): number =>
 export const exchangeRateCacheTTLFromEnv = (): boolean => hasConfig('EXCHANGE_RATE_CACHE_TTL_SECONDS');
 
 // -- store / sequelize logging --
-export const sqlLog = (): boolean => readConfig('SQL_LOG') === '1';
-export const sqlBenchmark = (): boolean => readConfig('SQL_BENCHMARK') === '1';
+export const sqlLog = (): boolean => parseBool(readConfig('SQL_LOG'));
+export const sqlBenchmark = (): boolean => parseBool(readConfig('SQL_BENCHMARK'));
 
 // -- CF worker runtime detection + env mirror (set by cloudflare/worker.ts on
 //    globalThis; the boundary so core never reads the global directly) --
@@ -184,17 +217,26 @@ export const isCfWorker = (): boolean => !!cfEnv();
  * THE single, reusable gate for Blocklet-Server-ONLY features.
  *
  * True only under Blocklet Server, where the full @blocklet/sdk host runtime is
- * present — BLOCKLET_APP_ID plus the rest of the env the SDK's
- * `checkBlockletEnvironment` requires (BLOCKLET_DID / BLOCKLET_APP_EK / ABT_NODE_*).
- * BLOCKLET_APP_ID is the canonical marker; arc-node and the CF worker run the
- * embedded core with NONE of it.
+ * present — the env the SDK's `checkBlockletEnvironment` requires (BLOCKLET_APP_ID /
+ * BLOCKLET_DID / BLOCKLET_APP_EK / ABT_NODE_*).
+ *
+ * Keyed on BLOCKLET_DID, NOT BLOCKLET_APP_ID: the CF worker injects
+ * BLOCKLET_APP_ID = APP_PID into the config slot (cloudflare/worker.ts
+ * envToPaymentCoreConfig — blockletAppId() legitimately needs it for app identity
+ * in auth.ts / util.ts), which made the old BLOCKLET_APP_ID check spuriously true
+ * on CF and defeated the transport guard below. BLOCKLET_DID is supplied only by
+ * the real Blocklet Server runtime — the CF worker uses APP_PID for the node DID
+ * and never sets BLOCKLET_DID in config, and arc-node never injects it — so it
+ * cleanly distinguishes the three hosts. (BLOCKLET_APP_EK would also be BS-only in
+ * production, but the test harness sets it for the crypto shim, so DID is the
+ * unambiguous discriminator.)
  *
  * Any integration that only works on Blocklet Server (the @blocklet/sdk
  * notification / eventbus / relay transports, and any future host-service feature)
  * MUST gate on this and skip itself off Blocklet Server — never branch on
  * isCfWorker()/hasDynamicIdentity() ad hoc, so "what is BS-only" stays in one place.
  */
-export const isBlockletServer = (): boolean => hasConfig('BLOCKLET_APP_ID');
+export const isBlockletServer = (): boolean => hasConfig('BLOCKLET_DID');
 
 export default {
   ...env,

package/api/src/routes/hono/credit-grants.ts

@@ -394,7 +394,7 @@ app.get('/verify-availability', authMine, async (c) => {
     const pendingAmountBN = new BN(pendingAmount);
 
     // 5. Check system-level maximum pending amount limit (highest priority, cannot be bypassed)
-    // systemMaxPendingAmount() is configured via PAYMENT_KIT_MAX_PENDING_AMOUNT (in token format)
+    // systemMaxPendingAmount() is configured via PAYMENT_MAX_PENDING_AMOUNT (in token format)
     if (systemMaxPendingAmount() > 0 && pendingAmountBN.gt(new BN(0))) {
       const systemMaxPendingAmountBN = fromTokenToUnit(
         trimDecimals(String(systemMaxPendingAmount()), currency.decimal),

package/api/tests/integrations/app-store/client.spec.ts

@@ -8,18 +8,35 @@ process.env.APP_STORE_SKIP_SIGNATURE_VERIFY = 'true';
 
 import { AppStoreClient, AppStoreSettings } from '../../../src/integrations/app-store/client';
 
-const mockConfigApple = jest.fn();
-const mockValidateAppleReceipt = jest.fn();
-jest.mock('node-apple-receipt-verify', () => ({
-  config: (...args: any[]) => mockConfigApple(...args),
-  validate: (...args: any[]) => mockValidateAppleReceipt(...args),
-}));
-
-beforeEach(() => {
-  mockConfigApple.mockReset();
-  mockValidateAppleReceipt.mockReset();
+// Path C (verifyLegacyReceipt) is now native fetch — mock the verifyReceipt HTTP
+// call instead of the evicted node-apple-receipt-verify package.
+type LegacyCall = { url: string; body: any };
+let legacyCalls: LegacyCall[] = [];
+
+/** Mock Apple's verifyReceipt with one JSON response per call (production→sandbox). */
+function mockVerifyReceipt(responses: Array<{ status: number; latest_receipt_info?: any[]; receipt?: any }>): void {
+  let i = 0;
+  legacyCalls = [];
+  global.fetch = jest.fn(async (url: unknown, init?: unknown) => {
+    legacyCalls.push({ url: String(url), body: JSON.parse(String((init as RequestInit).body)) });
+    const r = responses[Math.min(i, responses.length - 1)]!;
+    i += 1;
+    return { ok: true, status: 200, json: async () => r } as unknown as Response;
+  }) as unknown as typeof fetch;
+}
+
+/** Apple verifyReceipt success body with snake_case item(s). */
+const legacyItem = (over: Record<string, unknown> = {}) => ({
+  product_id: 'sub_06',
+  transaction_id: 'txn_1',
+  original_transaction_id: 'orig_1',
+  purchase_date_ms: '1700000000000',
+  expires_date_ms: '1800000000000',
+  ...over,
 });
 
+afterEach(() => jest.restoreAllMocks());
+
 const baseSettings: AppStoreSettings = {
   bundle_id: 'com.example.app',
   environment: 'sandbox',
@@ -232,38 +249,20 @@ describe('AppStoreClient.verifyLegacyReceipt', () => {
     await expect(c.verifyLegacyReceipt('base64-receipt')).rejects.toThrow(/shared_secret is required/);
   });
 
-  it('configures node-apple-receipt-verify with provided secret + both envs', async () => {
-    mockValidateAppleReceipt.mockResolvedValue([
-      {
-        bundleId: 'com.example.app',
-        productId: 'sub_06',
-        transactionId: 'txn_1',
-        originalTransactionId: 'orig_1',
-        purchaseDate: 1700000000000,
-        expirationDate: 1800000000000,
-      },
-    ]);
+  it('POSTs receipt-data + secret + exclude-old-transactions to the production Apple host', async () => {
+    mockVerifyReceipt([{ status: 0, receipt: { bundle_id: 'com.example.app' }, latest_receipt_info: [legacyItem()] }]);
     const c = AppStoreClient.fromSettings(withSecret);
     await c.verifyLegacyReceipt('base64-receipt');
-    expect(mockConfigApple).toHaveBeenCalledWith(
-      expect.objectContaining({
-        secret: 'sk_test_secret',
-        environment: ['production', 'sandbox'],
-      })
-    );
+    expect(legacyCalls[0]!.url).toBe('https://buy.itunes.apple.com/verifyReceipt');
+    expect(legacyCalls[0]!.body).toEqual({
+      'receipt-data': 'base64-receipt',
+      password: 'sk_test_secret',
+      'exclude-old-transactions': true,
+    });
   });
 
   it('normalizes one-item receipt to AppStoreTransactionPayload', async () => {
-    mockValidateAppleReceipt.mockResolvedValue([
-      {
-        bundleId: 'com.example.app',
-        productId: 'sub_06',
-        transactionId: 'txn_1',
-        originalTransactionId: 'orig_1',
-        purchaseDate: 1700000000000,
-        expirationDate: 1800000000000,
-      },
-    ]);
+    mockVerifyReceipt([{ status: 0, receipt: { bundle_id: 'com.example.app' }, latest_receipt_info: [legacyItem()] }]);
     const c = AppStoreClient.fromSettings(withSecret);
     const result = await c.verifyLegacyReceipt('base64-receipt');
     expect(result).toEqual({
@@ -280,10 +279,16 @@ describe('AppStoreClient.verifyLegacyReceipt', () => {
   });
 
   it('picks the item with the latest expirationDate when receipt contains multiple', async () => {
-    mockValidateAppleReceipt.mockResolvedValue([
-      { productId: 'sub_06', transactionId: 'old', expirationDate: 1500000000000 },
-      { productId: 'sub_06', transactionId: 'new', expirationDate: 1800000000000 },
-      { productId: 'sub_06', transactionId: 'mid', expirationDate: 1600000000000 },
+    mockVerifyReceipt([
+      {
+        status: 0,
+        receipt: { bundle_id: 'com.example.app' },
+        latest_receipt_info: [
+          legacyItem({ transaction_id: 'old', expires_date_ms: '1500000000000' }),
+          legacyItem({ transaction_id: 'new', expires_date_ms: '1800000000000' }),
+          legacyItem({ transaction_id: 'mid', expires_date_ms: '1600000000000' }),
+        ],
+      },
     ]);
     const c = AppStoreClient.fromSettings(withSecret);
     const result = await c.verifyLegacyReceipt('base64-receipt');
@@ -291,9 +296,15 @@ describe('AppStoreClient.verifyLegacyReceipt', () => {
   });
 
   it('filters by expectedProductIds when provided', async () => {
-    mockValidateAppleReceipt.mockResolvedValue([
-      { productId: 'other_sku', transactionId: 'wrong', expirationDate: 1900000000000 },
-      { productId: 'sub_06', transactionId: 'right', expirationDate: 1800000000000 },
+    mockVerifyReceipt([
+      {
+        status: 0,
+        receipt: { bundle_id: 'com.example.app' },
+        latest_receipt_info: [
+          legacyItem({ product_id: 'other_sku', transaction_id: 'wrong', expires_date_ms: '1900000000000' }),
+          legacyItem({ product_id: 'sub_06', transaction_id: 'right', expires_date_ms: '1800000000000' }),
+        ],
+      },
     ]);
     const c = AppStoreClient.fromSettings(withSecret);
     const result = await c.verifyLegacyReceipt('base64-receipt', { expectedProductIds: ['sub_06'] });
@@ -301,8 +312,12 @@ describe('AppStoreClient.verifyLegacyReceipt', () => {
   });
 
   it('throws when no item matches expectedProductIds', async () => {
-    mockValidateAppleReceipt.mockResolvedValue([
-      { productId: 'unknown_sku', transactionId: 'x', expirationDate: 1800000000000 },
+    mockVerifyReceipt([
+      {
+        status: 0,
+        receipt: { bundle_id: 'com.example.app' },
+        latest_receipt_info: [legacyItem({ product_id: 'unknown_sku', transaction_id: 'x' })],
+      },
     ]);
     const c = AppStoreClient.fromSettings(withSecret);
     await expect(c.verifyLegacyReceipt('base64-receipt', { expectedProductIds: ['sub_06'] })).rejects.toThrow(
@@ -311,25 +326,36 @@ describe('AppStoreClient.verifyLegacyReceipt', () => {
   });
 
   it('rejects when receipt bundleId disagrees with configured bundle_id', async () => {
-    mockValidateAppleReceipt.mockResolvedValue([
-      {
-        bundleId: 'com.evil.app',
-        productId: 'sub_06',
-        transactionId: 'txn_1',
-        originalTransactionId: 'orig_1',
-        expirationDate: 1800000000000,
-      },
-    ]);
+    mockVerifyReceipt([{ status: 0, receipt: { bundle_id: 'com.evil.app' }, latest_receipt_info: [legacyItem()] }]);
     const c = AppStoreClient.fromSettings(withSecret);
     await expect(c.verifyLegacyReceipt('base64-receipt')).rejects.toThrow(/bundleId mismatch/);
   });
 
   it('falls back to transactionId when originalTransactionId is absent', async () => {
-    mockValidateAppleReceipt.mockResolvedValue([
-      { productId: 'sub_06', transactionId: 'txn_only', expirationDate: 1800000000000 },
+    mockVerifyReceipt([
+      {
+        status: 0,
+        receipt: { bundle_id: 'com.example.app' },
+        latest_receipt_info: [legacyItem({ transaction_id: 'txn_only', original_transaction_id: undefined })],
+      },
     ]);
     const c = AppStoreClient.fromSettings(withSecret);
     const result = await c.verifyLegacyReceipt('base64-receipt');
     expect(result.originalTransactionId).toBe('txn_only');
   });
+
+  it('retries the sandbox host when production returns 21007', async () => {
+    mockVerifyReceipt([
+      { status: 21007 },
+      {
+        status: 0,
+        receipt: { bundle_id: 'com.example.app' },
+        latest_receipt_info: [legacyItem({ transaction_id: 'sb' })],
+      },
+    ]);
+    const c = AppStoreClient.fromSettings(withSecret);
+    const result = await c.verifyLegacyReceipt('base64-receipt');
+    expect(legacyCalls.map((x) => new URL(x.url).host)).toEqual(['buy.itunes.apple.com', 'sandbox.itunes.apple.com']);
+    expect(result.transactionId).toBe('sb');
+  });
 });

package/api/tests/integrations/app-store/fixtures/README.md

@@ -0,0 +1,54 @@
+# App Store native-verify test fixtures
+
+## `make-chain.ts` — synthetic chain generator (0.1)
+
+Generates a self-signed Apple-style 3-cert chain (root → CA intermediate w/ Apple
+OID `1.2.840.113635.100.6.2.1` → leaf w/ Apple OID `1.2.840.113635.100.6.11.1`)
+plus an ES256 `header.payload.p1363sig` JWS signed by the leaf key, and a
+`crossSignedLeaf` (same subject DN, different key) for chain-failure negatives.
+Cert validity windows are pinned via `certValidFrom`/`certValidTo` so skew
+boundary tests can position `signedDate` precisely. See the file header for the
+full contract — chiefly: **`signedDate` is the `effectiveDate`, never `Date.now()`.**
+
+**Determinism:** the EC P-256 signing keys are committed under `keys/`
+(`{root,int,leaf,wrongint}.key.pem`, synthetic + test-only) and certs are derived
+from them at runtime with pinned windows — so value assertions are stable and the
+certs never expire. Pass `freshKeys: true` for unique per-call keys. These keys
+are test-only and **must never be imported by `src/`** — `make-chain.spec.ts`
+asserts that structurally (a data-leak regression fails CI).
+
+## `real-sandbox.jws` / `real-sandbox.json` — real Apple fixture (0.4)
+
+A genuine Apple-signed (ES256) sandbox `signedTransactionInfo`, fetched via the
+App Store Server API `getTransactionInfo()` (`bundle_id: io.arcblock.ai.stro`,
+`transaction_id: 2000001186283296`). The real x5c chain is:
+
+```
+leaf:  Prod ECC Mac App Store and iTunes Store Receipt Signing (expires 2027-10-13)
+int:   Apple Worldwide Developer Relations Certification Authority G6
+root:  Apple Root CA - G3 (expires 2039-04-30)
+```
+
+This is **public, Apple-signed data — it contains no credentials** (a JWS is the
+signed transaction itself; the signing keys stay at Apple). Committing it is safe
+and it is the golden vector that exercises Apple's **real** OID + 3-cert chain
+end-to-end — the gap synthetic self-signed chains cannot close (design §11).
+
+`real-sandbox.json` carries the decoded header/payload + provenance `_meta` for
+reference; tests assert against `real-sandbox.jws`.
+
+**Maintenance:** the leaf cert expires 2027-10-13. After that, `verifyAppleJws`
+will reject this fixture on the validity check unless tests pin `signedDate` to
+the original `2026-06-15T11:02:14.379Z` (`payload.signedDate = 1781521334379`),
+which is what the native-jws spec does — so the fixture stays valid indefinitely
+for the algorithm assertions.
+
+## 0.3 — OID-encoding contract (production vs probe)
+
+Production code (`native-asn1.ts`, Phase 1) matches the **FULL DER OID tag**
+`[0x06, len, ...content]` against `cert.raw`. This is intentionally STRICTER than
+the workerd probe's content-only `oidContentHex` scan (`x509-probe.mjs`), which
+stays looser because a probe only needs a presence signal. Defense-in-depth: the
+OID marker is **not** the trust anchor — the chain-to-pinned-Apple-root is
+(design §4/§5.5). Both certs in `make-chain.ts` carry the OIDs as `DER:0500`
+extensions so the full-tag scan finds them.

package/api/tests/integrations/app-store/fixtures/keys/int.key.pem

@@ -0,0 +1,5 @@
+-----BEGIN EC PRIVATE KEY-----
+MHcCAQEEIOLX/gC4P1qjaOE/Ed/QHleT9P2Ib5bQ9YOZP8SXpFuNoAoGCCqGSM49
+AwEHoUQDQgAEnIlK3BCZxjk0kCXqbaNe/BYVG4VQ69YAkENkl9sL8sjDZGVwasEa
+OmnFMayUJIJPhfs+GyfSeY4p6m9kMiojrg==
+-----END EC PRIVATE KEY-----

package/api/tests/integrations/app-store/fixtures/keys/leaf.key.pem

@@ -0,0 +1,5 @@
+-----BEGIN EC PRIVATE KEY-----
+MHcCAQEEIFKVpAVLag9q7o02jUj0hsrZs2+Wp9VlZ1rvvXAdRDnNoAoGCCqGSM49
+AwEHoUQDQgAEi6jIb2EAAEGl8zcWyBd1No5Qz6wyZJLTS5sjbAA04FPX1FDlxReK
+X7q8vLFRhtkiR8OYnpCfLAeFng0rNi6Vdw==
+-----END EC PRIVATE KEY-----

package/api/tests/integrations/app-store/fixtures/keys/root.key.pem

@@ -0,0 +1,5 @@
+-----BEGIN EC PRIVATE KEY-----
+MHcCAQEEIG+D+QBzI7gMWT4Zuk9iqw663wEtMWol4ccQfydNehdNoAoGCCqGSM49
+AwEHoUQDQgAE7hyZ2JQcvmLQIrzj8j5UUSl/tOBgJG5bhFRwMu3isC8xibmLb/cj
+P2IIOGfGAXz0Iu5NLEm7etUmR3HKvQlKTg==
+-----END EC PRIVATE KEY-----

package/api/tests/integrations/app-store/fixtures/keys/wrongint.key.pem

@@ -0,0 +1,5 @@
+-----BEGIN EC PRIVATE KEY-----
+MHcCAQEEIB4LVWQHO0Sx74I6JjkEmglD6b5sfnt+CmU6Tf711WNtoAoGCCqGSM49
+AwEHoUQDQgAE3fF1vJNolgjgt+rIqLDQCzZ1Irrr4VKxwxTwNzTD4p16sa5U6DOR
+qPd67ubvIOmQldtn4DJ8yi+sAxNjLVevGA==
+-----END EC PRIVATE KEY-----