payment-kit 1.29.2 → 1.29.4

package/api/src/bootstrap.ts

@@ -9,7 +9,9 @@
 
 import logger from './libs/logger';
 import { getDefaultInstanceDid, getTenantMode } from './libs/tenant';
+import { createBlockletServerDidConnectRuntime } from './libs/auth';
 import { createEmbeddedPaymentService, type EmbeddedPaymentService } from './service';
+import { attachNodeStatic } from './host-node/serve-static';
 import { sequelize } from './store/sequelize';
 import { blockletPort } from './libs/env';
 
@@ -23,6 +25,15 @@ export function buildService(): { service: EmbeddedPaymentService; port: number
     config: { ...process.env }, // Phase 12 narrows this to an explicit schema
     db: { sequelize },
     tenancy,
+    // S3-CF Phase 1 ①: the blocklet-server host owns static/SPA serving (moved out
+    // of the runtime-neutral buildHonoApp). attachNodeStatic is production-gated, so
+    // dev (this same bootstrap) is unaffected — identical to the prior behavior.
+    staticHandler: attachNodeStatic,
+    // S3-CF (DID convergence): blocklet-server is the ONE host that uses the
+    // @blocklet/sdk DID-Connect wrapper (autoConnect / notification relay /
+    // federated login). Injected explicitly via the same host-injection entry as
+    // CF/arc-node — not relied on as an implicit libs/auth default.
+    didConnectRuntime: createBlockletServerDidConnectRuntime(),
   });
 
   const port = parseInt(blockletPort()!, 10);

package/api/src/crons/index.ts

@@ -34,6 +34,7 @@ import { CheckoutSession } from '../store/models';
 import { createOverdueDetection } from './overdue-detection';
 import { createPaymentStat } from './payment-stat';
 import { retryPendingEvents } from './retry-pending-events';
+import { perTenant } from './tenant-fanout';
 import { SubscriptionTrialWillEndSchedule } from './subscription-trial-will-end';
 import { SubscriptionWillCanceledSchedule } from './subscription-will-canceled';
 import { SubscriptionWillRenewSchedule } from './subscription-will-renew';
@@ -72,19 +73,19 @@ function init() {
       {
         name: 'subscription.will.renew',
         time: notificationCronTime(),
-        fn: () => new SubscriptionWillRenewSchedule().run(),
+        fn: perTenant('subscription.will.renew', () => new SubscriptionWillRenewSchedule().run()),
         options: { runOnInit: true },
       },
       {
         name: 'subscription.trial.will.end',
         time: notificationCronTime(),
-        fn: () => new SubscriptionTrialWillEndSchedule().run(),
+        fn: perTenant('subscription.trial.will.end', () => new SubscriptionTrialWillEndSchedule().run()),
         options: { runOnInit: true },
       },
       {
         name: 'customer.subscription.will_canceled',
         time: notificationCronTime(),
-        fn: () => new SubscriptionWillCanceledSchedule().run(),
+        fn: perTenant('customer.subscription.will_canceled', () => new SubscriptionWillCanceledSchedule().run()),
         options: { runOnInit: true },
       },
       {
@@ -105,34 +106,34 @@ function init() {
       {
         name: 'checkoutSession.cleanup.expired',
         time: expiredSessionCleanupCronTime(),
-        fn: async () => {
+        fn: perTenant('checkoutSession.cleanup.expired', async () => {
           const removedCount = await CheckoutSession.cleanupExpiredSessions();
           logger.info('CheckoutSession.cleanupExpiredSessions', { removedCount });
-        },
+        }),
         options: { runOnInit: true },
       },
       {
         name: 'stripe.invoice.sync',
         time: stripeInvoiceCronTime(),
-        fn: batchHandleStripeInvoices,
+        fn: perTenant('stripe.invoice.sync', batchHandleStripeInvoices),
         options: { runOnInit: false },
       },
       {
         name: 'stripe.payment.sync',
         time: stripePaymentCronTime(),
-        fn: batchHandleStripePayments,
+        fn: perTenant('stripe.payment.sync', batchHandleStripePayments),
         options: { runOnInit: false },
       },
       {
         name: 'stripe.subscription.sync',
         time: stripeSubscriptionCronTime(),
-        fn: batchHandleStripeSubscriptions,
+        fn: perTenant('stripe.subscription.sync', batchHandleStripeSubscriptions),
         options: { runOnInit: false },
       },
       {
         name: 'customer.stake.revoked',
         time: revokeStakeCronTime(),
-        fn: checkStakeRevokeTx,
+        fn: perTenant('customer.stake.revoked', checkStakeRevokeTx),
         options: { runOnInit: false },
       },
       {
@@ -141,7 +142,7 @@ function init() {
         // webhook missed). See blocklets/core/api/src/integrations/iap-reconcile.ts.
         name: 'iap.reconcile',
         time: iapReconcileCronTime(),
-        fn: () => runIapReconcile(),
+        fn: perTenant('iap.reconcile', () => runIapReconcile()),
         options: { runOnInit: false },
       },
       {
@@ -150,19 +151,19 @@ function init() {
         // See blocklets/core/api/src/crons/retry-pending-events.ts.
         name: 'event.retry',
         time: eventRetryCronTime(),
-        fn: () => retryPendingEvents(),
+        fn: perTenant('event.retry', () => retryPendingEvents()),
         options: { runOnInit: false },
       },
       {
         name: 'payment.stat',
         time: paymentStatCronTime(),
-        fn: () => createPaymentStat(),
+        fn: perTenant('payment.stat', () => createPaymentStat()),
         options: { runOnInit: false },
       },
       {
         name: 'payment.daily.report',
         time: overdueDetectionCronTime(),
-        fn: () => createOverdueDetection(),
+        fn: perTenant('payment.daily.report', () => createOverdueDetection()),
         options: { runOnInit: false },
       },
       {

package/api/src/crons/tenant-fanout.ts

@@ -0,0 +1,82 @@
+// Multi-tenant cron fan-out (S3 arc-payment-embed — Phase 7).
+//
+// Background crons that issue a top-level tenant-scoped model query
+// (subscription schedules, reconciliation, payment stat, overdue detection,
+// stake-revoke, expired-session cleanup, stripe sync, event retry) have NO
+// request to carry a tenant. In multi mode `getInstanceDid()` throws
+// TENANT_CONTEXT_MISSING and the whole pass does nothing. Single mode is
+// unaffected — the default tenant auto-resolves.
+//
+// Tenant enumeration is SELF-CONTAINED (decision 2026-06-13): payment-core owns
+// its own scope, so we iterate the tenants that have payment configuration in
+// OUR OWN store (`provisionTenant` seeds a PaymentMethod row per tenant) rather
+// than asking the host for a registry. A tenant with no payment rows has
+// nothing for these crons to do, and this fits a lazily-provisioned host
+// (arc-node) where a tenant appears in payment.db only after its first request.
+//
+// Queue-starter crons (startXQueue) are NOT wrapped: each persisted job already
+// carries its own instance_did and runs inside withTenant(job.tenant) via the
+// queue runtime (libs/queue runJobWithTenant). Wrapping them would re-scan and
+// double-process.
+
+import { withTenant } from '../libs/context';
+import logger from '../libs/logger';
+import { getTenantMode } from '../libs/tenant';
+import { systemFindAll } from '../store/scoped';
+
+/**
+ * Tenants that have payment configuration in payment-core's own store. Reads
+ * across tenants (systemFindAll runs inside runAsSystem so the TenantModel base
+ * does not re-scope to a — here absent — active tenant). DISTINCT is done in JS
+ * to stay compatible with both real Sequelize and the worker's sequelize-d1
+ * shim. PaymentMethod is the canonical "provisioned tenant" marker; a tenant
+ * that has any payment data necessarily has a payment method.
+ */
+export async function listProvisionedTenants(): Promise<string[]> {
+  // eslint-disable-next-line global-require
+  const { PaymentMethod } = require('../store/models');
+  // raw:true returns plain rows, not Model instances — cast through unknown.
+  const rows = (await systemFindAll(PaymentMethod, {
+    attributes: ['instance_did'],
+    raw: true,
+  })) as unknown as Array<{ instance_did?: string | null }>;
+  const dids = new Set<string>();
+  for (const row of rows) {
+    if (row?.instance_did) dids.add(row.instance_did);
+  }
+  return [...dids];
+}
+
+/**
+ * Wrap a tenant-scoped cron fn so it runs once per provisioned tenant inside
+ * `withTenant`. Single mode runs the fn as-is (the default tenant auto-resolves
+ * in getInstanceDid). Multi mode enumerates provisioned tenants and runs the fn
+ * per tenant; per-tenant errors are ISOLATED (caught + logged) so one tenant's
+ * failure never aborts the rest of the pass.
+ *
+ * @param listTenants enumeration seam (defaults to listProvisionedTenants;
+ *   injected in tests so the fan-out logic is exercised without a DB).
+ */
+export function perTenant(
+  name: string,
+  fn: () => Promise<unknown> | unknown,
+  listTenants: () => Promise<string[]> = listProvisionedTenants
+): () => Promise<void> {
+  return async () => {
+    if (getTenantMode() === 'single') {
+      await fn();
+      return;
+    }
+    const dids = await listTenants();
+    if (dids.length === 0) return;
+    logger.info('cron.tenant.fanout', { cron: name, tenantCount: dids.length });
+    for (const instanceDid of dids) {
+      // async callback so a SYNCHRONOUS throw from fn surfaces as a rejection
+      // (and stays inside the tenant's ALS scope) — then .catch isolates it.
+      // eslint-disable-next-line no-await-in-loop, require-await -- sequential per-tenant pass; async wraps sync throws
+      await withTenant(instanceDid, async () => fn()).catch((error: unknown) =>
+        logger.error('cron tenant pass failed', { cron: name, instanceDid, error })
+      );
+    }
+  };
+}

package/api/src/host-node/did-connect-runtime-node.ts

@@ -0,0 +1,33 @@
+// Node host adapter — the AUTH_SERVICE-backed DID-Connect runtime for the
+// arc-node embedded host. The node analog of cloudflare/did-connect-runtime.ts:
+// the shared @arcblock/did-connect-js runtime whose signing wallet/appInfo are
+// resolved per-tenant via resolveTenantIdentity (getInstanceAppIdentity), NOT a
+// fixed isolate key.
+//
+// Without this, a bare host falls back to createBlockletServerDidConnectRuntime,
+// whose WalletAuthenticator is constructed with `makeWallet()` (env BLOCKLET_APP_SK)
+// — which arc never sets — so the first DID-Connect sign (e.g. /api/did/payment/token
+// → generateSession) throws "Missing public key for SK wallet: BLOCKLET_APP_PK".
+//
+// Differences from the CF runtime are node-only:
+//   - txEncoder = the @ocap/client/encode CBOR encoder (same one the
+//     blocklet-server runtime passes), resolved from the host's node_modules.
+//   - tokenStorage omitted → buildTokenStorage's file-backed nedb default
+//     (os.tmpdir on a bare host; DID-Connect session tokens are ephemeral).
+//   - chainInfo omitted → the 14 payment DID handlers resolve it per-payment in
+//     onConnect, exactly as the blocklet-server runtime (which passes none).
+import type { DidConnectRuntime, DidConnectTokenStorage } from '../libs/auth';
+import { createDidConnectJsRuntime } from '../libs/did-connect/runtime-did-connect-js';
+
+export function createNodeDidConnectRuntime(opts?: {
+  tokenStorage?: DidConnectTokenStorage;
+  timeout?: number;
+}): DidConnectRuntime {
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const { createTxEncoder } = require('@ocap/client/encode');
+  return createDidConnectJsRuntime({
+    tokenStorage: opts?.tokenStorage,
+    txEncoder: createTxEncoder(),
+    timeout: opts?.timeout ?? 30000,
+  });
+}

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

@@ -0,0 +1,68 @@
+// P3b (README D3 / F3) — clean node static + SPA handler for embedded hosts (arc).
+//
+// Unlike `attachNodeStatic` (serve-static.ts), this is NOT blocklet-server bound:
+//   - no isProduction gate, no blockletAppDir (host passes an explicit webRoot)
+//   - does NOT reuse the @blocklet/sdk-bound `fallback` middleware, which injects
+//     getBlockletJs / theme server-side. This handler serves index.html VERBATIM
+//     — the window.blocklet bootstrap is already baked in at BUILD time (P2), so
+//     there is ZERO server-side injection (T3b.3).
+//
+// Wired via the host `staticHandler` slot (P3a / service.ts:81), AFTER the
+// api/connect routes. Order (T3b.1): SPA fallback FIRST (html GET/HEAD that is
+// not a RESOURCE_PATTERN asset → index.html), serveStatic AFTER (real asset
+// files; a miss falls through to 404, never index.html — T3b.2).
+import fs from 'fs';
+import path from 'path';
+
+import type { Hono } from 'hono';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { RESOURCE_PATTERN } from '@blocklet/constant';
+
+function acceptsHtml(accept: string): boolean {
+  if (!accept) return true;
+  return accept.includes('text/html') || accept.includes('application/xhtml+xml') || accept.includes('*/*');
+}
+
+/**
+ * Build a host-injectable static/SPA handler over `webRoot` (the arc webRoot =
+ * `@arcblock/payment-service/web`). Returns a `(app) => void` for the
+ * staticHandler slot. Throws at construction if webRoot has no index.html
+ * (fail fast — a misconfigured webRoot must not silently 404 every navigation).
+ */
+export function createNodeStaticHandler(webRoot: string): (app: Hono) => void {
+  const indexPath = path.join(webRoot, 'index.html');
+  if (!fs.existsSync(indexPath)) {
+    throw new Error(`createNodeStaticHandler: webRoot has no index.html: ${indexPath}`);
+  }
+  // index.html is an immutable build artifact for the process lifetime — read once.
+  let cachedIndex: string | null = null;
+
+  return (app: Hono) => {
+    // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+    const { serveStatic } = require('@hono/node-server/serve-static');
+
+    // SPA fallback FIRST — html navigations (not assets) get index.html VERBATIM.
+    app.use('*', async (c, next) => {
+      const method = c.req.method.toUpperCase();
+      if (
+        (method !== 'GET' && method !== 'HEAD') ||
+        !acceptsHtml(c.req.header('accept') || '') ||
+        RESOURCE_PATTERN.test(c.req.path)
+      ) {
+        return next();
+      }
+      if (cachedIndex == null) cachedIndex = fs.readFileSync(indexPath, 'utf8');
+      return c.html(cachedIndex);
+    });
+
+    // Real asset files. Pass the ABSOLUTE webRoot: serveStatic does
+    // `join(root, filename)` + existsSync, so an absolute root resolves the file
+    // regardless of process.cwd(). (attachNodeStatic mapped to a cwd-relative
+    // path; that breaks in an embedded host whose cwd is not the app dir — e.g.
+    // the arc daemon, whose cwd ≠ the node_modules webRoot.) A miss falls
+    // through (→ 404).
+    app.use('*', serveStatic({ root: webRoot }));
+  };
+}
+
+export default createNodeStaticHandler;

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

@@ -0,0 +1,41 @@
+// Node host (blocklet-server) static + SPA serving.
+//
+// S3-CF Phase 1 inversion ①: this is the node-only static/SPA shell that used to
+// live INSIDE buildHonoApp (service.ts). It is moved here so the runtime-neutral
+// hono app carries ZERO node:fs / @hono/node-server — that is what let `http.fetch`
+// converge to a single surface shared by node, CF, and the standalone worker.
+//
+// The blocklet-server entry (bootstrap.ts) injects this as the `staticHandler`
+// slot. It is a verbatim move of the old block (serveStatic + the node:fs
+// fallback), still production-gated, so blocklet-server behavior is unchanged. The
+// CF/standalone worker serves assets via env.ASSETS and injects nothing here, so
+// this module is never reached by the worker bundle.
+import path from 'path';
+
+import type { Hono } from 'hono';
+
+import { isProduction, blockletAppDir } from '../libs/env';
+
+/**
+ * Wire production static + SPA fallback onto the full node hono app. No-op outside
+ * production (identical to the old `if (isProduction())` gate in buildHonoApp).
+ *
+ * `fallback` runs first and skips asset paths (RESOURCE_PATTERN) + non-html, so
+ * real files fall through to serveStatic and html navigations get the injected
+ * index.html. Both modules are required lazily so this file's import stays cheap.
+ */
+export function attachNodeStatic(app: Hono): void {
+  if (!isProduction()) return;
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const { serveStatic } = require('@hono/node-server/serve-static');
+  // eslint-disable-next-line global-require
+  const { fallback } = require('../middlewares/hono/fallback');
+  const staticDir = path.resolve(blockletAppDir()!, 'dist');
+  // serveStatic resolves `root` relative to process.cwd(); map the absolute app
+  // dist dir back to a cwd-relative path so it resolves to the same place.
+  const staticRoot = path.relative(process.cwd(), staticDir) || '.';
+  app.use('*', fallback('index.html', { root: staticDir })); // injected index.html for html GET (skips assets)
+  app.use('*', serveStatic({ root: staticRoot })); // real asset files
+}
+
+export default attachNodeStatic;

package/api/src/libs/auth.ts

@@ -1,8 +1,10 @@
+import os from 'os';
 import path from 'path';
 
 import type { LiteralUnion } from 'type-fest';
 import type { WalletObject } from '@ocap/wallet';
 import env, { blockletAppId } from './env';
+import { getIdentityDriver } from './drivers';
 
 import logger from './logger';
 
@@ -91,42 +93,179 @@ function makeWallet(...args: any[]): WalletObject {
   return getWallet(...args);
 }
 
-export const wallet: WalletObject = lazyProxy(() => makeWallet());
-export const ethWallet: WalletObject = lazyProxy(() => makeWallet('ethereum'));
+// The blocklet-server business wallets — env-derived (BLOCKLET_APP_SK), lazy as
+// before. They are the FALLBACK when the active IdentityDriver provides no
+// getBusinessWallet (blocklet-server / tests); the @blocklet/sdk getWallet alone
+// handles the remote-sign / delegation / migration cases a bare appSk cannot.
+const envWallet: WalletObject = lazyProxy(() => makeWallet());
+const envEthWallet: WalletObject = lazyProxy(() => makeWallet('ethereum'));
 
-// Workaround for migrated blocklets where `BLOCKLET_APP_SK` is a rotating session
-// key whose derived address ≠ appId. Upstream @blocklet/sdk's WalletAuthenticator
-// passes `wallet: getWallet()` to did-connect-js, so outer.agentDid becomes that
-// rotating address. Meanwhile the federated cert (signed by master) sets
-// agentDid = `did:abt:${verifySite.appId}` (permanent), so the wallet-side strict
-// check `cert.agentDid === outer.agentDid` fails with "Agent did does not match
-// with certificate issuer."
+// THE SINGLE SEAM (wallet-authenticator-dynamic.md §0 — "差异收敛在 IdentityDriver"):
+// the active business wallet is whatever the active IdentityDriver provides, else
+// the env wallet. arc-node + CF inject a driver whose getBusinessWallet resolves the
+// current request/job tenant's wallet from the warmed cache (fail-closed outside a
+// warmed scope); blocklet-server's default driver provides none → env wallet,
+// unchanged. No consumer branches on the runtime — only on driver capability. The
+// driver is consulted on EVERY access so two concurrent tenants never share a wallet.
+function activeBusinessWallet(chain: 'arcblock' | 'ethereum'): WalletObject {
+  const driver = getIdentityDriver();
+  if (typeof driver.getBusinessWallet === 'function') {
+    return driver.getBusinessWallet(chain);
+  }
+  return chain === 'ethereum' ? envEthWallet : envWallet;
+}
+
+/** Per-access proxy onto the active tenant's business wallet (see activeBusinessWallet). */
+function businessWalletProxy(chain: 'arcblock' | 'ethereum'): WalletObject {
+  return new Proxy({} as WalletObject, {
+    get(_t, prop) {
+      const w = activeBusinessWallet(chain) as any;
+      const value = w[prop];
+      if (typeof value !== 'function') return value;
+      if (value._isMockFunction) return value; // keep jest spies usable (parity with lazyProxy)
+      return value.bind(w);
+    },
+    set(_t, prop, value) {
+      (activeBusinessWallet(chain) as any)[prop] = value;
+      return true;
+    },
+    has(_t, prop) {
+      return prop in (activeBusinessWallet(chain) as any);
+    },
+  });
+}
+
+export const wallet: WalletObject = businessWalletProxy('arcblock');
+export const ethWallet: WalletObject = businessWalletProxy('ethereum');
+
+// S3-CF Phase 1 (DID convergence): the DID-Connect token storage is a host slot.
+export interface DidConnectTokenStorage {
+  read(token: string): Promise<any> | any;
+  create(token: string, status?: string): Promise<any> | any;
+  update(token: string, updates: Record<string, any>): Promise<any> | any;
+  delete(token: string): Promise<any> | any;
+  [key: string]: any;
+}
+
+// S3-CF Phase 1 (DID convergence) — the DID-Connect RUNTIME is host-injectable.
 //
-// Force the authenticator to derive its signing wallet from BLOCKLET_APP_PK
-// (permanent app pk → address = appId), aligning with the fix in
-// @blocklet/sdk PR #12810 that already corrected getDelegatee.
-export const authenticator: any = lazyProxy(() => {
-  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
-  const { WalletAuthenticator } = require('@blocklet/sdk/lib/wallet-authenticator');
-  return new WalletAuthenticator({ wallet: makeWallet(undefined, '', 'sk') });
-});
+// The boundary is by HOST, not by node-vs-CF:
+//   - blocklet-server         → the @blocklet/sdk WalletAuthenticator/WalletHandlers
+//                               wrapper (autoConnect / notification relay /
+//                               federated login). The ONLY runtime that uses SDK.
+//   - arc-node embedded + CF  → the REAL @arcblock/did-connect-js stack, identity
+//                               from AUTH_SERVICE.getInstanceAppIdentity, host-
+//                               injected tokenStorage. They differ ONLY in the host
+//                               adapter (storage/DB/event/waitUntil, CF chain
+//                               config/txEncoder/timeout), NOT in SDK-vs-non-SDK.
+// Unified = the host-injection + identity-resolution mechanism; SDK is one runtime
+// implementation, not the node default. Every host injects via setDidConnectRuntime
+// BEFORE `handlers` first materializes (lazyProxy → buildConnectRoutesHono).
+export interface DidConnectRuntime {
+  /** Build the DID-Connect authenticator (signs sessions/certs). */
+  createAuthenticator(): any;
+  /** Wrap the authenticator + tokenStorage into the WalletHandlers used to attach routes. */
+  createHandlers(opts: { authenticator: any; tokenStorage: DidConnectTokenStorage }): any;
+  /** The DID-Connect token store; falls back to the blocklet-server nedb default when omitted. */
+  tokenStorage?: DidConnectTokenStorage;
+}
 
-export const handlers: any = lazyProxy(() => {
+let injectedRuntime: DidConnectRuntime | null = null;
+let injectedTokenStorage: DidConnectTokenStorage | null = null;
+
+/** Inject the full DID-Connect runtime (CF: real @arcblock/did-connect-js stack). */
+export function setDidConnectRuntime(runtime: DidConnectRuntime | null): void {
+  injectedRuntime = runtime;
+}
+
+/** Inject only the DID-Connect token storage (storage slot; runtime keeps its default authenticator/handlers). */
+export function setDidConnectTokenStorage(storage: DidConnectTokenStorage | null): void {
+  injectedTokenStorage = storage;
+}
+
+// The blocklet-server runtime — the ONLY runtime that uses the @blocklet/sdk
+// wallet wrapper (autoConnect / notification relay / memberAppInfo / federated
+// login / BlockletService). This is NOT "the node default": arc-node embedded and
+// CF use the AUTH_SERVICE + @arcblock/did-connect-js runtime instead. The
+// blocklet-server bootstrap injects this explicitly; it is also the legacy
+// fallback when no runtime is injected (tests / a bare blocklet-server start).
+//
+// The signing wallet is derived from BLOCKLET_APP_PK (permanent app pk → address =
+// appId) to fix the migrated-blocklet rotating-session-key cert mismatch
+// ("Agent did does not match with certificate issuer", @blocklet/sdk PR #12810).
+export function createBlockletServerDidConnectRuntime(): DidConnectRuntime {
+  return {
+    createAuthenticator() {
+      // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+      const { WalletAuthenticator } = require('@blocklet/sdk/lib/wallet-authenticator');
+      // @blocklet/sdk bundles @arcblock/did-connect-js@4.0.2, which made `txEncoder`
+      // mandatory for encoding *Tx prepareTx claims (scan-to-pay → TransferV3Tx) and
+      // dropped the old internal @ocap/client fallback (now only a devDependency; the
+      // shipped dist never requires it). The SDK's WalletAuthenticator wrapper does not
+      // inject one, so we pass the same CBOR encoder the CF/arc runtime uses
+      // (`createTxEncoder` from @ocap/client/encode). It passes through the wrapper's
+      // `...getAuthenticatorProps(options)` spread untouched.
+      // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+      const { createTxEncoder } = require('@ocap/client/encode');
+      return new WalletAuthenticator({ wallet: makeWallet(undefined, '', 'sk'), txEncoder: createTxEncoder() });
+    },
+    createHandlers({ authenticator: auth, tokenStorage }) {
+      // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+      const { WalletHandlers } = require('@blocklet/sdk/lib/wallet-handler');
+      return new WalletHandlers({ authenticator: auth, tokenStorage });
+    },
+  };
+}
+
+// Consume the injected runtime. When none is injected we fall back to the
+// blocklet-server (SDK) runtime as a LEGACY compat for a bare blocklet-server /
+// test start — NOT as a generic node default. CF and arc-node embedded hosts MUST
+// inject their AUTH_SERVICE runtime; if a CF host ever reaches this fallback, the
+// workerd @blocklet/sdk wallet-* shims are fail-fast (they throw on construct), so
+// it can never silently register zero DID routes. (A spec also asserts the
+// AUTH_SERVICE runtime never imports the @blocklet/sdk wallet modules.)
+function activeRuntime(): DidConnectRuntime {
+  return injectedRuntime ?? createBlockletServerDidConnectRuntime();
+}
+
+function buildTokenStorage(): DidConnectTokenStorage {
+  // priority: runtime-provided store → explicit storage slot → blocklet-server
+  // nedb default (file-backed; the node blocklet-server host only).
+  if (injectedRuntime?.tokenStorage) return injectedRuntime.tokenStorage;
+  if (injectedTokenStorage) return injectedTokenStorage;
   // eslint-disable-next-line global-require, import/no-extraneous-dependencies
   const AuthStorage = require('@arcblock/did-connect-storage-nedb');
-  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
-  const { WalletHandlers } = require('@blocklet/sdk/lib/wallet-handler');
-  return new WalletHandlers({
-    authenticator,
-    tokenStorage: new AuthStorage({
-      dbPath: path.join(env.dataDir, 'auth.db'),
-      // @ts-ignore
-      onload: console.warn,
-    }),
+  return new AuthStorage({
+    // `env.dataDir` (the blocklet runtime data dir) is undefined in a bare
+    // embedded host like arc — `store/sequelize.ts` already guards its own
+    // use, but this DID-Connect token store was the one unguarded path and
+    // crashed `buildConnectRoutesHono` with `path.join(undefined, …)`. Fall
+    // back to the OS temp dir (DID-Connect session tokens are ephemeral; the
+    // blocklet server still gets its real dataDir natively).
+    dbPath: path.join(env.dataDir || os.tmpdir(), 'auth.db'),
+    // @ts-ignore
+    onload: console.warn,
   });
+}
+
+export const authenticator: any = lazyProxy(() => activeRuntime().createAuthenticator());
+
+export const handlers: any = lazyProxy(() => {
+  const tokenStorage = buildTokenStorage();
+  return activeRuntime().createHandlers({ authenticator, tokenStorage });
 });
 
+// The user directory (`blocklet.getUser` etc.). SAME single seam as the wallet:
+// the active IdentityDriver's `directory()` if it provides one, else the real
+// @blocklet/sdk BlockletService. arc-node injects a DID-echo directory (the real
+// BlockletService can't construct without BLOCKLET_APP_ID); CF resolves the real
+// BlockletService to its build-alias shim; blocklet-server gets the real one. No
+// `isCfWorker`/runtime branch — only "does the driver provide a directory".
 export const blocklet: any = lazyProxy(() => {
+  const driver = getIdentityDriver();
+  if (typeof driver.directory === 'function') {
+    return driver.directory();
+  }
   ensureNotificationPatch();
   // eslint-disable-next-line global-require, import/no-extraneous-dependencies
   const { BlockletService } = require('@blocklet/sdk/service/auth');

package/api/src/libs/context.ts

@@ -63,6 +63,17 @@ class RequestContextManager {
     throw new TenantError(TENANT_CONTEXT_MISSING, 'tenant context is missing in multi-tenant mode');
   }
 
+  /**
+   * Non-throwing peek at the established tenant context — returns the stored
+   * instanceDid or undefined when no context is set (regardless of tenant mode).
+   * Used by the DID-Connect tenant-context middleware to decide whether the
+   * request is already scoped (e.g. the CF worker wrapped /api/* in withTenant) or
+   * needs its own Host→tenant resolution.
+   */
+  peekInstanceDid(): string | undefined {
+    return this.storage.getStore()?.instanceDid;
+  }
+
   /**
    * 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.