payment-kit 1.29.1 → 1.29.2

package/api/src/libs/drivers/identity.ts

@@ -0,0 +1,81 @@
+// Phase 10 (W2-2): identity slot driver contract.
+//
+// The identity slot resolves a request Host to a tenant (instanceDid) and, from
+// Phase 11, supplies per-tenant encryption keys. It mirrors the relevant slice
+// of BlockletServiceRPCInterface (resolveInstanceDidForHost). The CF identity
+// shims (blocklet-sdk/{auth-service,session,verify-session,verify-sign}) sit
+// behind this contract.
+//
+// Resolution is single-point: ONLY the tenant-resolving middleware calls
+// resolveInstanceDidForHost (the scanner enforces that no route/queue/cron
+// reads Host directly). In single-tenant mode the default driver ignores the
+// host and returns the deployment app DID, so Blocklet Server behavior is
+// unchanged; multi-tenant hosts inject a driver that maps Host -> instanceDid
+// and returns null for unknown hosts (the middleware then fails closed 4xx).
+
+import { getDefaultInstanceDid, getTenantMode, TenantError, TENANT_HOST_UNRESOLVED } from '../tenant';
+
+export interface IdentityDriver {
+  /**
+   * Resolve a request Host to its tenant instanceDid, or null/undefined when
+   * the host is unknown (multi-tenant fail-closed). The host value is the raw
+   * Host header — never a proxy header.
+   */
+  resolveInstanceDidForHost(host: string | undefined): Promise<string | null> | string | null;
+  /**
+   * Phase 11: the tenant's encryption key (EK). Required by the keyring secrets
+   * driver; optional on the contract because the single-tenant default secrets
+   * driver uses the process key and never calls it.
+   */
+  getAppEk?(instanceDid: string): Promise<string> | string;
+}
+
+/**
+ * Single-tenant default: every host maps to the deployment app DID. Used by
+ * Blocklet Server and the standalone worker's single-mode transition.
+ */
+export function createDefaultIdentityDriver(): IdentityDriver {
+  return {
+    resolveInstanceDidForHost() {
+      return getDefaultInstanceDid();
+    },
+  };
+}
+
+let activeIdentityDriver: IdentityDriver = createDefaultIdentityDriver();
+
+/** Inject the identity driver (multi-tenant hosts wire a Host->tenant map here). */
+export function setIdentityDriver(driver: IdentityDriver): void {
+  activeIdentityDriver = driver;
+}
+
+export function getIdentityDriver(): IdentityDriver {
+  return activeIdentityDriver;
+}
+
+/**
+ * Resolve a request's raw Host header to a tenant instanceDid. SINGLE POINT of
+ * Host -> tenant resolution — both host adapters funnel through here (the
+ * Express `contextMiddleware` and the CF worker `tenantMiddleware`), so neither
+ * reinvents Host parsing (the tenant-scan rule forbids any route/queue/cron
+ * from reading Host directly).
+ *
+ * single mode: always the deployment app DID (Blocklet Server / standalone
+ * worker unchanged). multi mode: the identity driver maps Host -> instanceDid;
+ * an unknown/missing host throws TENANT_HOST_UNRESOLVED so the caller fails
+ * closed 4xx with no default-tenant fallback.
+ *
+ * The host MUST be the raw Host header — never a proxy header
+ * (X-Forwarded-Host / X-Real-IP). The runtime host (CF route / blocklet server /
+ * reverse proxy) is responsible for ensuring it cannot be forged by the client.
+ */
+export async function resolveTenantForHost(host: string | undefined): Promise<string> {
+  if (getTenantMode() === 'single') {
+    return getDefaultInstanceDid();
+  }
+  const resolved = await activeIdentityDriver.resolveInstanceDidForHost(host);
+  if (!resolved) {
+    throw new TenantError(TENANT_HOST_UNRESOLVED, `no tenant resolved for host "${host ?? ''}"`);
+  }
+  return resolved;
+}

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

@@ -0,0 +1,40 @@
+// Phase 8 (W2-1a): db / locks driver contracts barrel.
+export type { DbDriver, DbDriverKind, DbExecResult, D1Binding } from './db';
+export { createNodeDbDriver, createD1DbDriver } from './db';
+
+export type { LockHandle, LocksDriver, LocksDriverKind, LockScope } from './locks';
+export { createMemoryLocksDriver, createD1LocksDriver, scopedLockName, MemoryLock } from './locks';
+
+export type { AuthRecord } from './auth-storage';
+export { DbAuthStorage, createAuthStorage } from './auth-storage';
+
+export type { QueueOptions, PushParams, JobEvents, QueueHandle, QueueFactory, QueueHostHooks } from './queue';
+export { nodeQueueHostHooks, setQueueHostHooks, getQueueHostHooks } from './queue';
+
+export type { CronJob, CronDriver } from './cron';
+export { matchesCron, shouldRunInWindow, createCronRegistry, setCronDriver, getCronDriver } from './cron';
+
+export type { SqlMigration } from './migrate-runner';
+export { applySqlMigrations, splitStatements } from './migrate-runner';
+
+// The embedded D1 SQL lineage, inlined (store/sql-migrations is generated from
+// cloudflare/migrations/*.sql) so it ships INSIDE the @arcblock/payment-service
+// bundle. A host provisions the embedded schema with applyPaymentCoreMigrations
+// alone — no repo paths, no wrangler. See migrate-runner.ts.
+// eslint-disable-next-line import/first
+import type { DbDriver as DbDriverForMigrations } from './db';
+// eslint-disable-next-line import/first
+import { applySqlMigrations as applySql } from './migrate-runner';
+// eslint-disable-next-line import/first
+import { paymentCoreSqlMigrations } from '../../store/sql-migrations';
+
+export { paymentCoreSqlMigrations };
+export function applyPaymentCoreMigrations(driver: DbDriverForMigrations): Promise<string[]> {
+  return applySql(driver, paymentCoreSqlMigrations);
+}
+
+export type { IdentityDriver } from './identity';
+export { createDefaultIdentityDriver, setIdentityDriver, getIdentityDriver } from './identity';
+
+export type { SecretsDriver } from './secrets';
+export { createDefaultSecretsDriver, createKeyringSecretsDriver, setSecretsDriver, getSecretsDriver } from './secrets';

package/api/src/libs/drivers/locks.ts

@@ -0,0 +1,226 @@
+// Phase 8 (W2-1a): locks slot driver contract.
+//
+// W1 §2.2 exempts the `locks` table from an instance_did column: tenant
+// isolation for locks is achieved by prefixing the lock NAME, not by a column.
+// `scopedLockName` is the single place that prefix is applied, so both drivers
+// (and the libs/lock facade) stay consistent.
+//
+// Two implementations conform to the contract:
+//   - memory driver: the original in-process EventEmitter lock (Blocklet Server
+//     single-process Node.js). Semantics unchanged — Phase 8 wraps, never
+//     rewrites.
+//   - d1 driver: the Cloudflare D1-backed lock (atomic INSERT OR IGNORE + TTL
+//     expiry + owner token), relocated here from the previously-orphaned
+//     cloudflare/shims/lock.ts so the worker wires it through the locks slot.
+
+// the two lock classes are the two driver implementations — cohesive in one module
+/* eslint-disable max-classes-per-file */
+
+import type { D1Binding } from './db';
+
+export interface LockHandle {
+  name: string;
+  /** whether this handle currently holds the lock — used by singleton start guards */
+  locked: boolean;
+  /**
+   * Acquire the lock. `maxWaitMs` is a bounded-wait hint: the d1 driver enforces
+   * it as a hard timeout (and rejects on expiry) because a holder lives in a
+   * different isolate and may crash; the in-process memory driver waits until
+   * release and does not time out — single process means there is no
+   * crashed-holder / cross-isolate-wait scenario. The shared parity cases
+   * (acquire-when-free, block-until-release) hold on both; TTL-expiry and
+   * timeout are d1-only capabilities (see drivers/locks.spec.ts).
+   */
+  acquire(maxWaitMs?: number): Promise<true>;
+  release(): void;
+}
+
+export type LocksDriverKind = 'memory' | 'd1';
+
+export interface LocksDriver {
+  kind: LocksDriverKind;
+  getLock(name: string, options?: { ttl?: number }): LockHandle;
+}
+
+export type LockScope = 'tenant' | 'global';
+
+/**
+ * Apply the tenant prefix to a lock name. Tenant-scoped locks (the default for
+ * per-resource locks) are isolated per deployment/tenant; global-scoped locks
+ * (process-level singleton guards like queue start guards) are intentionally
+ * shared and keep their bare name. In single-tenant mode the prefix is the
+ * constant deployment app DID, so lock identity is unchanged in practice.
+ */
+export function scopedLockName(name: string, instanceDid: string | null, scope: LockScope): string {
+  if (scope === 'global') return name;
+  if (!instanceDid) {
+    // tenant scope requires a tenant — callers resolve it fail-closed before
+    // reaching here (see libs/lock.ts). Guard anyway so a programming error is
+    // loud rather than silently producing a cross-tenant-shared lock.
+    throw new Error('scopedLockName: tenant-scoped lock requires a non-empty instanceDid');
+  }
+  return `tenant:${instanceDid}::${name}`;
+}
+
+// ---------------------------------------------------------------------------
+// memory driver — original in-process lock semantics
+// ---------------------------------------------------------------------------
+
+const { EventEmitter } = require('events');
+
+export class MemoryLock implements LockHandle {
+  name: string;
+  locked: boolean;
+  private events: any;
+
+  constructor(name: string) {
+    this.name = name;
+    this.locked = false;
+    this.events = new EventEmitter();
+  }
+
+  acquire(): Promise<true> {
+    return new Promise((resolve) => {
+      if (this.locked) {
+        const tryAcquire = () => {
+          if (!this.locked) {
+            this.locked = true;
+            this.events.removeListener('release', tryAcquire);
+            resolve(true);
+          }
+        };
+        this.events.on('release', tryAcquire);
+      } else {
+        this.locked = true;
+        resolve(true);
+      }
+    });
+  }
+
+  release(): void {
+    this.locked = false;
+    setImmediate(() => this.events.emit('release'));
+  }
+}
+
+export function createMemoryLocksDriver(): LocksDriver {
+  const locks = new Map<string, MemoryLock>();
+  return {
+    kind: 'memory',
+    getLock(name: string): LockHandle {
+      const exist = locks.get(name);
+      if (exist instanceof MemoryLock) return exist;
+      const lock = new MemoryLock(name);
+      locks.set(name, lock);
+      return lock;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// d1 driver — D1-backed cross-isolate lock (relocated from shims/lock.ts)
+// ---------------------------------------------------------------------------
+
+let nanoidCounter = 0;
+function simpleId(): string {
+  nanoidCounter += 1;
+  return `${Date.now().toString(36)}-${nanoidCounter.toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+class D1Lock implements LockHandle {
+  name: string;
+  owner: string;
+  locked: boolean;
+  ttl: number;
+  private getBinding: () => D1Binding;
+
+  constructor(getBinding: () => D1Binding, name: string, options?: { ttl?: number }) {
+    this.getBinding = getBinding;
+    this.name = name;
+    this.owner = simpleId();
+    this.locked = false;
+    this.ttl = options?.ttl || 5000;
+  }
+
+  async acquire(maxWaitMs = 10000): Promise<true> {
+    const db: any = this.getBinding();
+    const deadline = Date.now() + maxWaitMs;
+    let delay = 30;
+
+    while (Date.now() < deadline) {
+      const now = Date.now();
+      try {
+        // eslint-disable-next-line no-await-in-loop -- polling retry until acquired or timed out
+        const batchResult = await db.batch([
+          db.prepare('DELETE FROM _locks WHERE name = ? AND expires_at < ?').bind(this.name, now),
+          db
+            .prepare('INSERT OR IGNORE INTO _locks (name, owner, expires_at) VALUES (?, ?, ?)')
+            .bind(this.name, this.owner, now + this.ttl),
+          db.prepare('SELECT owner FROM _locks WHERE name = ?').bind(this.name),
+        ]);
+        const row = batchResult[2]?.results?.[0] as { owner: string } | undefined;
+        if (row?.owner === this.owner) {
+          this.locked = true;
+          return true;
+        }
+      } catch (err: any) {
+        // eslint-disable-next-line no-console
+        console.error(`[D1Lock] acquire error for "${this.name}":`, err?.message || err);
+      }
+      // backoff with jitter, capped — captured into a const so the closure does
+      // not reference the mutated `delay`
+      const waitMs = delay + Math.random() * delay * 0.3;
+      // eslint-disable-next-line no-await-in-loop, no-promise-executor-return
+      await new Promise((r) => setTimeout(r, waitMs));
+      delay = Math.min(delay * 2, 500);
+    }
+    throw new Error(`[D1Lock] Failed to acquire lock "${this.name}" within ${maxWaitMs}ms`);
+  }
+
+  release(): void {
+    if (!this.locked) return;
+    this.locked = false;
+    try {
+      const db: any = this.getBinding();
+      const promise = db
+        .prepare('DELETE FROM _locks WHERE name = ? AND owner = ?')
+        .bind(this.name, this.owner)
+        .run()
+        // eslint-disable-next-line no-console
+        .catch((err: any) => console.error(`[D1Lock] release error for "${this.name}":`, err?.message || err));
+
+      // release is fire-and-forget; the worker shell flushes the pending delete
+      // before responding. This depends on ambient worker globals
+      // (__cfHttpContext__ / __cfWaitUntil__ / __cfPendingJobs__) set by the CF
+      // request handler — a host injecting the d1 locks driver must provide the
+      // same flush hooks (Phase 9 formalizes the flush contract). Outside a
+      // worker (e.g. the consistency suite) the delete still runs; it is simply
+      // not registered for flushing.
+      const isHttp = (globalThis as any).__cfHttpContext__;
+      if (isHttp) {
+        const waitUntil = (globalThis as any).__cfWaitUntil__;
+        if (typeof waitUntil === 'function') waitUntil(promise);
+      } else {
+        const pending = (globalThis as any).__cfPendingJobs__;
+        if (Array.isArray(pending)) pending.push(promise);
+      }
+    } catch (err: any) {
+      // eslint-disable-next-line no-console
+      console.error(`[D1Lock] release setup error for "${this.name}":`, err?.message || err);
+    }
+  }
+}
+
+/**
+ * D1-backed locks driver. `getBinding` is a getter (the binding is resolved
+ * lazily per request in the worker). Each call returns a fresh lock — isolates
+ * never share instances, matching the original shim's behavior.
+ */
+export function createD1LocksDriver(getBinding: () => D1Binding): LocksDriver {
+  return {
+    kind: 'd1',
+    getLock(name: string, options?: { ttl?: number }): LockHandle {
+      return new D1Lock(getBinding, name, options);
+    },
+  };
+}

package/api/src/libs/drivers/migrate-runner.ts

@@ -0,0 +1,70 @@
+// Phase 11 (W2′): runtime-neutral SQL migration runner — the migration-driver
+// boundary. The library provisions the embedded D1 schema by applying the D1 SQL
+// migrations through the host's db driver (its `exec`), NEVER by shelling out to
+// the wrangler CLI. `wrangler d1 migrations apply` stays the CF-native local-dev
+// / deploy provisioning mechanism for the SAME .sql files; this runner is the
+// in-process path arc-node (and any non-CF host) uses via lifecycle/host wiring.
+//
+// Idempotent: applied migrations are tracked in `_sql_migrations`, so re-running
+// is a no-op (the .sql contain non-IF-NOT-EXISTS DDL like ALTER ... ADD COLUMN).
+//
+// NOTE: this tracker (`_sql_migrations`) is independent of wrangler's own
+// `d1_migrations` table. That is safe because the two provisioning paths target
+// DIFFERENT databases — arc-node's embedded SQLite (this runner) vs the CF
+// worker's bound D1 (wrangler) — and never share one. Do NOT run both paths
+// against the SAME database: the runner is blind to `d1_migrations`, so it would
+// re-apply everything and the non-idempotent ALTER ... ADD COLUMN would fail.
+
+import type { DbDriver, DbBatchOp } from './db';
+
+export interface SqlMigration {
+  /** stable id (the migration filename) — the idempotency key */
+  name: string;
+  /** the migration body; may contain multiple `;`-separated statements */
+  sql: string;
+}
+
+/** Strip line comments and split a migration body into individual statements. */
+export function splitStatements(sql: string): string[] {
+  return sql
+    .split('\n')
+    .filter((line) => !line.trim().startsWith('--'))
+    .join('\n')
+    .split(';')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Apply pending SQL migrations through the db driver, in order. Returns the
+ * names actually applied this run (empty on a fully-migrated db). No wrangler.
+ *
+ * Each migration is applied ATOMICALLY: all of its statements PLUS the tracker
+ * insert run in a single `driver.batch(...)` (the contract's all-or-nothing
+ * transactional primitive). So a mid-migration failure rolls the whole migration
+ * back AND leaves the tracker unwritten — a re-run retries that migration from a
+ * clean slate, never replaying half-applied (non-IF-NOT-EXISTS) DDL like
+ * `ALTER ... ADD COLUMN`. This satisfies "中断后重跑不丢已迁移状态（幂等 + 事务边界）".
+ */
+export async function applySqlMigrations(driver: DbDriver, migrations: SqlMigration[]): Promise<string[]> {
+  await driver.exec('CREATE TABLE IF NOT EXISTS _sql_migrations (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)');
+  const rows = await driver.all<{ name: string }>('SELECT name FROM _sql_migrations');
+  const applied = new Set(rows.map((r) => r.name));
+
+  const ran: string[] = [];
+  const pending = migrations.filter((m) => !applied.has(m.name));
+  /* eslint-disable no-await-in-loop -- migrations are ordered + must apply sequentially */
+  for (const m of pending) {
+    const ops: DbBatchOp[] = splitStatements(m.sql).map((sql) => ({ sql }));
+    // tracker insert is the LAST op in the same batch — committed iff every
+    // schema statement of this migration committed (atomic boundary).
+    ops.push({
+      sql: 'INSERT INTO _sql_migrations (name, applied_at) VALUES (?, ?)',
+      params: [m.name, new Date().toISOString()],
+    });
+    await driver.batch(ops);
+    ran.push(m.name);
+  }
+  /* eslint-enable no-await-in-loop */
+  return ran;
+}

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

@@ -0,0 +1,104 @@
+// Phase 9 (W2-1b): queue slot driver contract.
+//
+// The queue contract is the WHOLE semantics the two engines share, not just
+// enqueue:
+//   - jobs table (createQueueStore) = persistent scheduler / source of truth
+//   - immediate vs delayed dispatch (delayed rows wait for the due-poll)
+//   - consumer ack + failure re-delivery (retry_count up to maxRetries, then
+//     failed; nonRetryable errors fail immediately)
+//   - pushAndWait inline execution (caller awaits the result)
+//   - host flush hook (CF flushes pending push/timer work before responding;
+//     the Node long-lived process is a no-op)
+//   - tenant is carried in the payload (Phase 5/6); the contract layer passes
+//     it through and NEVER resolves Host on the background path
+//
+// ONE engine (api/src/libs/queue) serves every runtime (Phase 12b, option A):
+// the host swaps only the EXECUTOR (real fastq on node, cloudflare/shims/fastq
+// in the worker) and the TRIGGER (in-process poll loop on node, CF scheduled()
+// calling the engine's dispatchDueJobs() in the worker — see
+// api/src/libs/queue/runtime.ts). Persistence, retry policy and tenant handling
+// are shared because there is no second engine. The old cloudflare/shims/queue.ts
+// duplicate engine was removed in Phase 12c.
+
+import type EventEmitter from 'events';
+
+export interface QueueOptions<T> {
+  id?: (job: T) => string;
+  concurrency?: number;
+  maxRetries?: number;
+  maxTimeout?: number;
+  retryDelay?: number;
+  enableScheduledJob?: boolean;
+}
+
+export interface PushParams<T> {
+  job: T;
+  id?: string;
+  persist?: boolean;
+  /** seconds */
+  delay?: number;
+  /** unix timestamp in seconds */
+  runAt?: number;
+  skipDuplicateCheck?: boolean;
+  /**
+   * Internal re-delivery flag for rows already persisted (startup / scheduled
+   * recovery). Skips the enqueue tenant gate so the execution-side legacy
+   * strategy applies. NEVER set from application code.
+   */
+  fromStore?: boolean;
+}
+
+/** the per-job event channel returned by push (emits queued/finished/failed/retry/cancelled) */
+export type JobEvents = EventEmitter & { id?: string };
+
+export interface QueueHandle<T = any> {
+  push(params: PushParams<T>): JobEvents;
+  pushAndWait(params: PushParams<T>): Promise<{ id: string; job: T; result: any }>;
+  get(id: string): Promise<T | null>;
+  delete(id: string, knownExists?: boolean): Promise<boolean>;
+  cancel(id: string): Promise<T | null>;
+  update(id: string, updates: any): Promise<any>;
+  /**
+   * D2 teardown: stop this queue's node poll loop (clears its sleep timer).
+   * No-op when the queue is not scheduled or on a workerd host (no loop runs).
+   * The Node host tears every queue down via lifecycle.stop() → stopAllQueues().
+   */
+  stop?(): void;
+  options: Required<Omit<QueueOptions<T>, 'id'>>;
+}
+
+/** factory shape both engines export as default */
+export type QueueFactory = <T = any>(params: {
+  name: string;
+  onJob: (job: T) => Promise<any>;
+  options?: QueueOptions<T>;
+}) => QueueHandle<T> & EventEmitter;
+
+/**
+ * Host flush hook. CF must flush pending push/timer work before returning the
+ * response (the isolate is torn down after); a long-lived Node process never
+ * needs to and uses the no-op below.
+ */
+export interface QueueHostHooks {
+  flush(): Promise<void>;
+}
+
+/** Node host: long-lived process, nothing to flush before a response. */
+export const nodeQueueHostHooks: QueueHostHooks = {
+  async flush() {
+    /* no-op — the process stays alive, in-flight jobs continue */
+  },
+};
+
+// Active host hooks — injectable by the factory's `queue` slot; defaults to the
+// Node no-op. The worker shell injects hooks that flush pending push/timer work
+// before responding.
+let activeQueueHostHooks: QueueHostHooks = nodeQueueHostHooks;
+
+export function setQueueHostHooks(hooks: QueueHostHooks): void {
+  activeQueueHostHooks = hooks;
+}
+
+export function getQueueHostHooks(): QueueHostHooks {
+  return activeQueueHostHooks;
+}