payment-kit 1.29.0 → 1.29.2

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

@@ -0,0 +1,194 @@
+// Phase 11 (W2-3): secrets slot driver contract — per-tenant keyring.
+//
+// Replaces the process-level single key (cloudflare/shims/blocklet-sdk/security
+// `_password`, initialized once from APP_PID's EK). Each tenant gets its own
+// encryption key derived from its own EK, so one tenant's key can never decrypt
+// another's ciphertext.
+//
+// Two surfaces, because the payment hot path (PaymentMethod.encrypt/decrypt
+// Settings, getStripeClient, ~50 sync call sites) cannot become async without a
+// large, risky ripple:
+//   - encrypt/decrypt (async): the full contract — lazy EK fetch + cache + TTL,
+//     and decrypt-failure forces one EK re-fetch (tolerates identity-side EK
+//     rotation). Hosts use this.
+//   - encryptSync/decryptSync: the hot path — uses an already-resolved key
+//     (default driver: the process key; keyring driver: the cached password,
+//     warmed via warmup()). Throws if the keyring key is cold (fail-closed).
+//   - warmup(instanceDid): async pre-resolve so the sync path is a cache hit
+//     (no-op for the single-tenant default driver).
+//
+// single mode (Blocklet Server) uses the default driver = the existing process
+// `@blocklet/sdk/lib/security`, so existing ciphertext stays decryptable and
+// behavior is unchanged.
+
+/* eslint-disable max-classes-per-file */
+import crypto from 'crypto';
+
+import type { IdentityDriver } from './identity';
+
+// crypto-js ships no type declarations; required untyped (same AES chain as the
+// prior process security so ciphertext is interchangeable)
+// eslint-disable-next-line @typescript-eslint/no-var-requires, global-require, import/no-extraneous-dependencies
+const CryptoJS: any = require('crypto-js');
+
+export interface SecretsDriver {
+  /** async per-tenant encrypt — lazy-resolves the tenant key on first use */
+  encrypt(instanceDid: string, value: string): Promise<string>;
+  /** async per-tenant decrypt — re-fetches the EK once on failure (EK rotation tolerance) */
+  decrypt(instanceDid: string, value: string): Promise<string>;
+  /** sync hot path — requires the tenant key already resolved (warmup first for the keyring) */
+  encryptSync(instanceDid: string, value: string): string;
+  decryptSync(instanceDid: string, value: string): string;
+  /** pre-resolve the tenant key so the sync path is a cache hit (no-op for the default driver) */
+  warmup(instanceDid: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// default driver — single-tenant, delegates to the process @blocklet/sdk security
+// ---------------------------------------------------------------------------
+
+class DefaultSecretsDriver implements SecretsDriver {
+  // lazily required so importing this module stays side-effect-free
+  private security() {
+    // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+    return require('@blocklet/sdk/lib/security').default ?? require('@blocklet/sdk/lib/security');
+  }
+
+  encryptSync(_instanceDid: string, value: string): string {
+    return this.security().encrypt(value);
+  }
+
+  decryptSync(_instanceDid: string, value: string): string {
+    return this.security().decrypt(value);
+  }
+
+  // eslint-disable-next-line require-await -- async contract; the single key is sync
+  async encrypt(instanceDid: string, value: string): Promise<string> {
+    return this.encryptSync(instanceDid, value);
+  }
+
+  // eslint-disable-next-line require-await -- async contract; the single key is sync
+  async decrypt(instanceDid: string, value: string): Promise<string> {
+    return this.decryptSync(instanceDid, value);
+  }
+
+  async warmup(): Promise<void> {
+    /* single key is always available — nothing to warm */
+  }
+}
+
+export function createDefaultSecretsDriver(): SecretsDriver {
+  return new DefaultSecretsDriver();
+}
+
+// ---------------------------------------------------------------------------
+// keyring driver — per-tenant key derived from each tenant's EK
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000; // 10 min
+
+type CacheEntry = { password: string; expiresAt: number };
+
+// AES decrypt with a wrong key can throw "Malformed UTF-8" or return empty,
+// depending on the ciphertext bytes. Normalize both to '' so a wrong key is a
+// deterministic failure (never the plaintext, never a crash) — this is what
+// drives the decrypt-retry and what keeps cross-tenant decryption safe.
+function safeUtf8(decrypted: any): string {
+  try {
+    return decrypted.toString(CryptoJS.enc.Utf8);
+  } catch {
+    return '';
+  }
+}
+
+function derivePassword(appEk: string, instanceDid: string): string {
+  // identical chain to the prior process security: PBKDF2(EK, salt) -> AES key.
+  // salt = the tenant DID (== blockletDid in single mode), so single-mode
+  // ciphertext written by the old path stays decryptable when the same EK is
+  // returned by identity.getAppEk(instanceDid).
+  return crypto.pbkdf2Sync(appEk, instanceDid, 256, 32, 'sha512').toString('hex');
+}
+
+class KeyringSecretsDriver implements SecretsDriver {
+  private identity: IdentityDriver;
+  private ttlMs: number;
+  private cache = new Map<string, CacheEntry>();
+
+  constructor(identity: IdentityDriver, opts?: { ttlMs?: number }) {
+    if (typeof identity.getAppEk !== 'function') {
+      throw new Error('createKeyringSecretsDriver: identity driver must provide getAppEk(instanceDid)');
+    }
+    this.identity = identity;
+    this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+  }
+
+  private fresh(instanceDid: string): string | null {
+    const entry = this.cache.get(instanceDid);
+    if (entry && entry.expiresAt > Date.now()) return entry.password;
+    return null;
+  }
+
+  private async resolvePassword(instanceDid: string, force = false): Promise<string> {
+    if (!force) {
+      const cached = this.fresh(instanceDid);
+      if (cached) return cached;
+    }
+    const appEk = await this.identity.getAppEk!(instanceDid);
+    if (!appEk) {
+      throw new Error(`secrets: no EK for tenant ${instanceDid}`);
+    }
+    const password = derivePassword(appEk, instanceDid);
+    this.cache.set(instanceDid, { password, expiresAt: Date.now() + this.ttlMs });
+    return password;
+  }
+
+  async warmup(instanceDid: string): Promise<void> {
+    await this.resolvePassword(instanceDid);
+  }
+
+  encryptSync(instanceDid: string, value: string): string {
+    const password = this.fresh(instanceDid);
+    if (!password) throw new Error(`secrets: key for tenant ${instanceDid} is not warmed (call warmup first)`);
+    return CryptoJS.AES.encrypt(value, password).toString();
+  }
+
+  decryptSync(instanceDid: string, value: string): string {
+    const password = this.fresh(instanceDid);
+    if (!password) throw new Error(`secrets: key for tenant ${instanceDid} is not warmed (call warmup first)`);
+    return safeUtf8(CryptoJS.AES.decrypt(value, password));
+  }
+
+  async encrypt(instanceDid: string, value: string): Promise<string> {
+    const password = await this.resolvePassword(instanceDid);
+    return CryptoJS.AES.encrypt(value, password).toString();
+  }
+
+  async decrypt(instanceDid: string, value: string): Promise<string> {
+    let password = await this.resolvePassword(instanceDid);
+    let plain = safeUtf8(CryptoJS.AES.decrypt(value, password));
+    if (!plain) {
+      // empty result == wrong key (likely rotated EK) -> force one re-fetch + retry
+      password = await this.resolvePassword(instanceDid, true);
+      plain = safeUtf8(CryptoJS.AES.decrypt(value, password));
+    }
+    return plain;
+  }
+}
+
+export function createKeyringSecretsDriver(identity: IdentityDriver, opts?: { ttlMs?: number }): SecretsDriver {
+  return new KeyringSecretsDriver(identity, opts);
+}
+
+// ---------------------------------------------------------------------------
+// active driver + tenant-aware facade (resolves tenant from TenantContext)
+// ---------------------------------------------------------------------------
+
+let activeSecretsDriver: SecretsDriver = createDefaultSecretsDriver();
+
+export function setSecretsDriver(driver: SecretsDriver): void {
+  activeSecretsDriver = driver;
+}
+
+export function getSecretsDriver(): SecretsDriver {
+  return activeSecretsDriver;
+}

package/api/src/libs/env.ts

@@ -1,68 +1,184 @@
 import { env } from '@blocklet/sdk/lib/env';
 
-export const paymentStatCronTime: string = '0 1 0 * * *'; // 默认每天一次，计算前一天的
-export const subscriptionCronTime: string = process.env.SUBSCRIPTION_CRON_TIME || '0 */30 * * * *'; // 默认每 30 min 行一次
-export const notificationCronTime: string = process.env.NOTIFICATION_CRON_TIME || '0 5 */6 * * *'; // 默认每6个小时执行一次
-export const expiredSessionCleanupCronTime: string = process.env.EXPIRED_SESSION_CLEANUP_CRON_TIME || '0 1 * * * *'; // 默认每小时执行一次
-export const notificationCronConcurrency: number = Number(process.env.NOTIFICATION_CRON_CONCURRENCY) || 8; // 默认并发数为 8
-export const stripeInvoiceCronTime: string = process.env.STRIPE_INVOICE_CRON_TIME || '0 */30 * * * *'; // 默认每 30min 执行一次
-export const stripePaymentCronTime: string = process.env.STRIPE_PAYMENT_CRON_TIME || '0 */20 * * * *'; // 默认每 20min 执行一次
-export const stripeSubscriptionCronTime: string = process.env.STRIPE_SUBSCRIPTION_CRON_TIME || '0 10 */8 * * *'; // 默认每 8小时 执行一次
-export const revokeStakeCronTime: string = process.env.REVOKE_STAKE_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次
-export const daysUntilCancel: string | undefined = process.env.DAYS_UNTIL_CANCEL;
-export const meteringSubscriptionDetectionCronTime: string =
-  process.env.METERING_SUBSCRIPTION_DETECTION_CRON_TIME || '0 0 10 * * *'; // 默认每天 10:00 执行
-export const overdueDetectionCronTime: string = process.env.OVERDUE_DETECTION_CRON_TIME || '0 0 10 * * *'; // 默认每天 10:00 执行
-export const overdueThreshold: number = process.env.OVERDUE_THRESHOLD ? +process.env.OVERDUE_THRESHOLD : 5; // 默认超额阈值为 5
-export const depositVaultCronTime: string = process.env.DEPOSIT_VAULT_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次
-export const creditConsumptionCronTime: string = process.env.CREDIT_CONSUMPTION_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
-export const vendorStatusCheckCronTime: string = process.env.VENDOR_STATUS_CHECK_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
-export const vendorReturnScanCronTime: string = process.env.VENDOR_RETURN_SCAN_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
-export const iapReconcileCronTime: string = process.env.IAP_RECONCILE_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次:webhook 兜底,拉 App Store / Google Play 订阅最新状态
-export const eventRetryCronTime: string = process.env.EVENT_RETRY_CRON_TIME || '30 */5 * * * *'; // 默认每 5 min 执行一次(错开整点避开 iap-reconcile):扫 pending_webhooks>0 的事件兜底投递
-export const quoteCleanupCronTime: string = process.env.QUOTE_CLEANUP_CRON_TIME || '0 0 2 * * *'; // 默认每天凌晨 2 点执行一次
-export const vendorTimeoutMinutes: number = process.env.VENDOR_TIMEOUT_MINUTES
-  ? +process.env.VENDOR_TIMEOUT_MINUTES
-  : 10; // 默认 10 分钟超时
-export const webhookAlertWindowMinutes: number = process.env.WEBHOOK_ALERT_WINDOW_MINUTES
-  ? +process.env.WEBHOOK_ALERT_WINDOW_MINUTES
-  : 10; // webhook 连续失败告警时间窗口，默认 10 分钟
-export const webhookAlertMinFailures: number = process.env.WEBHOOK_ALERT_MIN_FAILURES
-  ? +process.env.WEBHOOK_ALERT_MIN_FAILURES
-  : 3; // webhook 触发告警的最小失败次数，默认 3 次
-
-export const shortUrlApiKey: string = process.env.SHORT_URL_API_KEY || '';
-export const shortUrlDomain: string = process.env.SHORT_URL_DOMAIN || 's.abtnet.io';
+// ──────────────────────────────────────────────────────────────────────────
+// Phase 8 (W2′): the injected-config slot, made authoritative here.
+//
+// libs/env.ts is the ONE module the core-env scanner exempts — the single
+// allowed reader of process.env / the CF env mirror. Phase 8 converges every
+// scattered `process.env.X` read in api/src INTO the accessors below so the
+// whitelist goes to zero.
+//
+// The factory (createEmbeddedPaymentService) calls setCoreConfig(config) so the
+// injected config object becomes the source of truth. Reads fall back to
+// process.env when a key is absent from the injected config — which keeps every
+// host working unchanged: the blocklet server populates process.env natively,
+// and the CF worker mirrors CF env into process.env per request (that mirror is
+// deleted in Phase 12, once the worker routes through the factory config slot).
+// ──────────────────────────────────────────────────────────────────────────
+let activeConfig: Record<string, any> | undefined;
+
+/** Wire the injected config object (factory only). Pass undefined to clear (tests). */
+export function setCoreConfig(config: Record<string, any> | undefined): void {
+  activeConfig = config;
+}
+
+/** The injected config object, or undefined before the factory has run. */
+export function getCoreConfig(): Record<string, any> | undefined {
+  return activeConfig;
+}
+
+/**
+ * Read a config key: the injected config wins; otherwise the process.env
+ * fallback (blocklet server native / worker mirror). Returns a string or
+ * undefined — callers parse/typecheck. This is the single boundary read.
+ */
+export function readConfig(key: string): string | undefined {
+  const injected = activeConfig?.[key];
+  if (injected !== undefined && injected !== null) return String(injected);
+  const fromEnv = process.env[key];
+  return fromEnv === undefined ? undefined : fromEnv;
+}
+
+/** True iff the key is present (non-empty) in injected config or process.env. */
+export function hasConfig(key: string): boolean {
+  const v = readConfig(key);
+  return v !== undefined && v !== '';
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// P1 (9a review fix): these were import-time `process.env` consts — frozen
+// before the factory could setCoreConfig, so injected config could never
+// override them (now that 9a bundles the canonical core into the published
+// package, that mattered for arc). They are LAZY getters now, reading via the
+// readConfig boundary, honored at call time. Consumers call them at use time.
+// ──────────────────────────────────────────────────────────────────────────
+const numConfig = (key: string, fallback: number): number => {
+  const v = readConfig(key);
+  return v ? +v : fallback;
+};
+
+export const paymentStatCronTime = (): string => '0 1 0 * * *'; // 默认每天一次，计算前一天的
+export const subscriptionCronTime = (): string => readConfig('SUBSCRIPTION_CRON_TIME') || '0 */30 * * * *';
+export const notificationCronTime = (): string => readConfig('NOTIFICATION_CRON_TIME') || '0 5 */6 * * *';
+export const expiredSessionCleanupCronTime = (): string =>
+  readConfig('EXPIRED_SESSION_CLEANUP_CRON_TIME') || '0 1 * * * *';
+export const notificationCronConcurrency = (): number => Number(readConfig('NOTIFICATION_CRON_CONCURRENCY')) || 8;
+export const stripeInvoiceCronTime = (): string => readConfig('STRIPE_INVOICE_CRON_TIME') || '0 */30 * * * *';
+export const stripePaymentCronTime = (): string => readConfig('STRIPE_PAYMENT_CRON_TIME') || '0 */20 * * * *';
+export const stripeSubscriptionCronTime = (): string => readConfig('STRIPE_SUBSCRIPTION_CRON_TIME') || '0 10 */8 * * *';
+export const revokeStakeCronTime = (): string => readConfig('REVOKE_STAKE_CRON_TIME') || '0 */5 * * * *';
+export const daysUntilCancel = (): string | undefined => readConfig('DAYS_UNTIL_CANCEL');
+export const meteringSubscriptionDetectionCronTime = (): string =>
+  readConfig('METERING_SUBSCRIPTION_DETECTION_CRON_TIME') || '0 0 10 * * *';
+export const overdueDetectionCronTime = (): string => readConfig('OVERDUE_DETECTION_CRON_TIME') || '0 0 10 * * *';
+export const overdueThreshold = (): number => numConfig('OVERDUE_THRESHOLD', 5);
+export const depositVaultCronTime = (): string => readConfig('DEPOSIT_VAULT_CRON_TIME') || '0 */5 * * * *';
+export const creditConsumptionCronTime = (): string => readConfig('CREDIT_CONSUMPTION_CRON_TIME') || '0 */10 * * * *';
+export const vendorStatusCheckCronTime = (): string => readConfig('VENDOR_STATUS_CHECK_CRON_TIME') || '0 */10 * * * *';
+export const vendorReturnScanCronTime = (): string => readConfig('VENDOR_RETURN_SCAN_CRON_TIME') || '0 */10 * * * *';
+export const iapReconcileCronTime = (): string => readConfig('IAP_RECONCILE_CRON_TIME') || '0 */5 * * * *';
+export const eventRetryCronTime = (): string => readConfig('EVENT_RETRY_CRON_TIME') || '30 */5 * * * *';
+export const quoteCleanupCronTime = (): string => readConfig('QUOTE_CLEANUP_CRON_TIME') || '0 0 2 * * *';
+export const vendorTimeoutMinutes = (): number => numConfig('VENDOR_TIMEOUT_MINUTES', 10);
+export const webhookAlertWindowMinutes = (): number => numConfig('WEBHOOK_ALERT_WINDOW_MINUTES', 10);
+export const webhookAlertMinFailures = (): number => numConfig('WEBHOOK_ALERT_MIN_FAILURES', 3);
+
+export const shortUrlApiKey = (): string => readConfig('SHORT_URL_API_KEY') || '';
+export const shortUrlDomain = (): string => readConfig('SHORT_URL_DOMAIN') || 's.abtnet.io';
 
 // sequelize 配置相关
-export const sequelizeOptionsPoolMin: number = process.env.SEQUELIZE_OPTIONS_POOL_MIN
-  ? +process.env.SEQUELIZE_OPTIONS_POOL_MIN
-  : 0;
-export const sequelizeOptionsPoolMax: number = process.env.SEQUELIZE_OPTIONS_POOL_MAX
-  ? +process.env.SEQUELIZE_OPTIONS_POOL_MAX
-  : 5;
-export const sequelizeOptionsPoolIdle: number = process.env.SEQUELIZE_OPTIONS_POOL_IDLE
-  ? +process.env.SEQUELIZE_OPTIONS_POOL_IDLE
-  : 10 * 1000;
-
-export const updateDataConcurrency: number = process.env.UPDATE_DATA_CONCURRENCY
-  ? +process.env.UPDATE_DATA_CONCURRENCY
-  : 5; // 默认并发数为 5
+export const sequelizeOptionsPoolMin = (): number => numConfig('SEQUELIZE_OPTIONS_POOL_MIN', 0);
+export const sequelizeOptionsPoolMax = (): number => numConfig('SEQUELIZE_OPTIONS_POOL_MAX', 5);
+export const sequelizeOptionsPoolIdle = (): number => numConfig('SEQUELIZE_OPTIONS_POOL_IDLE', 10 * 1000);
+
+export const updateDataConcurrency = (): number => numConfig('UPDATE_DATA_CONCURRENCY', 5);
 
 // When set to 'true' or '1', the system stops accepting new orders.
 // Existing checkout sessions can still be viewed but new submissions will be rejected.
-export const stopAcceptingOrders: boolean =
-  process.env.PAYMENT_KIT_STOP_ACCEPTING_ORDERS === 'true' || process.env.PAYMENT_KIT_STOP_ACCEPTING_ORDERS === '1';
+export const stopAcceptingOrders = (): boolean =>
+  readConfig('PAYMENT_KIT_STOP_ACCEPTING_ORDERS') === 'true' || readConfig('PAYMENT_KIT_STOP_ACCEPTING_ORDERS') === '1';
 
-export const exchangeRateCacheTTLSeconds: number = process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS
-  ? +process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS
-  : 10 * 60;
+export const exchangeRateCacheTTLSeconds = (): number => numConfig('EXCHANGE_RATE_CACHE_TTL_SECONDS', 10 * 60);
 
 // System-level maximum pending amount limit (in token format, e.g., "10")
 // Default is 0 (disabled). Set PAYMENT_KIT_MAX_PENDING_AMOUNT to enable this limit.
-export const systemMaxPendingAmount: number = process.env.PAYMENT_KIT_MAX_PENDING_AMOUNT
-  ? +process.env.PAYMENT_KIT_MAX_PENDING_AMOUNT
-  : 5;
+export const systemMaxPendingAmount = (): number => numConfig('PAYMENT_KIT_MAX_PENDING_AMOUNT', 5);
+
+// Whether a locked price may still be edited. Lazy (reads injected config via
+// the boundary at call time) like every other Phase 8 accessor.
+export const allowChangeLockedPrice = (): boolean => readConfig('PAYMENT_CHANGE_LOCKED_PRICE') === '1';
+
+// ──────────────────────────────────────────────────────────────────────────
+// Phase 8 (W2′): converged accessors. Every read below used to live inline in
+// api/src as a direct process.env / __CF_ENV__ access (the 57-entry whitelist).
+// They are LAZY (functions, not import-time consts) so the injected config —
+// wired by the factory AFTER module import — is honored at call time, and so
+// tests that flip process.env at runtime keep working.
+// ──────────────────────────────────────────────────────────────────────────
+
+// -- runtime mode / environment --
+export const blockletMode = (): string | undefined => readConfig('BLOCKLET_MODE');
+export const isProduction = (): boolean => blockletMode() === 'production';
+export const nodeEnv = (): string | undefined => readConfig('NODE_ENV');
+export const isTestEnv = (): boolean => nodeEnv() === 'test';
+export const isDevelopmentEnv = (): boolean => nodeEnv() === 'development';
+export const enableDevFakeAuth = (): boolean => readConfig('ENABLE_DEV_FAKE_AUTH') === '1';
+
+// -- tenant mode-source (getTenantMode / getDefaultInstanceDid read these) --
+export const tenantModeRaw = (): string | undefined => readConfig('PAYMENT_TENANT_MODE');
+export const blockletAppPid = (): string | undefined => readConfig('BLOCKLET_APP_PID');
+
+// -- app identity / urls --
+export const blockletAppId = (): string | undefined => readConfig('BLOCKLET_APP_ID');
+export const blockletAppName = (): string | undefined => readConfig('BLOCKLET_APP_NAME');
+export const blockletAppUrl = (): string | undefined => readConfig('BLOCKLET_APP_URL');
+export const blockletAppHost = (): string | undefined => readConfig('BLOCKLET_APP_HOST');
+export const blockletAppDir = (): string | undefined => readConfig('BLOCKLET_APP_DIR');
+export const blockletPort = (): string | undefined => readConfig('BLOCKLET_PORT');
+export const blockletMountPoints = (): string | undefined => readConfig('BLOCKLET_MOUNT_POINTS');
+
+// -- integrations --
+export const appStoreWriteEnabled = (): boolean => readConfig('APP_STORE_WRITE_ENABLED') === 'true';
+export const appStoreSkipSignatureVerify = (): boolean => readConfig('APP_STORE_SKIP_SIGNATURE_VERIFY') === 'true';
+export const googlePubsubSkipSignatureVerify = (): boolean =>
+  readConfig('GOOGLE_PUBSUB_SKIP_SIGNATURE_VERIFY') === 'true';
+export const googlePubsubPushServiceAccount = (): string | undefined =>
+  readConfig('GOOGLE_PUBSUB_PUSH_SERVICE_ACCOUNT');
+export const googlePubsubAllowUnverifiedSender = (): boolean =>
+  readConfig('GOOGLE_PUBSUB_ALLOW_UNVERIFIED_SENDER') === 'true';
+export const googlePlayWebhookUrl = (): string | undefined => readConfig('GOOGLE_PLAY_WEBHOOK_URL');
+export const stripeWebhookSecret = (): string | undefined => readConfig('STRIPE_WEBHOOK_SECRET');
+export const iapReconcileBatchSize = (): number => Number(readConfig('IAP_RECONCILE_BATCH_SIZE') ?? '100');
+
+// -- payment params --
+export const paymentBillingThreshold = (): number => +(readConfig('PAYMENT_BILLING_THRESHOLD') as string);
+export const paymentMinStakeAmount = (): number => +(readConfig('PAYMENT_MIN_STAKE_AMOUNT') as string);
+export const paymentDaysUntilDue = (): string | undefined => readConfig('PAYMENT_DAYS_UNTIL_DUE');
+export const paymentDaysUntilCancel = (): string | undefined => readConfig('PAYMENT_DAYS_UNTIL_CANCEL');
+export const paymentReloadSubscriptionJobs = (): boolean => readConfig('PAYMENT_RELOAD_SUBSCRIPTION_JOBS') === '1';
+export const paymentRateVolatilityThreshold = (): string | undefined => readConfig('PAYMENT_RATE_VOLATILITY_THRESHOLD');
+export const paymentLivemode = (): boolean => readConfig('PAYMENT_LIVEMODE') !== 'false';
+
+// -- credit queue --
+export const creditLowBalanceThresholdPercentage = (): number =>
+  parseInt(readConfig('CREDIT_LOW_BALANCE_THRESHOLD_PERCENTAGE') || '10', 10);
+export const creditBatchSize = (): number => Math.max(1, parseInt(readConfig('CREDIT_BATCH_SIZE') || '50', 10));
+export const creditBatchWindowMs = (): number =>
+  Math.max(10, parseInt(readConfig('CREDIT_BATCH_WINDOW_MS') || '3000', 10));
+export const creditQueueConcurrency = (): number =>
+  Math.max(1, Math.min(20, parseInt(readConfig('CREDIT_QUEUE_CONCURRENCY') || '5', 10) || 5));
+
+// -- exchange rate cache TTL source (the value itself is exchangeRateCacheTTLSeconds above) --
+export const exchangeRateCacheTTLFromEnv = (): boolean => hasConfig('EXCHANGE_RATE_CACHE_TTL_SECONDS');
+
+// -- store / sequelize logging --
+export const sqlLog = (): boolean => readConfig('SQL_LOG') === '1';
+export const sqlBenchmark = (): boolean => readConfig('SQL_BENCHMARK') === '1';
+
+// -- CF worker runtime detection + env mirror (set by cloudflare/worker.ts on
+//    globalThis; the boundary so core never reads the global directly) --
+export const cfEnv = (): any => (globalThis as any).__CF_ENV__;
+export const isCfWorker = (): boolean => !!cfEnv();
 
 export default {
   ...env,

package/api/src/libs/exchange-rate/service.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-await-in-loop */
 import BigNumber from 'bignumber.js';
+import { exchangeRateCacheTTLFromEnv, exchangeRateCacheTTLSeconds } from '../env';
 import { ExchangeRateProvider } from '../../store/models/exchange-rate-provider';
 import logger from '../logger';
 import { events } from '../event';
@@ -8,15 +9,15 @@ import { SymbolNotSupportedError } from './types';
 import { TokenDataProvider } from './token-data-provider';
 import { CoinGeckoProvider } from './coingecko-provider';
 import { CoinMarketCapProvider } from './coinmarketcap-provider';
-import { exchangeRateCacheTTLSeconds } from '../env';
 
 interface CacheEntry {
   data: ExchangeRateResult;
   timestamp: number;
 }
 
-// Cache TTL from environment variable, default 10 minutes
-const CACHE_TTL_MS = (exchangeRateCacheTTLSeconds || 10 * 60) * 1000;
+// Cache TTL from config, default 10 minutes. Lazy so injected config (set after
+// module import) is honored — not frozen in a module-level const.
+const cacheTtlMs = (): number => (exchangeRateCacheTTLSeconds() || 10 * 60) * 1000;
 const MAX_RATE_AGE_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_DEVIATION_PERCENT = 5; // 5%
 const HISTORY_WINDOW_SIZE = 10;
@@ -185,7 +186,7 @@ export class ExchangeRateService {
 
     // Check cache first
     const cached = this.cache.get(cacheKey);
-    if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+    if (cached && Date.now() - cached.timestamp < cacheTtlMs()) {
       logger.debug('Exchange rate cache hit', { symbol, age: Date.now() - cached.timestamp });
       return cached.data;
     }
@@ -575,8 +576,8 @@ export function getExchangeRateService(): ExchangeRateService {
   if (!serviceInstance) {
     serviceInstance = new ExchangeRateService();
     logger.info('Exchange rate service initialized', {
-      cache_ttl_seconds: CACHE_TTL_MS / 1000,
-      cache_ttl_source: process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS ? 'env' : 'default',
+      cache_ttl_seconds: cacheTtlMs() / 1000,
+      cache_ttl_source: exchangeRateCacheTTLFromEnv() ? 'env' : 'default',
     });
   }
   return serviceInstance;

package/api/src/libs/http-fetch-adapter.ts

@@ -0,0 +1,50 @@
+// D5 — the Web-Fetch entry for hosts that own their own app shell (arc-node's
+// registerPrefixHandler): `svc.http.fetch(req, {basePath})` with no express bridge.
+//
+// Phase 4 (express→hono): the loopback http.Server + express app are gone, so this
+// is just a base-strip wrapper over `honoApp.fetch`. The outward signature +
+// strip semantics are unchanged (arc consumes this contract); raw-body fidelity
+// (Stripe webhook signature) holds because the stripped path reuses the exact
+// request bytes/headers, and status/Set-Cookie/redirect come from the hono Response.
+
+import type { Hono } from 'hono';
+
+/** Options for svc.http.fetch — basePath is stripped to reach the internal /api/*. */
+export interface PaymentFetchOptions {
+  /** the host's mount prefix (e.g. "/.well-known/payment"); stripped, no alias special-case */
+  basePath?: string;
+}
+
+export interface FetchHandler {
+  (request: Request, opts?: PaymentFetchOptions): Promise<Response>;
+  /** teardown hook (host lifecycle). No-op now that there is no loopback server. */
+  close(): Promise<void>;
+}
+
+export function createFetchHandler(app: Hono): FetchHandler {
+  const handler = (async (request: Request, opts?: PaymentFetchOptions): Promise<Response> => {
+    const url = new URL(request.url);
+
+    // ① base-strip: remove basePath → internal /api/* path (no alias special-case).
+    //    Precise segment-boundary check (=== basePath || startsWith(basePath + '/'))
+    //    so "/foo" never matches "/foobar" — byte-identical to the old loopback strip.
+    const basePath = opts?.basePath ?? '';
+    if (basePath && (url.pathname === basePath || url.pathname.startsWith(`${basePath}/`))) {
+      url.pathname = url.pathname.slice(basePath.length) || '/';
+      // ② rebuild the request at the stripped URL. The body is read ONCE into a
+      //    fixed buffer (raw bytes preserved for Stripe webhook signature) and the
+      //    original headers/method are carried verbatim (Host preserved).
+      const method = request.method.toUpperCase();
+      const hasBody = method !== 'GET' && method !== 'HEAD';
+      const body = hasBody ? await request.arrayBuffer() : undefined;
+      return app.fetch(new Request(url.toString(), { method, headers: request.headers, body }));
+    }
+
+    // no strip needed — hand the request straight to hono (it owns body parsing).
+    return app.fetch(request);
+  }) as FetchHandler;
+
+  handler.close = (): Promise<void> => Promise.resolve();
+
+  return handler;
+}

package/api/src/libs/invoice.ts

@@ -1,4 +1,4 @@
-import { component } from '@blocklet/sdk';
+import component from '@blocklet/sdk/lib/component';
 import type { LiteralUnion } from 'type-fest';
 import { withQuery } from 'ufo';