payment-kit 1.29.1 → 1.29.2

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

@@ -0,0 +1,175 @@
+// Phase 12b (W2′): the core queue RUNTIME surface.
+//
+// Decision (2026-06-12, build-phases 12b, option A): the node engine
+// (api/src/libs/queue) is the ONE canonical queue semantics for every runtime.
+// A host swaps only the TRIGGER (CF scheduled() vs the in-process poll loop),
+// the EXECUTOR (fastq shim vs real fastq) and FLUSH (drain-before-response vs
+// no-op). It NEVER forks the engine — the old cloudflare/shims/queue.ts
+// duplicate engine is dead under the canonical build.ts (nothing populates its
+// registry there) and is removed in 12c.
+//
+// This module is the seam the worker drives instead of reaching into
+// shims/queue internals:
+//   - a queue REGISTRY (each createQueue registers its handle + due-dispatch)
+//   - dispatchDueJobs() — host-driven scheduled re-dispatch (workerd trigger =
+//     CF scheduled(); on node the per-queue loop() does the same on a timer)
+//   - flushQueueWork()  — drain in-flight push/execution work before the
+//     isolate freezes (no-op on a long-lived node process)
+//
+// Runtime modes:
+//   'node'    — long-lived process: each scheduled queue's loop() polls D1.
+//   'workerd' — frozen isolate: loop() is disabled; the host calls
+//               dispatchDueJobs() from scheduled() and flushQueueWork() before
+//               returning the response.
+
+export type QueueRuntimeMode = 'node' | 'workerd';
+
+let mode: QueueRuntimeMode = 'node';
+
+export function setQueueRuntimeMode(next: QueueRuntimeMode): void {
+  mode = next;
+}
+
+export function getQueueRuntimeMode(): QueueRuntimeMode {
+  return mode;
+}
+
+export interface RegisteredQueue {
+  name: string;
+  /** whether this queue accepts delayed/scheduled jobs (gates due-dispatch) */
+  enableScheduledJob: boolean;
+  /** the public queue handle (push / pushAndWait / cancel / get / ...) */
+  handle: any;
+  /**
+   * Re-deliver this queue's due delayed rows once — the body of the node
+   * loop(). The host (CF scheduled()) calls this through dispatchDueJobs();
+   * the node loop() calls it on its own timer. Same code path either way.
+   */
+  redispatchDue: () => Promise<{ dispatched: number; failed: number }>;
+  /**
+   * D2 teardown: stop this queue's node poll loop (clears its sleep timer). The
+   * host (arc/Node) calls stopAllQueues() on lifecycle.stop() so no poll timer
+   * survives a stop / ARC_PAYMENT toggle. No-op on workerd (no loop runs).
+   */
+  stop?: () => void;
+}
+
+const registry = new Map<string, RegisteredQueue>();
+
+export function registerQueue(entry: RegisteredQueue): void {
+  registry.set(entry.name, entry);
+}
+
+/** the queue handle the worker's queue() consumer looks up by name (no more shim registry) */
+export function getQueueHandler(name: string): any | undefined {
+  return registry.get(name)?.handle;
+}
+
+export function getAllQueueNames(): string[] {
+  return Array.from(registry.keys());
+}
+
+/**
+ * Host-driven scheduled dispatch (the workerd trigger is CF scheduled()). Runs
+ * every registered scheduled queue's due-row re-dispatch once. On a node host
+ * the per-queue loop() does exactly this on a timer; a workerd host calls this
+ * explicitly because it cannot run a background timer in a frozen isolate.
+ */
+export async function dispatchDueJobs(): Promise<{ dispatched: number; failed: number; queues: string[] }> {
+  let dispatched = 0;
+  let failed = 0;
+  const queues: string[] = [];
+  for (const entry of registry.values()) {
+    // eslint-disable-next-line no-continue -- skip non-scheduled queues in the dispatch loop
+    if (!entry.enableScheduledJob) continue;
+    try {
+      // eslint-disable-next-line no-await-in-loop -- queues dispatch sequentially within a tick
+      const r = await entry.redispatchDue();
+      dispatched += r.dispatched;
+      failed += r.failed;
+      if (r.dispatched > 0 || r.failed > 0) queues.push(entry.name);
+    } catch {
+      failed += 1;
+    }
+  }
+  return { dispatched, failed, queues };
+}
+
+/**
+ * D2 teardown: stop every registered queue's node poll loop. The Node host
+ * (arc) calls this from lifecycle.stop() so no background poll timer survives a
+ * stop / ARC_PAYMENT toggle. The registry entries stay (a later start() rebuilds
+ * the loops by recreating the queues). Idempotent — safe to call when stopped.
+ */
+export function stopAllQueues(): void {
+  for (const entry of registry.values()) {
+    try {
+      entry.stop?.();
+    } catch {
+      /* a queue already stopped — ignore */
+    }
+  }
+}
+
+/** stop every queue loop AND clear the registry (full reset). */
+export function disposeQueues(): void {
+  stopAllQueues();
+  registry.clear();
+}
+
+// --- in-flight push tracking (workerd flush) ---
+// On node the process stays alive and fastq drains naturally; nothing is
+// tracked (zero overhead, byte-identical behavior). On workerd the isolate is
+// torn down after the response, so the host must await in-flight executions
+// before it returns — otherwise an immediate push is silently dropped.
+const pending = new Set<Promise<any>>();
+
+export function trackPending(p: Promise<any>): void {
+  if (mode !== 'workerd') return;
+  const wrapped = Promise.resolve(p).catch(() => undefined);
+  pending.add(wrapped);
+  wrapped.then(() => {
+    pending.delete(wrapped);
+  });
+}
+
+/**
+ * Drain in-flight push/execution work. The CF worker calls this before
+ * returning the HTTP response and at the end of scheduled()/queue() so no
+ * immediate push is lost when the isolate freezes. No-op on a node host.
+ */
+export async function flushQueueWork(): Promise<void> {
+  if (mode !== 'workerd') return;
+  const MAX_ITERATIONS = 10;
+  // Wall-clock guard: a misbehaving handler whose fastq callback never fires
+  // must not block the isolate's response forever. The D1 jobs row is the
+  // source of truth, so anything still pending past the budget is re-dispatched
+  // on the next scheduled() tick rather than lost.
+  const deadline = Date.now() + 5000;
+  for (let i = 0; i < MAX_ITERATIONS; i++) {
+    if (pending.size === 0) break;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    const batch = Array.from(pending);
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.race([
+      Promise.allSettled(batch),
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, remaining);
+      }),
+    ]);
+  }
+}
+
+// Exported for unit tests only — not part of the host-facing surface.
+// eslint-disable-next-line @typescript-eslint/naming-convention -- test-only export sentinel
+export const __test__ = {
+  reset() {
+    registry.clear();
+    pending.clear();
+    mode = 'node';
+  },
+  registrySize() {
+    return registry.size;
+  },
+};

package/api/src/libs/resource.ts

@@ -10,9 +10,9 @@ import { fromTokenToUnit } from '@ocap/util';
 
 import { updatePassportExtra } from '../integrations/blocklet/passport';
 import { replace } from '../locales';
-import { createPaymentLink } from '../routes/payment-links';
-import { createPrice } from '../routes/prices';
-import { createProductAndPrices } from '../routes/products';
+import { createPaymentLink } from '../routes/hono/payment-links';
+import { createPrice } from '../routes/hono/prices';
+import { createProductAndPrices } from '../routes/hono/products';
 import { PaymentCurrency, PaymentLink, Price, Product, nextPriceId } from '../store/models';
 
 export async function getPackResource(type: string) {

package/api/src/libs/secrets.ts

@@ -0,0 +1,38 @@
+// Phase 11 (W2-3): tenant-aware secrets facade.
+//
+// Replaces direct `security.encrypt/decrypt` calls in the payment hot path. The
+// tenant is resolved from the TenantContext (single point), so call sites do
+// not change signature. single mode -> the default secrets driver (process
+// key), unchanged; multi mode -> the keyring driver keyed per tenant.
+//
+// Sync surface: the payment loop (PaymentMethod.encrypt/decrypt Settings,
+// getStripeClient, ~50 sync callers) stays synchronous. The keyring driver's
+// sync path requires the tenant key to be warmed (the worker shell warms it at
+// request entry); the default driver's process key is always available.
+
+import { getInstanceDid } from './context';
+import { getSecretsDriver } from './drivers/secrets';
+
+/** Encrypt a value under the current tenant's key (sync hot path). */
+export function encryptSecret(value: string): string {
+  return getSecretsDriver().encryptSync(getInstanceDid(), value);
+}
+
+/** Decrypt a value under the current tenant's key (sync hot path). */
+export function decryptSecret(value: string): string {
+  return getSecretsDriver().decryptSync(getInstanceDid(), value);
+}
+
+/** Async per-tenant variants (lazy EK fetch + retry) for non-hot-path callers. */
+export function encryptSecretAsync(value: string): Promise<string> {
+  return getSecretsDriver().encrypt(getInstanceDid(), value);
+}
+
+export function decryptSecretAsync(value: string): Promise<string> {
+  return getSecretsDriver().decrypt(getInstanceDid(), value);
+}
+
+/** Pre-resolve the current tenant's key so the sync path is a cache hit. */
+export function warmupSecrets(instanceDid?: string): Promise<void> {
+  return getSecretsDriver().warmup(instanceDid ?? getInstanceDid());
+}

package/api/src/libs/session.ts

@@ -6,6 +6,7 @@ import cloneDeep from 'lodash/cloneDeep';
 import isEqual from 'lodash/isEqual';
 import pAll from 'p-all';
 import omit from 'lodash/omit';
+import { paymentBillingThreshold, paymentMinStakeAmount } from './env';
 import dayjs from './dayjs';
 import { validCoupon } from './discount/coupon';
 import { getPriceUintAmountByCurrency, getPriceCurrencyOptions } from './price';
@@ -425,7 +426,7 @@ export function getBillingThreshold(config: Record<string, any> = {}) {
     }
   }
 
-  const threshold = +(process.env.PAYMENT_BILLING_THRESHOLD as string);
+  const threshold = paymentBillingThreshold();
   if (threshold > 0) {
     return threshold;
   }
@@ -441,7 +442,7 @@ export function getMinStakeAmount(config: Record<string, any> = {}) {
     }
   }
 
-  const threshold = +(process.env.PAYMENT_MIN_STAKE_AMOUNT as string);
+  const threshold = paymentMinStakeAmount();
   if (threshold > 0) {
     return threshold;
   }

package/api/src/libs/subscription.ts

@@ -8,6 +8,7 @@ import type { LiteralUnion } from 'type-fest';
 import { withQuery } from 'ufo';
 
 import { Op } from 'sequelize';
+import env, { paymentDaysUntilDue, paymentDaysUntilCancel } from './env';
 import {
   ChainType,
   Customer,
@@ -27,9 +28,8 @@ import {
   TLineItemExpanded,
   UsageRecord,
 } from '../store/models';
-import { createEvent } from './audit';
+import { createEvent, reportAuditFailure } from './audit';
 import dayjs from './dayjs';
-import env from './env';
 import logger from './logger';
 import { getExchangeRateService } from './exchange-rate';
 import { getExchangeRateSymbol } from './exchange-rate/token-address-mapping';
@@ -107,11 +107,11 @@ export function parseIntegerConfig(alternatives: any[], defaultValue: number) {
 }
 
 export function getDaysUntilDue(query: Record<string, any> = {}) {
-  return parseIntegerConfig([query.days_until_due, process.env.PAYMENT_DAYS_UNTIL_DUE], 6);
+  return parseIntegerConfig([query.days_until_due, paymentDaysUntilDue()], 6);
 }
 
 export function getDaysUntilCancel(query: Record<string, any> = {}) {
-  return parseIntegerConfig([query.days_until_cancel, process.env.PAYMENT_DAYS_UNTIL_CANCEL], 0);
+  return parseIntegerConfig([query.days_until_cancel, paymentDaysUntilCancel()], 0);
 }
 
 export const getDueUnit = (interval: string) => {
@@ -821,7 +821,7 @@ export async function finalizeStripeSubscriptionUpdate({
     await Lock.acquire(`${subscription.id}-change-plan`, releaseAt);
     logger.info('subscription plan change lock acquired on finalize', { subscription: subscription.id, releaseAt });
 
-    createEvent('Subscription', 'customer.subscription.upgraded', subscription).catch(console.error);
+    createEvent('Subscription', 'customer.subscription.upgraded', subscription).catch(reportAuditFailure);
   }
 
   logger.info('subscription update finalized', { subscription: subscription.id, updates, items });

package/api/src/libs/tenant.ts

@@ -0,0 +1,92 @@
+import { tenantModeRaw, blockletAppPid } from './env';
+
+export type TenantMode = 'single' | 'multi';
+
+export const TENANT_CONTEXT_MISSING = 'TENANT_CONTEXT_MISSING';
+export const TENANT_MISMATCH = 'TENANT_MISMATCH';
+// programmer error: a scoped helper was pointed at a non-tenant model —
+// distinct from TENANT_MISMATCH so monitoring can tell data races from bugs
+export const INVALID_TENANT_TABLE = 'INVALID_TENANT_TABLE';
+// multi-tenant fail-closed: a request Host did not resolve to any tenant
+// (Phase 10) — the request is refused 4xx with no default-tenant fallback
+export const TENANT_HOST_UNRESOLVED = 'TENANT_HOST_UNRESOLVED';
+
+export type TenantErrorCode =
+  | typeof TENANT_CONTEXT_MISSING
+  | typeof TENANT_MISMATCH
+  | typeof INVALID_TENANT_TABLE
+  | typeof TENANT_HOST_UNRESOLVED;
+
+export class TenantError extends Error {
+  code: TenantErrorCode;
+
+  constructor(code: TenantErrorCode, message: string) {
+    super(message);
+    this.name = 'TenantError';
+    this.code = code;
+  }
+}
+
+/**
+ * Tenant mode of this deployment:
+ * - `single` (default, blocklet server legacy): tenant context falls back to the deployment's own app DID
+ * - `multi`: no fallback — missing tenant context is a fail-closed error
+ *
+ * Source of the mode is the existing env mechanism for now; Phase 12 converges it into the config slot.
+ */
+export function getTenantMode(): TenantMode {
+  // Phase 8: mode-source reads the injected config (libs/env boundary), falling
+  // back to process.env. Not request-tamperable — config is set once at factory
+  // init, never from request input.
+  return tenantModeRaw() === 'multi' ? 'multi' : 'single';
+}
+
+/**
+ * Single source of truth for "this deployment's app DID" (single-tenant default tenant).
+ * Phase 2 backfill values and Phase 10 `tenancy.instanceDid` must reuse this getter.
+ */
+// Phase 10: the single-mode tenancy slot value, when the host supplies one via
+// createEmbeddedPaymentService({ tenancy: { mode:'single', instanceDid } }).
+// Preferred over the env snapshot so a host can declare its single-tenant
+// identity explicitly (and so the slot is not silently ignored).
+let overrideDefaultInstanceDid: string | undefined;
+
+/** Wire the single-mode tenancy slot value (factory only). Pass undefined to clear. */
+export function setDefaultInstanceDid(did: string | undefined): void {
+  if (did !== undefined) assertValidInstanceDid(did);
+  overrideDefaultInstanceDid = did;
+}
+
+export function getDefaultInstanceDid(): string {
+  // explicit tenancy slot value wins; otherwise the app DID from the injected
+  // config (libs/env boundary), which itself falls back to process.env's
+  // BLOCKLET_APP_PID (the value @blocklet/sdk's env.appPid wrapped before Phase 8).
+  const did = overrideDefaultInstanceDid || blockletAppPid() || '';
+  if (!did) {
+    throw new TenantError(TENANT_CONTEXT_MISSING, 'app DID is not configured for this deployment');
+  }
+  return did;
+}
+
+// Deliberately loose: deployments use both bare addresses (z8iZ...) and
+// did:abt: URIs, so we only reject values that cannot be a DID at all
+// (non-strings, empty/whitespace, embedded whitespace). Strict format
+// enforcement belongs to the identity slot (Phase 10), which resolves
+// Host -> instanceDid from a trusted source.
+/**
+ * Tenant of a loaded row, fail-closed: rows written since Phase 2 always
+ * carry instance_did; a NULL means pre-backfill data, which is only legal in
+ * single mode (where it can only belong to the default tenant).
+ */
+export function resolveRowTenant(row: { instance_did?: string | null } | null | undefined): string {
+  const fromRow = row?.instance_did;
+  if (fromRow) return fromRow;
+  if (getTenantMode() === 'single') return getDefaultInstanceDid();
+  throw new TenantError(TENANT_CONTEXT_MISSING, 'row has no tenant and deployment is in multi mode');
+}
+
+export function assertValidInstanceDid(instanceDid: unknown): asserts instanceDid is string {
+  if (typeof instanceDid !== 'string' || !/^\S{3,}$/.test(instanceDid)) {
+    throw new TenantError(TENANT_CONTEXT_MISSING, `invalid instanceDid: ${JSON.stringify(instanceDid)}`);
+  }
+}

package/api/src/libs/url.ts

@@ -30,7 +30,7 @@ export async function formatToShortUrl({
   validUntil?: string;
   maxVisits?: number;
 }): Promise<string> {
-  const apiKey = shortUrlApiKey;
+  const apiKey = shortUrlApiKey();
 
   if (!apiKey) {
     return url;
@@ -43,14 +43,14 @@ export async function formatToShortUrl({
       maxVisits,
       tags: [],
       shortCodeLength: 8,
-      domain: shortUrlDomain,
+      domain: shortUrlDomain(),
       findIfExists: true,
       validateUrl: true,
       forwardQuery: true,
       crawlable: true,
     };
 
-    const response = await fetch(`https://${shortUrlDomain}/rest/v3/short-urls`, {
+    const response = await fetch(`https://${shortUrlDomain()}/rest/v3/short-urls`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',

package/api/src/libs/util.ts

@@ -10,10 +10,10 @@ import type { LiteralUnion } from 'type-fest';
 import { joinURL, withQuery, withTrailingSlash } from 'ufo';
 
 import axios from 'axios';
-import { ethers } from 'ethers';
 import { fromUnitToToken } from '@ocap/util';
 import get from 'lodash/get';
 import trimEnd from 'lodash/trimEnd';
+import { googlePlayWebhookUrl, blockletAppUrl, blockletMountPoints, blockletAppId, blockletAppName } from './env';
 import dayjs from './dayjs';
 import { blocklet, wallet } from './auth';
 import type { PaymentCurrency, PaymentMethod, Subscription } from '../store/models';
@@ -37,7 +37,7 @@ export const STRIPE_ENDPOINT: string = getUrl('/api/integrations/stripe/webhook'
 // Lazy-eval (function not constant) because dotenv loads env AFTER this module
 // is imported — a constant captured at module-load would only see BLOCKLET_APP_URL.
 export const googlePlayEndpoint = (): string =>
-  process.env.GOOGLE_PLAY_WEBHOOK_URL || getUrl('/api/integrations/google-play/webhook');
+  googlePlayWebhookUrl() || getUrl('/api/integrations/google-play/webhook');
 
 // Back-compat constant for any caller that captures it at module-load.
 // Prefer googlePlayEndpoint() going forward.
@@ -262,7 +262,7 @@ const cachedBlockletJsonResult = new Map<string, { data: any; expiry: number }>(
 const CACHE_TTL = 60 * 60 * 1000; // 1 hour
 
 export async function getBlockletJson(url?: string) {
-  const blockletKey = url || process.env.BLOCKLET_APP_URL || 'default';
+  const blockletKey = url || blockletAppUrl() || 'default';
   const now = Date.now();
 
   if (cachedBlockletJsonResult.has(blockletKey)) {
@@ -271,7 +271,7 @@ export async function getBlockletJson(url?: string) {
       return cached.data;
     }
   }
-  const baseUrl = url || process.env.BLOCKLET_APP_URL;
+  const baseUrl = url || blockletAppUrl();
   if (!baseUrl) {
     return null;
   }
@@ -282,14 +282,14 @@ export async function getBlockletJson(url?: string) {
     return blockletMeta;
   } catch (err) {
     logger.error(`getBlockletJson error for ${scriptUrl}`, err);
-    if (process.env.BLOCKLET_MOUNT_POINTS) {
-      const BLOCKLET_MOUNT_POINTS = safeJsonParse(process.env.BLOCKLET_MOUNT_POINTS, []);
+    if (blockletMountPoints()) {
+      const BLOCKLET_MOUNT_POINTS = safeJsonParse(blockletMountPoints(), []);
       return {
         componentMountPoints: BLOCKLET_MOUNT_POINTS,
-        appId: process.env.BLOCKLET_APP_ID,
-        appName: process.env.BLOCKLET_APP_NAME,
+        appId: blockletAppId(),
+        appName: blockletAppName(),
         appLogo: '/.well-known/service/blocklet/logo',
-        appUrl: process.env.BLOCKLET_APP_URL,
+        appUrl: blockletAppUrl(),
       };
     }
     return null;
@@ -313,9 +313,9 @@ export async function getUserOrAppInfo(
     if (appInfo) {
       return {
         name: appInfo.name,
-        avatar: joinURL(process.env.BLOCKLET_APP_URL!, `.well-known/service/blocklet/logo-bundle/${appInfo.did}`),
+        avatar: joinURL(blockletAppUrl()!, `.well-known/service/blocklet/logo-bundle/${appInfo.did}`),
         type: 'dapp',
-        url: joinURL(process.env.BLOCKLET_APP_URL!, appInfo.mountPoint),
+        url: joinURL(blockletAppUrl()!, appInfo.mountPoint),
       };
     }
   }
@@ -324,7 +324,7 @@ export async function getUserOrAppInfo(
     const locale = get(user, 'locale', 'en');
     return {
       name: user?.fullName,
-      avatar: joinURL(process.env.BLOCKLET_APP_URL!, user?.avatar),
+      avatar: joinURL(blockletAppUrl()!, user?.avatar),
       type: 'user',
       url: getCustomerProfileUrl({ userDid: address, locale }),
     };
@@ -608,7 +608,15 @@ export async function isUserInBlocklist(did: string, paymentMethod: PaymentMetho
 }
 
 export function resolveAddressChainTypes(address: string): LiteralUnion<'ethereum' | 'base' | 'arcblock', string>[] {
-  if (ethers.isAddress(address)) {
+  // Phase 13b2: lazy ethers. An eager top-level `import 'ethers'` loaded ethers
+  // during createEmbeddedPaymentService assembly (libs/util is pulled in at factory
+  // time), so a host that force-resolves an incompatible @noble/hashes (e.g. arc's
+  // `@noble/hashes:^2.2.0` override vs ethers@6.16's declared 1.3.2) crashed ethers
+  // at require. Deferring to call time keeps the factory + rpc.entitlements.check
+  // ethers-free; this fn runs only on EVM address resolution.
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const { isAddress } = require('ethers');
+  if (isAddress(address)) {
     return ['ethereum', 'base', 'arcblock'];
   }
   return ['arcblock'];

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

@@ -0,0 +1,63 @@
+// Phase 1 (express→hono) — hono fork of @blocklet/sdk/lib/middlewares/cdn.js.
+//
+// The express version monkeypatches res.send to rewrite asset URLs to the CDN
+// host on outgoing HTML. hono responses are built differently, so this fork
+// rewrites in the RESPONSE phase: run the handler, then if the response is HTML
+// (production GET/HEAD, non-resource, html-accepting), read it once and rebuild
+// the Response with rewritten URLs. The transform core (AssetHostTransformer) is
+// REUSED VERBATIM from the SDK — byte-identical rewriting. Inert for JSON /api
+// routes (content-type is not text/html), which is the only surface in Phases
+// 1-3; it becomes load-bearing when SPA HTML serving moves off the bridge.
+import type { MiddlewareHandler } from 'hono';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { AssetHostTransformer } from '@blocklet/sdk/lib/util/asset-host-transformer';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { env } from '@blocklet/sdk/lib/config';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { BLOCKLET_PROXY_PATH_PREFIX } from '@abtnode/constant';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { RESOURCE_PATTERN } from '@blocklet/constant';
+import { nodeEnv, readConfig } from '../../libs/env';
+
+function isProductionRuntime(): boolean {
+  return nodeEnv() === 'production' || readConfig('ABT_NODE_SERVICE_ENV') === 'production';
+}
+
+// Parity with express req.accepts(['html', ...]) for the html family.
+function acceptsHtml(accept: string): boolean {
+  if (!accept) return true; // express treats a missing Accept as accept-all
+  return accept.includes('text/html') || accept.includes('application/xhtml+xml') || accept.includes('*/*');
+}
+
+function shouldProcess(method: string, path: string, accept: string): boolean {
+  if (!isProductionRuntime()) return false;
+  if (method !== 'GET' && method !== 'HEAD') return false;
+  if (path.includes('/.well-known/service/')) return false;
+  if (RESOURCE_PATTERN.test(path)) return false;
+  return acceptsHtml(accept);
+}
+
+export function cdn(): MiddlewareHandler {
+  // Lazy + skip-if-absent: a bare/embedded host without componentDid never
+  // rewrites (the SDK throws "did is required" eagerly; the fork stays inert).
+  let transformer: AssetHostTransformer | undefined;
+  return async (c, next) => {
+    await next();
+    const assetHost = (env as any).assetCdnHost;
+    const did = (env as any).componentDid;
+    if (!assetHost || !did) return;
+    if (!shouldProcess(c.req.method.toUpperCase(), c.req.path, c.req.header('accept') || '')) return;
+
+    const contentType = c.res.headers.get('content-type') || '';
+    if (!contentType.includes('text/html')) return;
+
+    transformer ??= new AssetHostTransformer(`${BLOCKLET_PROXY_PATH_PREFIX}/${did}/`);
+    const html = await c.res.text();
+    const transformed = transformer.transform(html, assetHost);
+    const rebuilt = new Response(transformed, c.res);
+    rebuilt.headers.delete('content-length'); // body length changed; let the server derive it
+    c.res = rebuilt;
+  };
+}
+
+export default cdn;

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

@@ -0,0 +1,73 @@
+// Phase 1 (express→hono) — hono fork of api/src/libs/middleware.ts
+// (ensureI18n + contextMiddleware). Behavior is identical to the express
+// version; only the req/res plumbing changes:
+//   - req.query.locale / req.t=      → c.req.query('locale') / c.set('t', ...)
+//   - req.get('x-component-sig')      → c.req.header('x-component-sig')
+//   - req.body (component sig verify) → c.get('sanitizedBody') (xss is the single
+//                                       body read-point, already ran upstream)
+//   - req.headers.host (tenant)       → c.req.header('host') (raw Host only, never
+//                                       a proxy header — single tenant resolution)
+//   - res.status(400).json(...)       → c.json(..., 400) (fail-closed on unknown
+//                                       host in multi mode)
+//   - context.run(..., next)          → context.run(..., () => next()) (same ALS)
+import type { MiddlewareHandler } from 'hono';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { verify } from '@blocklet/sdk/lib/util/verify-sign';
+import { translate } from '../../locales';
+import { context } from '../../libs/context';
+import { TenantError, TENANT_HOST_UNRESOLVED } from '../../libs/tenant';
+import { resolveTenantForHost } from '../../libs/drivers/identity';
+
+export function ensureI18n(): MiddlewareHandler {
+  return (c, next) => {
+    c.set('locale', String(c.req.query('locale') || 'en'));
+    c.set('t', translate);
+    return next();
+  };
+}
+
+export function contextMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    const requestId = c.req.header('x-request-id') || `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    let requestedBy = 'system';
+
+    // component signature — verify against the SANITIZED body (xss ran first)
+    const sig = c.req.header('x-component-sig');
+    const componentDid = c.req.header('x-component-did');
+    if (sig && componentDid) {
+      const data = c.get('sanitizedBody') ?? {};
+      const verified = await verify(data, sig);
+      if (verified) {
+        requestedBy = componentDid;
+      }
+    }
+
+    // user DID from headers
+    const userDid = c.req.header('x-user-did');
+    if (userDid) {
+      requestedBy = userDid;
+    }
+
+    // authenticated user (security middleware set this upstream)
+    const user = c.get('user');
+    if (user?.did) {
+      requestedBy = user.did;
+    }
+
+    // Resolve tenant from the raw Host (single point). Multi-mode unknown host →
+    // 4xx fail-closed, no default-tenant fallback.
+    let instanceDid: string;
+    try {
+      instanceDid = await resolveTenantForHost(c.req.header('host'));
+    } catch (err) {
+      if (err instanceof TenantError && err.code === TENANT_HOST_UNRESOLVED) {
+        return c.json({ error: { code: err.code, message: err.message } }, 400);
+      }
+      throw err;
+    }
+
+    return context.run({ requestId, requestedBy, instanceDid }, async () => {
+      await next();
+    });
+  };
+}