payment-kit 1.29.2 → 1.29.4

package/api/src/libs/did-connect/runtime-did-connect-js.ts

@@ -0,0 +1,88 @@
+// S3-CF (DID convergence) — the REAL @arcblock/did-connect-js runtime, SHARED by
+// the non-blocklet-server hosts (CF + arc-node embedded).
+//
+// Both build the same authenticator/handlers; they differ ONLY in the host adapter
+// passed in here (tokenStorage, chain config, txEncoder, timeout). The signing
+// wallet + appInfo are FUNCTION-VALUED and resolved per-request, per-tenant through
+// the shared `resolveTenantIdentity` (AUTH_SERVICE.getInstanceAppIdentity) — never
+// a fixed isolate key — so one isolate serves every tenant with its own appSk.
+//
+// @arcblock/did-connect-js supports function-valued `wallet` (base.js: typeof
+// wallet === 'function' → resolved via getWalletInfo with a timeout before each
+// sign), so per-tenant signing is safe.
+
+import type { DidConnectRuntime, DidConnectTokenStorage } from '../auth';
+import { resolveTenantIdentity } from './tenant-identity';
+
+/** Chain config for the DID-Connect authenticator (id/type/host), or a resolver. */
+export type ChainInfoOption =
+  | { id: string; type: string; host: string }
+  | ((params: any) => { id: string; type: string; host: string } | Promise<{ id: string; type: string; host: string }>);
+
+export interface DidConnectJsRuntimeOptions {
+  /** Host-injected token store (CF: D1 tenant-aware adapter). Omit to let
+   *  buildTokenStorage fall back to the file-backed nedb default (arc-node). */
+  tokenStorage?: DidConnectTokenStorage;
+  /** Chain config for `signature`/`prepareTx` claims (omit on chain-less hosts). */
+  chainInfo?: ChainInfoOption;
+  /** On-chain tx encoder (CF: @ocap/client/encode CBOR encoder). Omit to disable tx claims. */
+  txEncoder?: (params: { type: string; data: any; wallet: any; chainHost: string }) => Promise<Buffer>;
+  /** Authenticator timeout (CF chain RPC can exceed the 8s default; worker used 30s). */
+  timeout?: number;
+  /** Branding fallback when an instance's getInstanceAppIdentity omits appInfo. */
+  defaultAppInfo?: { name?: string; description?: string; icon?: string };
+}
+
+const DEFAULT_APP_INFO = {
+  name: 'Payment Kit',
+  description: 'Payment Kit',
+  icon: 'https://www.arcblock.io/favicon.ico',
+};
+
+/**
+ * Build a DID-Connect runtime backed by the real @arcblock/did-connect-js stack.
+ * Used by `createCloudflareDidConnectRuntime` (CF) and the arc-node embedded host.
+ */
+export function createDidConnectJsRuntime(opts: DidConnectJsRuntimeOptions): DidConnectRuntime {
+  const fallbackAppInfo = { ...DEFAULT_APP_INFO, ...(opts.defaultAppInfo ?? {}) };
+
+  return {
+    tokenStorage: opts.tokenStorage,
+
+    createAuthenticator() {
+      // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+      const { WalletAuthenticator } = require('@arcblock/did-connect-js');
+
+      const config: Record<string, any> = {
+        // Function-valued, per-tenant: resolve the signing wallet from the host
+        // IdentityDriver.getInstanceAppIdentity each time the authenticator signs.
+        // `.toJSON()` matches the standalone worker (the SDK reconstructs the full
+        // wallet — incl. sk — via fromJSON before signing).
+        wallet: async () => {
+          const { wallet } = await resolveTenantIdentity();
+          return wallet.toJSON();
+        },
+        appInfo: async ({ baseUrl }: { baseUrl?: string } = {}) => {
+          const { appInfo } = await resolveTenantIdentity();
+          return {
+            name: appInfo.name || fallbackAppInfo.name,
+            description: appInfo.description || fallbackAppInfo.description,
+            icon: appInfo.icon || fallbackAppInfo.icon,
+            link: appInfo.link || baseUrl,
+          };
+        },
+        timeout: opts.timeout ?? 30000,
+      };
+      if (opts.chainInfo) config.chainInfo = opts.chainInfo;
+      if (opts.txEncoder) config.txEncoder = opts.txEncoder;
+
+      return new WalletAuthenticator(config);
+    },
+
+    createHandlers({ authenticator, tokenStorage }) {
+      // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+      const { WalletHandlers } = require('@arcblock/did-connect-js');
+      return new WalletHandlers({ authenticator, tokenStorage });
+    },
+  };
+}

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

@@ -0,0 +1,221 @@
+// S3-CF (DID convergence) — the SHARED per-tenant DID-Connect identity resolver.
+//
+// Both non-blocklet-server runtimes (CF + arc-node embedded) build their REAL
+// `@arcblock/did-connect-js` WalletAuthenticator from a per-tenant signing wallet
+// resolved HERE — never from a fixed isolate-level APP_SK. The signing identity
+// comes from the host IdentityDriver's `getInstanceAppIdentity(instanceDid)`
+// (AUTH_SERVICE-backed), which already resolves the arc run-mode (instance app:sk
+// → instance identity; else auth-service root; else fail-closed), so payment-core
+// never reimplements "instance ?? root" and never reads connect-service internals.
+//
+// The wallet is derived from the returned `appSk` with @ocap/wallet (a stable
+// public API) — the same ROLE_APPLICATION/ED25519/SHA3 wallet type the standalone
+// CF worker used. The blocklet-server runtime does NOT use this resolver (it keeps
+// the @blocklet/sdk wallet wrapper); only the AUTH_SERVICE/did-connect-js runtimes do.
+//
+// eslint-disable-next-line import/no-extraneous-dependencies
+import * as Mcrypto from '@ocap/mcrypto';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { fromSecretKey, WalletType } from '@ocap/wallet';
+import type { WalletObject } from '@ocap/wallet';
+
+import { getInstanceDid } from '../context';
+import { getIdentityDriver, type InstanceAppInfo, type BlockletDirectory } from '../drivers';
+import logger from '../logger';
+
+const walletType = {
+  role: Mcrypto.types.RoleType.ROLE_APPLICATION,
+  pk: Mcrypto.types.KeyType.ED25519,
+  hash: Mcrypto.types.HashType.SHA3,
+};
+
+// The ethereum business wallet is derived from the SAME instance appSk as the
+// arcblock wallet, mirroring @blocklet/sdk getWallet('ethereum', appSk): the
+// secp256k1/keccak WalletType('ethereum') over the first 66 chars of the appSk.
+// Using @ocap/wallet directly (not the SDK) keeps this CF-worker-safe — the CF
+// build shims the SDK wallet-* modules, but @ocap/wallet is a stable public API.
+const ethWalletType = WalletType('ethereum');
+
+export interface ResolvedTenantIdentity {
+  instanceDid: string;
+  /** App signing wallet derived from the instance appSk (the DID-Connect signer). */
+  wallet: WalletObject;
+  /** Ethereum business wallet derived from the same appSk (EVM chains / refunds). */
+  ethWallet: WalletObject;
+  /** Permanent app signing wallet (when keys rotated); falls back to `wallet`. */
+  permanentWallet: WalletObject;
+  /** Branding for DID-Connect prompts (name/description/icon/link). */
+  appInfo: InstanceAppInfo;
+}
+
+// Per-instance TTL cache of the DERIVED identity (Layer 2 of
+// wallet-authenticator-dynamic.md). The business wallet proxies (libs/auth.ts)
+// read it SYNCHRONOUSLY via getCachedTenantIdentity, so resolveTenantIdentity
+// (async — it RPCs getInstanceAppIdentity) must run first per request/job (the
+// HTTP contextMiddleware and queue runJobWithTenant warm it). TTL bounds key-
+// rotation staleness; for a single-tenant deployment this holds exactly one entry.
+// A hard size cap (insertion-order eviction via Map iteration) keeps a host with
+// many tenants from growing the map unbounded — expired entries are pruned on
+// read but never proactively, so the cap is the only growth bound.
+const IDENTITY_TTL_MS = 5 * 60 * 1000;
+const IDENTITY_CACHE_MAX = 512;
+const identityCache = new Map<string, { value: ResolvedTenantIdentity; expiry: number }>();
+
+function cacheIdentity(instanceDid: string, value: ResolvedTenantIdentity): void {
+  identityCache.set(instanceDid, { value, expiry: Date.now() + IDENTITY_TTL_MS });
+  // evict the oldest entry (Map preserves insertion order) once over the cap
+  if (identityCache.size > IDENTITY_CACHE_MAX) {
+    const oldest = identityCache.keys().next().value;
+    if (oldest !== undefined) identityCache.delete(oldest);
+  }
+}
+
+/** Drop a tenant's cached identity (or all) — key rotation / test isolation. */
+export function clearTenantIdentityCache(instanceDid?: string): void {
+  if (instanceDid) identityCache.delete(instanceDid);
+  else identityCache.clear();
+}
+
+/**
+ * Whether the active host runtime resolves app identity dynamically per tenant
+ * (arc-node embedded + CF, via AUTH_SERVICE.getInstanceAppIdentity) vs the
+ * blocklet-server runtime, which keeps the @blocklet/sdk env wallet. The
+ * business wallet proxies branch on this so blocklet-server stays byte-for-byte
+ * unchanged (it never touches the resolver / cache).
+ */
+export function hasDynamicIdentity(): boolean {
+  return typeof getIdentityDriver().getInstanceAppIdentity === 'function';
+}
+
+/**
+ * Resolve the current (or given) tenant's DID-Connect signing identity. Throws a
+ * clear error — never silently falls back to a fixed key — when:
+ *   - the active IdentityDriver does not implement getInstanceAppIdentity (a
+ *     non-SDK runtime reached an SDK-only driver), or
+ *   - the instance has no app signing key (fail-closed; AUTH_SERVICE 4.0.3 itself
+ *     fails closed when neither instance app:sk nor root APP_SK exists).
+ */
+export async function resolveTenantIdentity(instanceDidArg?: string): Promise<ResolvedTenantIdentity> {
+  const instanceDid = instanceDidArg ?? getInstanceDid();
+
+  const cached = identityCache.get(instanceDid);
+  if (cached && cached.expiry > Date.now()) return cached.value;
+
+  const driver = getIdentityDriver();
+  if (typeof driver.getInstanceAppIdentity !== 'function') {
+    throw new Error(
+      'resolveTenantIdentity: the active IdentityDriver does not implement getInstanceAppIdentity — ' +
+        'a non-blocklet-server DID-Connect runtime requires an AUTH_SERVICE-backed identity driver'
+    );
+  }
+  const identity = await driver.getInstanceAppIdentity(instanceDid);
+  if (!identity || !identity.appSk) {
+    throw new Error(`resolveTenantIdentity: no app signing key for instance "${instanceDid}" (fail-closed)`);
+  }
+  // A too-short appSk would silently yield a WRONG ethereum address (slice below)
+  // and thus a wrong receiving/signing wallet — fail closed instead. A real
+  // ED25519 app sk is 128 hex chars; the eth slice needs at least 66.
+  if (identity.appSk.length < 66) {
+    throw new Error(
+      `resolveTenantIdentity: appSk for instance "${instanceDid}" is too short ` +
+        `(${identity.appSk.length} chars) to derive a wallet (fail-closed)`
+    );
+  }
+  const wallet = fromSecretKey(identity.appSk, walletType) as WalletObject;
+  // Mirror @blocklet/sdk getWallet('ethereum', appSk): secp256k1 over appSk[0..66].
+  const ethWallet = fromSecretKey(identity.appSk.slice(0, 66), ethWalletType) as WalletObject;
+  const permanentWallet = identity.appPsk ? (fromSecretKey(identity.appPsk, walletType) as WalletObject) : wallet;
+  const value: ResolvedTenantIdentity = {
+    instanceDid,
+    wallet,
+    ethWallet,
+    permanentWallet,
+    appInfo: identity.appInfo ?? {},
+  };
+  cacheIdentity(instanceDid, value);
+  return value;
+}
+
+/**
+ * SYNCHRONOUS accessor for the current (or given) tenant's resolved identity —
+ * the business wallet proxies (libs/auth.ts) call this on every `wallet.address`
+ * / `wallet.sign(...)`. It NEVER resolves (no RPC): it reads the cache that
+ * `warmTenantIdentity` populated earlier in the request/job. A miss means the
+ * identity was never warmed (fail-closed): throw rather than silently fall back
+ * to a wrong/default key.
+ */
+export function getCachedTenantIdentity(instanceDidArg?: string): ResolvedTenantIdentity {
+  const instanceDid = instanceDidArg ?? getInstanceDid();
+  const cached = identityCache.get(instanceDid);
+  if (!cached || cached.expiry <= Date.now()) {
+    throw new Error(
+      `tenant identity for "${instanceDid}" is not resolved (fail-closed) — ` +
+        'warmTenantIdentity must run in the request/job scope before any wallet access'
+    );
+  }
+  return cached.value;
+}
+
+/**
+ * Best-effort warm of the current tenant's identity into the cache so later
+ * SYNCHRONOUS wallet access resolves. No-op for the blocklet-server runtime
+ * (env wallet, no dynamic driver). Errors are swallowed (logged): a request that
+ * never touches a wallet must not be blocked by an identity hiccup, while one
+ * that DOES touch it still fails-closed at getCachedTenantIdentity.
+ */
+export async function warmTenantIdentity(instanceDidArg?: string): Promise<void> {
+  if (!hasDynamicIdentity()) return;
+  try {
+    await resolveTenantIdentity(instanceDidArg);
+  } catch (err: unknown) {
+    logger.warn('[tenant-identity] warm failed — wallet access will fail-closed', {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+// The host user directory for the embedded runtime. In the DID-Connect world the
+// user's DID IS the wallet DID, so getUser echoes it as a connected wallet account
+// (so getWalletDid(user) resolves to the user's own DID); the rest are no-ops. This
+// is the shared semantics the CF build-alias shim also implements
+// (cloudflare/shims/blocklet-sdk/auth-service.ts).
+const EMBEDDED_DIRECTORY: BlockletDirectory = {
+  getUser(did: string) {
+    if (!did) return { user: null };
+    return {
+      user: { did, fullName: did, email: '', phone: '', remark: '', connectedAccounts: [{ provider: 'wallet', did }] },
+    };
+  },
+  getUsers() {
+    return { users: [] };
+  },
+  getVault() {
+    return null;
+  },
+  getBlocklet() {
+    return { id: '', site: { id: '' } };
+  },
+};
+
+/**
+ * The embedded host identity services — the AUTH_SERVICE-backed implementations of
+ * the optional IdentityDriver methods, derived entirely from getInstanceAppIdentity
+ * (so a host need not reimplement them). arc-node spreads BOTH into its identity
+ * driver; CF spreads `getBusinessWallet` only (it keeps its build-alias directory
+ * shim). Stateless — every call reads the active driver via resolveTenantIdentity /
+ * getCachedTenantIdentity, so one instance serves every tenant.
+ */
+export function createEmbeddedIdentityServices(): {
+  getBusinessWallet(chain: 'arcblock' | 'ethereum'): WalletObject;
+  directory(): BlockletDirectory;
+} {
+  return {
+    getBusinessWallet(chain: 'arcblock' | 'ethereum'): WalletObject {
+      const identity = getCachedTenantIdentity();
+      return chain === 'ethereum' ? identity.ethWallet : identity.wallet;
+    },
+    directory(): BlockletDirectory {
+      return EMBEDDED_DIRECTORY;
+    },
+  };
+}

package/api/src/libs/drivers/identity.ts

@@ -13,8 +13,34 @@
 // unchanged; multi-tenant hosts inject a driver that maps Host -> instanceDid
 // and returns null for unknown hosts (the middleware then fails closed 4xx).
 
+import type { WalletObject } from '@ocap/wallet';
+
 import { getDefaultInstanceDid, getTenantMode, TenantError, TENANT_HOST_UNRESOLVED } from '../tenant';
 
+/** Branding/profile used by DID-Connect prompts (mirrors did-connect-service InstanceAppInfoDTO). */
+export interface InstanceAppInfo {
+  name?: string;
+  description?: string;
+  icon?: string;
+  link?: string;
+}
+
+/**
+ * Per-instance app signing identity used to build the DID-Connect authenticator
+ * (mirrors did-connect-service@4.0.3 InstanceAppIdentityDTO). The AUTH_SERVICE
+ * RPC `getInstanceAppIdentity(instanceDid)` already resolves the arc run-mode
+ * (instance `app:sk` → instance identity; else auth-service root `APP_SK/APP_PSK`;
+ * else fail-closed), so the payment runtime never reimplements "instance ?? root".
+ */
+export interface InstanceAppIdentity {
+  /** Current app signing key for this instance. */
+  appSk: string;
+  /** Permanent app signing key, present when the instance has rotated keys. */
+  appPsk?: string;
+  /** Branding/profile for DID-Connect prompts. */
+  appInfo?: InstanceAppInfo;
+}
+
 export interface IdentityDriver {
   /**
    * Resolve a request Host to its tenant instanceDid, or null/undefined when
@@ -28,6 +54,41 @@ export interface IdentityDriver {
    * driver uses the process key and never calls it.
    */
   getAppEk?(instanceDid: string): Promise<string> | string;
+  /**
+   * S3-CF (DID convergence): the per-instance app signing identity backing the
+   * DID-Connect authenticator. The AUTH_SERVICE-backed driver (CF + arc-node
+   * embedded) implements this via `AUTH_SERVICE.getInstanceAppIdentity`; the
+   * blocklet-server runtime uses the @blocklet/sdk wallet wrapper and never calls
+   * it. Optional on the contract for that reason — `resolveTenantIdentity` throws
+   * a clear error if a non-SDK runtime reaches a driver that lacks it.
+   */
+  getInstanceAppIdentity?(instanceDid: string): Promise<InstanceAppIdentity> | InstanceAppIdentity;
+  /**
+   * The current tenant's business chain wallet (the receiving address + on-chain
+   * tx/refund/payout signer). SYNCHRONOUS — `wallet.address` is read inline on hot
+   * paths — so it reads the warmed per-tenant cache (see warmTenantIdentity), never
+   * an RPC. Present on AUTH_SERVICE-backed drivers (arc-node + CF, derived from
+   * getInstanceAppIdentity); ABSENT on the blocklet-server default, where auth.ts
+   * falls back to the @blocklet/sdk env wallet (which alone handles the remote-sign
+   * / delegation / migration cases a bare appSk cannot). This is the single seam:
+   * a consumer never branches on the runtime, only on "does the driver provide it".
+   */
+  getBusinessWallet?(chain: 'arcblock' | 'ethereum'): WalletObject;
+  /**
+   * The host user directory (`blocklet.getUser` etc.). Present on the arc-node
+   * embedded driver (a DID-echo: the DID-Connect DID IS the wallet DID); ABSENT on
+   * blocklet-server (real BlockletService) and on CF (its build-alias shim). auth.ts
+   * uses `driver.directory?.() ?? <real BlockletService>` — same one-seam pattern.
+   */
+  directory?(): BlockletDirectory;
+}
+
+/** The subset of @blocklet/sdk BlockletService the payment runtime calls. */
+export interface BlockletDirectory {
+  getUser(did: string, opts?: any): Promise<{ user: any }> | { user: any };
+  getUsers(params?: any): Promise<{ users: any[] }> | { users: any[] };
+  getVault(): Promise<any> | any;
+  getBlocklet(): Promise<any> | any;
 }
 
 /**

package/api/src/libs/drivers/index.ts

@@ -33,7 +33,7 @@ export function applyPaymentCoreMigrations(driver: DbDriverForMigrations): Promi
   return applySql(driver, paymentCoreSqlMigrations);
 }
 
-export type { IdentityDriver } from './identity';
+export type { IdentityDriver, InstanceAppIdentity, InstanceAppInfo, BlockletDirectory } from './identity';
 export { createDefaultIdentityDriver, setIdentityDriver, getIdentityDriver } from './identity';
 
 export type { SecretsDriver } from './secrets';

package/api/src/libs/http-fetch-adapter.ts

@@ -37,7 +37,17 @@ export function createFetchHandler(app: Hono): FetchHandler {
       const method = request.method.toUpperCase();
       const hasBody = method !== 'GET' && method !== 'HEAD';
       const body = hasBody ? await request.arrayBuffer() : undefined;
-      return app.fetch(new Request(url.toString(), { method, headers: request.headers, body }));
+      // ③ re-expose the stripped mount prefix as `x-path-prefix` so internal
+      //    absolute-URL builders reconstruct the PUBLIC url. The DID-Connect
+      //    authenticator's wallet callback URL is built by did-connect-js
+      //    `prepareBaseUrl`, which reads `x-path-prefix`; without it the wallet is
+      //    told to call <origin>/api/did/payment/auth instead of
+      //    <origin><basePath>/api/did/payment/auth and the connect times out. The
+      //    Request's headers are immutable, so set it on a fresh Headers; never
+      //    clobber a host-provided value (blocklet-server sets its own mount).
+      const headers = new Headers(request.headers);
+      if (!headers.has('x-path-prefix')) headers.set('x-path-prefix', basePath);
+      return app.fetch(new Request(url.toString(), { method, headers, body }));
     }
 
     // no strip needed — hand the request straight to hono (it owns body parsing).

package/api/src/libs/queue/index.ts

@@ -56,13 +56,25 @@ function injectJobTenant(job: any): any {
  * Phase 5 have no instance_did: single mode falls back to the deployment
  * default, multi mode refuses permanently (non-retryable + structured alert).
  */
+// Warm the tenant identity then run the handler — the queue analogue of the HTTP
+// contextMiddleware warm. Signing queues (payment/refund/payout/...) access the
+// business wallet synchronously; warming inside the tenant span makes `wallet`/
+// `ethWallet` resolve to the job's tenant (no-op on blocklet-server).
+async function warmThenRun<T>(onJob: (job: T) => Promise<any>, job: T): Promise<any> {
+  const { warmTenantIdentity } =
+    // eslint-disable-next-line global-require
+    require('../did-connect/tenant-identity') as typeof import('../did-connect/tenant-identity');
+  await warmTenantIdentity();
+  return onJob(job);
+}
+
 function runJobWithTenant<T>(job: any, onJob: (job: T) => Promise<any>): Promise<any> {
   const tenant = job?.instance_did;
   if (tenant) {
-    return withTenant(tenant, () => onJob(job));
+    return withTenant(tenant, () => warmThenRun(onJob, job));
   }
   if (getTenantMode() === 'single') {
-    return withTenant(getDefaultInstanceDid(), () => onJob(job));
+    return withTenant(getDefaultInstanceDid(), () => warmThenRun(onJob, job));
   }
   const err = new TenantError(TENANT_CONTEXT_MISSING, 'legacy job without tenant refused in multi mode');
   (err as any).nonRetryable = true;

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

@@ -17,6 +17,7 @@ import { translate } from '../../locales';
 import { context } from '../../libs/context';
 import { TenantError, TENANT_HOST_UNRESOLVED } from '../../libs/tenant';
 import { resolveTenantForHost } from '../../libs/drivers/identity';
+import { warmTenantIdentity } from '../../libs/did-connect/tenant-identity';
 
 export function ensureI18n(): MiddlewareHandler {
   return (c, next) => {
@@ -67,6 +68,12 @@ export function contextMiddleware(): MiddlewareHandler {
     }
 
     return context.run({ requestId, requestedBy, instanceDid }, async () => {
+      // Warm the tenant's signing identity (arc/CF dynamic runtime only — no-op on
+      // blocklet-server) so the synchronous business wallet proxies (libs/auth.ts:
+      // `wallet`/`ethWallet`) resolve to THIS tenant's wallet inside the handler.
+      // Best-effort: a request that never touches a wallet is not blocked; one that
+      // does fails-closed at getCachedTenantIdentity.
+      await warmTenantIdentity(instanceDid);
       await next();
     });
   };

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

@@ -13,9 +13,20 @@ import { getCookie, setCookie } from 'hono/cookie';
 import { sign, verify, getCsrfSecret } from '@blocklet/sdk/lib/util/csrf';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { isDidWalletConnect } from '@blocklet/sdk/lib/util/wallet';
+import { readConfig } from '../../libs/env';
 
 const isEmpty = (v: unknown): boolean => v === undefined || v === null || v === '';
 
+// The CSRF secret is HOST-GLOBAL, not per-tenant: this middleware runs BEFORE the
+// tenant context is established (pipeline order cors→xss→csrf→…→context), so it
+// has no instanceDid, and it binds the host-global login_token anyway. An embedded
+// host (arc) that has no BLOCKLET_APP_SK env injects a dedicated secret via the
+// config slot (`PAYMENT_CSRF_SECRET`); the standard blocklet server falls back to
+// the SDK's env-based secret. See docs/architecture/payment-credential-sourcing.md.
+function csrfSecret(): string {
+  return readConfig('PAYMENT_CSRF_SECRET') || getCsrfSecret();
+}
+
 // Express SDK: shouldGenerateToken === GET; shouldVerifyToken === mutating
 // method AND an x-csrf-token cookie already exists AND path is not /mcp AND the
 // caller is not a DID Wallet connect request.
@@ -43,7 +54,7 @@ export function csrf(): MiddlewareHandler {
 
     if (method === 'GET') {
       if (loginToken) {
-        const newCsrf = sign(getCsrfSecret(), loginToken);
+        const newCsrf = sign(csrfSecret(), loginToken);
         if (newCsrf !== existingCsrf) {
           setCookie(c, 'x-csrf-token', newCsrf, { sameSite: 'Strict', secure: true });
         }
@@ -59,7 +70,7 @@ export function csrf(): MiddlewareHandler {
       if (isDidWalletConnect(c.req.header())) return next();
 
       const headerCsrf = c.req.header('x-csrf-token');
-      if (existingCsrf === headerCsrf && verify(getCsrfSecret(), existingCsrf as string, loginToken as string)) {
+      if (existingCsrf === headerCsrf && verify(csrfSecret(), existingCsrf as string, loginToken as string)) {
         return next();
       }
       return c.text('Invalid request: csrf token mismatch, please refresh the page try again', 403);

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

@@ -16,19 +16,14 @@ import type { Model } from 'sequelize';
 import { getVerifyData, verify } from '@blocklet/sdk/lib/util/verify-sign';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { verifyLoginToken } from '@blocklet/sdk/lib/util/verify-session';
-// eslint-disable-next-line import/no-extraneous-dependencies
-import { getWallet } from '@blocklet/sdk/lib/wallet';
 import { isDevelopmentEnv, enableDevFakeAuth } from '../../libs/env';
+// The embed-auth wallet (verifies the embed authToken signature) is the dynamic
+// business wallet (libs/auth.ts): the active tenant's wallet on arc/CF, the env
+// wallet on blocklet-server. The embed branch runs inside the warmed request
+// scope, so synchronous access resolves the tenant wallet.
+import { wallet } from '../../libs/auth';
 import { Customer } from '../../store/models/customer';
 
-// Phase 13b parity: lazy wallet — getWallet() needs BLOCKLET_APP_PK which a bare
-// host lacks; only the embed branch uses it.
-let cachedWallet: ReturnType<typeof getWallet> | undefined;
-const wallet = () => {
-  cachedWallet ??= getWallet();
-  return cachedWallet;
-};
-
 type PermissionSpec<T extends Model> = {
   component?: boolean;
   roles?: string[];
@@ -132,7 +127,7 @@ export function authenticate<T extends Model>({
       // the express version, which does not await next()).
       let embedOk = false;
       try {
-        const w = wallet();
+        const w = wallet;
         const verified = await w.verify(embedId, embedToken);
         if (!verified) {
           return c.json({ error: `Invalid signature for embed: ${embedId}` }, 401);

package/api/src/queues/checkout-session.ts

@@ -5,6 +5,7 @@ import { systemFindAll, systemFindByPk, systemFindOne } from '../store/scoped';
 import { mintNftForCheckoutSession } from '../integrations/arcblock/nft';
 import { ensurePassportIssued } from '../integrations/blocklet/passport';
 import { ensureInvoiceForCheckout } from '../routes/connect/shared';
+import { withTenant } from '../libs/context';
 import dayjs from '../libs/dayjs';
 import { events } from '../libs/event';
 import logger from '../libs/logger';
@@ -89,16 +90,27 @@ export async function startCheckoutSessionQueue() {
     },
   });
 
-  checkoutSessions.forEach(async (checkoutSession) => {
-    const exist = await checkoutSessionQueue.get(checkoutSession.id);
-    if (!exist) {
-      checkoutSessionQueue.push({
-        id: checkoutSession.id,
-        job: { id: checkoutSession.id, action: 'expire' },
-        runAt: checkoutSession.expires_at,
-      });
+  // Per-record tenant context: queue push stamps the job tenant via getInstanceDid,
+  // which fails closed in multi mode without it. for-of + await (not forEach(async),
+  // which leaks an unhandledRejection → FATAL on boot); per-record catch isolates.
+  for (const checkoutSession of checkoutSessions) {
+    const dispatch = async () => {
+      const exist = await checkoutSessionQueue.get(checkoutSession.id);
+      if (!exist) {
+        checkoutSessionQueue.push({
+          id: checkoutSession.id,
+          job: { id: checkoutSession.id, action: 'expire' },
+          runAt: checkoutSession.expires_at,
+        });
+      }
+    };
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await (checkoutSession.instance_did ? withTenant(checkoutSession.instance_did, dispatch) : dispatch());
+    } catch (error) {
+      logger.error('startCheckoutSessionQueue: re-queue failed', { id: checkoutSession.id, error });
     }
-  });
+  }
 }
 
 checkoutSessionQueue.on('failed', ({ id, job, error }) => {

package/api/src/queues/event.ts

@@ -2,6 +2,7 @@ import { Op } from 'sequelize';
 import { isCfWorker } from '../libs/env';
 import { systemFindAll, systemFindByPk } from '../store/scoped';
 
+import { withTenant } from '../libs/context';
 import { events } from '../libs/event';
 import logger from '../libs/logger';
 import createQueue from '../libs/queue';
@@ -83,22 +84,43 @@ export const eventQueue = createQueue<EventJob>({
 });
 
 export const startEventQueue = async () => {
+  // Cross-tenant recovery scan: fetch instance_did too so the recovered push
+  // carries its tenant. In multi mode startup runs with NO tenant context, so a
+  // push without instance_did would hit injectJobTenant -> getInstanceDid ->
+  // TENANT_CONTEXT_MISSING (a FATAL unhandledRejection from the async forEach
+  // below). The handler re-derives the tenant from the row, but the PUSH itself
+  // must already be tenant-stamped to survive multi mode.
   const docs = await systemFindAll(Event, {
     where: {
       pending_webhooks: { [Op.gt]: 0 },
     },
-    attributes: ['id'],
+    attributes: ['id', 'instance_did'],
   });
 
   logger.info(`Found ${docs.length} events with pending webhooks`);
 
-  docs.forEach(async (x) => {
-    const exist = await eventQueue.get(x.id);
-    if (!exist) {
-      logger.info(`Pushing event ${x.id} to queue`);
-      eventQueue.push({ id: x.id, job: { eventId: x.id }, persist: false });
+  // Sequential + per-doc try/catch: one bad row must never crash startup
+  // recovery (await in the original forEach left rejections unhandled). The
+  // push runs inside withTenant(event.instance_did) so injectJobTenant stamps
+  // the correct tenant — in multi mode there is no ambient context at startup.
+  for (const x of docs) {
+    if (!x.instance_did) {
+      logger.warn('skip pending-webhook event with no tenant', { id: x.id });
+    } else {
+      try {
+        // eslint-disable-next-line no-await-in-loop -- bounded startup recovery
+        await withTenant(x.instance_did, async () => {
+          const exist = await eventQueue.get(x.id);
+          if (!exist) {
+            logger.info(`Pushing event ${x.id} to queue`);
+            eventQueue.push({ id: x.id, job: { eventId: x.id }, persist: false });
+          }
+        });
+      } catch (error) {
+        logger.error('failed to recover pending-webhook event', { id: x.id, error });
+      }
     }
-  });
+  }
 
   logger.info('Finished starting event queue');
 };