payment-kit 1.29.2 → 1.29.3

package/cloudflare/cf-adapter.ts

@@ -0,0 +1,419 @@
+// @arcblock/payment-service/cf — the Cloudflare host adapter (S3-CF Phase 2/3).
+//
+// This is the LIBRARY entry that did-pay pre-bundles (via packages/payment-core/
+// build-cf.mjs + the shared esbuild-cf-config alias table) into a self-contained,
+// re-bundleable `dist/cf.js`. A consumer (arc's CF worker) does:
+//
+//   import { createCloudflarePaymentAdapter } from "@arcblock/payment-service/cf";
+//   const payment = await createCloudflarePaymentAdapter({ ...host wiring... });
+//   export default { fetch: (req, env, ctx) => payment.fetch(req, env, ctx) };
+//
+// and needs ZERO alias / ZERO define / ZERO external of its own — every Node/server
+// dependency is already inlined behind worker-safe shims in this bundle.
+//
+// The adapter only does HOST GLUE (S3-CF README §Adapter 职责): it drives the
+// runtime-neutral core `http.fetch` (the single payment HTTP surface converged in
+// Phase 1), bridges the host's request-level tenant resolver into the core
+// IdentityDriver, injects the host-resolved caller as `x-user-did` (CF API gate —
+// decision #5, NO in-process login_token verify), lazily provisions a tenant on
+// first request (in-flight deduped), and drives scheduled due-dispatch + the CF
+// Queue consumer. It NEVER re-assembles routes or mounts DID-Connect by hand.
+
+// MUST be first: pin the core queue engine to 'workerd' mode BEFORE any business
+// queue module is constructed (createQueue reads the mode at import to disable the
+// node background poll loop a frozen isolate cannot run). ESM runs imported module
+// bodies in source order, so this side-effect import has to lead.
+import './queue-runtime-mode';
+
+// Register the queue handlers + cron jobs that are NOT transitively imported by the
+// route graph, so scheduled() due-dispatch and the queue consumer can resolve every
+// handle by name (mirrors worker.ts). Side-effect imports.
+import '../api/src/queues/refund';
+import '../api/src/queues/checkout-session';
+import '../api/src/queues/discount-status';
+import '../api/src/queues/exchange-rate-health';
+import '../api/src/queues/event';
+import '../api/src/queues/webhook';
+import crons from '../api/src/crons/index';
+
+import { createEmbeddedPaymentService } from '../api/src/service';
+import type { EmbeddedPaymentService } from '../api/src/service';
+import { context as requestContext } from '../api/src/libs/context';
+import {
+  createD1DbDriver,
+  createD1LocksDriver,
+  createKeyringSecretsDriver,
+  createCronRegistry,
+  applyPaymentCoreMigrations,
+} from '../api/src/libs/drivers';
+import type { IdentityDriver } from '../api/src/libs/drivers';
+import { flushQueueWork, dispatchDueJobs, getQueueHandler } from '../api/src/libs/queue/runtime';
+import { Sequelize } from './shims/sequelize-d1/sequelize-class';
+import { setDB } from './shims/sequelize-d1/model';
+import { withD1Retry } from './shims/sequelize-d1/retry';
+import { cronInstance } from './shims/cron';
+import { createCloudflareDidConnectRuntime, createCloudflareIdentityDriver } from './did-connect-runtime';
+
+/**
+ * The reserved mount prefix for the embedded payment service. The internal
+ * payment app serves `/api/*`; the host mounts it under this prefix and the
+ * adapter base-strips it before reaching the runtime-neutral core app.
+ */
+export const PAYMENT_PREFIX = '/.well-known/payment';
+
+/** A Cloudflare D1 binding (the subset the adapter touches). */
+export interface D1Binding {
+  withSession: (constraint?: string) => any;
+  prepare: (sql: string) => any;
+  batch: (statements: any[]) => Promise<any>;
+  exec: (sql: string) => Promise<any>;
+}
+
+/** The caller identity the host resolved (CF API gate — decision #5, no in-process login_token verify). */
+export interface CloudflareCallerIdentity {
+  did: string;
+  role?: string;
+  authMethod?: string;
+  displayName?: string;
+}
+
+/**
+ * The CF host-wire contract (S3-CF README §目标 Package Surface + decision #5).
+ *
+ * Deliberately has NO `sessionSecret`: on CF the caller identity is resolved by
+ * the host and injected as `x-user-did` (payment trusts that branch); payment does
+ * NOT verify `login_token` in-process (verify-session is a no-op shim). The csrf
+ * secret IS host-global (csrf runs before the tenant context).
+ *
+ * Also NO public `secrets` slot (decision #1): the keyring `SecretsDriver` is
+ * constructed INTERNALLY below from `identity.getAppEk`, so a consumer never wires
+ * a `SecretsDriver` or imports `@arcblock/payment-service/drivers`.
+ */
+export interface CloudflarePaymentAdapterOptions {
+  /** Mount prefix; base-stripped before the core app. Default `/.well-known/payment`. */
+  basePath?: string;
+  /** Runtime configuration (the config boundary — never raw process.env). */
+  config?: Record<string, any>;
+  /** The independent payment D1 binding (NOT arc/connect-service DB). */
+  db: { d1: D1Binding };
+  /** CF embed is always multi-tenant. */
+  tenancy?: { mode: 'multi' };
+  /** Request-level tenant resolver — delegates to arc's host→instanceDid mapping. */
+  tenant: {
+    resolve: (request: Request) => Promise<string | null> | string | null;
+  };
+  /** Per-tenant EK source (semantics aligned with arc-node: connect-service `app:ek` else derive). */
+  identity: {
+    getAppEk: (instanceDid: string) => Promise<string> | string;
+  };
+  /**
+   * Host-resolved caller (CF API gate). The adapter injects it as `x-user-did`
+   * before forwarding. Optional — when absent the request runs anonymous
+   * (client-forged identity is always stripped, so this is fail-safe).
+   */
+  caller?: {
+    resolve: (
+      request: Request,
+      instanceDid: string | null,
+    ) => Promise<CloudflareCallerIdentity | null> | CloudflareCallerIdentity | null;
+  };
+  /** Host-global csrf secret (NOT per-tenant). Injected via the config slot as PAYMENT_CSRF_SECRET. */
+  csrfSecret?: string;
+}
+
+/** The adapter the host drives. */
+export interface CloudflarePaymentAdapter {
+  /** Drive the single payment HTTP surface for a `/.well-known/payment/*` request. */
+  fetch: (request: Request, env: any, ctx: ExecutionContext) => Promise<Response>;
+  /** CF scheduled handler — host wires its `crons` to this; drives cron runAll + D1 due-dispatch. */
+  scheduled: (event: ScheduledEvent, env: any, ctx: ExecutionContext) => Promise<void>;
+  /** Optional CF Queue consumer — the host demuxes payment messages to this. */
+  queue: (batch: MessageBatch<any>, env: any, ctx: ExecutionContext) => Promise<void>;
+  /** Lazy per-tenant base-data provisioning (idempotent DB seed; no chain/Stripe calls). */
+  provisionTenant: (instanceDid: string) => Promise<void>;
+  /** Heavy per-tenant bootstrap (chain stake / Stripe / currency logo) — scheduled/enumeration ONLY, never first-request. */
+  bootstrapTenant: (instanceDid: string) => Promise<void>;
+  /**
+   * Idempotent deploy-time schema application (decision #4: driven by CI/wrangler at
+   * deploy, NOT per-request — a per-request auto-sync burns D1 rows_read). Applies the
+   * payment-core SQL migrations against PAYMENT_DB; cheap version check once applied.
+   */
+  ensureSchema: () => Promise<string[]>;
+}
+
+/** Client-forged identity headers — always stripped before the host injects the real caller. */
+const USER_HEADERS = ['x-user-did', 'x-user-role', 'x-user-provider', 'x-user-fullname', 'x-user-wallet-os'];
+
+/**
+ * CF API gate caller header glue (decision #5). STRIP any client-supplied
+ * `x-user-*` first (a forged `x-user-did` would be an auth bypass), then inject the
+ * host-resolved caller as canonical headers the core `authenticate()` trusts. No
+ * caller → the request runs anonymous (the strip already happened, so it is never
+ * forged). Mirrors the standalone worker's identical strip-then-inject.
+ */
+export function injectCaller(headers: Headers, caller: CloudflareCallerIdentity | null): void {
+  for (const h of USER_HEADERS) headers.delete(h);
+  if (!caller) return;
+  const canonicalDid = caller.did?.startsWith('did:abt:') ? caller.did : `did:abt:${caller.did}`;
+  headers.set('x-user-did', canonicalDid);
+  headers.set('x-user-role', `blocklet-${caller.role || 'guest'}`);
+  headers.set('x-user-provider', caller.authMethod === 'access-key' ? 'access-key' : caller.authMethod || 'wallet');
+  headers.set('x-user-fullname', encodeURIComponent(caller.displayName || ''));
+  headers.set('x-user-wallet-os', '');
+}
+
+/**
+ * Lazy per-tenant provisioning with in-flight dedup. Concurrent first-requests for
+ * the same tenant await the SAME provision() call — a Set would let a burst at
+ * isolate start double-seed before the DB idempotency guard commits. A resolved
+ * promise stays cached so later requests are instant; a FAILED provision is dropped
+ * so the next request retries. Null tenant is a no-op. Copied from the node witness
+ * (runtimes/node/src/daemon/payment/index.ts:72-105).
+ */
+export function createTenantProvisioner(
+  provision: (instanceDid: string) => Promise<void>,
+): (instanceDid: string | null) => Promise<void> {
+  const inflight = new Map<string, Promise<void>>();
+  return (instanceDid) => {
+    if (!instanceDid) return Promise.resolve();
+    let p = inflight.get(instanceDid);
+    if (!p) {
+      p = provision(instanceDid).catch((err) => {
+        inflight.delete(instanceDid); // drop so the next request retries
+        throw err;
+      });
+      inflight.set(instanceDid, p);
+    }
+    return p;
+  };
+}
+
+/** Dependencies for the request handler (factored out so it is testable with a fake service). */
+export interface FetchDeps {
+  svc: Pick<EmbeddedPaymentService, 'http'>;
+  basePath: string;
+  resolveTenant: (request: Request) => Promise<string | null> | string | null;
+  resolveCaller?: (
+    request: Request,
+    instanceDid: string | null,
+  ) => Promise<CloudflareCallerIdentity | null> | CloudflareCallerIdentity | null;
+  provision: (instanceDid: string | null) => Promise<void>;
+  bindEnv: (env: any, ctx: ExecutionContext, httpContext: boolean) => void;
+  flush: () => Promise<void>;
+}
+
+/** Build the request handler: strip+inject caller, lazy-provision, run http.fetch under the tenant context. */
+export function buildFetch(deps: FetchDeps) {
+  return async (request: Request, env: any, ctx: ExecutionContext): Promise<Response> => {
+    deps.bindEnv(env, ctx, true);
+
+    // Resolve the tenant from the real request (arc's host→instanceDid mapping).
+    const instanceDid = await deps.resolveTenant(request);
+
+    // Lazy first-request provisioning. Never block the request on a transient
+    // failure: provisionTenant is idempotent and the provisioner drops failures so
+    // the next request retries; a true missing-config surfaces downstream.
+    try {
+      await deps.provision(instanceDid);
+    } catch (err) {
+      console.error('[payment] lazy provisionTenant failed:', err);
+    }
+
+    // CF API gate: strip client-forged x-user-*, inject the host-resolved caller.
+    const caller = deps.resolveCaller ? await deps.resolveCaller(request, instanceDid) : null;
+    const headers = new Headers(request.headers);
+    injectCaller(headers, caller);
+    // new Request(request, { headers }) carries the raw body bytes UNCONSUMED — the
+    // adapter never reads the body, so the Stripe webhook signature stays intact.
+    const forwarded = new Request(request, { headers });
+
+    // Run the core under the tenant context. An unknown host (null) is NOT wrapped:
+    // the core's connect/context middleware then resolves via the identity driver,
+    // which returns null → TENANT_HOST_UNRESOLVED 4xx (multi-mode fail-closed). The
+    // bare health route still answers without a tenant.
+    const run = () => deps.svc.http.fetch(forwarded, { basePath: deps.basePath });
+    const res = instanceDid ? await requestContext.withTenant(instanceDid, run) : await run();
+
+    await deps.flush(); // drain workerd deferred queue work before responding
+    return res;
+  };
+}
+
+/** Dependencies for scheduled due-dispatch (factored out for testability). */
+export interface ScheduledDeps {
+  bindEnv: (env: any, ctx: ExecutionContext, httpContext: boolean) => void;
+  runCrons: (intendedMinute: Date) => Promise<void>;
+  dispatchDue: () => Promise<unknown>;
+  flush: () => Promise<void>;
+}
+
+/**
+ * Build the scheduled handler: run the cron jobs for the INTENDED minute
+ * (event.scheduledTime, not new Date() — a late delivery must not miss exact-minute
+ * crons), then the workerd trigger for the node queue engine's D1 due-job
+ * re-dispatch, then drain the re-pushed work before the isolate freezes.
+ */
+export function buildScheduled(deps: ScheduledDeps) {
+  return async (event: ScheduledEvent, env: any, ctx: ExecutionContext): Promise<void> => {
+    deps.bindEnv(env, ctx, false);
+    await deps.runCrons(new Date(event.scheduledTime));
+    await deps.dispatchDue();
+    await deps.flush();
+  };
+}
+
+/** A registered core queue handle (the subset the consumer drives). */
+interface QueueHandle {
+  pushAndWait: (params: { job: any; id: string; persist?: boolean }) => Promise<unknown>;
+}
+
+/** Dependencies for the CF Queue consumer (factored out for testability). */
+export interface QueueDeps {
+  bindEnv: (env: any, ctx: ExecutionContext, httpContext: boolean) => void;
+  getHandle: (queueName: string) => QueueHandle | undefined;
+  flush: () => Promise<void>;
+}
+
+/**
+ * Build the CF Queue consumer: resolve each message's core queue handle by name and
+ * run the job inline (persist:false — the D1 row already exists from the original
+ * push). Always ack: an unknown handler must not redeliver forever, and a failed
+ * job is owned by the D1 scheduled redispatch, NOT a CF Queue retry. The arc top
+ * level demuxes payment messages to this (decision #3) — it never sees the others.
+ */
+export function buildQueueConsumer(deps: QueueDeps) {
+  return async (batch: MessageBatch<any>, env: any, ctx: ExecutionContext): Promise<void> => {
+    deps.bindEnv(env, ctx, false);
+    for (const msg of batch.messages) {
+      const { queueName, jobId, job } = msg.body as { queueName: string; jobId: string; job: any };
+      const handle = deps.getHandle(queueName);
+      if (!handle) {
+        console.error(`[queue:consumer] no core queue registered for "${queueName}", acking`);
+        msg.ack();
+        continue;
+      }
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await handle.pushAndWait({ job, id: jobId, persist: false });
+        msg.ack();
+      } catch (err: any) {
+        console.error(`[queue:consumer] failed ${queueName}:${jobId}:`, err?.message || err);
+        msg.ack(); // D1 scheduled() will re-dispatch — do not retry via CF Queue
+      }
+    }
+    await deps.flush();
+  };
+}
+
+/**
+ * Build the Cloudflare payment adapter. Async to match the host-wire contract
+ * (`await createCloudflarePaymentAdapter(...)`). Constructs the embedded payment
+ * service ONCE; the D1 binding is rebound per request (CF env is per-request).
+ */
+export async function createCloudflarePaymentAdapter(
+  options: CloudflarePaymentAdapterOptions,
+): Promise<CloudflarePaymentAdapter> {
+  if (!options || typeof options !== 'object') {
+    throw new Error('createCloudflarePaymentAdapter: options object is required');
+  }
+  if (!options.db?.d1) {
+    throw new Error('createCloudflarePaymentAdapter: db.d1 (PAYMENT_DB binding) is required');
+  }
+  if (typeof options.tenant?.resolve !== 'function') {
+    throw new Error('createCloudflarePaymentAdapter: tenant.resolve(request) is required (multi-tenant)');
+  }
+  if (typeof options.identity?.getAppEk !== 'function') {
+    throw new Error('createCloudflarePaymentAdapter: identity.getAppEk(instanceDid) is required (multi-tenant)');
+  }
+
+  const basePath = options.basePath ?? PAYMENT_PREFIX;
+  const d1 = options.db.d1;
+
+  // The shim Sequelize is a thin model registry; the ACTUAL D1 binding is rebound
+  // per request via setDB() (CF env is per-request). Models bind to this instance
+  // at construction (createEmbeddedPaymentService → initialize).
+  const sequelize = new Sequelize();
+
+  // The core IdentityDriver: the host supplies the per-tenant EK; the DID-Connect
+  // signing identity (getInstanceAppIdentity) comes from the AUTH_SERVICE-backed CF
+  // driver (the arc binding is finalized in Phase 6). resolveInstanceDidForHost is
+  // a fail-closed fallback: the adapter pre-resolves the tenant per request and
+  // wraps the core call in withTenant, so this host-only bridge is never the
+  // authoritative path (a bare host string cannot reconstruct arc's request-level
+  // resolution — returning null fails closed rather than guessing).
+  const cfDidConnectIdentity = createCloudflareIdentityDriver();
+  const identity: IdentityDriver = {
+    resolveInstanceDidForHost: () => null,
+    getAppEk: (instanceDid: string) => options.identity.getAppEk(instanceDid),
+    getInstanceAppIdentity: cfDidConnectIdentity.getInstanceAppIdentity?.bind(cfDidConnectIdentity),
+    // per-tenant business wallet (single seam); directory stays the CF alias shim
+    getBusinessWallet: cfDidConnectIdentity.getBusinessWallet,
+  };
+
+  const svc: EmbeddedPaymentService = createEmbeddedPaymentService({
+    // Host-global csrf secret via the config boundary (payment-core's csrf reads
+    // PAYMENT_CSRF_SECRET through readConfig). NO sessionSecret (decision #5).
+    config: { ...(options.config ?? {}), ...(options.csrfSecret ? { PAYMENT_CSRF_SECRET: options.csrfSecret } : {}) },
+    db: { sequelize },
+    tenancy: { mode: 'multi' },
+    identity,
+    // not omittable: a multi-tenant host without the per-tenant keyring would fall
+    // back to a single process key (cross-tenant leak) — the factory fails closed.
+    secrets: createKeyringSecretsDriver(identity),
+    // D1-backed cross-isolate locks (the binding is read lazily at lock time).
+    locks: createD1LocksDriver(() => d1),
+    // passive cf-cron: never owns a timer; the host drives runDue from scheduled().
+    cron: createCronRegistry('cf-cron'),
+    // the converged CF DID-Connect runtime (real did-connect-js + D1 token store).
+    didConnectRuntime: createCloudflareDidConnectRuntime(),
+  });
+
+  // Per-request env setup: flush deferred init timers, expose env + waitUntil to
+  // the createEvent/global shims, and rebind the D1 session (first-primary read
+  // policy + transient-error retry). Mirrors the standalone worker's middleware.
+  const bindEnv = (env: any, ctx: ExecutionContext, httpContext: boolean) => {
+    if (typeof (globalThis as any).__flushDeferredTimers === 'function') {
+      (globalThis as any).__flushDeferredTimers();
+    }
+    (globalThis as any).__CF_ENV__ = env;
+    (globalThis as any).__cfHttpContext__ = httpContext;
+    (globalThis as any).__cfWaitUntil__ = (p: Promise<any>) => ctx.waitUntil(p);
+    setDB(withD1Retry((env.PAYMENT_DB ?? d1).withSession('first-primary')));
+  };
+
+  // Lazy first-request provisioning (light DB seed only — no chain/Stripe calls).
+  const provision = createTenantProvisioner((instanceDid) => svc.provisionTenant(instanceDid));
+
+  // cron jobs register once per isolate; runAll dispatches those due for the minute.
+  let cronsInitialized = false;
+  const runCrons = async (intendedMinute: Date) => {
+    if (!cronsInitialized) {
+      try {
+        crons.init();
+      } catch (err) {
+        console.error('[payment] cron init failed (non-fatal):', err);
+      }
+      cronsInitialized = true;
+    }
+    await cronInstance.runAll(intendedMinute);
+  };
+
+  return {
+    fetch: buildFetch({
+      svc,
+      basePath,
+      resolveTenant: (request) => options.tenant.resolve(request),
+      resolveCaller: options.caller ? (request, did) => options.caller!.resolve(request, did) : undefined,
+      provision,
+      bindEnv,
+      flush: flushQueueWork,
+    }),
+    scheduled: buildScheduled({ bindEnv, runCrons, dispatchDue: dispatchDueJobs, flush: flushQueueWork }),
+    queue: buildQueueConsumer({ bindEnv, getHandle: (name) => getQueueHandler(name), flush: flushQueueWork }),
+    provisionTenant: (instanceDid: string) => svc.provisionTenant(instanceDid),
+    bootstrapTenant: (instanceDid: string) => svc.bootstrapTenant(instanceDid),
+    // Deploy-time schema application (decision #4): idempotent SQL migrations against
+    // PAYMENT_DB, driven by CI/wrangler — never per-request.
+    ensureSchema: () => applyPaymentCoreMigrations(createD1DbDriver(d1)),
+  };
+}

package/cloudflare/did-connect-runtime.ts

@@ -0,0 +1,96 @@
+// S3-CF (DID convergence) — the Cloudflare DID-Connect runtime + identity driver.
+//
+// These are the CF host adapters that turn the shared core runtime
+// (createDidConnectJsRuntime) into a working CF DID-Connect surface:
+//   - createCloudflareDidConnectRuntime: real @arcblock/did-connect-js + the CF
+//     chain config / @ocap CBOR txEncoder / 30s timeout / chain pre-warm, with the
+//     tenant-aware D1 token store.
+//   - createCloudflareIdentityDriver: getInstanceAppIdentity via the AUTH_SERVICE
+//     binding (did-connect-service@4.0.3) with a short TTL cache; fail-closed.
+//
+// abt-wallet 4.20+ is dual-decode, so we use @ocap/client/encode's CBOR-only
+// txEncoder (drops ~300KB google-protobuf). fetchContext pre-warms the module
+// context cache at isolate init so the first merchant request doesn't eat the 8s
+// chain round-trip.
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { createTxEncoder, fetchContext } from '@ocap/client/encode';
+
+import type { IdentityDriver, InstanceAppIdentity } from '../api/src/libs/drivers';
+import { createDidConnectJsRuntime } from '../api/src/libs/did-connect/runtime-did-connect-js';
+import { createEmbeddedIdentityServices } from '../api/src/libs/did-connect/tenant-identity';
+import { CloudflareTenantTokenStorage } from './did-connect-token-storage';
+
+// Trailing slash REQUIRED (without it the host times out ~50% — verified 2026-04-20);
+// matches D1 payment_methods.settings.arcblock.api_host.
+const CHAIN_HOST = 'https://beta.abtnetwork.io/api/';
+
+let prewarmed = false;
+
+/** The CF DID-Connect runtime: real did-connect-js + CF chain/txEncoder/storage. */
+export function createCloudflareDidConnectRuntime() {
+  if (!prewarmed) {
+    prewarmed = true;
+    // Non-fatal: on failure the first real request retries via the encoder's own fetchContext.
+    fetchContext(CHAIN_HOST).catch((err: any) =>
+      console.warn('[did-connect] chain pre-warm failed:', err?.message || err)
+    );
+  }
+  return createDidConnectJsRuntime({
+    tokenStorage: new CloudflareTenantTokenStorage({ ttl: 300 }),
+    chainInfo: { type: 'arcblock', host: CHAIN_HOST, id: 'beta' },
+    txEncoder: createTxEncoder(),
+    timeout: 30000,
+    defaultAppInfo: {
+      name: 'Payment Kit',
+      description: 'Payment Kit on Cloudflare Workers',
+      icon: 'https://www.arcblock.io/favicon.ico',
+    },
+  });
+}
+
+/**
+ * The CF identity driver: per-instance app signing identity via the AUTH_SERVICE
+ * binding. Reads the request env from globalThis.__CF_ENV__ (the service binding is
+ * per-request). Short TTL cache to avoid an RPC per DID-Connect sign. Fail-closed
+ * when the binding or the identity is missing — never derives a key from env.APP_SK.
+ */
+export function createCloudflareIdentityDriver(): IdentityDriver {
+  const cache = new Map<string, { value: InstanceAppIdentity; expires: number }>();
+  const TTL_MS = 60_000;
+  const authService = (): any => (globalThis as any).__CF_ENV__?.AUTH_SERVICE;
+
+  return {
+    resolveInstanceDidForHost(host) {
+      const svc = authService();
+      if (svc && typeof svc.resolveInstanceDidForHost === 'function') {
+        return svc.resolveInstanceDidForHost(host ?? '');
+      }
+      return null;
+    },
+    getAppEk(instanceDid) {
+      const svc = authService();
+      if (!svc || typeof svc.getAppEk !== 'function') {
+        throw new Error('[did-connect] AUTH_SERVICE.getAppEk unavailable — fail-closed');
+      }
+      return svc.getAppEk(instanceDid);
+    },
+    async getInstanceAppIdentity(instanceDid: string): Promise<InstanceAppIdentity> {
+      const cached = cache.get(instanceDid);
+      if (cached && cached.expires > Date.now()) return cached.value;
+      const svc = authService();
+      if (!svc || typeof svc.getInstanceAppIdentity !== 'function') {
+        throw new Error('[did-connect] AUTH_SERVICE.getInstanceAppIdentity unavailable — fail-closed');
+      }
+      const value: InstanceAppIdentity = await svc.getInstanceAppIdentity(instanceDid);
+      if (!value || !value.appSk) {
+        throw new Error(`[did-connect] getInstanceAppIdentity returned no appSk for "${instanceDid}" — fail-closed`);
+      }
+      cache.set(instanceDid, { value, expires: Date.now() + TTL_MS });
+      return value;
+    },
+    // The per-tenant business wallet (derived from getInstanceAppIdentity via the
+    // shared resolver) — the single convergence seam. The `directory` is omitted:
+    // CF keeps its build-alias BlockletService shim (auth.ts falls back to it).
+    getBusinessWallet: createEmbeddedIdentityServices().getBusinessWallet,
+  };
+}

package/cloudflare/did-connect-token-storage.ts

@@ -0,0 +1,151 @@
+// S3-CF (DID convergence) — the CF DID-Connect token store, tenant-aware.
+//
+// Carries forward the proven standalone-worker behavior (the `_did_connect_tokens`
+// D1 table + first-primary read-your-writes + the `waitUntil` hack for the
+// fire-and-forget `update` that did-connect-js's onProcessError performs) and ADDS
+// per-tenant isolation: every record is stamped with the creating `instanceDid`
+// (from the TenantContext), and read/update/delete/exist reject a token whose
+// stored instanceDid != the current tenant's (treated as not-found). A token minted
+// under tenant A can never be read/advanced under tenant B's host.
+//
+// Isolation lives in the record JSON (no schema migration): the existing `data`
+// column already holds JSON, so we add an `instanceDid` field. Tokens are short-TTL
+// ephemeral sessions, so older untagged rows simply read as not-found under a tenant
+// once this ships — acceptable per the convergence plan (fail-closed, no migration).
+import { EventEmitter } from 'events';
+
+import { getInstanceDid } from '../api/src/libs/context';
+
+interface TokenRecord {
+  token: string;
+  status?: string;
+  instanceDid?: string;
+  [key: string]: any;
+}
+
+export class CloudflareTenantTokenStorage extends EventEmitter {
+  private ttl: number;
+
+  constructor(options: { ttl?: number } = {}) {
+    super();
+    this.ttl = options.ttl ?? 300;
+  }
+
+  private _getDB() {
+    const env = (globalThis as any).__CF_ENV__;
+    const db = env?.DB;
+    if (!db) {
+      console.error('[D1TokenStore] DB not available — __CF_ENV__ missing or no DB binding');
+      return db;
+    }
+    return db.withSession('first-primary');
+  }
+
+  /** The tenant whose context this storage op runs under. Throws (fail-closed) in
+   * multi mode without an established context — the caller is misrouted. */
+  private _tenant(): string {
+    return getInstanceDid();
+  }
+
+  /** Read the raw row, enforcing tenant isolation: a record stamped with a
+   * different instanceDid is invisible (treated as not-found). */
+  private async _readScoped(token: string): Promise<TokenRecord | null> {
+    const db = this._getDB();
+    if (!db) return null;
+    const now = Math.floor(Date.now() / 1000);
+    const row = await db
+      .prepare('SELECT data FROM _did_connect_tokens WHERE token = ? AND expires_at > ?')
+      .bind(token, now)
+      .first();
+    if (!row) return null;
+    const record = JSON.parse(row.data as string) as TokenRecord;
+    // tenant isolation: untagged (legacy) or cross-tenant tokens are not-found.
+    if (record.instanceDid !== this._tenant()) return null;
+    return record;
+  }
+
+  async create(token: string, status = 'created') {
+    try {
+      const db = this._getDB();
+      if (!db) throw new Error('DB not available');
+      const record: TokenRecord = { token, status, instanceDid: this._tenant() };
+      const expiresAt = Math.floor(Date.now() / 1000) + this.ttl;
+      await db
+        .prepare('INSERT OR REPLACE INTO _did_connect_tokens (token, data, expires_at) VALUES (?, ?, ?)')
+        .bind(token, JSON.stringify(record), expiresAt)
+        .run();
+      this.emit('create', record);
+      return record;
+    } catch (err: any) {
+      console.error('[D1TokenStore] create failed:', token, err?.message || err);
+      throw err;
+    }
+  }
+
+  async read(token: string) {
+    try {
+      return await this._readScoped(token);
+    } catch (err: any) {
+      console.error('[D1TokenStore] read failed:', token, err?.message || err);
+      return null;
+    }
+  }
+
+  update(token: string, updates: Record<string, any>) {
+    // did-connect-js's onProcessError calls tokenStorage.update WITHOUT awaiting
+    // (fire-and-forget). On workerd a non-awaited Promise is killed when the handler
+    // returns, so the UPDATE never lands and the token sticks at "scanned" forever
+    // (wallet UI loops on "validating…"). Register the write via ctx.waitUntil
+    // (exposed as __cfWaitUntil__) so the isolate stays alive until D1 acks,
+    // regardless of whether the caller awaits us. (Carried forward verbatim.)
+    const promise = (async () => {
+      try {
+        const existing = await this._readScoped(token); // tenant-scoped read
+        if (!existing) return null;
+        delete updates.token;
+        delete updates.instanceDid; // never let an update rewrite the owning tenant
+        const merged = { ...existing, ...updates };
+        const expiresAt = Math.floor(Date.now() / 1000) + this.ttl;
+        const db = this._getDB();
+        if (!db) throw new Error('DB not available');
+        await db
+          .prepare('UPDATE _did_connect_tokens SET data = ?, expires_at = ? WHERE token = ?')
+          .bind(JSON.stringify(merged), expiresAt, token)
+          .run();
+        this.emit('update', merged);
+        return merged;
+      } catch (err: any) {
+        console.error('[D1TokenStore] update failed:', token, err?.message || err);
+        throw err;
+      }
+    })();
+
+    const waitUntil = (globalThis as any).__cfWaitUntil__ as ((p: Promise<any>) => void) | undefined;
+    if (typeof waitUntil === 'function') {
+      waitUntil(promise.catch(() => {}));
+    }
+    return promise;
+  }
+
+  async delete(token: string) {
+    try {
+      const existing = await this._readScoped(token); // tenant-scoped
+      if (!existing) return; // cross-tenant / missing → no-op
+      this.emit('destroy', existing);
+      const db = this._getDB();
+      if (!db) return;
+      await db.prepare('DELETE FROM _did_connect_tokens WHERE token = ?').bind(token).run();
+    } catch (err: any) {
+      console.error('[D1TokenStore] delete failed:', token, err?.message || err);
+    }
+  }
+
+  async exist(token: string, did?: string) {
+    const record = await this._readScoped(token);
+    if (!record) return false;
+    if (did) return record.did === did;
+    return true;
+  }
+}
+
+export default CloudflareTenantTokenStorage;