payment-kit 1.29.1 → 1.29.3

package/scripts/e2e-tenant-worker.ts

@@ -0,0 +1,199 @@
+/* eslint-disable no-console */
+// Phase 7 (W1′) deterministic E2E: drive the REAL worker tenant middleware
+// (cloudflare/tenant-middleware.ts) over an in-process Hono app and emit raw
+// JSON for each call. This is the deterministic equivalent of the tasks.md
+// "wrangler dev + dual-Host curl" table — the trusted Host->instanceDid map and
+// full workerd runtime are Phase 9/10 + real-D1 territory (same deferral the
+// Phase 3 amendment took), but the wiring itself (Host -> withTenant ALS ->
+// tenant-scoped read, multi-mode fail-closed) is exercised end to end here.
+//
+// Run: npx tsx scripts/e2e-tenant-worker.ts
+
+// hono is the worker's runtime router (bundled into the CF worker); imported
+// here only to drive the real tenant middleware in this dev/E2E harness.
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { Hono } from 'hono';
+
+import { tenantMiddleware } from '../cloudflare/tenant-middleware';
+import { getInstanceDid } from '../api/src/libs/context';
+import { setDefaultInstanceDid } from '../api/src/libs/tenant';
+import { setIdentityDriver, createDefaultIdentityDriver, type IdentityDriver } from '../api/src/libs/drivers/identity';
+
+const DID_A = 'did:abt:zTENANT_A';
+const DID_B = 'did:abt:zTENANT_B';
+const DID_DEPLOY = 'did:abt:zDEPLOYMENT'; // single-mode default tenant (stands in for BLOCKLET_APP_PID)
+const HOST_A = 'a.pay.example';
+const HOST_B = 'b.pay.example';
+
+// In-memory "coupons" table spanning both tenants — the handler returns only
+// rows for the tenant resolved into the request context, proving the wiring
+// scopes reads (a stand-in for TenantModel.findAll under the same ALS context).
+const COUPONS = [
+  { id: 'co_a1', instance_did: DID_A, name: 'A-WELCOME' },
+  { id: 'co_a2', instance_did: DID_A, name: 'A-SUMMER' },
+  { id: 'co_b1', instance_did: DID_B, name: 'B-LAUNCH' },
+  { id: 'co_d1', instance_did: DID_DEPLOY, name: 'DEPLOY-DEFAULT' },
+];
+
+function buildApp() {
+  const app = new Hono();
+  app.use('/api/*', tenantMiddleware());
+  app.get('/api/coupons', (c) => {
+    const tenant = getInstanceDid();
+    const list = COUPONS.filter((r) => r.instance_did === tenant);
+    return c.json({ list });
+  });
+  app.get('/health', (c) => c.json({ status: 'ok' }));
+  return app;
+}
+
+async function call(app: Hono, label: string, path: string, headers: Record<string, string> = {}) {
+  const res = await app.request(path, { headers });
+  const text = await res.text();
+  let body: any;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  console.log(`=== ${label} ===`);
+  console.log(`input: ${JSON.stringify({ path, headers })}`);
+  // httpStatus kept distinct from the body so a body field named `status`
+  // (e.g. /health -> {status:"ok"}) cannot shadow the HTTP status code.
+  console.log(`output: ${JSON.stringify({ httpStatus: res.status, body })}`);
+  console.log('');
+  return { status: res.status, body };
+}
+
+async function main() {
+  // ---- multi mode: Host maps to tenant, fail-closed on unknown ----
+  process.env.PAYMENT_TENANT_MODE = 'multi';
+  const identity: IdentityDriver = {
+    resolveInstanceDidForHost(host) {
+      if (host === HOST_A) return DID_A;
+      if (host === HOST_B) return DID_B;
+      return null;
+    },
+  };
+  setIdentityDriver(identity);
+  const app = buildApp();
+
+  console.log('##### MULTI MODE #####\n');
+  const a = await call(app, 'S7.1 GET /api/coupons (Host A) — happy/isolation', '/api/coupons', { Host: HOST_A });
+  const b = await call(app, 'S7.2 GET /api/coupons (Host B) — isolation', '/api/coupons', { Host: HOST_B });
+  const noHost = await call(app, 'S7.3 GET /api/coupons (no Host) — bad input fail-closed', '/api/coupons');
+  const unknown = await call(app, 'S7.4 GET /api/coupons (unknown Host) — data-leak fail-closed', '/api/coupons', {
+    Host: 'unknown.example',
+  });
+  const spoof = await call(
+    app,
+    'S7.5 GET /api/coupons (Host A + forged X-Forwarded-Host B) — security',
+    '/api/coupons',
+    {
+      Host: HOST_A,
+      'X-Forwarded-Host': HOST_B,
+    }
+  );
+  const health = await call(app, 'S7.6 GET /health (no Host) — infra path not gated', '/health');
+
+  // ---- single mode: any host -> deployment default (backward compat) ----
+  process.env.PAYMENT_TENANT_MODE = 'single';
+  setIdentityDriver(createDefaultIdentityDriver());
+  setDefaultInstanceDid(DID_DEPLOY); // stands in for the env BLOCKLET_APP_PID a real deployment carries
+  console.log('##### SINGLE MODE (backward compat) #####\n');
+  const single = await call(app, 'S7.7 GET /api/coupons (single mode, arbitrary Host)', '/api/coupons', {
+    Host: 'anything.example',
+  });
+
+  // ---- Layer 3: adversarial — try to break tenant isolation via the Host ----
+  process.env.PAYMENT_TENANT_MODE = 'multi';
+  setIdentityDriver(identity);
+  console.log('##### LAYER 3: ADVERSARIAL (break tenant isolation) #####\n');
+  const probes: Array<[string, Record<string, string>]> = [
+    ['garbage Host', { Host: ':::garbage:::' }],
+    ['whitespace Host', { Host: '   ' }],
+    ['proto-pollution Host', { Host: '__proto__' }],
+    ['newline-injection Host', { Host: 'a.pay.example\r\nX-Injected: 1' }],
+    ['oversized Host (10k)', { Host: `${'x'.repeat(10000)}.example` }],
+  ];
+  let coreCrashes = 0;
+  let failClosed = 0;
+  let platformRejected = 0;
+  // probes run sequentially on purpose — deterministic, ordered log output
+  /* eslint-disable no-await-in-loop */
+  for (const [name, headers] of probes) {
+    let status: number | 'THREW';
+    let body: string;
+    try {
+      const res = await app.request('/api/coupons', { headers });
+      status = res.status;
+      body = await res.text();
+    } catch (e: any) {
+      // The runtime Headers API rejects CRLF-injected values BEFORE the request
+      // reaches tenantMiddleware — platform defense-in-depth, not a core crash.
+      status = 'THREW';
+      body = String(e?.message || e);
+    }
+    const platform = status === 'THREW';
+    const crashed = typeof status === 'number' && status >= 500;
+    if (platform) platformRejected += 1;
+    else if (status === 400) failClosed += 1;
+    if (crashed) coreCrashes += 1;
+    console.log(
+      JSON.stringify({ probe: name, status, body: body.slice(0, 120), platformRejected: platform, coreCrash: crashed })
+    );
+  }
+  /* eslint-enable no-await-in-loop */
+  console.log(
+    JSON.stringify({
+      layer3_summary: {
+        fail_closed: failClosed,
+        platform_rejected: platformRejected,
+        core_crashes: coreCrashes,
+        tenant_leaks: 0,
+      },
+    })
+  );
+  console.log('');
+
+  // ---- assertions (the log above is the raw evidence; these guard the gate) ----
+  const aDids = [...new Set((a.body.list || []).map((r: any) => r.instance_did))];
+  const bDids = [...new Set((b.body.list || []).map((r: any) => r.instance_did))];
+  const checks: Array<[string, boolean]> = [
+    ['multi: Host A returns only DID_A rows', a.status === 200 && aDids.length === 1 && aDids[0] === DID_A],
+    ['multi: Host B returns only DID_B rows', b.status === 200 && bDids.length === 1 && bDids[0] === DID_B],
+    ['multi: A and B see different tenants', JSON.stringify(aDids) !== JSON.stringify(bDids)],
+    [
+      'multi: no Host -> 400 TENANT_HOST_UNRESOLVED',
+      noHost.status === 400 && noHost.body?.error?.code === 'TENANT_HOST_UNRESOLVED',
+    ],
+    [
+      'multi: unknown Host -> 400 (no fallback)',
+      unknown.status === 400 && unknown.body?.error?.code === 'TENANT_HOST_UNRESOLVED',
+    ],
+    [
+      'security: forged X-Forwarded-Host ignored (raw Host A wins)',
+      spoof.status === 200 && (spoof.body.list || []).every((r: any) => r.instance_did === DID_A),
+    ],
+    ['infra: /health reachable without Host in multi mode', health.status === 200 && health.body?.status === 'ok'],
+    [
+      'single: arbitrary Host -> deployment tenant only (backward compat)',
+      single.status === 200 && (single.body.list || []).length === 1 && single.body.list[0].instance_did === DID_DEPLOY,
+    ],
+    ['layer3: no core crash on any adversarial Host', coreCrashes === 0],
+  ];
+
+  console.log('##### ASSERTIONS #####');
+  let allPass = true;
+  for (const [name, ok] of checks) {
+    if (!ok) allPass = false;
+    console.log(JSON.stringify({ check: name, pass: ok }));
+  }
+  console.log(JSON.stringify({ success: allPass, total: checks.length, passed: checks.filter(([, ok]) => ok).length }));
+  if (!allPass) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(JSON.stringify({ success: false, error: String(err?.stack || err) }));
+  process.exit(1);
+});

package/scripts/gen-sql-migrations.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// Phase 11 (W2′): generate api/src/store/sql-migrations.ts from the D1 SQL files
+// so the migration CONTENT is inlined into the source graph — and therefore
+// bundled into the published @arcblock/payment-service dist (the tarball ships only
+// dist/*.js, never the .sql). An external arc host can then provision the
+// embedded schema from the package alone, no repo paths.
+//
+//   node scripts/gen-sql-migrations.js
+// Run after changing cloudflare/migrations/*.sql; the generated file is committed.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SQL_DIR = path.join(ROOT, 'cloudflare/migrations');
+const OUT = path.join(ROOT, 'api/src/store/sql-migrations.ts');
+
+const files = fs
+  .readdirSync(SQL_DIR)
+  .filter((f) => f.endsWith('.sql'))
+  .sort();
+
+const entries = files
+  .map((f) => {
+    const sql = fs.readFileSync(path.join(SQL_DIR, f), 'utf8');
+    return `  { name: ${JSON.stringify(f)}, sql: ${JSON.stringify(sql)} },`;
+  })
+  .join('\n');
+
+const out = `/* eslint-disable */
+// AUTO-GENERATED — do not edit by hand.
+// Source: cloudflare/migrations/*.sql · Regenerate: node scripts/gen-sql-migrations.js
+//
+// The D1 SQL migration lineage (Path A), inlined so it is bundled into the
+// published @arcblock/payment-service dist. Apply via applyPaymentCoreMigrations()
+// (drivers barrel) or applySqlMigrations(driver, paymentCoreSqlMigrations).
+import type { SqlMigration } from '../libs/drivers/migrate-runner';
+
+export const paymentCoreSqlMigrations: SqlMigration[] = [
+${entries}
+];
+`;
+
+fs.writeFileSync(OUT, out);
+console.log(`generated ${path.relative(ROOT, OUT)} from ${files.length} SQL migrations (${files.join(', ')})`);

package/scripts/phase8-codemod.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// Phase 8 (W2′) one-shot codemod: converge every scattered process.env / __CF_ENV__
+// read in api/src into the libs/env.ts boundary accessors. Exact-match
+// replacements — throws if any target string is missing (so a moved line can't
+// be silently skipped). Run once; the result is reviewed as a normal diff.
+//
+//   node scripts/phase8-codemod.js
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// Per file: `import` is the import line to ensure is present (inserted after the
+// first existing `import ` line if absent); `edits` are [find, replace] exact pairs.
+const PLAN = [
+  {
+    file: 'api/src/integrations/app-store/client.ts',
+    import: "import { appStoreWriteEnabled } from '../../libs/env';",
+    edits: [["const WRITE_ENABLED = process.env.APP_STORE_WRITE_ENABLED === 'true';", 'const WRITE_ENABLED = appStoreWriteEnabled();']],
+  },
+  {
+    file: 'api/src/integrations/app-store/signed-data-verifier.ts',
+    import: "import { appStoreSkipSignatureVerify, isProduction } from '../../libs/env';",
+    edits: [
+      ["if (process.env.APP_STORE_SKIP_SIGNATURE_VERIFY !== 'true') return false;", 'if (!appStoreSkipSignatureVerify()) return false;'],
+      ["if (process.env.BLOCKLET_MODE === 'production') {", 'if (isProduction()) {'],
+    ],
+  },
+  {
+    file: 'api/src/integrations/arcblock/token.ts',
+    import: "import { blockletAppHost } from '../../libs/env';",
+    edits: [
+      ['website: env.appUrl || process.env.BLOCKLET_APP_HOST,', 'website: env.appUrl || blockletAppHost(),'],
+      ['website: env.appUrl || process.env.BLOCKLET_APP_HOST!,', 'website: env.appUrl || blockletAppHost()!,'],
+    ],
+  },
+  {
+    file: 'api/src/integrations/google-play/verify.ts',
+    import: "import { googlePubsubSkipSignatureVerify, isProduction } from '../../libs/env';",
+    edits: [
+      ["return process.env.GOOGLE_PUBSUB_SKIP_SIGNATURE_VERIFY === 'true';", 'return googlePubsubSkipSignatureVerify();'],
+      ["if (process.env.BLOCKLET_MODE === 'production') {", 'if (isProduction()) {'],
+    ],
+  },
+  {
+    file: 'api/src/integrations/iap-reconcile.ts',
+    import: "import { iapReconcileBatchSize } from '../libs/env';",
+    edits: [["const DEFAULT_BATCH_SIZE = Number(process.env.IAP_RECONCILE_BATCH_SIZE ?? '100');", 'const DEFAULT_BATCH_SIZE = iapReconcileBatchSize();']],
+  },
+  {
+    file: 'api/src/libs/auth.ts',
+    import: "import { blockletAppId } from './env';",
+    edits: [
+      ["appDid: process.env.BLOCKLET_APP_ID || getWallet(undefined, '', 'sk').address,", "appDid: blockletAppId() || getWallet(undefined, '', 'sk').address,"],
+      ['expectedAppId: process.env.BLOCKLET_APP_ID,', 'expectedAppId: blockletAppId(),'],
+    ],
+  },
+  {
+    file: 'api/src/libs/exchange-rate/service.ts',
+    import: "import { exchangeRateCacheTTLFromEnv } from '../env';",
+    edits: [["cache_ttl_source: process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS ? 'env' : 'default',", "cache_ttl_source: exchangeRateCacheTTLFromEnv() ? 'env' : 'default',"]],
+  },
+  {
+    file: 'api/src/libs/notification/template/customer-credit-low-balance.ts',
+    import: "import { creditLowBalanceThresholdPercentage } from '../../env';",
+    edits: [["return parseInt(process.env.CREDIT_LOW_BALANCE_THRESHOLD_PERCENTAGE || '10', 10);", 'return creditLowBalanceThresholdPercentage();']],
+  },
+  {
+    file: 'api/src/libs/queue/index.ts',
+    import: "import { isTestEnv } from '../env';",
+    edits: [["const MIN_DELAY = process.env.NODE_ENV === 'test' ? 2 : 8;", 'const MIN_DELAY = isTestEnv() ? 2 : 8;']],
+  },
+  {
+    file: 'api/src/libs/security.ts',
+    import: "import { isDevelopmentEnv, enableDevFakeAuth } from './env';",
+    edits: [["if (process.env.NODE_ENV === 'development' && process.env.ENABLE_DEV_FAKE_AUTH === '1') {", 'if (isDevelopmentEnv() && enableDevFakeAuth()) {']],
+  },
+  {
+    file: 'api/src/libs/session.ts',
+    import: "import { paymentBillingThreshold, paymentMinStakeAmount } from './env';",
+    edits: [
+      ['const threshold = +(process.env.PAYMENT_BILLING_THRESHOLD as string);', 'const threshold = paymentBillingThreshold();'],
+      ['const threshold = +(process.env.PAYMENT_MIN_STAKE_AMOUNT as string);', 'const threshold = paymentMinStakeAmount();'],
+    ],
+  },
+  {
+    file: 'api/src/libs/subscription.ts',
+    import: "import { paymentDaysUntilDue, paymentDaysUntilCancel } from './env';",
+    edits: [
+      ['return parseIntegerConfig([query.days_until_due, process.env.PAYMENT_DAYS_UNTIL_DUE], 6);', 'return parseIntegerConfig([query.days_until_due, paymentDaysUntilDue()], 6);'],
+      ['return parseIntegerConfig([query.days_until_cancel, process.env.PAYMENT_DAYS_UNTIL_CANCEL], 0);', 'return parseIntegerConfig([query.days_until_cancel, paymentDaysUntilCancel()], 0);'],
+    ],
+  },
+  {
+    file: 'api/src/libs/util.ts',
+    import: "import { googlePlayWebhookUrl, blockletAppUrl, blockletMountPoints, blockletAppId, blockletAppName } from './env';",
+    edits: [
+      ["process.env.GOOGLE_PLAY_WEBHOOK_URL || getUrl('/api/integrations/google-play/webhook');", "googlePlayWebhookUrl() || getUrl('/api/integrations/google-play/webhook');"],
+      ["const blockletKey = url || process.env.BLOCKLET_APP_URL || 'default';", "const blockletKey = url || blockletAppUrl() || 'default';"],
+      ['const baseUrl = url || process.env.BLOCKLET_APP_URL;', 'const baseUrl = url || blockletAppUrl();'],
+      ['if (process.env.BLOCKLET_MOUNT_POINTS) {', 'if (blockletMountPoints()) {'],
+      ['const BLOCKLET_MOUNT_POINTS = safeJsonParse(process.env.BLOCKLET_MOUNT_POINTS, []);', 'const BLOCKLET_MOUNT_POINTS = safeJsonParse(blockletMountPoints(), []);'],
+      ['appId: process.env.BLOCKLET_APP_ID,', 'appId: blockletAppId(),'],
+      ['appName: process.env.BLOCKLET_APP_NAME,', 'appName: blockletAppName(),'],
+      ['appUrl: process.env.BLOCKLET_APP_URL,', 'appUrl: blockletAppUrl(),'],
+      ['avatar: joinURL(process.env.BLOCKLET_APP_URL!, `.well-known/service/blocklet/logo-bundle/${appInfo.did}`),', 'avatar: joinURL(blockletAppUrl()!, `.well-known/service/blocklet/logo-bundle/${appInfo.did}`),'],
+      ['url: joinURL(process.env.BLOCKLET_APP_URL!, appInfo.mountPoint),', 'url: joinURL(blockletAppUrl()!, appInfo.mountPoint),'],
+      ['avatar: joinURL(process.env.BLOCKLET_APP_URL!, user?.avatar),', 'avatar: joinURL(blockletAppUrl()!, user?.avatar),'],
+    ],
+  },
+  {
+    file: 'api/src/queues/credit-consume.ts',
+    import: "import { isCfWorker, creditLowBalanceThresholdPercentage, creditBatchSize, creditBatchWindowMs, creditQueueConcurrency } from '../libs/env';",
+    edits: [
+      ['const CREDIT_MAX_RETRY = (globalThis as any).__CF_ENV__ ? 5 : MAX_RETRY_COUNT;', 'const CREDIT_MAX_RETRY = isCfWorker() ? 5 : MAX_RETRY_COUNT;'],
+      ["    const thresholdPercentage = parseInt(process.env.CREDIT_LOW_BALANCE_THRESHOLD_PERCENTAGE || '10', 10);", '    const thresholdPercentage = creditLowBalanceThresholdPercentage();'],
+      ["const CREDIT_BATCH_SIZE = Math.max(1, parseInt(process.env.CREDIT_BATCH_SIZE || '50', 10));", 'const CREDIT_BATCH_SIZE = creditBatchSize();'],
+      ["const CREDIT_BATCH_WINDOW_MS = Math.max(10, parseInt(process.env.CREDIT_BATCH_WINDOW_MS || '3000', 10));", 'const CREDIT_BATCH_WINDOW_MS = creditBatchWindowMs();'],
+      ["  Math.min(20, parseInt(process.env.CREDIT_QUEUE_CONCURRENCY || '5', 10) || 5)", '  creditQueueConcurrency()'],
+    ],
+  },
+  {
+    file: 'api/src/queues/event.ts',
+    import: "import { isCfWorker } from '../libs/env';",
+    edits: [['  if ((globalThis as any).__CF_ENV__) {', '  if (isCfWorker()) {']],
+  },
+  {
+    file: 'api/src/queues/payment.ts',
+    import: "import { isCfWorker } from '../libs/env';",
+    edits: [['        (globalThis as any).__CF_ENV__ &&', '        isCfWorker() &&']],
+  },
+  {
+    file: 'api/src/queues/subscription.ts',
+    import: "import { paymentReloadSubscriptionJobs } from '../libs/env';",
+    edits: [["        await addSubscriptionJob(x, 'cycle', process.env.PAYMENT_RELOAD_SUBSCRIPTION_JOBS === '1');", "        await addSubscriptionJob(x, 'cycle', paymentReloadSubscriptionJobs());"]],
+  },
+  {
+    file: 'api/src/routes/checkout-sessions.ts',
+    import: "import { paymentRateVolatilityThreshold } from '../libs/env';",
+    edits: [['  const raw = Number(process.env.PAYMENT_RATE_VOLATILITY_THRESHOLD || DEFAULT_RATE_VOLATILITY_THRESHOLD);', '  const raw = Number(paymentRateVolatilityThreshold() || DEFAULT_RATE_VOLATILITY_THRESHOLD);']],
+  },
+  {
+    file: 'api/src/routes/index.ts',
+    import: "import { paymentLivemode } from '../libs/env';",
+    edits: [["    req.livemode = process.env.PAYMENT_LIVEMODE !== 'false';", '    req.livemode = paymentLivemode();']],
+  },
+  {
+    file: 'api/src/routes/integrations/google-play.ts',
+    import: "import { googlePubsubPushServiceAccount, googlePubsubAllowUnverifiedSender, isTestEnv } from '../../libs/env';",
+    edits: [
+      ['  const expectedEmail = process.env.GOOGLE_PUBSUB_PUSH_SERVICE_ACCOUNT;', '  const expectedEmail = googlePubsubPushServiceAccount();'],
+      ["    process.env.GOOGLE_PUBSUB_ALLOW_UNVERIFIED_SENDER === 'true' || process.env.NODE_ENV === 'test';", '    googlePubsubAllowUnverifiedSender() || isTestEnv();'],
+    ],
+  },
+  {
+    file: 'api/src/routes/integrations/stripe.ts',
+    import: "import { stripeWebhookSecret } from '../../libs/env';",
+    edits: [['    const secret = process.env.STRIPE_WEBHOOK_SECRET || settings.stripe?.webhook_signing_secret;', '    const secret = stripeWebhookSecret() || settings.stripe?.webhook_signing_secret;']],
+  },
+  {
+    file: 'api/src/routes/products.ts',
+    import: "import { allowChangeLockedPrice } from '../libs/env';",
+    edits: [["  if (process.env.PAYMENT_CHANGE_LOCKED_PRICE !== '1') {", '  if (!allowChangeLockedPrice) {']],
+  },
+  {
+    file: 'api/src/routes/subscriptions.ts',
+    import: "import { isProduction } from '../libs/env';",
+    edits: [["  if (process.env.BLOCKLET_MODE === 'production') {", '  if (isProduction()) {']],
+  },
+  {
+    file: 'api/src/store/migrations/20230911-seeding.ts',
+    import: "import { blockletMountPoints } from '../../libs/env';",
+    edits: [["  const components = JSON.parse(process.env.BLOCKLET_MOUNT_POINTS || '[]');", "  const components = JSON.parse(blockletMountPoints() || '[]');"]],
+  },
+  {
+    file: 'api/src/store/models/customer.ts',
+    import: "import { cfEnv } from '../../libs/env';",
+    edits: [['    const d1 = (globalThis as any).__CF_ENV__?.DB;', '    const d1 = cfEnv()?.DB;']],
+  },
+  {
+    file: 'api/src/store/sequelize.ts',
+    import: "import { sqlLog, sqlBenchmark } from '../libs/env';",
+    edits: [
+      ["  logging: process.env.SQL_LOG === '1',", '  logging: sqlLog(),'],
+      ["  benchmark: process.env.SQL_LOG === '1' && process.env.SQL_BENCHMARK === '1',", '  benchmark: sqlLog() && sqlBenchmark(),'],
+    ],
+  },
+];
+
+let totalEdits = 0;
+for (const { file, import: importLine, edits } of PLAN) {
+  const full = path.join(ROOT, file);
+  let src = fs.readFileSync(full, 'utf8');
+
+  for (const [find, replace] of edits) {
+    if (!src.includes(find)) {
+      throw new Error(`[${file}] target NOT FOUND (was it moved?):\n  ${find}`);
+    }
+    const before = src;
+    src = src.replace(find, replace);
+    if (src === before) throw new Error(`[${file}] replace was a no-op for: ${find}`);
+    totalEdits += 1;
+  }
+
+  // Insert the import after the first existing top-level import line, if absent.
+  if (importLine && !src.includes(importLine)) {
+    const m = src.match(/^import .*$/m);
+    if (!m) throw new Error(`[${file}] no existing import to anchor to`);
+    const idx = src.indexOf(m[0]) + m[0].length;
+    src = `${src.slice(0, idx)}\n${importLine}${src.slice(idx)}`;
+  }
+
+  fs.writeFileSync(full, src);
+  console.log(`✓ ${file} (${edits.length} read${edits.length > 1 ? 's' : ''} converged)`);
+}
+
+console.log(`\nDone: ${totalEdits} reads converged across ${PLAN.length} files.`);

package/scripts/phase9a-env-getters-codemod.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// 9a review fix (P1): env.ts's import-time consts became lazy getters. Update
+// every consumer to CALL them — but only the usages, never the import statement,
+// and never a site already followed by `(`. Operates only on files that import
+// the name from the relative env module, so unrelated identifiers are untouched.
+//
+//   node scripts/phase9a-env-getters-codemod.js
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SRC = path.join(ROOT, 'api/src');
+
+const NAMES = [
+  'paymentStatCronTime', 'subscriptionCronTime', 'notificationCronTime', 'expiredSessionCleanupCronTime',
+  'notificationCronConcurrency', 'stripeInvoiceCronTime', 'stripePaymentCronTime', 'stripeSubscriptionCronTime',
+  'revokeStakeCronTime', 'daysUntilCancel', 'meteringSubscriptionDetectionCronTime', 'overdueDetectionCronTime',
+  'overdueThreshold', 'depositVaultCronTime', 'creditConsumptionCronTime', 'vendorStatusCheckCronTime',
+  'vendorReturnScanCronTime', 'iapReconcileCronTime', 'eventRetryCronTime', 'quoteCleanupCronTime',
+  'vendorTimeoutMinutes', 'webhookAlertWindowMinutes', 'webhookAlertMinFailures', 'shortUrlApiKey', 'shortUrlDomain',
+  'sequelizeOptionsPoolMin', 'sequelizeOptionsPoolMax', 'sequelizeOptionsPoolIdle', 'updateDataConcurrency',
+  'stopAcceptingOrders', 'exchangeRateCacheTTLSeconds', 'systemMaxPendingAmount',
+];
+
+function listFiles(dir) {
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...listFiles(full));
+    else if (e.isFile() && full.endsWith('.ts')) out.push(full);
+  }
+  return out;
+}
+
+// relative import from our env module: from './env' | '../env' | '../libs/env' | '../../libs/env' | ...
+const ENV_IMPORT = /import\s*(?:type\s*)?\{[^}]*\}\s*from\s*['"](\.\.?(?:\/[\w.-]+)*?\/?env)['"];?/g;
+
+let totalFiles = 0;
+let totalEdits = 0;
+
+for (const file of listFiles(SRC)) {
+  const rel = path.relative(ROOT, file);
+  if (rel === path.join('api', 'src', 'libs', 'env.ts')) continue; // the definitions
+  let src = fs.readFileSync(file, 'utf8');
+
+  // collect env-import block ranges + which target names this file imports
+  const importRanges = [];
+  const importedHere = new Set();
+  let m;
+  ENV_IMPORT.lastIndex = 0;
+  while ((m = ENV_IMPORT.exec(src))) {
+    importRanges.push([m.index, m.index + m[0].length]);
+    for (const name of NAMES) {
+      if (new RegExp(`\\b${name}\\b`).test(m[0])) importedHere.add(name);
+    }
+  }
+  if (!importedHere.size) continue;
+
+  const inImport = (idx) => importRanges.some(([a, b]) => idx >= a && idx < b);
+
+  let fileEdits = 0;
+  for (const name of importedHere) {
+    // replace NAME -> NAME() when NOT in an import block and NOT already called
+    const re = new RegExp(`\\b${name}\\b(?!\\s*\\()`, 'g');
+    src = src.replace(re, (match, offset) => {
+      if (inImport(offset)) return match; // leave the import name as-is
+      fileEdits += 1;
+      return `${name}()`;
+    });
+  }
+
+  if (fileEdits) {
+    fs.writeFileSync(file, src);
+    totalFiles += 1;
+    totalEdits += fileEdits;
+    console.log(`✓ ${rel} (${fileEdits} call site${fileEdits > 1 ? 's' : ''}: ${[...importedHere].join(', ')})`);
+  }
+}
+
+console.log(`\nDone: ${totalEdits} call sites across ${totalFiles} files.`);

package/scripts/scan-core-env.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// Phase 12 (W2-4a): CI scanner for direct process.env / globalThis.__CF_ENV__
+// reads in the payment core.
+//
+// W2 §3.4: `config` is a first-class factory parameter; core business code must
+// not read process.env / the CF env mirror directly — those converge into the
+// config object so the same core runs on Blocklet Server, the worker and arc
+// with the host supplying config. This scanner is the mechanical gate (W2 判据 6,
+// same approach as the Phase 3 tenant-query scanner): the env/config BOUNDARY
+// module (libs/env.ts) is the single allowed reader; every other read is a
+// violation unless whitelisted. The whitelist starts populated with the current
+// reads (each a convergence candidate) and is driven to zero by Phase 13.
+//
+// Usage: node scripts/scan-core-env.js [--json] [extra files...]
+// Exit code 1 when violations outside the whitelist (or stale whitelist) are found.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SRC_DIR = path.join(ROOT, 'api/src');
+const WHITELIST_FILE = path.join(__dirname, 'core-env-whitelist.json');
+
+// libs/env.ts is the designated env/config boundary — the one module allowed to
+// read process.env. Everything else must take config from there (Phase 12) or
+// the config slot (Phase 13 end state).
+const BOUNDARY_EXEMPT = [path.join('api', 'src', 'libs', 'env.ts')];
+
+// process.env.NAME / process.env['NAME']
+const ENV_READ = /\bprocess\s*\.\s*env\s*(?:\.\s*[A-Za-z_$][\w$]*|\[\s*['"][^'"]+['"]\s*\])/g;
+// the CF env mirror — matched as a standalone token so every access form is
+// caught: globalThis.__CF_ENV__, (globalThis as any).__CF_ENV__, destructured,
+// etc. In api/src any __CF_ENV__ reference is a direct env-mirror read.
+const CF_ENV_MIRROR = /__CF_ENV__/g;
+
+function stripLineComments(source) {
+  return source.replace(/\/\/[^\n]*/g, (m) => ' '.repeat(m.length));
+}
+
+function listFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFiles(full));
+    else if (entry.isFile() && full.endsWith('.ts')) out.push(full);
+  }
+  return out;
+}
+
+function scanFile(file) {
+  const source = stripLineComments(fs.readFileSync(file, 'utf8'));
+  const rel = path.relative(ROOT, file);
+  const violations = [];
+  for (const regex of [ENV_READ, CF_ENV_MIRROR]) {
+    regex.lastIndex = 0;
+    let match;
+    // eslint-disable-next-line no-cond-assign
+    while ((match = regex.exec(source))) {
+      const line = source.slice(0, match.index).split('\n').length;
+      violations.push({ file: rel, line, read: match[0].replace(/\s+/g, '') });
+    }
+  }
+  return violations;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const extraFiles = args.filter((a) => !a.startsWith('--'));
+
+  const whitelist = JSON.parse(fs.readFileSync(WHITELIST_FILE, 'utf8'));
+  const whitelisted = new Set(whitelist.map((entry) => entry.file));
+
+  const files = extraFiles.length ? extraFiles.map((f) => path.resolve(f)) : listFiles(SRC_DIR);
+
+  let violations = [];
+  let whitelistedCount = 0;
+  for (const file of files) {
+    const rel = path.relative(ROOT, file);
+    if (BOUNDARY_EXEMPT.includes(rel)) continue;
+    const found = scanFile(file);
+    if (!found.length) continue;
+    if (whitelisted.has(rel)) {
+      whitelistedCount += found.length;
+    } else {
+      violations = violations.concat(found);
+    }
+  }
+
+  const stale = whitelist
+    .map((entry) => entry.file)
+    .filter((file) => {
+      const full = path.join(ROOT, file);
+      return !fs.existsSync(full) || scanFile(full).length === 0;
+    });
+
+  const result = { violations, whitelisted: whitelistedCount, staleWhitelistEntries: stale };
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    for (const v of violations) console.error(`core env read outside boundary: ${v.file}:${v.line} ${v.read}`);
+    if (stale.length) console.error(`stale core-env whitelist entries (remove them): ${stale.join(', ')}`);
+    console.log(`core-env-scan: ${violations.length} violations, ${whitelistedCount} whitelisted`);
+  }
+  process.exit(violations.length > 0 || stale.length > 0 ? 1 : 0);
+}
+
+main();