payment-kit 1.29.1 → 1.29.2

package/cloudflare/shims/blocklet-sdk/util-wallet.ts

@@ -0,0 +1,8 @@
+// CF shim for @blocklet/sdk/lib/util/wallet.
+//
+// DEAD on the CF path: the only importer is the csrf middleware (node-shell only;
+// see util-csrf.ts), which reads isDidWalletConnect to skip csrf for DID-wallet
+// requests. Never executes on the worker — a resolving stub is enough.
+export const isDidWalletConnect = (_userAgent?: string): boolean => false;
+
+export default { isDidWalletConnect };

package/cloudflare/shims/cron.ts

@@ -1,182 +1,62 @@
-// @abtnode/cron shim for CF Cron Triggers
+// @abtnode/cron shim for CF Cron Triggers (Phase 9, W2-1b).
 //
-// The real @abtnode/cron exports { init } where init({ context, jobs, onError }) registers jobs.
-// In CF Workers, we store the jobs and execute them via the scheduled() handler.
-//
-// The shim parses 6-field cron expressions (sec min hour day month weekday)
-// and only runs jobs whose schedule matches the current 5-minute window.
-
-type CronJob = {
-  name: string;
-  time: string;
-  fn: () => Promise<any> | any;
-  options?: { runOnInit?: boolean };
-};
+// The real @abtnode/cron exports { init } where init({ jobs, onError }) registers
+// jobs. In CF Workers we store the jobs and execute due ones from scheduled().
+// The cron-expression matcher + registry now live in the shared cron driver
+// (api/src/libs/drivers/cron.ts) so embedded and worker agree on when a job is
+// due; this file is the thin worker adapter that keeps the @abtnode/cron API.
+
+import {
+  createCronRegistry,
+  setCronDriver,
+  getCronDriver,
+  matchesCron,
+  shouldRunInWindow,
+} from '../../api/src/libs/drivers/cron';
+
+// D2: crons/index.ts now registers through getCronDriver() instead of importing
+// @abtnode/cron directly. On CF this shim is the active cron driver, so make the
+// cf-cron registry the global driver at module load — BEFORE worker.ts calls
+// crons.init(). That keeps crons.init()'s register() and this shim's runAll() on
+// the SAME passive cf-cron registry (host drives runDue from scheduled(); no
+// @abtnode/cron self-scheduling timer is ever created in the frozen isolate).
+const registry = createCronRegistry('cf-cron');
+setCronDriver(registry);
 
 type InitOptions = {
   context?: any;
-  jobs: CronJob[];
+  jobs: Array<{ name: string; time: string; fn: () => Promise<any> | any; options?: { runOnInit?: boolean } }>;
   onError?: (error: Error, name: string) => void;
 };
 
-// Singleton storage for registered cron jobs
-const registeredJobs: CronJob[] = [];
-let onErrorHandler: ((error: Error, name: string) => void) | undefined;
-
-// --- Cron expression matcher ---
-// Supports 6-field format: second minute hour dayOfMonth month dayOfWeek
-// Supports: numbers, *, */N, ranges (1-5), lists (1,3,5)
-
-function parseField(field: string, min: number, max: number): number[] | null {
-  // null means "match all"
-  if (field === '*') return null;
-
-  const values = new Set<number>();
-
-  for (const part of field.split(',')) {
-    // */N — every N
-    const stepMatch = part.match(/^\*\/(\d+)$/);
-    if (stepMatch) {
-      const step = parseInt(stepMatch[1], 10);
-      for (let i = min; i <= max; i += step) {
-        values.add(i);
-      }
-      continue;
-    }
-
-    // N-M — range
-    const rangeMatch = part.match(/^(\d+)-(\d+)$/);
-    if (rangeMatch) {
-      const from = parseInt(rangeMatch[1], 10);
-      const to = parseInt(rangeMatch[2], 10);
-      for (let i = from; i <= to; i++) {
-        values.add(i);
-      }
-      continue;
-    }
-
-    // N — single value
-    const num = parseInt(part, 10);
-    if (!isNaN(num)) {
-      values.add(num);
-    }
-  }
-
-  return values.size > 0 ? Array.from(values) : null;
-}
-
-/**
- * Check if a date matches a 6-field cron expression.
- * Returns true if the date's minute/hour/day/month/weekday match.
- * Seconds field is ignored (CF triggers are minute-level).
- */
-function matchesCron(cronExpr: string, date: Date): boolean {
-  const fields = cronExpr.trim().split(/\s+/);
-  if (fields.length < 5) return true; // Can't parse — run it
-
-  // 6-field: sec min hour dom month dow
-  // 5-field: min hour dom month dow
-  const offset = fields.length >= 6 ? 1 : 0;
-
-  const minuteField = parseField(fields[offset], 0, 59);
-  const hourField = parseField(fields[offset + 1], 0, 23);
-  const domField = parseField(fields[offset + 2], 1, 31);
-  const monthField = parseField(fields[offset + 3], 0, 11); // cron months are 1-12, JS is 0-11
-  const dowField = parseField(fields[offset + 4], 0, 6);
-
-  const m = date.getUTCMinutes();
-  const h = date.getUTCHours();
-  const dom = date.getUTCDate();
-  const month = date.getUTCMonth() + 1; // JS 0-based → cron 1-based
-  const dow = date.getUTCDay(); // 0=Sunday
-
-  if (minuteField && !minuteField.includes(m)) return false;
-  if (hourField && !hourField.includes(h)) return false;
-  if (domField && !domField.includes(dom)) return false;
-  if (monthField && !monthField.includes(month)) return false;
-  if (dowField && !dowField.includes(dow)) return false;
-
-  return true;
-}
-
-// Check if a cron expression should fire at the given date (minute-level match).
-//
-// History: this helper previously used a 5-minute look-ahead window, under the
-// assumption that CF Cron Triggers fire every 5 minutes. Once the deploy config
-// switched to every-minute cron, that window made every stepped expression fire
-// 5x more often than intended, driving CF Queues past the free-tier daily cap
-// (2026-04-17 incident). With CF Scheduled firing every minute, we only check
-// the current minute — each cron expression triggers at its designed frequency.
-// See docs/cf-queues-ops-alert-analysis.md § 改动 B.
-function shouldRunInWindow(cronExpr: string, date: Date): boolean {
-  return matchesCron(cronExpr, date);
-}
-
-// --- Cron shim API ---
-
 function init(options: InitOptions) {
-  registeredJobs.length = 0;
-  onErrorHandler = options.onError;
-
-  for (const job of options.jobs || []) {
-    if (job.name && job.time && typeof job.fn === 'function') {
-      registeredJobs.push(job);
-    }
-  }
-
-  // Skip runOnInit jobs in CF Workers — they'll run on the next matching trigger
-  // (running them at module init time would block the request and may exceed CPU limits)
-
+  registry.register(options.jobs || [], options.onError);
+  // runOnInit jobs are skipped in CF Workers — they run on the next matching
+  // trigger (running them at module init would block the request / risk CPU limits)
   return {
     addJob(name: string, time: string, fn: Function, opts?: any) {
-      registeredJobs.push({ name, time, fn: fn as any, options: opts });
+      registry.addJob(name, time, fn as any, opts);
+    },
+    start() {
+      /* no-op — CF scheduled() drives runAll */
     },
-    start() { /* no-op */ },
   };
 }
 
-// Called by worker.ts scheduled handler — only runs jobs matching the trigger time.
-// Accepts an optional `now` so the caller can pass `event.scheduledTime` (the
-// intended trigger minute) instead of relying on wall-clock at execution time.
-// CF may deliver scheduled events with a small delay that crosses a minute
-// boundary; matching on `scheduledTime` keeps exact-minute cron reliable.
+// Called by worker.ts scheduled handler. Accepts an optional `now` so the caller
+// can pass `event.scheduledTime` (the intended trigger minute).
 async function runAll(now: Date = new Date()) {
-  const matched: string[] = [];
-  const skipped: string[] = [];
-
-  for (const job of registeredJobs) {
-    if (shouldRunInWindow(job.time, now)) {
-      matched.push(job.name);
-      try {
-        await job.fn();
-      } catch (err: any) {
-        console.error(`[Cron] ${job.name} failed:`, err?.message || err);
-        onErrorHandler?.(err, job.name);
-      }
-    } else {
-      skipped.push(job.name);
-    }
-  }
-
-  console.log(`[Cron] Ran ${matched.length} jobs: [${matched.join(', ')}]. Skipped ${skipped.length}.`);
+  const { ran, skipped } = await getCronDriver().runDue(now);
+  // eslint-disable-next-line no-console
+  console.log(`[Cron] Ran ${ran.length} jobs: [${ran.join(', ')}]. Skipped ${skipped.length}.`);
 }
 
 async function runJob(name: string) {
-  const job = registeredJobs.find((j) => j.name === name);
-  if (job) {
-    try {
-      await job.fn();
-    } catch (err: any) {
-      console.error(`[Cron] ${name} failed:`, err?.message || err);
-      onErrorHandler?.(err, name);
-    }
-  } else {
-    console.warn(`[Cron] Job ${name} not found`);
-  }
+  await getCronDriver().runJob(name);
 }
 
 function getJobNames(): string[] {
-  return registeredJobs.map((j) => `${j.name} (${j.time})`);
+  return getCronDriver().getJobNames();
 }
 
 // Export matching @abtnode/cron API: default export is { init }

package/cloudflare/shims/events.ts

@@ -0,0 +1,124 @@
+// EventEmitter shim for CF Workers.
+//
+// workerd's nodejs_compat provides `node:events` for ESM `import from 'events'`,
+// but the esbuild banner's globalThis.require polyfill (build.ts) does NOT list
+// `events`, so CJS `const { EventEmitter } = require('events')` resolves to an
+// empty object and `class X extends EventEmitter` throws at global init
+// ("Class extends value undefined"). Two core drivers hit this:
+//   - api/src/libs/drivers/locks.ts   (MemoryLock)
+//   - api/src/libs/drivers/auth-storage.ts (DbAuthStorage extends EventEmitter)
+//
+// Aliasing `events` to this shim (build.ts) makes BOTH the CJS-require and
+// ESM-import forms resolve to one deterministic implementation, removing the
+// fragile split between nodejs_compat (ESM) and the banner (CJS). Only the core
+// queue/lock/auth-storage event buses use it — emit / on / once / removeListener
+// are the methods exercised (verified by grep), so a compact but correct
+// implementation suffices.
+
+type Listener = (...args: any[]) => void;
+
+export class EventEmitter {
+  private _events: Map<string | symbol, Listener[]> = new Map();
+
+  private _maxListeners = 10;
+
+  addListener(event: string | symbol, listener: Listener): this {
+    return this.on(event, listener);
+  }
+
+  on(event: string | symbol, listener: Listener): this {
+    const list = this._events.get(event);
+    if (list) {
+      list.push(listener);
+    } else {
+      this._events.set(event, [listener]);
+    }
+    return this;
+  }
+
+  prependListener(event: string | symbol, listener: Listener): this {
+    const list = this._events.get(event);
+    if (list) {
+      list.unshift(listener);
+    } else {
+      this._events.set(event, [listener]);
+    }
+    return this;
+  }
+
+  once(event: string | symbol, listener: Listener): this {
+    const wrapper = (...args: any[]) => {
+      this.removeListener(event, wrapper);
+      listener.apply(this, args);
+    };
+    // keep a handle to the original so removeListener(event, listener) still works
+    (wrapper as any).listener = listener;
+    return this.on(event, wrapper);
+  }
+
+  prependOnceListener(event: string | symbol, listener: Listener): this {
+    const wrapper = (...args: any[]) => {
+      this.removeListener(event, wrapper);
+      listener.apply(this, args);
+    };
+    (wrapper as any).listener = listener;
+    return this.prependListener(event, wrapper);
+  }
+
+  removeListener(event: string | symbol, listener: Listener): this {
+    const list = this._events.get(event);
+    if (!list) return this;
+    const idx = list.findIndex((l) => l === listener || (l as any).listener === listener);
+    if (idx >= 0) {
+      list.splice(idx, 1);
+      if (list.length === 0) this._events.delete(event);
+    }
+    return this;
+  }
+
+  off(event: string | symbol, listener: Listener): this {
+    return this.removeListener(event, listener);
+  }
+
+  removeAllListeners(event?: string | symbol): this {
+    if (event === undefined) {
+      this._events.clear();
+    } else {
+      this._events.delete(event);
+    }
+    return this;
+  }
+
+  emit(event: string | symbol, ...args: any[]): boolean {
+    const list = this._events.get(event);
+    if (!list || list.length === 0) return false;
+    // copy so once()-removals during iteration don't skip listeners
+    for (const listener of [...list]) {
+      listener.apply(this, args);
+    }
+    return true;
+  }
+
+  listeners(event: string | symbol): Listener[] {
+    return [...(this._events.get(event) || [])];
+  }
+
+  listenerCount(event: string | symbol): number {
+    return this._events.get(event)?.length || 0;
+  }
+
+  eventNames(): (string | symbol)[] {
+    return [...this._events.keys()];
+  }
+
+  setMaxListeners(n: number): this {
+    this._maxListeners = n;
+    return this;
+  }
+
+  getMaxListeners(): number {
+    return this._maxListeners;
+  }
+}
+
+export default EventEmitter;

package/cloudflare/shims/fastq.ts

@@ -12,7 +12,21 @@
 
 type Task = { data: any; cb?: Function };
 
-export default function fastq(_context: any, worker: Function, _concurrency: number) {
+// Phase 9 (W2-1b): faithful fastq executor driver for the worker.
+//
+// Match the real fastq calling convention. The Node queue engine
+// (api/src/libs/queue) calls `fastq(workerFn, concurrency)` (2-arg form);
+// real fastq detects a function first arg and shifts (context => null). The
+// previous shim assumed the 3-arg `fastq(context, worker, concurrency)` form,
+// so the 2-arg call landed `worker` on `context` and every job execution threw
+// "worker is not a function". This shift makes the shim a drop-in executor so
+// the SAME engine runs identically on Node (real fastq) and the worker (shim).
+export default function fastq(context: any, worker: Function, concurrency: number) {
+  if (typeof context === 'function') {
+    concurrency = worker as unknown as number;
+    worker = context;
+    context = null;
+  }
   const pending: Task[] = [];
   let running = false;
   let drainFn: (() => void) | null = null;

package/cloudflare/shims/nedb-storage.ts

@@ -1,9 +1,17 @@
-// NeDB → D1 storage shim for DID Connect sessions
-export default class AuthStorage {
-  constructor(_opts?: any) {}
-  create(_id: string, _data: any) { return Promise.resolve(); }
-  read(_id: string) { return Promise.resolve(null); }
-  update(_id: string, _data: any) { return Promise.resolve(); }
-  delete(_id: string) { return Promise.resolve(); }
-  on(_event: string, _fn: Function) {}
+// NeDB → D1 storage shim for DID Connect sessions (Phase 8, W2-1a).
+//
+// Was a no-op stub (DID Connect state silently dropped in the worker). Now a
+// thin worker adapter: it builds a D1 db driver from the bound D1 database and
+// delegates to the real, contract-tested DbAuthStorage. The `{ dbPath }` option
+// is ignored — persistence is the D1 binding, not a disk file.
+
+import { createD1DbDriver, DbAuthStorage } from '../../api/src/libs/drivers';
+
+import { getDB } from './sequelize-d1/model';
+
+export default class AuthStorage extends DbAuthStorage {
+  constructor(_opts?: any) {
+    // lazy getter — the D1 binding is set per request, not at module import
+    super(createD1DbDriver(() => getDB()));
+  }
 }

package/cloudflare/shims/xss.ts

@@ -1,3 +1,11 @@
 export function xss(_opts?: any) {
   return (_req: any, _res: any, next: any) => next();
 }
+
+// Phase 4 (express→hono): the hono xss middleware (LITE app-shell on CF) calls
+// initSanitize(...)(body) to produce sanitizedBody. The old express-compat worker
+// path set req.body WITHOUT xss sanitization, so an identity sanitizer preserves
+// the worker's exact behavior (the node host uses the real @blocklet/xss).
+export function initSanitize(_opts?: any) {
+  return <T>(body: T): T => body;
+}

package/cloudflare/tenant-middleware.ts

@@ -0,0 +1,36 @@
+// Phase 7 (W1′): worker tenant-context wiring.
+//
+// The CF worker's `*` middleware only set up DB/env — it never established a
+// tenant context, so every TenantModel query in the worker fell back to the
+// single-mode default. This Hono middleware mirrors the Express
+// `contextMiddleware`: it resolves the request's raw Host to a tenant via the
+// SINGLE-POINT resolver (`resolveTenantForHost`) and wraps the downstream chain
+// in `context.withTenant` so the resolved tenant flows through AsyncLocalStorage
+// into every handler/query.
+//
+// single mode: resolves to the deployment app DID (standalone worker unchanged).
+// multi mode : unknown/missing Host -> 400 fail-closed, no default-tenant
+// fallback, and the handler never runs.
+
+import type { Context, Next } from 'hono';
+
+import { context } from '../api/src/libs/context';
+import { TenantError, TENANT_HOST_UNRESOLVED } from '../api/src/libs/tenant';
+import { resolveTenantForHost } from '../api/src/libs/drivers/identity';
+
+export function tenantMiddleware() {
+  return async (c: Context, next: Next) => {
+    let instanceDid: string;
+    try {
+      // raw Host header only — never a proxy header (X-Forwarded-Host); the CF
+      // route is responsible for ensuring it cannot be forged by the client.
+      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.withTenant(instanceDid, () => next());
+  };
+}

package/cloudflare/tests/tenant-middleware.spec.ts

@@ -0,0 +1,160 @@
+// Phase 7 (W1′): worker `withTenant` wiring. The CF worker had no tenant
+// context — its `*` middleware only `setDB`. This drives the real Hono tenant
+// middleware (the same factory mounted in worker.ts) over a tiny Hono app so
+// the actual Host -> instanceDid resolution, multi-mode fail-closed 4xx, and
+// `context.withTenant` ALS wrapping are exercised end to end.
+
+import { Hono } from 'hono';
+
+import { tenantMiddleware } from '../tenant-middleware';
+import { getInstanceDid, context } from '../../api/src/libs/context';
+import { getDefaultInstanceDid } from '../../api/src/libs/tenant';
+import { setIdentityDriver, createDefaultIdentityDriver, type IdentityDriver } from '../../api/src/libs/drivers/identity';
+
+const TENANT_A = 'did:abt:zHOSTA';
+const TENANT_B = 'did:abt:zHOSTB';
+
+// Build a Hono app wired exactly like worker.ts: tenant middleware on /api/*,
+// then a handler that reports the tenant resolved from the ALS context.
+function buildApp() {
+  const app = new Hono();
+  app.use('/api/*', tenantMiddleware());
+  app.get('/api/whoami', (c) => c.json({ tenant: getInstanceDid() }));
+  // /health is OUTSIDE /api/* — must never require a tenant (infra health check)
+  app.get('/health', (c) => c.json({ status: 'ok' }));
+  return app;
+}
+
+async function get(app: Hono, path: string, headers: Record<string, string> = {}) {
+  const res = await app.request(path, { headers });
+  let body: any;
+  try {
+    body = await res.json();
+  } catch {
+    body = await res.text();
+  }
+  return { status: res.status, body };
+}
+
+const ORIGINAL_MODE = process.env.PAYMENT_TENANT_MODE;
+
+afterEach(() => {
+  if (ORIGINAL_MODE === undefined) delete process.env.PAYMENT_TENANT_MODE;
+  else process.env.PAYMENT_TENANT_MODE = ORIGINAL_MODE;
+  setIdentityDriver(createDefaultIdentityDriver());
+});
+
+describe('single mode (standalone worker legacy) — unchanged', () => {
+  beforeEach(() => {
+    process.env.PAYMENT_TENANT_MODE = 'single';
+  });
+
+  it('any host resolves to the deployment app DID', async () => {
+    const expected = getDefaultInstanceDid();
+    const app = buildApp();
+    const r1 = await get(app, '/api/whoami', { Host: 'anything.example.com' });
+    expect(r1.status).toBe(200);
+    expect(r1.body.tenant).toBe(expected);
+    const r2 = await get(app, '/api/whoami', { Host: 'other.example.com' });
+    expect(r2.body.tenant).toBe(expected); // default regardless of host
+  });
+
+  it('a request with no Host still resolves (single-mode default, no crash)', async () => {
+    const expected = getDefaultInstanceDid();
+    const app = buildApp();
+    const r = await get(app, '/api/whoami');
+    expect(r.status).toBe(200);
+    expect(r.body.tenant).toBe(expected);
+  });
+});
+
+describe('multi mode — Host maps to tenant, fail-closed on unknown', () => {
+  const identity: IdentityDriver = {
+    resolveInstanceDidForHost(host) {
+      if (host === 'a.example.com') return TENANT_A;
+      if (host === 'b.example.com') return TENANT_B;
+      return null;
+    },
+  };
+
+  beforeEach(() => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    setIdentityDriver(identity);
+  });
+
+  // Happy path — two hosts see two tenants (data isolation)
+  it('two hosts resolve to two tenants', async () => {
+    const app = buildApp();
+    const a = await get(app, '/api/whoami', { Host: 'a.example.com' });
+    const b = await get(app, '/api/whoami', { Host: 'b.example.com' });
+    expect(a.body.tenant).toBe(TENANT_A);
+    expect(b.body.tenant).toBe(TENANT_B);
+    expect(a.body.tenant).not.toBe(b.body.tenant);
+  });
+
+  // Bad input — missing Host fails closed (no default-tenant fallback)
+  it('missing Host fails closed with 4xx (no APP_PID fallback)', async () => {
+    const app = buildApp();
+    const r = await get(app, '/api/whoami');
+    expect(r.status).toBe(400);
+    expect(r.body.error.code).toBe('TENANT_HOST_UNRESOLVED');
+    expect(r.body.tenant).toBeUndefined();
+  });
+
+  // Data leak — unknown (unregistered) host must never fall into a tenant
+  it('unknown host fails closed with 4xx + error code', async () => {
+    const app = buildApp();
+    const r = await get(app, '/api/whoami', { Host: 'unknown.example.com' });
+    expect(r.status).toBe(400);
+    expect(r.body.error.code).toBe('TENANT_HOST_UNRESOLVED');
+    expect(r.body.tenant).toBeUndefined();
+  });
+
+  // Security — a forged X-Forwarded-Host must not change resolution (raw Host only)
+  it('SECURITY: X-Forwarded-Host cannot override the raw Host', async () => {
+    const app = buildApp();
+    const r = await get(app, '/api/whoami', { Host: 'a.example.com', 'X-Forwarded-Host': 'b.example.com' });
+    expect(r.body.tenant).toBe(TENANT_A);
+  });
+
+  it('SECURITY: X-Forwarded-Host pointing at a known tenant cannot rescue an unknown raw Host', async () => {
+    const app = buildApp();
+    const r = await get(app, '/api/whoami', { Host: 'unknown.example.com', 'X-Forwarded-Host': 'a.example.com' });
+    expect(r.status).toBe(400);
+  });
+
+  // Data loss — a 4xx-rejected request must never reach the route handler
+  it('a 4xx-rejected request never runs the handler (no write)', async () => {
+    const app = new Hono();
+    app.use('/api/*', tenantMiddleware());
+    let handlerRuns = 0;
+    app.get('/api/whoami', (c) => {
+      handlerRuns += 1;
+      return c.json({ tenant: getInstanceDid() });
+    });
+    const r = await get(app, '/api/whoami', { Host: 'unknown.example.com' });
+    expect(r.status).toBe(400);
+    expect(handlerRuns).toBe(0);
+  });
+
+  // ALS propagation — the handler runs INSIDE the withTenant context
+  it('the handler observes the resolved tenant via context ALS', async () => {
+    const app = new Hono();
+    app.use('/api/*', tenantMiddleware());
+    let seen: string | undefined;
+    app.get('/api/whoami', (c) => {
+      seen = context.getInstanceDid();
+      return c.json({ ok: true });
+    });
+    await get(app, '/api/whoami', { Host: 'b.example.com' });
+    expect(seen).toBe(TENANT_B);
+  });
+
+  // /health is outside /api/* — tenant middleware must not gate it
+  it('/health is reachable without a Host even in multi mode', async () => {
+    const app = buildApp();
+    const r = await get(app, '/health');
+    expect(r.status).toBe(200);
+    expect(r.body.status).toBe('ok');
+  });
+});

package/cloudflare/tests/worker-handler-gate.spec.ts

@@ -0,0 +1,44 @@
+// Phase 12c HARD GATE (scan): the CF worker is a host adapter. It must mount the
+// embedded service's resource-route surface (svc.http.resourceRoutes) and NEVER
+// access svc.handler — whose lazy getter builds the node-only Express app shell
+// that does not belong under workerd. It also must not import the deleted legacy
+// shims/queue.ts duplicate engine. This statically scans the worker source so a
+// regression fails the suite (the runtime Proxy in ensurePaymentService is the
+// second line of defense).
+import fs from 'fs';
+import path from 'path';
+
+const workerSrc = fs.readFileSync(path.join(__dirname, '../worker.ts'), 'utf8');
+
+describe('Phase 12c — worker host-adapter hard gate', () => {
+  it('mounts the resource-route surface (svc.http.resourceRoutes)', () => {
+    expect(workerSrc).toMatch(/service\.http\.resourceRoutes/);
+  });
+
+  it('never reads .handler on the payment service', () => {
+    const offending = workerSrc
+      .split('\n')
+      .map((line, n) => ({ line: line.trim(), n: n + 1 }))
+      // ignore comment lines — only actual code may not read svc.handler
+      .filter(({ line }) => !line.startsWith('//') && !line.startsWith('*') && !line.startsWith('/*'))
+      .filter(({ line }) => /\b(service|paymentService|svc)\.handler\b/.test(line))
+      // the hard-gate trap string + the Proxy guard line are the gate itself
+      .filter(({ line }) => !/forbidden in the CF worker/.test(line) && !/prop === 'handler'/.test(line));
+    expect(offending).toEqual([]);
+  });
+
+  it('installs the runtime hard-gate Proxy that throws on handler access', () => {
+    expect(workerSrc).toMatch(/new Proxy\(svc,/);
+    expect(workerSrc).toMatch(/svc\.handler is forbidden in the CF worker/);
+  });
+
+  it('does not import the deleted legacy shims/queue engine', () => {
+    expect(workerSrc).not.toMatch(/from '\.\/shims\/queue'/);
+  });
+
+  it('drives the core queue runtime surface instead', () => {
+    expect(workerSrc).toMatch(/from '\.\.\/api\/src\/libs\/queue\/runtime'/);
+    expect(workerSrc).toMatch(/dispatchDueJobs\(\)/);
+    expect(workerSrc).toMatch(/flushQueueWork\(\)/);
+  });
+});