payment-kit 1.29.7 → 1.29.9

package/api/src/host-glue.ts

@@ -0,0 +1,79 @@
+/**
+ * Runtime-neutral payment host glue (lives in the canonical core source tree).
+ *
+ * Zero runtime dependency (only the Web `Headers` global and `Map`), so it is the
+ * SINGLE source of truth for the host API gate header glue and the lazy-provision
+ * dedup. Two hosts consume it:
+ *   - the CF adapter (`../../cloudflare/cf-adapter.ts`, sibling import), and
+ *   - the arc-node daemon, via the published `@arcblock/payment-service` main
+ *     entry (the barrel re-exposes these through the same `as string` facade it
+ *     uses for the other node-side helpers).
+ * They previously kept hand-mirrored copies that had already drifted (the node
+ * host injected a raw role, the CF adapter prefixed it with `blocklet-`); a single
+ * source removes that drift class.
+ */
+
+/** The reserved mount prefix for the embedded payment service. */
+export const PAYMENT_PREFIX = '/.well-known/payment';
+
+/**
+ * The caller identity the host resolved (host injects it as `x-user-*`; the core
+ * never verifies a `login_token` in-process — the host owns caller resolution).
+ */
+export interface HostCallerIdentity {
+  did: string;
+  role?: string;
+  authMethod?: string;
+  displayName?: string;
+}
+
+/** Client-forged identity headers — always stripped before the host injects the real caller. */
+export const USER_HEADERS = ['x-user-did', 'x-user-role', 'x-user-provider', 'x-user-fullname', 'x-user-wallet-os'];
+
+/**
+ * Host API gate caller header glue (decision #5). STRIP any client-supplied
+ * `x-user-*` first (a forged `x-user-did` would be an auth bypass), then inject the
+ * host-resolved caller as the canonical headers the core `authenticate()` trusts.
+ * No caller → the request runs anonymous (the strip already happened, so it is
+ * never forged).
+ *
+ * `x-user-role` carries the RAW role (e.g. `owner` / `admin`). The core normalizes
+ * it as `(role || '').replace('blocklet-', '') || 'guest'`, so the legacy
+ * `blocklet-` prefix is deliberately NOT added — it was vestigial (the core strips
+ * it either way) and a prefixed role is wrong.
+ */
+export function injectCaller(headers: Headers, caller: HostCallerIdentity | null): void {
+  for (const h of USER_HEADERS) headers.delete(h);
+  if (!caller) return;
+  const canonicalDid = caller.did?.startsWith('did:abt:') ? caller.did : `did:abt:${caller.did}`;
+  headers.set('x-user-did', canonicalDid);
+  headers.set('x-user-role', caller.role || 'guest');
+  headers.set('x-user-provider', caller.authMethod === 'access-key' ? 'access-key' : caller.authMethod || 'wallet');
+  headers.set('x-user-fullname', encodeURIComponent(caller.displayName || ''));
+  headers.set('x-user-wallet-os', '');
+}
+
+/**
+ * Lazy per-tenant provisioning with in-flight dedup. Concurrent first-requests for
+ * the same tenant await the SAME provision() call — a Set would let a burst at
+ * isolate/daemon start double-seed before the DB idempotency guard commits. A
+ * resolved promise stays cached so later requests are instant; a FAILED provision
+ * is dropped so the next request retries. Null tenant is a no-op.
+ */
+export function createTenantProvisioner(
+  provision: (instanceDid: string) => Promise<void>
+): (instanceDid: string | null) => Promise<void> {
+  const inflight = new Map<string, Promise<void>>();
+  return (instanceDid) => {
+    if (!instanceDid) return Promise.resolve();
+    let p = inflight.get(instanceDid);
+    if (!p) {
+      p = provision(instanceDid).catch((err) => {
+        inflight.delete(instanceDid); // drop so the next request retries
+        throw err;
+      });
+      inflight.set(instanceDid, p);
+    }
+    return p;
+  };
+}

package/api/src/host-node/serve-static-arc.ts

@@ -42,6 +42,7 @@ export function createNodeStaticHandler(webRoot: string): (app: Hono) => void {
     const { serveStatic } = require('@hono/node-server/serve-static');
 
     // SPA fallback FIRST — html navigations (not assets) get index.html VERBATIM.
+    // eslint-disable-next-line require-await -- Hono's app.use overload requires a Promise-returning handler
     app.use('*', async (c, next) => {
       const method = c.req.method.toUpperCase();
       if (

package/api/src/integrations/app-store/native-asn1.ts

@@ -12,6 +12,7 @@
 // is the chain-to-pinned-Apple-root (native-jws.ts §5.3–5.4). A spoofed cert could
 // embed these public OID bytes, but it cannot forge the chain signature.
 
+/* eslint-disable no-bitwise -- DER base-128 OID encoding requires 7-bit-group bitwise ops (ASN.1) */
 import type { X509Certificate } from 'node:crypto';
 
 /**

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

@@ -43,6 +43,10 @@ export function isSignatureVerificationSkipped(): boolean {
   return true;
 }
 
+/* eslint-disable require-await, @typescript-eslint/no-unused-vars --
+   async: the skip-verify branch returns a sync decodeUnsafe<T>(), so async keeps the
+   signature Promise<T>; _bundleId/_environment stay in the signature for caller-layer
+   enforcement (client.ts) + Apple API parity. */
 export async function verifySignedTransaction(
   signedTransaction: string,
   _bundleId: string,
@@ -69,6 +73,7 @@ export async function verifySignedNotification(
   }
   return verifyAppleJws<JwsNotificationPayload>(signedPayload);
 }
+/* eslint-enable require-await, @typescript-eslint/no-unused-vars */
 
 /** Decode-only fallback for when signature verification is intentionally bypassed. */
 function decodeUnsafe<T>(jws: string): T {
@@ -104,7 +109,7 @@ export type AppStoreApiCredentials = {
  * StatusResponse, whose `signedTransactionInfo` JWS strings are verified by the
  * caller (client.ts) with verifyAppleJws.
  */
-export async function getAllSubscriptionStatuses(
+export function getAllSubscriptionStatuses(
   originalTransactionId: string,
   creds: AppStoreApiCredentials
 ): Promise<StatusResponse> {

package/api/src/integrations/stripe/setup.ts

@@ -4,7 +4,7 @@ import { env } from '@blocklet/sdk/lib/env';
 
 import Stripe from 'stripe';
 import logger from '../../libs/logger';
-import { STRIPE_API_VERSION, STRIPE_ENDPOINT, STRIPE_EVENTS } from '../../libs/util';
+import { STRIPE_API_VERSION, stripeEndpoint, STRIPE_EVENTS } from '../../libs/util';
 import { PaymentMethod } from '../../store/models';
 
 // register stripe webhooks on start/create if there are any stripe payment methods
@@ -23,7 +23,7 @@ export async function ensureWebhookRegistered() {
     const exist = data.find((webhook) => webhook.metadata?.appPid === env.appPid);
     if (exist) {
       await stripe.webhookEndpoints.update(exist.id, {
-        url: STRIPE_ENDPOINT,
+        url: stripeEndpoint(),
         description: env.appName,
         enabled_events: STRIPE_EVENTS,
         disabled: false,
@@ -31,7 +31,7 @@ export async function ensureWebhookRegistered() {
       logger.info('stripe webhook updated');
     } else {
       const result = await stripe.webhookEndpoints.create({
-        url: STRIPE_ENDPOINT,
+        url: stripeEndpoint(),
         description: env.appName,
         enabled_events: STRIPE_EVENTS,
         api_version: STRIPE_API_VERSION,

package/api/src/libs/arcblock-transfer.ts

@@ -0,0 +1,27 @@
+import type { Transaction } from '@ocap/client';
+import { encodeTx, fetchContext } from '@ocap/client/encode';
+
+type TransferWallet = {
+  address: string;
+  publicKey?: string;
+  pk?: string;
+};
+
+export async function encodeArcblockTransfer({
+  chainHost,
+  tx,
+  wallet,
+}: {
+  chainHost: string;
+  tx: Partial<Transaction>;
+  wallet: TransferWallet;
+}) {
+  const context = await fetchContext(chainHost);
+  return encodeTx({
+    type: 'TransferV3Tx',
+    tx: tx as any,
+    wallet,
+    chainId: context.chainId,
+    feeConfig: context.txFee,
+  });
+}

package/api/src/libs/context.ts

@@ -14,6 +14,7 @@ interface RequestContext {
   requestedBy?: string;
   requestId?: string;
   instanceDid?: string;
+  publicBaseUrl?: string;
 }
 
 class RequestContextManager {
@@ -74,6 +75,11 @@ class RequestContextManager {
     return this.storage.getStore()?.instanceDid;
   }
 
+  /** Request-scoped externally reachable payment base URL, when supplied by an embedded host. */
+  peekPublicBaseUrl(): string | undefined {
+    return this.storage.getStore()?.publicBaseUrl;
+  }
+
   /**
    * Run fn as a system operation: TenantModel scoping is bypassed for the span
    * of fn so legitimate cross-tenant reads can load rows regardless of tenant.
@@ -92,17 +98,19 @@ class RequestContextManager {
 
   run<T>(context: RequestContext, fn: () => Promise<T> | T): Promise<T> {
     const requestId = context.requestId || `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-    // inherit tenant from the enclosing scope unless explicitly provided
+    // inherit host-established request fields unless explicitly provided
     const instanceDid = context.instanceDid ?? this.storage.getStore()?.instanceDid;
+    const publicBaseUrl = context.publicBaseUrl ?? this.storage.getStore()?.publicBaseUrl;
 
     this.contexts.set(requestId, {
       ...context,
       instanceDid,
+      publicBaseUrl,
       requestId,
     });
 
     return new Promise((resolve, reject) => {
-      this.storage.run({ ...context, instanceDid, requestId }, async () => {
+      this.storage.run({ ...context, instanceDid, publicBaseUrl, requestId }, async () => {
         const resource = new AsyncResource('RequestContext');
         try {
           const result = await resource.runInAsyncScope(fn);

package/api/src/libs/did-connect/tenant-identity.ts

@@ -22,6 +22,7 @@ import type { WalletObject } from '@ocap/wallet';
 import { getInstanceDid } from '../context';
 import { getIdentityDriver, type InstanceAppInfo, type BlockletDirectory } from '../drivers';
 import logger from '../logger';
+import { warmupSecrets } from '../secrets';
 
 const walletType = {
   role: Mcrypto.types.RoleType.ROLE_APPLICATION,
@@ -165,10 +166,27 @@ export function getCachedTenantIdentity(instanceDidArg?: string): ResolvedTenant
  */
 export async function warmTenantIdentity(instanceDidArg?: string): Promise<void> {
   if (!hasDynamicIdentity()) return;
+  // The wallet signing identity (getInstanceAppIdentity) and the secrets keyring EK
+  // (getAppEk) are INDEPENDENT host concerns. Warm them in SEPARATE try blocks: a
+  // wallet-identity failure (e.g. an AUTH_SERVICE that does not implement
+  // getInstanceAppIdentity) must NOT also skip the secrets warm. Coupling them left
+  // the keyring cold whenever wallet identity was unavailable, so every PaymentMethod
+  // settings/Stripe decrypt 500'd on an undefined crypto key — even though the
+  // Stripe/USD path never needs the wallet identity.
   try {
     await resolveTenantIdentity(instanceDidArg);
   } catch (err: unknown) {
-    logger.warn('[tenant-identity] warm failed — wallet access will fail-closed', {
+    logger.warn('[tenant-identity] wallet identity warm failed — wallet access will fail-closed', {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+  // The keyring secrets driver warms the tenant EK so PaymentMethod settings
+  // encrypt/decrypt + getStripeClient resolve on the sync hot path (else "secrets:
+  // key for tenant <did> is not warmed"). No-op for the default single-key driver.
+  try {
+    await warmupSecrets(instanceDidArg);
+  } catch (err: unknown) {
+    logger.warn('[tenant-identity] secrets warm failed — settings/Stripe decrypt will fail-closed', {
       error: err instanceof Error ? err.message : String(err),
     });
   }

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,16 +168,17 @@ 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 stripeWebhookUrl = (): string | undefined => readConfig('STRIPE_WEBHOOK_URL');
 export const iapReconcileBatchSize = (): number => Number(readConfig('IAP_RECONCILE_BATCH_SIZE') ?? '100');
 
 // -- payment params --
@@ -155,9 +186,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 +206,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 +218,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/libs/notification/index.ts

@@ -12,10 +12,11 @@ let blockletSdkTransportGuarded = false;
 
 /** Replace `fns` with no-ops on both the module namespace and its `default` export. */
 function noopSdkTransport(mod: any, fns: string[]): void {
-  const noop = async (): Promise<undefined> => undefined;
+  const noop = (): Promise<undefined> => Promise.resolve(undefined);
   for (const target of [mod, mod?.default]) {
-    if (!target) continue;
-    for (const fn of fns) target[fn] = noop;
+    if (target) {
+      for (const fn of fns) target[fn] = noop;
+    }
   }
 }
 

package/api/src/libs/util.ts

@@ -13,7 +13,16 @@ import axios from 'axios';
 import { fromUnitToToken } from '@ocap/util';
 import get from 'lodash/get';
 import trimEnd from 'lodash/trimEnd';
-import { googlePlayWebhookUrl, blockletAppUrl, blockletMountPoints, blockletAppId, blockletAppName } from './env';
+import {
+  googlePlayWebhookUrl,
+  stripeWebhookUrl,
+  blockletAppUrl,
+  blockletMountPoints,
+  blockletAppId,
+  blockletAppName,
+  readConfig,
+} from './env';
+import { context } from './context';
 import dayjs from './dayjs';
 import { blocklet, wallet } from './auth';
 import type { PaymentCurrency, PaymentMethod, Subscription } from '../store/models';
@@ -29,7 +38,19 @@ export const MIN_RETRY_MAIL = 13; // total retry time before sending first mail:
 export const CHECKOUT_SESSION_TTL = 6 * 60 * 60; // expires in 6 hours, then removed after 12 hours
 
 export const STRIPE_API_VERSION = '2023-08-16';
-export const STRIPE_ENDPOINT: string = getUrl('/api/integrations/stripe/webhook');
+// Stripe webhook must be an ABSOLUTE https URL. In the embedded (arc-node) runtime
+// getUrl() returns a relative path (no host) which Stripe rejects — registration
+// then fails (and is currently swallowed) so payments never reconcile (session
+// stuck unpaid). Mirror googlePlayEndpoint: prefer the STRIPE_WEBHOOK_URL override,
+// fall back to getUrl. Lazy-eval (function) because dotenv loads env AFTER this
+// module is imported — a module-load constant would only ever see the relative path.
+export const stripeEndpoint = (): string => {
+  const override = stripeWebhookUrl();
+  if (override) return override;
+  const publicBaseUrl = context.peekPublicBaseUrl();
+  if (publicBaseUrl) return joinURL(publicBaseUrl, '/api/integrations/stripe/webhook');
+  return getUrl('/api/integrations/stripe/webhook');
+};
 // Pub/Sub OIDC tokens carry the push-subscription endpoint as `aud` claim. When
 // the dev server is reached via a custom domain (e.g. a Cloudflare tunnel), the
 // BLOCKLET_APP_URL-derived default won't match the URL Google signs against.
@@ -95,6 +116,14 @@ export const api = axios.create({
   timeout: 10 * 1000,
 });
 
+export function getPublicAssetUrl(assetUrl: string): string {
+  if (!assetUrl || !assetUrl.startsWith('/') || assetUrl.startsWith('//')) return assetUrl;
+  const basePath = readConfig('PAYMENT_PUBLIC_BASE_PATH');
+  if (!basePath) return getUrl(assetUrl);
+  if (assetUrl === basePath || assetUrl.startsWith(`${basePath}/`)) return assetUrl;
+  return joinURL(basePath, assetUrl);
+}
+
 export function md5(input: string) {
   return crypto.createHash('md5').update(input).digest('hex');
 }

package/api/src/middlewares/hono/csrf.ts

@@ -48,6 +48,12 @@ export function csrf(): MiddlewareHandler {
   // type to the MiddlewareHandler contract.
   // eslint-disable-next-line require-await
   return async (c, next) => {
+    // Escape hatch (TEST / STAGING ONLY): PAYMENT_DISABLE_CSRF=true bypasses CSRF
+    // verification entirely. This removes cross-site request forgery protection on
+    // ALL mutating payment routes — NEVER set it in production. Defaults off, so the
+    // standard secure behavior is unchanged unless a deployment opts out explicitly.
+    if (readConfig('PAYMENT_DISABLE_CSRF') === 'true') return next();
+
     const method = c.req.method.toUpperCase();
     const loginToken = getCookie(c, 'login_token');
     const existingCsrf = getCookie(c, 'x-csrf-token');

package/api/src/middlewares/hono/session.ts

@@ -104,6 +104,28 @@ export function sessionMiddleware(options: SessionOptions = {}): MiddlewareHandl
       return c.json({ error: err.message }, 401);
     }
 
+    // Embedded / blocklet-server PRIMARY auth path. The host adapter (arc-node CF
+    // gate via cf-adapter.injectCaller, or blocklet-server) verifies the caller
+    // upstream, STRIPS any client-forged `x-user-*`, then injects the real caller as
+    // `x-user-*` headers — exactly what authenticate() (security.ts) already trusts.
+    // sessionMiddleware historically only checked the login_token cookie, so under
+    // embedded (where the login_token is arc's, NOT verifiable by payment's
+    // @blocklet/sdk verifyLoginToken) session-scoped routes like /customers/me saw
+    // no user and 403'd even for a logged-in caller — which left the checkout
+    // customer form unpopulated. Honor the injected identity as a fallback.
+    if (!result) {
+      const injectedDid = c.req.header('x-user-did');
+      if (injectedDid) {
+        result = {
+          did: injectedDid,
+          role: c.req.header('x-user-role'),
+          provider: c.req.header('x-user-provider'),
+          fullName: decodeURIComponent(c.req.header('x-user-fullname') || ''),
+          walletOS: c.req.header('x-user-wallet-os') || '',
+        };
+      }
+    }
+
     if (result) {
       c.set('user', result);
     }

package/api/src/routes/connect/pay.ts

@@ -5,6 +5,7 @@ import { fromAddress } from '@ocap/wallet';
 import { encodeTransferItx } from '../../integrations/ethereum/token';
 import { executeEvmTransaction, waitForEvmTxConfirm } from '../../integrations/ethereum/tx';
 import { CallbackArgs, ethWallet } from '../../libs/auth';
+import { encodeArcblockTransfer } from '../../libs/arcblock-transfer';
 import logger from '../../libs/logger';
 import { parseChainError } from '../../libs/chain-error';
 import { getGasPayerExtra } from '../../libs/payment';
@@ -127,25 +128,36 @@ export default {
 
     if (paymentMethod.type === 'arcblock') {
       try {
-        await paymentIntent.update({ status: 'processing' });
         const client = paymentMethod.getOcapClient();
         const claim = claims.find((x) => x.type === 'prepareTx');
 
-        // Warm up chain context cache to avoid setTimeout(resolve,0) hang in workerd
-        await client.getContext();
-
         const tx: Partial<Transaction> = client.decodeTx(claim.finalTx);
         if (claim.delegator && claim.from) {
           tx.delegator = claim.delegator;
           tx.from = claim.from;
         }
 
-        // @ts-ignore
-        const { buffer } = await client.encodeTransferV3Tx({ tx });
+        const chainHost = paymentMethod.settings.arcblock?.api_host;
+        if (!chainHost) {
+          throw new Error('ArcBlock payment method API host is missing');
+        }
+        const signingWallet = fromAddress(userDid);
+        const { object: encodedTx, buffer } = await encodeArcblockTransfer({
+          chainHost,
+          tx,
+          wallet: signingWallet,
+        });
+        const gasPayerExtra = await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request), client);
+
+        // Only expose processing after all cold-start preparation has completed.
+        // If context fetching/encoding is canceled by workerd, the intent remains
+        // retryable instead of being stranded in processing without a tx hash.
+        await paymentIntent.update({ status: 'processing' });
         const txHash = await client.sendTransferV3Tx(
-          // @ts-ignore
-          { tx, wallet: fromAddress(userDid) },
-          await getGasPayerExtra(buffer, client.pickGasPayerHeaders(request), client)
+          // Passing the already-encoded signature skips the client's timer-backed
+          // encodeTransferV3Tx/getContext path in Cloudflare Workers.
+          { tx: encodedTx as any, wallet: signingWallet, signature: encodedTx.signature },
+          gasPayerExtra
         );
 
         const quoteValidation = await validateQuoteForPayment({

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/src/routes/hono/entitlements.ts

@@ -26,7 +26,14 @@ import { PaymentMethod } from '../../store/models';
 const app = new Hono();
 // component+owner/admin for cross-blocklet calls; ensureLogin for end users —
 // handler then enforces that non-admin users can only query their own DID.
-const auth = authenticate<PaymentMethod>({ component: true, roles: ['owner', 'admin'], ensureLogin: true });
+// Any signed-in user can query their OWN entitlements (the handler bodies
+// below already gate cross-customer reads via isSelf(...) + isAdminUser).
+// A roles-list here would block normal wallet users at the middleware (their
+// role is "user", not owner/admin) before isSelf ever runs, so the IAP
+// "Subscribe + check my own entitlement" loop returned 403 for every real
+// end user. Keep `component: true` so server-to-server signed calls bypass
+// auth as before; keep `ensureLogin` so unauthenticated requests still 401.
+const auth = authenticate<PaymentMethod>({ component: true, ensureLogin: true });
 
 function isAdminUser(role?: string): boolean {
   return role === 'owner' || role === 'admin';

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

@@ -109,7 +109,9 @@ app.post('/', auth, async (c) => {
 
     await method.update({ default_currency_id: currency.id });
 
-    ensureWebhookRegistered().catch(console.error);
+    ensureWebhookRegistered().catch((err) =>
+      logger.error('ensureWebhookRegistered failed (payments may not reconcile in real-time)', err)
+    );
 
     return c.json({ ...method.toJSON(), payment_currencies: [currency.toJSON()] });
   }
@@ -532,7 +534,9 @@ app.put('/:id', auth, async (c) => {
 
     const updatedMethod = await method.update(updateData);
     if (method.type === 'stripe') {
-      ensureWebhookRegistered().catch(console.error);
+      ensureWebhookRegistered().catch((err) =>
+        logger.error('ensureWebhookRegistered failed (payments may not reconcile in real-time)', err)
+      );
     }
     return c.json(updatedMethod);
   } catch (err) {