payment-kit 1.29.8 → 1.29.10

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/handlers/subscription.ts

@@ -110,7 +110,19 @@ export async function ingestVerifiedAppStorePurchase({
 
     const newExpiresAt = transaction.expiresDate ? Math.floor(Number(transaction.expiresDate) / 1000) : 0;
     const newTxnValid = !!newExpiresAt && newExpiresAt * 1000 > Date.now();
-    const lapsed = ['canceled', 'incomplete_expired', 'past_due'].includes(existing.status as string);
+    // A subscription is "lapsed" when one of two things is true:
+    //   (a) The stored status is already terminal (canceled / past_due / …).
+    //   (b) Status is still 'active' but stored current_period_end is in the
+    //       past. This is the Sandbox steady state — Apple doesn't send the
+    //       RTDN that would flip the status on expiry, so a freshly bought
+    //       5-minute Sandbox sub goes silently stale. Without case (b), a
+    //       re-Subscribe tap hits the idempotency `return existing` branch
+    //       below and the row never gets the new expires_at — the user
+    //       stays in the "Free" state because entitlement filters
+    //       current_period_end > now.
+    const storedExpiresAt = existing.current_period_end ?? 0;
+    const storedExpired = !!storedExpiresAt && storedExpiresAt * 1000 < Date.now();
+    const lapsed = ['canceled', 'incomplete_expired', 'past_due'].includes(existing.status as string) || storedExpired;
     // Sandbox re-subscribe / renewal arriving via client verify reuses the SAME
     // originalTransactionId. If the stored sub had lapsed (expired→canceled) but
     // the new transaction is valid, reactivate it instead of returning the stale
@@ -121,7 +133,7 @@ export async function ingestVerifiedAppStorePurchase({
       const updatePatch: any = {
         status: 'active',
         current_period_end: newExpiresAt,
-        ended_at: null,
+        end_at: null,
         cancel_at_period_end: false,
         payment_details: {
           ...(existing.payment_details || {}),
@@ -165,6 +177,45 @@ export async function ingestVerifiedAppStorePurchase({
       return { subscription: existing, isFirstSubscribe: false, transaction };
     }
 
+    // Lapsed + new transaction ALSO expired (Apple Sandbox steady state
+    // once a sub has cycled past its max auto-renewals: Apple keeps
+    // replaying the final expired transaction through Transaction.updates
+    // forever — both stored and replay are stale). Without an explicit
+    // terminal write here, the row stays status='active' with a past
+    // current_period_end, entitlement.check filters it out (correct), but
+    // the verify route keeps returning success: true on every replay so
+    // PaymentKit.handle() finishes the transaction successfully — yet
+    // Apple Sandbox redelivers it on the next tick anyway, producing the
+    // hundreds-per-minute verify spam seen in cf-aside logs. Marking
+    // incomplete_expired + ended_at converges the local truth, and a
+    // subsequent fresh purchase will land in the reactivate branch above
+    // (lapsed + newTxnValid) and revive the row cleanly.
+    if (lapsed && !newTxnValid) {
+      await existing.update({
+        status: 'incomplete_expired',
+        end_at: Math.floor(Date.now() / 1000),
+        cancel_at_period_end: false,
+        payment_details: {
+          ...(existing.payment_details || {}),
+          app_store: {
+            ...(existing.payment_details?.app_store || {}),
+            transaction_id: transaction.transactionId,
+            expires_at: newExpiresAt || (existing.payment_details?.app_store as any)?.expires_at,
+          },
+        },
+      } as any);
+      logger.info(
+        'app_store verify: subscription fully lapsed (stored + replay both expired) — marked incomplete_expired',
+        {
+          subscriptionId: existing.id,
+          originalTransactionId: transaction.originalTransactionId,
+          storedExpiresAt,
+          newExpiresAt,
+        }
+      );
+      return { subscription: existing, isFirstSubscribe: false, transaction };
+    }
+
     // SKU drift sync — when the StoreKit-side product_id differs from
     // what we have stored (Apple crossgrade / downgrade landed in
     // Sandbox immediately; or the production DID_RENEW webhook hadn't
@@ -579,7 +630,7 @@ async function handleAppStoreRenewed(
 
 async function markAppStoreExpired(subscription: Subscription): Promise<void> {
   if (['canceled', 'incomplete_expired'].includes(subscription.status as string)) return;
-  await subscription.update({ status: 'canceled', ended_at: Math.floor(Date.now() / 1000) });
+  await subscription.update({ status: 'canceled', end_at: Math.floor(Date.now() / 1000) });
   createEvent('Subscription', 'customer.subscription.deleted', subscription).catch(reportAuditFailure);
 }
 
@@ -607,7 +658,7 @@ async function handleAppStoreRevoked(
   const now = Math.floor(Date.now() / 1000);
   await subscription.update({
     status: 'canceled',
-    ended_at: now,
+    end_at: now,
     cancelation_details: {
       ...(subscription.cancelation_details ?? { comment: '', feedback: 'other' }),
       reason: 'cancellation_requested',

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/google-play/handlers/subscription.ts

@@ -541,7 +541,7 @@ async function handleRevoked(subscription: Subscription): Promise<void> {
   const now = Math.floor(Date.now() / 1000);
   await subscription.update({
     status: 'canceled',
-    ended_at: now,
+    end_at: now,
     cancelation_details: {
       ...(subscription.cancelation_details ?? { comment: '', feedback: 'other' }),
       reason: 'cancellation_requested',

package/api/src/integrations/google-play/handlers/voided.ts

@@ -80,7 +80,7 @@ export async function handleGooglePlayVoidedPurchase({
   if (subscription.status !== 'canceled' && subscription.status !== 'incomplete_expired') {
     await subscription.update({
       status: 'canceled',
-      ended_at: Math.floor(Date.now() / 1000),
+      end_at: Math.floor(Date.now() / 1000),
       cancelation_details: {
         ...(subscription.cancelation_details ?? { comment: '', feedback: 'other' }),
         reason: 'cancellation_requested',

package/api/src/integrations/stripe/handlers/payment-intent.ts

@@ -41,7 +41,9 @@ export async function handleStripePaymentSucceed(paymentIntent: PaymentIntent, e
 }
 
 export async function syncStripePayment(paymentIntent: PaymentIntent) {
-  if (!paymentIntent?.metadata?.stripe_id) {
+  const stripePaymentIntentId =
+    paymentIntent?.payment_details?.stripe?.payment_intent_id || paymentIntent?.metadata?.stripe_id;
+  if (!stripePaymentIntentId) {
     return;
   }
 
@@ -52,7 +54,7 @@ export async function syncStripePayment(paymentIntent: PaymentIntent) {
 
   const triggerRenew = paymentIntent.status !== 'succeeded';
   const client = await method.getStripeClient();
-  const stripeIntent = await client.paymentIntents.retrieve(paymentIntent.metadata.stripe_id);
+  const stripeIntent = await client.paymentIntents.retrieve(stripePaymentIntentId);
   if (stripeIntent) {
     // @ts-ignore
     await paymentIntent.update({

package/api/src/integrations/stripe/handlers/subscription.ts

@@ -148,7 +148,7 @@ export async function handleSubscriptionEvent(event: TEventExpanded, _: Stripe)
     if (['incomplete', 'incomplete_expired'].includes(subscription.status)) {
       logger.warn('subscription not ended on stripe event', { id: subscription.id });
     } else {
-      await subscription.update({ status: 'canceled', ended_at: event.data.object.ended_at });
+      await subscription.update({ status: 'canceled', end_at: event.data.object.ended_at });
       logger.info('subscription ended on stripe event', { id: subscription.id });
     }
   }

package/api/src/integrations/stripe/reconcile-checkout-core.ts

@@ -0,0 +1,60 @@
+export type ReconcileResult = {
+  status: string;
+  paymentStatus: string;
+  reconciled: boolean;
+};
+
+export type ReconcileDeps = {
+  findCheckoutSession: (id: string) => Promise<any>;
+  findPaymentIntent: (id: string) => Promise<any>;
+  getSubscriptionIds: (checkoutSession: any) => string[];
+  findSubscriptions: (ids: string[]) => Promise<any[]>;
+  syncPayment: (paymentIntent: any) => Promise<void>;
+  syncSubscription: (subscription: any) => Promise<void>;
+};
+
+export async function reconcileStripeCheckoutSessionWithDeps(
+  sessionId: string,
+  deps: ReconcileDeps
+): Promise<ReconcileResult> {
+  const checkoutSession = await deps.findCheckoutSession(sessionId);
+  if (!checkoutSession) {
+    throw new Error('Checkout session not found');
+  }
+  if (checkoutSession.status === 'complete') {
+    return {
+      status: checkoutSession.status,
+      paymentStatus: checkoutSession.payment_status,
+      reconciled: false,
+    };
+  }
+
+  let reconciled = false;
+  if (checkoutSession.payment_intent_id) {
+    const paymentIntent = await deps.findPaymentIntent(checkoutSession.payment_intent_id);
+    if (paymentIntent && paymentIntent.status !== 'succeeded') {
+      await deps.syncPayment(paymentIntent);
+      reconciled = true;
+    }
+  }
+
+  const subscriptionIds = deps.getSubscriptionIds(checkoutSession);
+  if (subscriptionIds.length > 0) {
+    const subscriptions = await deps.findSubscriptions(subscriptionIds);
+    for (const subscription of subscriptions) {
+      if (subscription.status === 'incomplete') {
+        // Sequential reconciliation avoids racing checkout success counters.
+        // eslint-disable-next-line no-await-in-loop
+        await deps.syncSubscription(subscription);
+        reconciled = true;
+      }
+    }
+  }
+
+  await checkoutSession.reload();
+  return {
+    status: checkoutSession.status,
+    paymentStatus: checkoutSession.payment_status,
+    reconciled,
+  };
+}

package/api/src/integrations/stripe/reconcile-checkout.ts

@@ -0,0 +1,40 @@
+import { getCheckoutSessionSubscriptionIds } from '../../libs/session';
+import { CheckoutSession, PaymentIntent, PaymentMethod, Subscription } from '../../store/models';
+import { syncStripePayment } from './handlers/payment-intent';
+import { handleStripeSubscriptionSucceed } from './handlers/subscription';
+import {
+  reconcileStripeCheckoutSessionWithDeps,
+  type ReconcileDeps,
+  type ReconcileResult,
+} from './reconcile-checkout-core';
+
+async function syncSubscription(subscription: Subscription): Promise<void> {
+  if (!subscription.payment_details?.stripe?.subscription_id) return;
+  const method = await PaymentMethod.findByPk(subscription.default_payment_method_id);
+  if (!method || method.type !== 'stripe') return;
+
+  const remote = await method
+    .getStripeClient()
+    .subscriptions.retrieve(subscription.payment_details.stripe.subscription_id, {
+      expand: ['latest_invoice.payment_intent', 'pending_setup_intent'],
+    });
+  if (['active', 'trialing'].includes(remote.status)) {
+    await handleStripeSubscriptionSucceed(subscription, remote.status);
+  }
+}
+
+const defaultDeps: ReconcileDeps = {
+  findCheckoutSession: (id) => CheckoutSession.findByPk(id),
+  findPaymentIntent: (id) => PaymentIntent.findByPk(id),
+  getSubscriptionIds: getCheckoutSessionSubscriptionIds,
+  findSubscriptions: (ids) => Subscription.findAll({ where: { id: ids } }),
+  syncPayment: syncStripePayment,
+  syncSubscription,
+};
+
+export function reconcileStripeCheckoutSession(
+  sessionId: string,
+  deps: ReconcileDeps = defaultDeps
+): Promise<ReconcileResult> {
+  return reconcileStripeCheckoutSessionWithDeps(sessionId, deps);
+}

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/entitlement.ts

@@ -49,6 +49,15 @@ export type EntitlementCheckResult = {
   subscription_id: string | null;
   source: 'subscription' | 'one_time' | null;
   credit_remaining?: string;
+  /**
+   * For subscription source: the customer has asked the platform (Apple,
+   * Google, Stripe) to STOP auto-renewing. The entitlement is still
+   * active until `expires_at` but won't renew. UIs should mark the card
+   * as "canceled, ends on X" and offer a re-enable action that deep-
+   * links to the platform's subscription management. Always omitted for
+   * one-time / credit-grant sources.
+   */
+  cancel_at_period_end?: boolean;
 };
 
 const SUBSCRIPTION_STATUS_PRIORITY: Record<string, number> = {
@@ -231,6 +240,7 @@ export async function checkEntitlement({
       expires_at: best.current_period_end ?? null,
       subscription_id: best.id,
       source: 'subscription',
+      cancel_at_period_end: !!best.cancel_at_period_end,
     };
   }
 
@@ -258,6 +268,7 @@ export type EntitlementListItem = {
   subscription_id: string | null;
   source: 'subscription' | 'one_time';
   credit_remaining?: string;
+  cancel_at_period_end?: boolean;
 };
 
 /**
@@ -367,6 +378,7 @@ export async function listEntitlements({
         expires_at: best.current_period_end ?? null,
         subscription_id: best.id,
         source: 'subscription',
+        cancel_at_period_end: !!best.cancel_at_period_end,
       };
       return item;
     })

package/api/src/libs/env.ts

@@ -178,6 +178,7 @@ export const googlePubsubAllowUnverifiedSender = (): boolean =>
   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 --

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/security.ts

@@ -24,6 +24,43 @@ import { isDevelopmentEnv, enableDevFakeAuth } from '../../libs/env';
 import { wallet } from '../../libs/auth';
 import { Customer } from '../../store/models/customer';
 
+// Bare ↔ prefixed DID coexist in this codebase:
+//   - Bearer-token branch stores `did:abt:<base58>` (token-path normalisation).
+//   - BS-injected `x-user-did` headers carry whichever shape the host emits.
+//   - Customer.did rows on multi-tenant deploys are mixed (older rows bare,
+//     CF-seeded rows prefixed).
+// Comparing `user.did === customer.did` with strict equality silently
+// false-negatives for half of these combinations, so every cross-DID match
+// goes through this helper. `findCustomerByEitherDid` runs a single
+// disjunction query so a row in either shape resolves.
+export function stripDidPrefix(did: string | undefined | null): string {
+  if (!did) return '';
+  return did.startsWith('did:abt:') ? did.slice('did:abt:'.length) : did;
+}
+
+/** True when both DIDs resolve to the same identity ignoring the `did:abt:`
+ * prefix. Use this for any cross-DID equality check on multi-tenant deploys
+ * (auth/record-access guards). Mirrors `blocklets/core/src/libs/did.ts`
+ * isSameDid — keep behaviour in sync. */
+export function isSameDid(a: string | undefined | null, b: string | undefined | null): boolean {
+  const x = stripDidPrefix(a);
+  const y = stripDidPrefix(b);
+  return !!x && x === y;
+}
+
+async function findCustomerByEitherDid(did: string): Promise<Customer | null> {
+  if (!did) return null;
+  const bare = stripDidPrefix(did);
+  if (!bare) return null;
+  const prefixed = `did:abt:${bare}`;
+  // Sequelize Op.or via plain object form; either shape resolves to the same
+  // logical user. Kept minimal to avoid an extra Op.in import path here.
+  // Bound to a local so the function body satisfies require-await without
+  // tripping no-return-await (returning the awaited binding, not the await).
+  const found = await Customer.findOne({ where: { did: [bare, prefixed] as any } });
+  return found;
+}
+
 type PermissionSpec<T extends Model> = {
   component?: boolean;
   roles?: string[];
@@ -173,7 +210,12 @@ export function authenticate<T extends Model>({
       }
 
       if (mine) {
-        const customer = await Customer.findOne({ where: { did: user.did } });
+        // Match Customer regardless of which DID shape the row was stored as
+        // (bare base58 from older single-tenant writes, did:abt: prefixed from
+        // CF multi-tenant flows). A strict findOne({did: user.did}) silently
+        // returned null when shapes mismatched, falling through to the 403
+        // even for the real owner.
+        const customer = await findCustomerByEitherDid(user.did);
         if (customer) {
           c.set('customer', customer);
           // hono query is immutable — inject the VERIFIED id into context so a
@@ -190,7 +232,10 @@ export function authenticate<T extends Model>({
         const doc: T | null =
           findById && typeof findById === 'function' ? await findById(id) : await (model as any).findByPk(id);
         if (doc && doc[field as keyof T]) {
-          const customer = await Customer.findOne({ where: { did: user.did } });
+          // Same shape-tolerant lookup as the mine branch — record-ownership
+          // checks were silently failing for users whose customer row lives in
+          // the other DID shape.
+          const customer = await findCustomerByEitherDid(user.did);
           c.set('doc', doc);
           c.set('customer', customer);
           if (customer && customer.id === doc[field as keyof T]) {