payment-kit 1.29.1 → 1.29.3

package/api/src/libs/audit.ts

@@ -5,9 +5,58 @@ import type { EventType } from '../store/models';
 import { Event } from '../store/models/event';
 import { events } from './event';
 import { context } from './context';
+import logger from './logger';
+import { TENANT_CONTEXT_MISSING, TENANT_MISMATCH, TenantError } from './tenant';
 
 const API_VERSION = '2023-09-05';
 
+/**
+ * Phase 4 (W1-3): tenant of an event, fail-closed.
+ * Order: model.instance_did, then TenantContext. Both missing or mutually
+ * contradictory -> reject. The rejection only kills the EVENT (the business
+ * transaction that triggered the hook is never blocked — see
+ * reportAuditFailure and the fire-and-forget catch sites in store/models).
+ */
+function resolveEventTenant(model?: { instance_did?: string | null } | null): string {
+  const fromModel = model?.instance_did || undefined;
+  // the EXPLICIT context tenant (withTenant), not the single-mode default
+  // fill — otherwise every model row of a non-default tenant would falsely
+  // conflict with the deployment app DID in single mode
+  const explicitContext = context.getContext().instanceDid || undefined;
+  if (fromModel && explicitContext && fromModel !== explicitContext) {
+    throw new TenantError(
+      TENANT_MISMATCH,
+      `event tenant conflict: model carries ${fromModel} but context is ${explicitContext}`
+    );
+  }
+  const tenant = fromModel || explicitContext;
+  if (tenant) return tenant;
+  // neither source explicit: single mode falls back to the app DID,
+  // multi mode fails closed
+  return context.getInstanceDid();
+}
+
+/**
+ * Create an event row under its resolved tenant. The event belongs to the
+ * model's tenant, which may differ from the ambient context (e.g. a system /
+ * cross-tenant path acting on another tenant's row). Now that Event extends
+ * TenantModel, the create must run under that tenant so stampTenant stamps the
+ * matching instance_did instead of rejecting the explicit one as a conflict.
+ */
+function createEventUnderTenant(instanceDid: string, values: any): Promise<any> {
+  return context.withTenant(instanceDid, () => Event.create(values));
+}
+
+/**
+ * Structured fire-and-forget alert for failed event creation. Tenant
+ * rejections keep their dedicated codes so monitoring/tests can assert them;
+ * everything else is EVENT_CREATE_FAILED. Mode-independent and never throws.
+ */
+export function reportAuditFailure(err: any): void {
+  const code = err?.code === TENANT_MISMATCH || err?.code === TENANT_CONTEXT_MISSING ? err.code : 'EVENT_CREATE_FAILED';
+  logger.error('[audit] event creation failed', { code, message: err?.message || String(err) });
+}
+
 /**
  * Invoke every registered listener for `eventName` and await any Promise
  * results. EventEmitter.emit() returns sync — listener async work would
@@ -58,6 +107,7 @@ export function createEvent(
 }
 
 async function doCreateEvent(scope: string, type: LiteralUnion<EventType, string>, model: any, options: any = {}) {
+  const instanceDid = resolveEventTenant(model);
   const data: any = {
     object: model.dataValues,
   };
@@ -65,8 +115,9 @@ async function doCreateEvent(scope: string, type: LiteralUnion<EventType, string
     data.previous_attributes = pick(model._previousDataValues, options.fields);
   }
 
-  const event = await Event.create({
+  const event = await createEventUnderTenant(instanceDid, {
     type,
+    instance_did: instanceDid,
     api_version: API_VERSION,
     livemode: !!model.livemode,
     object_id: model.id,
@@ -113,8 +164,10 @@ export async function createStatusEvent(
   }
 
   const suffix = config[data.object.status];
-  const event = await Event.create({
+  const instanceDid = resolveEventTenant(model);
+  const event = await createEventUnderTenant(instanceDid, {
     type: [prefix, suffix].join('.'),
+    instance_did: instanceDid,
     api_version: API_VERSION,
     livemode: !!model.livemode,
     object_id: model.id,
@@ -150,8 +203,10 @@ export async function createCustomEvent(
     return;
   }
 
-  const event = await Event.create({
+  const instanceDid = resolveEventTenant(model);
+  const event = await createEventUnderTenant(instanceDid, {
     type: [prefix, suffix].join('.'),
+    instance_did: instanceDid,
     api_version: API_VERSION,
     livemode: !!model.livemode,
     object_id: model.id,
@@ -185,9 +240,11 @@ export async function createFlexibleEvent(
   } = {}
 ) {
   const { livemode = false, requestedBy, metadata = {} } = options;
+  const instanceDid = resolveEventTenant(null);
 
-  const event = await Event.create({
+  const event = await createEventUnderTenant(instanceDid, {
     type,
+    instance_did: instanceDid,
     api_version: API_VERSION,
     livemode,
     object_id: objectId,

package/api/src/libs/auth.ts

@@ -1,18 +1,53 @@
+import os from 'os';
 import path from 'path';
 
-import AuthStorage from '@arcblock/did-connect-storage-nedb';
-// @ts-ignore
-import { BlockletService } from '@blocklet/sdk/service/auth';
-import { getWallet, getAccessWallet } from '@blocklet/sdk/lib/wallet';
-import { WalletAuthenticator } from '@blocklet/sdk/lib/wallet-authenticator';
-import { WalletHandlers } from '@blocklet/sdk/lib/wallet-handler';
-import type { Request } from 'express';
 import type { LiteralUnion } from 'type-fest';
 import type { WalletObject } from '@ocap/wallet';
+import env, { blockletAppId } from './env';
+import { getIdentityDriver } from './drivers';
 
-import env from './env';
 import logger from './logger';
 
+// Phase 13b: every blocklet-runtime binding below is constructed LAZILY, on first
+// property access, instead of at module import. Importing this module — and the
+// modules that transitively pull it in (libs/util, libs/payment, the models) —
+// therefore runs NO blocklet side effects, so createEmbeddedPaymentService +
+// rpc.entitlements.check work in a bare host with only the explicit config/db/
+// tenancy slots: no BLOCKLET_APP_SK/PK, no BLOCKLET_DATA_DIR, no ABT_NODE_*, no
+// notification patch. The node/full-handler and background-lifecycle paths still
+// materialize the real bindings on first use — transparently, through the proxies —
+// so every existing consumer (`wallet`, `ethWallet`, `blocklet`, `handlers`,
+// `authenticator`) keeps working unchanged.
+
+/** Transparent lazy proxy: defer factory() until the first property access. */
+function lazyProxy<T extends object>(factory: () => T): T {
+  let instance: T | undefined;
+  const resolve = (): T => {
+    instance ??= factory();
+    return instance;
+  };
+  return new Proxy({} as T, {
+    get(_t, prop) {
+      const obj = resolve();
+      const value: any = (obj as any)[prop];
+      if (typeof value !== 'function') return value;
+      // Don't re-bind jest mock functions: binding returns a plain wrapper that
+      // strips jest's mock helpers (.mockImplementation / .mockResolvedValue),
+      // which would make `jest.spyOn(blocklet, 'method')` unusable. Mocks ignore
+      // `this`, so leaving them unbound is safe. No-op in production (no mocks).
+      if (value._isMockFunction) return value;
+      return value.bind(obj);
+    },
+    set(_t, prop, value) {
+      (resolve() as any)[prop] = value;
+      return true;
+    },
+    has(_t, prop) {
+      return prop in (resolve() as any);
+    },
+  });
+}
+
 // Workaround #2: @blocklet/sdk's notification.getSender() uses
 // `getWallet().address` (BLOCKLET_APP_SK derived) as the sender appDid for
 // relay/EventBus broadcasts. On migrated blocklets that address (e.g. zNKti3…)
@@ -28,51 +63,214 @@ import logger from './logger';
 // Path must be `@blocklet/sdk/service/notification` (no `lib/`) — in Node it
 // is a thin re-export that resolves via the module cache to the same object
 // as `@blocklet/sdk/lib/service/notification`; in CF Workers the esbuild
-// config aliases it to a no-op shim (patching a no-op is harmless). Using
-// the `lib/` path breaks the CF build because it does not have an alias
-// and falls through to `@blocklet/sdk` → `shims/blocklet-sdk/index.ts/lib/...`.
-// Same root cause as the WalletAuthenticator override below — remove once the
-// upstream sdk is patched.
-// eslint-disable-next-line @typescript-eslint/no-var-requires, global-require, import/no-extraneous-dependencies
-const notificationExports = require('@blocklet/sdk/service/notification');
-
-notificationExports.getSender = () => ({
-  appDid: process.env.BLOCKLET_APP_ID || getWallet(undefined, '', 'sk').address,
-  wallet: getAccessWallet(),
-});
-logger.info('[sdk-patch] notification.getSender overridden', {
-  appDid: notificationExports.getSender().appDid,
-  expectedAppId: process.env.BLOCKLET_APP_ID,
-});
+// config aliases it to a no-op shim (patching a no-op is harmless).
+//
+// Phase 13b: applied LAZILY (once) the first time a blocklet binding is
+// materialized, instead of at module import — so a bare host that never touches a
+// binding never requires the wallet/notification modules. The override closure
+// still reads getWallet()/getAccessWallet() at send time, exactly as before.
+let notificationPatched = false;
+function ensureNotificationPatch(): void {
+  if (notificationPatched) return;
+  notificationPatched = true;
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const { getWallet, getAccessWallet } = require('@blocklet/sdk/lib/wallet');
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const notificationExports = require('@blocklet/sdk/service/notification');
+  notificationExports.getSender = () => ({
+    appDid: blockletAppId() || getWallet(undefined, '', 'sk').address,
+    wallet: getAccessWallet(),
+  });
+  // Note: do NOT invoke getSender() here — that would force a wallet read at patch
+  // time. Log only the expected appId (config-derived, env-free).
+  logger.info('[sdk-patch] notification.getSender overridden', { expectedAppId: blockletAppId() });
+}
+
+function makeWallet(...args: any[]): WalletObject {
+  ensureNotificationPatch();
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const { getWallet } = require('@blocklet/sdk/lib/wallet');
+  return getWallet(...args);
+}
 
-export const wallet: WalletObject = getWallet();
-export const ethWallet: WalletObject = getWallet('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. Remove once the
-// upstream wallet-authenticator.ts is patched accordingly.
-export const authenticator = new WalletAuthenticator({
-  wallet: getWallet(undefined, '', 'sk'),
-});
-export const handlers = new WalletHandlers({
-  authenticator,
-  tokenStorage: new AuthStorage({
-    dbPath: path.join(env.dataDir, 'auth.db'),
+// 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;
+}
+
+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');
+  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 });
 });
 
-export const blocklet = new BlockletService();
+// 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');
+  return new BlockletService();
+});
 
 export async function getVaultAddress() {
   try {
@@ -88,7 +286,9 @@ export async function getVaultAddress() {
 }
 
 export type CallbackArgs = {
-  request: Request & { context: Record<string, any> };
+  // did-connect-js passes its framework-adapted request to handler callbacks
+  // (createHonoRequest under attachHono); only `.context` is read here.
+  request: { context: Record<string, any>; [key: string]: any };
   userDid: string;
   userPk: string;
   didwallet: {

package/api/src/libs/context.ts

@@ -1,13 +1,29 @@
 import { AsyncLocalStorage, AsyncResource } from 'async_hooks';
 
+import {
+  TENANT_CONTEXT_MISSING,
+  TenantError,
+  assertValidInstanceDid,
+  getDefaultInstanceDid,
+  getTenantMode,
+} from './tenant';
+
+export * from './tenant';
+
 interface RequestContext {
   requestedBy?: string;
   requestId?: string;
+  instanceDid?: string;
 }
 
 class RequestContextManager {
   private storage = new AsyncLocalStorage<RequestContext>();
   private contexts = new Map<string, RequestContext>();
+  // System-operation flag: when set, TenantModel bypasses tenant scoping so a
+  // legitimate cross-tenant read (queue dispatch, IAP bundle->tenant reverse
+  // lookup, event fan-out) can load rows across tenants. Entered ONLY via the
+  // system* helpers — a normal route context can never read across tenants.
+  private systemStorage = new AsyncLocalStorage<boolean>();
 
   getContext(requestId?: string): RequestContext {
     if (requestId && this.contexts.has(requestId)) {
@@ -20,16 +36,73 @@ class RequestContextManager {
     return this.getContext(requestId).requestedBy;
   }
 
+  /**
+   * Run fn with the given tenant. Nested calls shadow the outer tenant and restore it on exit.
+   * Other context fields (requestId, requestedBy) are inherited from the enclosing scope.
+   */
+  withTenant<T>(instanceDid: string, fn: () => Promise<T> | T): Promise<T> {
+    try {
+      assertValidInstanceDid(instanceDid);
+    } catch (err) {
+      return Promise.reject(err);
+    }
+    const parent = this.storage.getStore();
+    // frozen so fn cannot mutate the stored context and affect sibling calls
+    const next = Object.freeze({ ...parent, instanceDid });
+    return this.storage.run(next, () => Promise.resolve(fn()));
+  }
+
+  /**
+   * Current tenant. Single mode falls back to the deployment app DID;
+   * multi mode fails closed with TENANT_CONTEXT_MISSING.
+   */
+  getInstanceDid(): string {
+    const instanceDid = this.storage.getStore()?.instanceDid;
+    if (instanceDid) return instanceDid;
+    if (getTenantMode() === 'single') return getDefaultInstanceDid();
+    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.
+   * The scope ends when fn settles — callers must enforce the row's tenant
+   * themselves (e.g. assertJobObjectTenant). Explicit by construction: only the
+   * system* helpers enter this, so a normal route can never read across tenants.
+   */
+  runAsSystem<T>(fn: () => Promise<T> | T): Promise<T> {
+    return this.systemStorage.run(true, () => Promise.resolve(fn()));
+  }
+
+  /** True inside a runAsSystem span — TenantModel checks this to skip scoping. */
+  isSystem(): boolean {
+    return this.systemStorage.getStore() === true;
+  }
+
   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
+    const instanceDid = context.instanceDid ?? this.storage.getStore()?.instanceDid;
 
     this.contexts.set(requestId, {
       ...context,
+      instanceDid,
       requestId,
     });
 
     return new Promise((resolve, reject) => {
-      this.storage.run({ ...context, requestId }, async () => {
+      this.storage.run({ ...context, instanceDid, requestId }, async () => {
         const resource = new AsyncResource('RequestContext');
         try {
           const result = await resource.runInAsyncScope(fn);
@@ -46,3 +119,18 @@ class RequestContextManager {
 }
 
 export const context = new RequestContextManager();
+
+/** Run fn with the given tenant — also the test injection helper for jest. */
+export function withTenant<T>(instanceDid: string, fn: () => Promise<T> | T): Promise<T> {
+  return context.withTenant(instanceDid, fn);
+}
+
+/** Current tenant; see RequestContextManager#getInstanceDid for mode semantics. */
+export function getInstanceDid(): string {
+  return context.getInstanceDid();
+}
+
+/** True inside a runAsSystem span; TenantModel uses it to bypass scoping. */
+export function isSystemContext(): boolean {
+  return context.isSystem();
+}

package/api/src/libs/currency.ts

@@ -1,8 +1,8 @@
 import { fromTokenToUnit, fromUnitToToken } from '@ocap/util';
-import { getUrl } from '@blocklet/sdk';
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { PaymentCurrency, Price, Product, RechargeConfig } from '../store/models';
 import { trimDecimals } from './math-utils';
-import { createPaymentLink } from '../routes/payment-links';
+import { createPaymentLink } from '../routes/hono/payment-links';
 import logger from './logger';
 
 export async function formatCurrencyToken(amount: string, currencyId: string) {

package/api/src/libs/dayjs.ts

@@ -5,8 +5,14 @@ import relativeTime from 'dayjs/plugin/relativeTime';
 import timezone from 'dayjs/plugin/timezone'; // dependent on utc plugin
 import utc from 'dayjs/plugin/utc';
 
-import('dayjs/locale/en');
-import('dayjs/locale/zh');
+// Use explicit `.js` so the dynamic import resolves under Node ESM (strict
+// resolution: dayjs ships no `exports` map, so the extensionless subpath
+// `dayjs/locale/en` fails when payment-core is embedded in a Node ESM host
+// like arc). Webpack/blocklet-server tolerate the extension too.
+// eslint-disable-next-line import/extensions -- explicit .js required for Node ESM hosts (arc)
+import('dayjs/locale/en.js');
+// eslint-disable-next-line import/extensions -- explicit .js required for Node ESM hosts (arc)
+import('dayjs/locale/zh.js');
 
 dayjs.extend(relativeTime);
 dayjs.extend(localizedFormat);