payment-kit 1.29.2 → 1.29.4

package/cloudflare/worker.ts

@@ -19,13 +19,13 @@ import { Sequelize } from './shims/sequelize-d1/sequelize-class';
 // loop). Side-effect import — keep it ahead of service/crons/queues below.
 import './queue-runtime-mode';
 
-// Phase 12a (Option 3 seam): the worker's /api business surface now comes from
-// the embedded payment service factory instead of a direct routes import. The
-// factory performs assembly (config slot authoritative via setCoreConfig + model
-// initialize), and exposes `http.resourceRoutes` — the resource routers only,
-// no node app shell, no DID-Connect handlers (the worker registers those through
-// its own Hono `attachDIDConnectRoutes`). The factory's lazy `handler` getter is
-// never touched here, so the node-only app shell never runs under the shim.
+// Phase 12a (Option 3 seam) + S3-CF Phase 1B: the worker's /api surface comes from
+// the embedded payment service factory. The factory performs assembly (config slot
+// authoritative via setCoreConfig + model initialize). Phase 1B: the worker forwards
+// every payment /api/* (business resource routes + DID payment actions) through the
+// runtime-neutral `http.fetch` (the core full app + full pipeline) — a SINGLE
+// surface. The factory's lazy `handler` getter is never touched here (hard-gated),
+// so the worker only ever drives the core via `http.fetch`.
 import { createEmbeddedPaymentService } from '../api/src/service';
 import type { PaymentCoreService } from '../api/src/service';
 
@@ -66,11 +66,10 @@ import { resetD1Timing, getD1Timing } from './shims/sequelize-d1/timing';
 import { withD1Retry } from './shims/sequelize-d1/retry';
 
 // DID Connect: login routes proxied to blocklet-service, business actions (pay/subscribe) handled locally
-import { attachDIDConnectRoutes } from './did-connect-auth';
+import { createCloudflareDidConnectRuntime, createCloudflareIdentityDriver } from './did-connect-runtime';
 
 // Phase 7: tenant-context middleware — resolves Host -> tenant (single point)
 // and wraps the request chain in context.withTenant (multi-mode fail-closed).
-import { tenantMiddleware } from './tenant-middleware';
 
 FetchRequest.registerGetUrl(async (req: FetchRequest) => {
   const resp = await fetch(req.url, {
@@ -100,7 +99,6 @@ interface CallerIdentityDTO {
 
 interface Env {
   DB: D1Database;
-  DID_CONNECT_KV: KVNamespace;
   JOB_QUEUE: Queue;
   ASSETS: { fetch: (request: Request | string) => Promise<Response> };
   APP_SK: string;
@@ -128,6 +126,17 @@ interface Env {
       role?: string;
       approved?: number;
     } | null>;
+    // S3-CF (DID convergence): did-connect-service@4.0.3 — the per-instance app
+    // signing identity for the DID-Connect authenticator. The RPC resolves the arc
+    // run-mode internally (instance app:sk → instance identity; else auth-service
+    // root APP_SK/APP_PSK; else fail-closed), so payment-core never reimplements it.
+    getInstanceAppIdentity: (instanceDid: string) => Promise<{
+      appSk: string;
+      appPsk?: string;
+      appInfo?: { name?: string; description?: string; icon?: string; link?: string };
+    }>;
+    getAppEk?: (instanceDid: string) => Promise<string | null>;
+    resolveInstanceDidForHost?: (host: string) => Promise<string | null>;
   };
   HYPERDRIVE: { connectionString: string };
   [key: string]: any;
@@ -270,18 +279,26 @@ function ensurePaymentService(env: Env): PaymentCoreService {
   const svc = createEmbeddedPaymentService({
     config: envToPaymentCoreConfig(env),
     db: { sequelize },
+    // S3-CF (DID convergence): inject the CF DID-Connect runtime (real
+    // @arcblock/did-connect-js + CF chain/txEncoder/timeout + tenant-aware D1 token
+    // store) and the AUTH_SERVICE-backed identity driver (getInstanceAppIdentity).
+    // The core buildConnectRoutesHono then registers the 14 payment DID actions with
+    // a per-tenant signing identity — the worker no longer owns a private DID surface.
+    identity: createCloudflareIdentityDriver(),
+    didConnectRuntime: createCloudflareDidConnectRuntime(),
   });
-  // Phase 12c HARD GATE: the CF worker is a host adapter. It mounts only
-  // svc.http.resourceRoutes and registers DID-Connect through its own Hono
-  // shell — it must NEVER touch svc.handler, whose lazy getter builds the
-  // node-only Express app shell (app.set / static / connect attach) that does
-  // not belong under workerd. Trap the access so a future regression fails loud
-  // at runtime instead of silently constructing the node app in the isolate.
+  // Phase 12c HARD GATE (updated S3-CF Phase 1B): the CF worker is a host adapter
+  // that drives the core via the runtime-neutral `svc.http.fetch`. It must NEVER
+  // read `svc.handler` directly — that lazy getter is the node-host convenience
+  // entry (it would wire the node staticHandler if one were injected). The worker
+  // forwards through `svc.http.fetch`, which builds the same full hono app but is
+  // the sanctioned runtime-neutral seam. Trap `handler` so a future regression
+  // fails loud instead of silently taking the node-convenience path.
   paymentService = new Proxy(svc, {
     get(target, prop, receiver) {
       if (prop === 'handler') {
         throw new Error(
-          '[worker hard-gate] svc.handler is forbidden in the CF worker — mount svc.http.resourceRoutes instead'
+          '[worker hard-gate] svc.handler is forbidden in the CF worker — use svc.http.fetch instead'
         );
       }
       return Reflect.get(target, prop, receiver);
@@ -340,16 +357,19 @@ function buildApp(env: Env): Hono<HonoEnv> {
     return cachedApp;
   }
 
-  // Phase 12a: assemble the embedded payment service (config/db/slots) and take
-  // its resource routes for mounting. Only `http.resourceRoutes` is read — the
-  // node-only `handler` getter is never touched, so the express app shell + the
-  // DID-Connect handlers it carries never run under the workerd shim.
+  // Phase 12a + S3-CF Phase 1B: assemble the embedded payment service
+  // (config/db/slots incl. the injected CF DID-Connect runtime). The worker drives
+  // it through `service.http.fetch` (the single runtime-neutral surface); the
+  // node-only `handler` getter is hard-gated and never touched.
   const service = ensurePaymentService(env);
 
   const app = new Hono<HonoEnv>();
 
   // CORS
-  app.use('/api/*', cors());
+  // S3-CF Phase 1B: payment `/api/*` CORS is owned by the CORE full pipeline
+  // (cors/xss/csrf/i18n/cdn/context), reached via service.http.fetch. The worker no
+  // longer pre-applies cors() to /api/* — that would double the CORS headers on
+  // every payment route. Worker-owned cross-origin surfaces keep their own cors:
   app.use('/.well-known/*', cors());
   // /__blocklet__.js is fetched by external wallets (e.g. abtwallet.io, localhost
   // dev wallets) to resolve app metadata + chain info before starting DID Connect.
@@ -413,7 +433,23 @@ function buildApp(env: Env): Hono<HonoEnv> {
         if (caller) {
           authSource = 'cache';
         } else {
-          caller = await authService.resolveIdentity(jwt, authHeader, c.env.APP_PID);
+          // S3-CF Phase 1B: parameterize the caller RPC with the request's actual
+          // tenant via the SAME Host→tenant resolver the core uses — not a fixed
+          // env.APP_PID — so a multi-tenant embed verifies the caller against the
+          // right instance. Non-throwing: an unresolved host (multi) keeps the
+          // APP_PID fallback. Lazily required (NOT a top-level import) to avoid
+          // pulling the identity module into the worker's eager startup graph. This
+          // does NOT wrap the business handler's ALS context (the core owns that).
+          let callerInstanceDid: string | undefined = c.env.APP_PID;
+          try {
+            // eslint-disable-next-line global-require
+            const { resolveTenantForHost } = require('../api/src/libs/drivers/identity');
+            const resolved = await resolveTenantForHost(c.req.header('host'));
+            if (resolved) callerInstanceDid = resolved;
+          } catch {
+            /* unresolved host → keep the APP_PID fallback for the caller RPC param */
+          }
+          caller = await authService.resolveIdentity(jwt, authHeader, callerInstanceDid);
           authSource = 'rpc';
           if (caller && cacheKey) {
             cacheIdentity(cacheKey, caller);
@@ -449,11 +485,13 @@ function buildApp(env: Env): Hono<HonoEnv> {
     c.res.headers.append('Server-Timing', timings.join(', '));
   });
 
-  // Tenant context: resolve Host -> tenant (single point) and wrap the request
-  // chain in context.withTenant so every TenantModel query is scoped. Scoped to
-  // /api/* so /health and static assets never require a tenant. multi mode:
-  // unknown/missing Host -> 400 fail-closed (no default-tenant fallback).
-  app.use('/api/*', tenantMiddleware());
+  // S3-CF Phase 1B: the ALS tenant context for payment `/api/*` business requests
+  // is owned by the CORE full pipeline (contextMiddleware), reached via
+  // service.http.fetch. The worker no longer wraps /api/* in tenantMiddleware() —
+  // that would double-resolve + double-wrap the tenant. The few worker-owned /api/*
+  // endpoints (dev/debug/proxies) run in single-mode default and never query under
+  // a per-request tenant. (DID payment actions get their context from the core
+  // buildConnectRoutesHono tenant middleware, also via http.fetch.)
 
   // Health check
   app.get('/health', (c) => c.json({ status: 'ok' }));
@@ -656,8 +694,9 @@ function buildApp(env: Env): Hono<HonoEnv> {
 
   // === DID Auth Login routes ===
   // Only proxy login-related /api/did/* paths to blocklet-service.
-  // Other /api/did/* paths (subscription, pay, collect, etc.) are Payment Kit's
-  // own DID Connect actions handled by attachDIDConnectRoutes below.
+  // Other /api/did/* paths (subscription, pay, collect, etc.) are Payment Kit's own
+  // DID Connect payment actions — they fall through to the /api/* → service.http.fetch
+  // dispatcher (the core full app's DID payment actions).
   const DID_AUTH_PROXY_PATHS = [
     '/api/did/login/',
     '/api/did/session',
@@ -668,7 +707,10 @@ function buildApp(env: Env): Hono<HonoEnv> {
   app.all('/api/did/*', async (c, next) => {
     const path = new URL(c.req.url).pathname;
     const shouldProxy = DID_AUTH_PROXY_PATHS.some((p) => path.startsWith(p) || path === p);
-    if (!shouldProxy) return next(); // Fall through to attachDIDConnectRoutes or Express routes
+    // S3-CF Phase 1B: non-proxy payment DID actions fall through to the /api/*
+    // dispatcher below → service.http.fetch (the core full app includes the DID
+    // payment actions via buildConnectRoutesHono).
+    if (!shouldProxy) return next();
 
     if (!c.env.AUTH_SERVICE) {
       return c.json({ error: 'AUTH_SERVICE not configured' }, 503);
@@ -685,14 +727,10 @@ function buildApp(env: Env): Hono<HonoEnv> {
   });
 
   // === DID Connect business actions (subscription, pay, collect, etc.) ===
-  if (env.APP_SK && env.DID_CONNECT_KV) {
-    try {
-      attachDIDConnectRoutes(app, env.DID_CONNECT_KV, env.APP_SK);
-      console.log('[CF Worker] DID Connect routes attached');
-    } catch (e: any) {
-      console.error('DID Connect init error:', e?.message || e);
-    }
-  }
+  // S3-CF Phase 1B: the 14 payment DID actions are part of the CORE full app and
+  // are reached through the /api/* → service.http.fetch dispatcher below (they were
+  // converged onto buildConnectRoutesHono in Phase 1A, backed by the CF DID-Connect
+  // runtime injected into the service above). No separate worker mount — one surface.
 
   // Notification unread count
   app.get('/api/notifications/unread-count', (c) => c.json({ unReadCount: 0 }));
@@ -730,11 +768,9 @@ function buildApp(env: Env): Hono<HonoEnv> {
   // for creating PaymentMethods is owner-gated, and staging has no owner yet
   // (Pengfei's blocklet-service role is `member`). Gated by PAYMENT_LIVEMODE
   // === 'false' so this only ever touches testmode data.
-  // Phase 4 (express→hono): the resource routes are a native hono app
-  // (service.http.resourceRoutes) mounted by the /api/* dispatcher registered
-  // AFTER the worker's own /api/__dev__ routes (see below, replacing the old
-  // "not implemented" catch-all). The old express-compat mountExpressRoutes shim
-  // is gone.
+  // S3-CF Phase 1B: payment business routes (and DID payment actions) are served by
+  // the core full app via the /api/* → service.http.fetch dispatcher, registered
+  // AFTER the worker's own /api/__dev__ routes so those match first.
 
   // Dev endpoint: D1 admin operations
   // Test CF Queue send directly
@@ -1079,17 +1115,21 @@ function buildApp(env: Env): Hono<HonoEnv> {
     }
   });
 
-  // Phase 4 (express→hono): native hono resource routes. Registered AFTER the
-  // worker's own /api/__dev__ routes so those match first; this dispatcher then
-  // handles every other /api/* path (returning resourceRoutes' own 404 for an
-  // unknown route). The RPC-resolved caller identity is injected as x-user-*
-  // request headers — the native authenticate() reads those — and any
-  // client-supplied x-user-* is overwritten/stripped so it can never be forged
-  // (component auth via x-component-sig is left intact: it is verified
-  // cryptographically downstream). The worker already provides cors + tenant, so
-  // resourceRoutes uses a LITE app-shell (xss only); flushQueueWork() preserves
-  // the workerd flush-before-response the old shim ran after each handler.
-  const resourceRoutes = service.http.resourceRoutes as Hono;
+  // S3-CF Phase 1B: the single payment HTTP surface. Every payment `/api/*` request
+  // (business resource routes + non-proxy DID payment actions) that wasn't handled
+  // by a worker-owned route above is forwarded to the CORE full app via
+  // service.http.fetch. The core full pipeline owns cors/xss/csrf/i18n/cdn/context
+  // + the resource routes + the DID payment actions — there is no more LITE
+  // resourceRoutes dispatcher and no second surface.
+  //
+  // The worker stays the HOST GLUE: it injects the caller identity it resolved
+  // (caller RPC) as canonical x-user-* request headers — the core authenticate()
+  // reads those — and STRIPS any client-supplied x-user-* first so it can never be
+  // forged (component auth via x-component-sig is verified cryptographically
+  // downstream and left intact). Raw body bytes are forwarded unconsumed (the
+  // worker never reads the body here), preserving Stripe webhook signature fidelity
+  // through to the core webhook route. flushQueueWork() drains the workerd deferred
+  // queue work before responding.
   const USER_HEADERS = ['x-user-did', 'x-user-role', 'x-user-provider', 'x-user-fullname', 'x-user-wallet-os'];
   app.all('/api/*', async (c) => {
     const headers = new Headers(c.req.raw.headers);
@@ -1103,7 +1143,9 @@ function buildApp(env: Env): Hono<HonoEnv> {
       headers.set('x-user-fullname', encodeURIComponent(caller.displayName || ''));
       headers.set('x-user-wallet-os', '');
     }
-    const res = await resourceRoutes.fetch(new Request(c.req.raw, { headers }), c.env, c.executionCtx);
+    // No basePath: the standalone worker serves payment routes at the root /api/*,
+    // so the core full app matches them directly (raw bytes/headers carried verbatim).
+    const res = await service.http.fetch(new Request(c.req.raw, { headers }));
     await flushQueueWork(); // drain workerd deferred queue work before responding
     return res;
   });

package/cloudflare/wrangler.json

@@ -17,12 +17,6 @@
       "migrations_dir": "migrations"
     }
   ],
-  "kv_namespaces": [
-    {
-      "binding": "DID_CONNECT_KV",
-      "id": "ca0bd29c73864115b713e1db11d97cd2"
-    }
-  ],
   "services": [
     {
       "binding": "MEDIA_KIT",

package/cloudflare/wrangler.jsonc

@@ -17,12 +17,6 @@
       "database_id": "ea6c75d0-39b8-40cd-a0ae-a2062e77c4b9"
     }
   ],
-  "kv_namespaces": [
-    {
-      "binding": "DID_CONNECT_KV",
-      "id": "ca0bd29c73864115b713e1db11d97cd2"
-    }
-  ],
   "hyperdrive": [
     {
       "binding": "HYPERDRIVE",

package/cloudflare/wrangler.local-e2e.jsonc

@@ -16,7 +16,6 @@
       "migrations_dir": "migrations"
     }
   ],
-  "kv_namespaces": [{ "binding": "DID_CONNECT_KV", "id": "local-e2e-kv" }],
   "vars": {
     "APP_NAME": "Payment Kit",
     "APP_PID": "payment-kit-dev",

package/cloudflare/wrangler.staging.json

@@ -18,12 +18,6 @@
       "migrations_dir": "migrations"
     }
   ],
-  "kv_namespaces": [
-    {
-      "binding": "DID_CONNECT_KV",
-      "id": "a2c98f81bc974fcabc191766698d170f"
-    }
-  ],
   "services": [
     {
       "binding": "MEDIA_KIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.29.2",
+  "version": "1.29.4",
   "scripts": {
     "dev": "blocklet dev --open",
     "prelint": "npm run types",
@@ -49,7 +49,7 @@
     "@abtnode/cron": "^1.17.13-beta-20260613-094425-b81920c8",
     "@apple/app-store-server-library": "^3.1.0",
     "@arcblock/did": "^1.30.24",
-    "@arcblock/did-connect-js": "4.0.1-beta.6",
+    "@arcblock/did-connect-js": "^4.0.6",
     "@arcblock/did-connect-react": "^3.5.4",
     "@arcblock/did-connect-storage-nedb": "^1.8.0",
     "@arcblock/did-util": "^1.30.24",
@@ -61,9 +61,9 @@
     "@blocklet/error": "^0.3.5",
     "@blocklet/js-sdk": "^1.17.13-beta-20260613-094425-b81920c8",
     "@blocklet/logger": "^1.17.13-beta-20260613-094425-b81920c8",
-    "@blocklet/payment-broker-client": "1.29.2",
-    "@blocklet/payment-react": "1.29.2",
-    "@blocklet/payment-vendor": "1.29.2",
+    "@blocklet/payment-broker-client": "1.29.4",
+    "@blocklet/payment-react": "1.29.4",
+    "@blocklet/payment-vendor": "1.29.4",
     "@blocklet/sdk": "^1.17.13-beta-20260613-094425-b81920c8",
     "@blocklet/ui-react": "^3.5.4",
     "@blocklet/uploader": "^0.3.20",
@@ -135,7 +135,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.17.13-beta-20260613-094425-b81920c8",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.29.2",
+    "@blocklet/payment-types": "1.29.4",
     "@types/connect": "^3.4.38",
     "@types/debug": "^4.1.12",
     "@types/dotenv-flow": "^3.3.3",
@@ -183,5 +183,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "b4f9a33207cb2341638efff848a900087a18e6cf"
+  "gitHead": "ffde8059827d7688a7e5a1e65830912e9093bb7c"
 }

package/scripts/bootstrap-inject.ts

@@ -0,0 +1,166 @@
+// P2 (README D2 / F2) — runtime-neutral bootstrap helper.
+//
+// Parameterizes the formerly CF-only `cf-inject-blocklet` logic
+// (cloudflare/vite.config.ts) so the node arc build (vite.arc.config.ts) and the
+// CF build share ONE source for the build-time HTML bootstrap. The pure
+// functions `buildBootstrap` / `mergeRemote` are jest-assertable
+// (api/tests/bootstrap/bootstrap.spec.ts); `buildBootstrapScript` serializes
+// `mergeRemote` (via .toString()) into the inline <script> so the browser runs
+// the identical merge at runtime.
+//
+// D-3 (user-confirmed 2026-06-14) put this under blocklets/core/build/. That
+// path is .gitignored (`blocklets/core/.gitignore:13` — `build` = production
+// outputs), so the file could never be tracked there. It lives in scripts/
+// instead — same intent (under blocklets/core, adjacent to both vite configs,
+// zero cross-package dep, where build tooling already lives: jest.js,
+// build-clean.js) but tracked. Extension is `.ts` (not `.mjs`) so ts-jest can
+// unit-test the pure functions directly; both vite configs are `.ts` and import
+// it natively.
+
+// Source of truth: packages/react/src/libs/util.ts:33. Re-declared here to keep
+// this build helper free of the heavy browser util graph (the only thing the
+// build needs from it is the bare DID literal).
+export const PAYMENT_KIT_DID = 'z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk';
+
+export interface BootstrapOptions {
+  /** the host's UI mount prefix (node arc = '/.well-known/payment'; cf custom). */
+  uiPrefix: string;
+  /** PAYMENT_KIT_DID so getPrefix() (packages/react/src/libs/util.ts:87) takes
+   *  the `componentId === PAYMENT_KIT_DID` branch and resolves to uiPrefix. */
+  componentId: string;
+  /** root-exact `/__blocklet__.js?type=json` — NEVER under uiPrefix (T2.3). */
+  remoteBlockletUrl: string;
+  /** session service host (node arc = arc '/.well-known/service'); CF root-deploy
+   *  omits it so window.blocklet.serviceHost stays undefined (app.tsx falls back
+   *  to prefix — P5 T5.1). */
+  serviceHost?: string;
+  /** baked appUrl; defaults to window.location.origin at runtime when omitted. */
+  appUrl?: string;
+  /** keys the remote __blocklet__.js must NOT clobber (G3 — `prefix` included). */
+  localOnly?: string[];
+  /** host-owned extras merged into the base bootstrap (navigation, mountpoints). */
+  extra?: Record<string, any>;
+}
+
+// G3: `prefix` MUST be local-only so the app-root prefix from the remote
+// __blocklet__.js never overwrites the payment reserved prefix.
+const DEFAULT_LOCAL_ONLY = ['prefix', 'navigation', 'componentMountPoints'];
+
+/**
+ * Build the synchronous window.blocklet skeleton. Pure — no IO, no globals.
+ * Throws (T2.3 regression lock) when remoteBlockletUrl is not root-exact, so a
+ * misconfigured build fails loudly at build time instead of silently fetching
+ * `/.well-known/payment/__blocklet__.js` (inside the reserved prefix).
+ */
+export function buildBootstrap(opts: BootstrapOptions): Record<string, any> {
+  const { uiPrefix, componentId, remoteBlockletUrl, serviceHost, appUrl, extra } = opts;
+  const localOnly = opts.localOnly || DEFAULT_LOCAL_ONLY;
+
+  if (!remoteBlockletUrl.startsWith('/__blocklet__')) {
+    throw new Error(`remoteBlockletUrl must be root-exact (start with /__blocklet__), got: ${remoteBlockletUrl}`);
+  }
+  if (uiPrefix !== '/' && remoteBlockletUrl.startsWith(uiPrefix)) {
+    throw new Error(`remoteBlockletUrl must not fall under uiPrefix ${uiPrefix}: ${remoteBlockletUrl}`);
+  }
+
+  return {
+    prefix: uiPrefix,
+    groupPrefix: uiPrefix,
+    componentId,
+    serviceHost,
+    appUrl: appUrl || '',
+    remoteBlockletUrl,
+    localOnly,
+    // @blocklet/ui-react nav/dashboard iterate these with .forEach — default to []
+    // so a host that doesn't override via `extra` never crashes on undefined. They
+    // are in localOnly, so the remote __blocklet__.js merge can't clobber them
+    // (AUTH_SERVICE doesn't know this blocklet's nav / mount points).
+    navigation: [],
+    componentMountPoints: [],
+    ...(extra || {}),
+  };
+}
+
+/**
+ * Merge the remote per-app __blocklet__.js JSON onto the local bootstrap.
+ *
+ * SELF-CONTAINED (no module-scope refs) so `buildBootstrapScript` can embed it
+ * via `.toString()` and the browser runs the identical merge. Guards:
+ *   - localOnly keys (prefix/navigation/componentMountPoints) are never clobbered
+ *   - __proto__/constructor/prototype keys are dropped (prototype-pollution)
+ *   - string values are angle-bracket escaped (<,> → entities) — blocks tag
+ *     injection without corrupting URL query strings (& preserved)
+ *   - payloads > 256KB are refused (resource exhaustion)
+ */
+export function mergeRemote(
+  wb: Record<string, any>,
+  remote: Record<string, any>,
+  localOnlyArg?: string[]
+): Record<string, any> {
+  var localOnly = localOnlyArg || (wb && wb.localOnly) || ['prefix', 'navigation', 'componentMountPoints'];
+
+  if (remote && typeof remote === 'object') {
+    var size = 0;
+    try {
+      size = JSON.stringify(remote).length;
+    } catch (e) {
+      size = Infinity;
+    }
+    if (size > 256 * 1024) {
+      throw new Error('remote bootstrap payload too large (>256KB), refusing merge');
+    }
+  }
+
+  var out: Record<string, any> = {};
+  Object.keys(wb || {}).forEach(function (k) {
+    out[k] = wb[k];
+  });
+  Object.keys(remote || {}).forEach(function (k) {
+    if (k === '__proto__' || k === 'constructor' || k === 'prototype') return;
+    // componentId is a structural invariant (getPrefix's PAYMENT_KIT_DID branch),
+    // protected independently of the configurable localOnly list.
+    if (k === 'componentId') return;
+    if (localOnly.indexOf(k) !== -1) return;
+    var v = remote[k];
+    if (typeof v === 'string') {
+      v = v.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    }
+    out[k] = v;
+  });
+  return out;
+}
+
+/**
+ * Produce the inline <script> for transformIndexHtml. Bakes the validated
+ * buildBootstrap() result as the synchronous window.blocklet, then embeds
+ * mergeRemote (serialized) so the runtime XHR merge is the same code jest tests.
+ */
+export function buildBootstrapScript(opts: BootstrapOptions): string {
+  const wb = buildBootstrap(opts);
+  const initial = JSON.stringify(wb);
+  const remoteUrl = JSON.stringify(wb.remoteBlockletUrl);
+  return `<script>
+window.global = globalThis;
+if (!window.blocklet) {
+  window.blocklet = ${initial};
+  window.blocklet.appUrl = window.blocklet.appUrl || window.location.origin;
+}
+(function () {
+  try {
+    var xhr = new XMLHttpRequest();
+    var url = ${remoteUrl};
+    xhr.open('GET', url + (url.indexOf('?') === -1 ? '?' : '&') + '_t=' + Date.now(), false);
+    xhr.send();
+    if (xhr.status === 200) {
+      var remote = JSON.parse(xhr.responseText);
+      window.blocklet = (${mergeRemote.toString()})(window.blocklet, remote);
+      if (!window.blocklet.env) window.blocklet.env = {};
+      window.blocklet.env.appName = window.blocklet.appName || '';
+      window.blocklet.env.appDescription = window.blocklet.appDescription || '';
+      window.blocklet.env.appLogo = window.blocklet.appLogo || '';
+      window.blocklet.env.appUrl = window.blocklet.appUrl || '';
+    }
+  } catch (e) { /* ignore — fall back to sync bootstrap */ }
+})();
+</script>`;
+}

package/src/app.tsx

@@ -13,6 +13,7 @@ import { Navigate, Route, BrowserRouter as Router, Routes, useNavigate } from 'r
 import { joinURL } from 'ufo';
 
 import ErrorFallback from './components/error-fallback';
+import { resolveServiceHost } from './libs/service-host';
 import UserLayoutDefault from './components/layout/user';
 import UserLayoutCF from './components/layout/user-cf';
 import { TransitionProvider } from './components/progress-bar';
@@ -250,7 +251,7 @@ export default function WrappedApp() {
       <ToastProvider>
         <PaymentThemeProvider>
           <SessionProvider
-            serviceHost={prefix}
+            serviceHost={resolveServiceHost(prefix)}
             useSocket={!(window as any).blocklet?.cloudflareWorker}
             protectedRoutes={['/admin/*', '/customer/*', '/integrations/*'].map((item) => joinURL(prefix, item))}>
             <Router basename={prefix}>

package/src/libs/service-host.ts

@@ -0,0 +1,13 @@
+// P5 T5.1 (README D4 / F5) — resolve the SessionProvider serviceHost.
+//
+// arc injects window.blocklet.serviceHost (the arc /.well-known/service endpoint)
+// at build time via the P2 bootstrap. The blocklet-server form does NOT inject it,
+// so we fall back to the app prefix — TM-8 regression: zero behavior change for the
+// blocklet-server deploy (serviceHost stays = prefix exactly as before).
+//
+// Zero imports on purpose so the rule is unit-testable in a node jest env without
+// pulling the frontend React graph.
+export function resolveServiceHost(prefix: string): string {
+  const injected = (typeof window !== 'undefined' && (window as any)?.blocklet?.serviceHost) || '';
+  return injected || prefix;
+}