payment-kit 1.29.1 → 1.29.3

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

@@ -6,15 +6,103 @@ import fastq from 'fastq';
 import { nanoid } from 'nanoid';
 
 import { AsyncLocalStorage } from 'async_hooks';
+import { isTestEnv } from '../env';
 import logger from '../logger';
-import { sleep, tryWithTimeout } from '../util';
+import { context, withTenant } from '../context';
+import {
+  TENANT_CONTEXT_MISSING,
+  TENANT_MISMATCH,
+  TenantError,
+  assertValidInstanceDid,
+  getDefaultInstanceDid,
+  getTenantMode,
+  resolveRowTenant,
+} from '../tenant';
+import { tryWithTimeout } from '../util';
 import dayjs from '../dayjs';
 import createQueueStore from './store';
+import { registerQueue, getQueueRuntimeMode, trackPending } from './runtime';
 import { Job } from '../../store/models/job';
 import { sequelize } from '../../store/sequelize';
 
 const CANCELLED = '__CANCELLED__';
-const MIN_DELAY = process.env.NODE_ENV === 'test' ? 2 : 8;
+// lazy so the injected config (set after import) is honored at call time
+const minDelay = (): number => (isTestEnv() ? 2 : 8);
+
+// ---------------------------------------------------------------------------
+// Phase 5 (W1-4a): generic queue tenant layer.
+// Every queue gets this uniformly — see docs/arc-integration/planning/w1-w2/
+// queue-matrix.md for the per-queue conclusions built on top of it.
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamp the active tenant into a job payload at enqueue time.
+ * - payload already carries instance_did: validated (and in multi mode it
+ *   must be a legal DID — a forged/illegal value is refused at the gate)
+ * - otherwise: the context tenant (single mode = app DID); multi mode
+ *   without context -> the push itself is rejected (fail-closed)
+ */
+function injectJobTenant(job: any): any {
+  if (!job || typeof job !== 'object') return job;
+  if (job.instance_did) {
+    assertValidInstanceDid(job.instance_did);
+    return job;
+  }
+  return { ...job, instance_did: context.getInstanceDid() };
+}
+
+/**
+ * Run a job handler inside its payload tenant. Legacy jobs persisted before
+ * Phase 5 have no instance_did: single mode falls back to the deployment
+ * default, multi mode refuses permanently (non-retryable + structured alert).
+ */
+// Warm the tenant identity then run the handler — the queue analogue of the HTTP
+// contextMiddleware warm. Signing queues (payment/refund/payout/...) access the
+// business wallet synchronously; warming inside the tenant span makes `wallet`/
+// `ethWallet` resolve to the job's tenant (no-op on blocklet-server).
+async function warmThenRun<T>(onJob: (job: T) => Promise<any>, job: T): Promise<any> {
+  const { warmTenantIdentity } =
+    // eslint-disable-next-line global-require
+    require('../did-connect/tenant-identity') as typeof import('../did-connect/tenant-identity');
+  await warmTenantIdentity();
+  return onJob(job);
+}
+
+function runJobWithTenant<T>(job: any, onJob: (job: T) => Promise<any>): Promise<any> {
+  const tenant = job?.instance_did;
+  if (tenant) {
+    return withTenant(tenant, () => warmThenRun(onJob, job));
+  }
+  if (getTenantMode() === 'single') {
+    return withTenant(getDefaultInstanceDid(), () => warmThenRun(onJob, job));
+  }
+  const err = new TenantError(TENANT_CONTEXT_MISSING, 'legacy job without tenant refused in multi mode');
+  (err as any).nonRetryable = true;
+  logger.error('[queue] legacy job without tenant refused', { code: TENANT_CONTEXT_MISSING, job });
+  return Promise.reject(err);
+}
+
+/**
+ * Handler-entry invariant for object-bound queues: the object loaded by id
+ * must belong to the payload tenant the handler is running under. A forged
+ * payload (tenant A, object of B) dies here permanently — nothing executes.
+ */
+export function assertJobObjectTenant(row: { instance_did?: string | null } | null | undefined): void {
+  if (!row) return; // absent objects are the handler's own no-op/warn path
+  const rowTenant = resolveRowTenant(row);
+  const jobTenant = context.getInstanceDid();
+  if (rowTenant !== jobTenant) {
+    // Phase 4 (W1-3): emit a structured violation alert BEFORE throwing, so a
+    // forged/mixed cross-tenant job is observable in logs (same dedicated code
+    // as the W1 §4.1 event-rejection path) even if the queue swallows the
+    // thrown error. Loading the object cross-tenant (systemFindByPk) is what
+    // makes this violation visible instead of folding into a scoped null.
+    logger.error('TENANT_VIOLATION', { code: TENANT_MISMATCH, rowTenant, jobTenant });
+    const err = new TenantError(TENANT_MISMATCH, `job object belongs to ${rowTenant} but payload says ${jobTenant}`);
+    (err as any).nonRetryable = true;
+    throw err;
+  }
+}
 
 type QueueOptions<T> = {
   id?: (job: T) => string;
@@ -46,6 +134,18 @@ type PushParams<T> = {
   delay?: number; // in seconds
   runAt?: number; // unix timestamp in seconds
   skipDuplicateCheck?: boolean; // Q1: skip addJob's findOne when caller guarantees no duplicate
+  /**
+   * Internal: re-delivery of a row already persisted in the jobs table
+   * (startup/scheduled recovery). Skips the push-side tenant gate so legacy
+   * pre-tenant rows reach runJobWithTenant, which owns the legacy strategy
+   * (single -> default tenant, multi -> structured non-retryable refusal).
+   *
+   * NEVER set this from application code: it bypasses the enqueue tenant
+   * gate. Object-bound handlers are still protected by
+   * assertJobObjectTenant, but system-operation queues (no object load)
+   * would run under whatever tenant the payload claims.
+   */
+  fromStore?: boolean;
 };
 
 export default function createQueue<T = any>({ name, onJob, options = defaults }: QueueParams<T>) {
@@ -98,7 +198,7 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
       }
 
       try {
-        const result = await tryWithTimeout(() => onJob(job), maxTimeout);
+        const result = await tryWithTimeout(() => runJobWithTenant(job, onJob), maxTimeout);
         logger.info('job finished', { id, result });
         cb(null, result);
       } catch (err) {
@@ -108,7 +208,15 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     // @ts-ignore
   }, concurrency);
 
-  const push = ({ job, id, persist = true, delay, runAt, skipDuplicateCheck = false }: PushParams<T>) => {
+  const push = ({
+    job: rawJob,
+    id,
+    persist = true,
+    delay,
+    runAt,
+    skipDuplicateCheck = false,
+    fromStore = false,
+  }: PushParams<T>) => {
     const jobEvents = new EventEmitter();
     const emit = (e: string, data: any) => {
       queueEvents.emit(e, data);
@@ -116,20 +224,24 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     };
     const now = dayjs().unix();
 
-    if (!job) {
+    if (!rawJob) {
       throw new Error('Can not queue empty job');
     }
 
+    // fail-closed gate: every NEW payload carries its tenant from here on;
+    // store re-deliveries pass through so the execution-side legacy strategy applies
+    const job = (fromStore ? rawJob : injectJobTenant(rawJob)) as T;
+
     const jobId = getJobId(id, job);
 
-    if ((delay && delay >= MIN_DELAY) || (runAt && runAt > now)) {
+    if ((delay && delay >= minDelay()) || (runAt && runAt > now)) {
       if (!enableScheduledJob) {
         throw new Error('Must set options.enableScheduledJob to true to run delay jobs');
       }
 
       // 这里不是精确的 delay, 延迟的时间太短没有意义，所以这里限制了最小 delay
-      if (delay && delay < MIN_DELAY) {
-        throw new Error(`minimum delay is ${MIN_DELAY}s`);
+      if (delay && delay < minDelay()) {
+        throw new Error(`minimum delay is ${minDelay()}s`);
       }
 
       const attrs: { delay?: number; will_run_at?: number } = {};
@@ -221,12 +333,31 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
         queue.push({ id: jobId, job, persist }, onJobComplete);
       });
 
+    // Phase 12b: workerd flush. Track this immediate execution so a frozen-
+    // isolate host can drain it before returning the response — otherwise the
+    // fire-and-forget setImmediate/fastq work is dropped when the isolate is
+    // torn down. Tracked ONLY on a workerd host: zero overhead and no extra
+    // listeners on a long-lived node process.
+    let resolveSettled: () => void = () => {};
+    if (getQueueRuntimeMode() === 'workerd') {
+      const settled = new Promise<void>((resolve) => {
+        resolveSettled = resolve;
+      });
+      jobEvents.on('finished', resolveSettled);
+      jobEvents.on('failed', resolveSettled);
+      jobEvents.on('cancelled', resolveSettled);
+      trackPending(settled);
+    }
+
     if (persist) {
       store
         .addJob(jobId, job, {}, skipDuplicateCheck)
         .then(queueJob)
         .catch((err) => {
           logger.error('Can not add job to store', { error: err });
+          // never enqueued (e.g. duplicate id) → emits nothing; release the
+          // workerd flush tracker so flushQueueWork() cannot hang on it.
+          resolveSettled();
         });
     } else {
       queueJob();
@@ -246,7 +377,11 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
 
         const job = push(params);
         job.on('finished', (data: { id: string; job: T; result: any }) => resolve(data));
-        job.on('canceled', (data: { id: string; job: T }) => resolve(data));
+        // Phase 12b: the engine emits 'cancelled' (two L); the old 'canceled'
+        // listener never fired, so a cancelled job left pushAndWait hanging
+        // forever — and the CF queue() consumer now runs through pushAndWait,
+        // where that hang would stall the queue batch until CF kills it.
+        job.on('cancelled', (data: { id: string; job: T }) => resolve(data));
         job.on('failed', (data: { id: string; job: T; error: Error }) => reject(data));
       } catch (err) {
         reject(err);
@@ -296,60 +431,128 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     return updatedJob;
   };
 
-  // Populate the queue on startup
-  process.nextTick(async () => {
-    try {
-      if (!Job.isInitialized()) {
-        Job.initialize(sequelize);
+  // Populate the queue on startup. Phase 12b: this is a long-lived-process
+  // recovery — re-queue persisted immediate rows on boot. A workerd host spins
+  // up a fresh isolate per request and MUST NOT re-run every persisted row on
+  // each cold start; it drives due-job re-dispatch through dispatchDueJobs()
+  // from scheduled() instead. So the boot recovery is node-mode only.
+  if (getQueueRuntimeMode() === 'node') {
+    process.nextTick(async () => {
+      try {
+        if (!Job.isInitialized()) {
+          Job.initialize(sequelize);
+        }
+        const jobs = await store.getJobs();
+        jobs.forEach((x) => {
+          if (x.job && x.id) {
+            try {
+              push({ job: x.job, id: x.id, persist: false, fromStore: true });
+            } catch (err: any) {
+              // one bad row must never break recovery of the rest
+              logger.error('failed to re-queue stored job', { id: x.id, code: err?.code, message: err?.message });
+            }
+          } else {
+            logger.info('skip invalid job from db', { job: x });
+          }
+        });
+        // eslint-disable-next-line no-shadow
+      } catch (err) {
+        console.error(err);
+        logger.error(`Can not load existing ${name} jobs`, { error: err });
       }
-      const jobs = await store.getJobs();
-      jobs.forEach((x) => {
-        if (x.job && x.id) {
-          push({ job: x.job, id: x.id, persist: false });
-        } else {
-          logger.info('skip invalid job from db', { job: x });
+    });
+  }
+
+  // Re-deliver this queue's due delayed rows once — the body shared by the node
+  // loop() (timer-driven) and the host dispatchDueJobs() (CF scheduled()-driven).
+  // Same cancel-then-replay-from-store path either way, so worker and node agree
+  // on exactly how a due delayed job runs.
+  const redispatchDue = async (): Promise<{ dispatched: number; failed: number }> => {
+    let dispatched = 0;
+    let failed = 0;
+    if (enableScheduledJob !== true) return { dispatched, failed };
+    const jobs = await store.getScheduledJobs();
+    for (const x of jobs) {
+      if (x.job && x.id) {
+        // fix: https://github.com/blocklet/payment-kit/issues/287
+        // Intentional cancel-then-replay: marking the row cancelled=true keeps
+        // the NEXT due-poll (loop tick / dispatchDueJobs) from re-picking it
+        // while this run is in flight; the immediate re-push below clears the
+        // in-memory cancel flag for THIS execution, and onJobComplete deletes
+        // the row on success. A reader watching raw DB state mid-dispatch will
+        // briefly see cancelled=true — that is the de-dupe latch, not an error.
+        // eslint-disable-next-line no-await-in-loop
+        await cancel(x.id);
+        logger.info('reschedule delayed or scheduled job', { id: x.id, job: x.job });
+        try {
+          push({ job: x.job, id: x.id, persist: false, fromStore: true });
+          dispatched += 1;
+        } catch (err: any) {
+          failed += 1;
+          logger.error('failed to reschedule stored job', { id: x.id, code: err?.code, message: err?.message });
         }
-      });
-      // eslint-disable-next-line no-shadow
-    } catch (err) {
-      console.error(err);
-      logger.error(`Can not load existing ${name} jobs`, { error: err });
+      } else {
+        logger.info('skip invalid job from db', { job: x });
+      }
     }
-  });
+    return { dispatched, failed };
+  };
 
-  const loop = async () => {
-    if (enableScheduledJob === true) {
-      // eslint-disable-next-line no-constant-condition
-      while (true) {
-        await sleep((MIN_DELAY * 1000) / 2);
+  // D2 teardown: the node poll loop is cancelable. `stopLoop()` flips the flag
+  // AND clears the pending sleep timer (so the process has no dangling handle on
+  // stop — the spec's "active handles 归零") and resolves the in-flight sleep so
+  // the loop observes the flag and returns immediately.
+  let loopStopped = false;
+  let loopTimer: ReturnType<typeof setTimeout> | null = null;
+  let loopWake: (() => void) | null = null;
+  const cancelableSleep = (ms: number): Promise<void> =>
+    new Promise<void>((resolve) => {
+      loopWake = resolve;
+      loopTimer = setTimeout(() => {
+        loopTimer = null;
+        loopWake = null;
+        resolve();
+      }, ms);
+    });
+  const stopLoop = (): void => {
+    loopStopped = true;
+    if (loopTimer) {
+      clearTimeout(loopTimer);
+      loopTimer = null;
+    }
+    if (loopWake) {
+      const wake = loopWake;
+      loopWake = null;
+      wake();
+    }
+  };
 
-        try {
-          /* eslint-disable no-await-in-loop */
-          const jobs = await store.getScheduledJobs();
-          for (const x of jobs) {
-            if (x.job && x.id) {
-              // fix: https://github.com/blocklet/payment-kit/issues/287
-              await cancel(x.id);
-              logger.info('reschedule delayed or scheduled job', {
-                id: x.id,
-                job: x.job,
-              });
-              push({ job: x.job, id: x.id, persist: false });
-            } else {
-              logger.info('skip invalid job from db', { job: x });
-            }
-          }
-        } catch (err) {
-          console.error(err);
-          logger.error(`Can not load scheduled ${name} jobs`, { error: err });
-        }
+  // The node poll loop. Disabled on a workerd host: a frozen isolate cannot run
+  // a background timer, so the host calls dispatchDueJobs() from scheduled()
+  // instead (which runs redispatchDue() above — the same code path).
+  const loop = async () => {
+    if (enableScheduledJob !== true) return;
+    if (getQueueRuntimeMode() !== 'node') return;
+    while (!loopStopped) {
+      // eslint-disable-next-line no-await-in-loop
+      await cancelableSleep((minDelay() * 1000) / 2);
+      // stopped during the sleep (teardown) — exit before doing any work.
+      if (loopStopped) return;
+      // mode can flip after assembly (a host that sets workerd late); stop then.
+      if (getQueueRuntimeMode() !== 'node') return;
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await redispatchDue();
+      } catch (err) {
+        console.error(err);
+        logger.error(`Can not load scheduled ${name} jobs`, { error: err });
       }
     }
   };
 
   loop();
 
-  return Object.assign(queueEvents, {
+  const queueInstance = Object.assign(queueEvents, {
     store,
     push,
     pushAndWait,
@@ -361,6 +564,8 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
     delete: deleteJob,
     cancel,
     update: updateJob,
+    /** D2 teardown: stop this queue's node poll loop (no-op if not scheduled). */
+    stop: stopLoop,
     options: {
       concurrency,
       maxRetries,
@@ -369,4 +574,18 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
       enableScheduledJob,
     },
   });
+
+  // Phase 12b: register into the host-facing queue runtime surface so the CF
+  // worker can look the handle up by name (queue() consumer) and drive due
+  // re-dispatch (scheduled()) through the service/slot boundary — no more
+  // direct cloudflare/shims/queue.ts imports.
+  registerQueue({
+    name,
+    enableScheduledJob: enableScheduledJob === true,
+    handle: queueInstance,
+    redispatchDue,
+    stop: stopLoop,
+  });
+
+  return queueInstance;
 }

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

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

package/api/src/libs/resource.ts

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

package/api/src/libs/secrets.ts

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

package/api/src/libs/session.ts

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