payment-kit 1.29.1 → 1.29.3

package/api/dev.ts

@@ -1,10 +1,49 @@
+// Dev shell — express→hono Phase 4. Dev-only (NOT bundled into production:
+// tsconfig.api excludes api/dev.ts; the production entry is ./src → index.ts).
+//
+// Hosts the Vite client + HMR on a `connect` app and routes backend paths to the
+// hono service. `vite-plugin-blocklet`'s setupClient only knows `app.use(vite
+// .middlewares)`, so the dev shell hosts Vite on connect (NOT express — core is
+// express-free). Backend paths are routed to service.fetch EXPLICITLY by prefix:
+// a Web-Fetch 404 cannot call connect next(), so hono must never be the trailing
+// catch-all (that would swallow client routes the SPA fallback should serve).
+import { createServer } from 'http';
+
+import { getRequestListener } from '@hono/node-server';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import connect from 'connect';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { setupClient } from 'vite-plugin-blocklet';
 
-import { app, server } from './src';
+import { buildService, onListening } from './src/bootstrap';
+
+const { service, port } = buildService();
+
+// Hand backend paths to the hono app; everything else falls through to the Vite
+// middleware setupClient() mounts after this router.
+const honoListener = getRequestListener(service.fetch);
+const isBackendPath = (url: string): boolean => {
+  const pathname = url.split('?')[0] || '';
+  return pathname === '/api' || pathname.startsWith('/api/') || pathname.startsWith('/.well-known/');
+};
 
+const app = connect();
+app.use((req, res, next) => {
+  if (isBackendPath(req.url || '')) {
+    honoListener(req, res);
+    return;
+  }
+  next();
+});
+
+const server = createServer(app);
+
+// setupClient appends the Vite connect middleware (client assets + HMR + SPA
+// fallback) AFTER our backend router, and wires the HMR ws upgrade onto `server`.
 setupClient(app, {
   server,
-  // @ts-ignore
+  // @ts-ignore — import.meta.hot is injected by tsx/vite-node at runtime
   importMetaHot: import.meta.hot,
 });
+
+server.listen(port, () => onListening(service, port));

package/api/hono.d.ts

@@ -0,0 +1,42 @@
+// ContextVariableMap skeleton (Phase 0, express→hono migration).
+//
+// Mirrors the express `Request` augmentation in api/third.d.ts so that
+// `c.set(...)` / `c.get(...)` are typed everywhere across the migration. This
+// file only declares the key→type contract; the actual injection lands later:
+//   - user / customer / doc / customer_id  → Phase 1 (libs/security.ts)
+//   - locale / t                           → Phase 1 (libs/middleware.ts)
+//   - sanitizedBody                        → Phase 1 (forked xss middleware)
+//   - livemode / baseCurrency              → Phase 3 (routes/index.ts middleware)
+//   - stripeEvent / stripeClient           → Phase 3e (stripe verifyWebhookSig)
+//
+// Two keys exist only on the hono side (no express equivalent), because hono's
+// Request is immutable and cannot be rewritten in place the way express was:
+//   - sanitizedBody : xss is the single body read-point; routes read this, never
+//                     c.req.json() (a re-read would return the UN-sanitized
+//                     original — see design §7 security note).
+//   - customer_id   : security "mine" mode injects the verified customer id here
+//                     (express wrote req.query.customer_id =, impossible on hono).
+import 'hono';
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    user: {
+      did: string;
+      role: string;
+      provider: string;
+      fullName: string;
+      walletOS: string;
+      via?: string;
+    };
+    livemode: boolean;
+    locale: string;
+    t: (key: string, ...args: any[]) => string;
+    doc: any;
+    customer: any;
+    baseCurrency: any;
+    customer_id: string;
+    sanitizedBody: any;
+    stripeEvent: any;
+    stripeClient: any;
+  }
+}

package/api/node-sqlite.d.ts

@@ -0,0 +1,12 @@
+// Ambient declaration for node:sqlite (experimental, Node 22+). It exists at
+// runtime (the tests + schema-drift-guard run on a node that ships it) but
+// @types/node does not yet declare it, so tsc --noEmit fails to resolve the import.
+// Declared as a class so it works both as a value (`new DatabaseSync()`) and as a
+// type (`let db: DatabaseSync`). Typed loosely — test/tooling-only consumers.
+declare module 'node:sqlite' {
+  export class DatabaseSync {
+    constructor(path?: string, options?: any);
+
+    [key: string]: any;
+  }
+}

package/api/src/bootstrap.ts

@@ -0,0 +1,47 @@
+// Blocklet server service bootstrap — shared by the production entry
+// (./index.ts → api/dist/index.js) and the dev shell (../dev.ts).
+//
+// Phase 4 (express→hono): the listened surface is the hono app (service.fetch).
+// Production serves it directly via @hono/node-server. Dev hosts the Vite client
+// + HMR on a `connect` shell (../dev.ts) and routes backend paths to the same
+// service.fetch — so both entries build the service identically here and only
+// differ in HOW they put it behind a socket.
+
+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';
+
+export function buildService(): { service: EmbeddedPaymentService; port: number } {
+  const tenancy =
+    getTenantMode() === 'multi'
+      ? ({ mode: 'multi' } as const)
+      : ({ mode: 'single', instanceDid: getDefaultInstanceDid() } as const);
+
+  const service = createEmbeddedPaymentService({
+    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);
+  return { service, port };
+}
+
+/** Start background services once the socket is bound (the listen callback). */
+export function onListening(service: EmbeddedPaymentService, port: number): void {
+  logger.info(`> payment-kit ready on ${port}`);
+  service.lifecycle.start().catch((startErr) => logger.error('failed to start background services', startErr));
+}

package/api/src/crons/base.ts

@@ -175,7 +175,7 @@ export abstract class BaseSubscriptionScheduleNotification<Options extends any>
     await pAll(
       deleteTasks.map((task) => () => task()),
       {
-        concurrency: notificationCronConcurrency,
+        concurrency: notificationCronConcurrency(),
         stopOnError: false,
       }
     );
@@ -192,7 +192,7 @@ export abstract class BaseSubscriptionScheduleNotification<Options extends any>
         };
       }),
       {
-        concurrency: notificationCronConcurrency,
+        concurrency: notificationCronConcurrency(),
         stopOnError: false,
       }
     );
@@ -231,7 +231,7 @@ export abstract class BaseSubscriptionScheduleNotification<Options extends any>
     );
 
     await pAll(deletePromises, {
-      concurrency: notificationCronConcurrency,
+      concurrency: notificationCronConcurrency(),
       stopOnError: false,
     });
   }

package/api/src/crons/currency.ts

@@ -1,5 +1,5 @@
 import { Op } from 'sequelize';
-import { getUrl } from '@blocklet/sdk';
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { PaymentMethod, PaymentCurrency } from '../store/models';
 import logger from '../libs/logger';
 

package/api/src/crons/index.ts

@@ -1,4 +1,4 @@
-import Cron from '@abtnode/cron';
+import { getCronDriver } from '../libs/drivers/cron';
 
 import { checkStakeRevokeTx } from '../integrations/arcblock/stake';
 import { runIapReconcile } from '../integrations/iap-reconcile';
@@ -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';
@@ -63,30 +64,33 @@ function init() {
           },
         ]
       : [];
-  Cron.init({
-    context: {},
-    jobs: [
+  // D2: register through the injected cron driver (no bare @abtnode/cron). On
+  // the node host the driver self-schedules via @abtnode/cron; on CF the host
+  // drives runDue() from scheduled(). register() is idempotent (clears + re-adds
+  // + restarts the scheduler), so a stop()/start() cycle never double-registers.
+  getCronDriver().register(
+    [
       {
         name: 'subscription.will.renew',
-        time: notificationCronTime,
-        fn: () => new SubscriptionWillRenewSchedule().run(),
+        time: notificationCronTime(),
+        fn: perTenant('subscription.will.renew', () => new SubscriptionWillRenewSchedule().run()),
         options: { runOnInit: true },
       },
       {
         name: 'subscription.trial.will.end',
-        time: notificationCronTime,
-        fn: () => new SubscriptionTrialWillEndSchedule().run(),
+        time: notificationCronTime(),
+        fn: perTenant('subscription.trial.will.end', () => new SubscriptionTrialWillEndSchedule().run()),
         options: { runOnInit: true },
       },
       {
         name: 'customer.subscription.will_canceled',
-        time: notificationCronTime,
-        fn: () => new SubscriptionWillCanceledSchedule().run(),
+        time: notificationCronTime(),
+        fn: perTenant('customer.subscription.will_canceled', () => new SubscriptionWillCanceledSchedule().run()),
         options: { runOnInit: true },
       },
       {
         name: 'subscription.schedule.retry',
-        time: subscriptionCronTime,
+        time: subscriptionCronTime(),
         fn: startSubscriptionQueue,
         options: { runOnInit: false },
       },
@@ -101,35 +105,35 @@ function init() {
       },
       {
         name: 'checkoutSession.cleanup.expired',
-        time: expiredSessionCleanupCronTime,
-        fn: async () => {
+        time: expiredSessionCleanupCronTime(),
+        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,
+        time: stripeInvoiceCronTime(),
+        fn: perTenant('stripe.invoice.sync', batchHandleStripeInvoices),
         options: { runOnInit: false },
       },
       {
         name: 'stripe.payment.sync',
-        time: stripePaymentCronTime,
-        fn: batchHandleStripePayments,
+        time: stripePaymentCronTime(),
+        fn: perTenant('stripe.payment.sync', batchHandleStripePayments),
         options: { runOnInit: false },
       },
       {
         name: 'stripe.subscription.sync',
-        time: stripeSubscriptionCronTime,
-        fn: batchHandleStripeSubscriptions,
+        time: stripeSubscriptionCronTime(),
+        fn: perTenant('stripe.subscription.sync', batchHandleStripeSubscriptions),
         options: { runOnInit: false },
       },
       {
         name: 'customer.stake.revoked',
-        time: revokeStakeCronTime,
-        fn: checkStakeRevokeTx,
+        time: revokeStakeCronTime(),
+        fn: perTenant('customer.stake.revoked', checkStakeRevokeTx),
         options: { runOnInit: false },
       },
       {
@@ -137,8 +141,8 @@ function init() {
         // subscription state and patches local drift (refunds/renewals the
         // webhook missed). See blocklets/core/api/src/integrations/iap-reconcile.ts.
         name: 'iap.reconcile',
-        time: iapReconcileCronTime,
-        fn: () => runIapReconcile(),
+        time: iapReconcileCronTime(),
+        fn: perTenant('iap.reconcile', () => runIapReconcile()),
         options: { runOnInit: false },
       },
       {
@@ -146,52 +150,52 @@ function init() {
         // with pending_webhooks>0 older than 60s and re-invokes handleEvent.
         // See blocklets/core/api/src/crons/retry-pending-events.ts.
         name: 'event.retry',
-        time: eventRetryCronTime,
-        fn: () => retryPendingEvents(),
+        time: eventRetryCronTime(),
+        fn: perTenant('event.retry', () => retryPendingEvents()),
         options: { runOnInit: false },
       },
       {
         name: 'payment.stat',
-        time: paymentStatCronTime,
-        fn: () => createPaymentStat(),
+        time: paymentStatCronTime(),
+        fn: perTenant('payment.stat', () => createPaymentStat()),
         options: { runOnInit: false },
       },
       {
         name: 'payment.daily.report',
-        time: overdueDetectionCronTime,
-        fn: () => createOverdueDetection(),
+        time: overdueDetectionCronTime(),
+        fn: perTenant('payment.daily.report', () => createOverdueDetection()),
         options: { runOnInit: false },
       },
       {
         name: 'deposit.vault',
-        time: depositVaultCronTime,
+        time: depositVaultCronTime(),
         fn: () => startDepositVaultQueue(),
         options: { runOnInit: true },
       },
       {
         name: 'credit.consumption',
-        time: creditConsumptionCronTime,
+        time: creditConsumptionCronTime(),
         fn: () => startCreditConsumeQueue(),
         options: { runOnInit: true },
       },
       {
         name: 'vendor.status.check',
-        time: vendorStatusCheckCronTime,
+        time: vendorStatusCheckCronTime(),
         fn: () => startVendorStatusCheckSchedule(),
         options: { runOnInit: false },
       },
       {
         name: 'vendor.return.scan',
-        time: vendorReturnScanCronTime,
+        time: vendorReturnScanCronTime(),
         fn: () => scheduleVendorReturnScan(),
         options: { runOnInit: false },
       },
       ...archiveJobs,
     ],
-    onError: (error: Error, name: string) => {
+    (error: Error, name: string) => {
       logger.error('run job failed', { name, error });
-    },
-  });
+    }
+  );
 }
 
 export default {

package/api/src/crons/metering-subscription-detection.ts

@@ -1,4 +1,4 @@
-import { Notification } from '@blocklet/sdk';
+import Notification from '@blocklet/sdk/service/notification';
 import { Op } from 'sequelize';
 import { env } from '@blocklet/sdk/lib/config';
 import dayjs from '../libs/dayjs';

package/api/src/crons/overdue-detection.ts

@@ -1,4 +1,4 @@
-import { Notification } from '@blocklet/sdk';
+import Notification from '@blocklet/sdk/service/notification';
 import { getUrl } from '@blocklet/sdk/lib/component';
 import { env } from '@blocklet/sdk/lib/config';
 import { fromUnitToToken, BN } from '@ocap/util';
@@ -175,7 +175,7 @@ export class HealthReportTemplate implements BaseEmailTemplate<HealthReportConte
           currencyTotals.set(currencyId, currentTotal.add(group.total));
 
           // Check if this user's pending exceeds threshold for this currency
-          const thresholdInUnit = new BN(overdueThreshold.toString()).mul(new BN(10).pow(new BN(currency.decimal)));
+          const thresholdInUnit = new BN(overdueThreshold().toString()).mul(new BN(10).pow(new BN(currency.decimal)));
           if (group.total.gt(thresholdInUnit)) {
             exceedsThreshold = true;
           }

package/api/src/crons/retry-pending-events.ts

@@ -33,6 +33,12 @@ const REALTIME_GRACE_SECONDS = 60;
 // generous headroom and we still drain the backlog over a few minutes.
 const BATCH_LIMIT = 5;
 
+// Phase 4 (W1-3): this scan is deliberately tenant-agnostic — it only
+// re-enqueues event IDs. Tenant enforcement happens downstream in
+// handleEvent's fanout (endpoints filtered by the event's instance_did) and
+// handleWebhook's event/endpoint tenant invariant. Events whose creation was
+// tenant-rejected never produced a row, so this backstop cannot "rescue"
+// them — permanent loss of rejected events is the intended semantic.
 export async function retryPendingEvents(): Promise<void> {
   const threshold = new Date(Date.now() - REALTIME_GRACE_SECONDS * 1000);
   const docs = await Event.findAll({

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;