payment-kit 1.29.1 → 1.29.3

package/api/src/libs/subscription.ts

@@ -8,6 +8,7 @@ import type { LiteralUnion } from 'type-fest';
 import { withQuery } from 'ufo';
 
 import { Op } from 'sequelize';
+import env, { paymentDaysUntilDue, paymentDaysUntilCancel } from './env';
 import {
   ChainType,
   Customer,
@@ -27,9 +28,8 @@ import {
   TLineItemExpanded,
   UsageRecord,
 } from '../store/models';
-import { createEvent } from './audit';
+import { createEvent, reportAuditFailure } from './audit';
 import dayjs from './dayjs';
-import env from './env';
 import logger from './logger';
 import { getExchangeRateService } from './exchange-rate';
 import { getExchangeRateSymbol } from './exchange-rate/token-address-mapping';
@@ -107,11 +107,11 @@ export function parseIntegerConfig(alternatives: any[], defaultValue: number) {
 }
 
 export function getDaysUntilDue(query: Record<string, any> = {}) {
-  return parseIntegerConfig([query.days_until_due, process.env.PAYMENT_DAYS_UNTIL_DUE], 6);
+  return parseIntegerConfig([query.days_until_due, paymentDaysUntilDue()], 6);
 }
 
 export function getDaysUntilCancel(query: Record<string, any> = {}) {
-  return parseIntegerConfig([query.days_until_cancel, process.env.PAYMENT_DAYS_UNTIL_CANCEL], 0);
+  return parseIntegerConfig([query.days_until_cancel, paymentDaysUntilCancel()], 0);
 }
 
 export const getDueUnit = (interval: string) => {
@@ -821,7 +821,7 @@ export async function finalizeStripeSubscriptionUpdate({
     await Lock.acquire(`${subscription.id}-change-plan`, releaseAt);
     logger.info('subscription plan change lock acquired on finalize', { subscription: subscription.id, releaseAt });
 
-    createEvent('Subscription', 'customer.subscription.upgraded', subscription).catch(console.error);
+    createEvent('Subscription', 'customer.subscription.upgraded', subscription).catch(reportAuditFailure);
   }
 
   logger.info('subscription update finalized', { subscription: subscription.id, updates, items });

package/api/src/libs/tenant.ts

@@ -0,0 +1,92 @@
+import { tenantModeRaw, blockletAppPid } from './env';
+
+export type TenantMode = 'single' | 'multi';
+
+export const TENANT_CONTEXT_MISSING = 'TENANT_CONTEXT_MISSING';
+export const TENANT_MISMATCH = 'TENANT_MISMATCH';
+// programmer error: a scoped helper was pointed at a non-tenant model —
+// distinct from TENANT_MISMATCH so monitoring can tell data races from bugs
+export const INVALID_TENANT_TABLE = 'INVALID_TENANT_TABLE';
+// multi-tenant fail-closed: a request Host did not resolve to any tenant
+// (Phase 10) — the request is refused 4xx with no default-tenant fallback
+export const TENANT_HOST_UNRESOLVED = 'TENANT_HOST_UNRESOLVED';
+
+export type TenantErrorCode =
+  | typeof TENANT_CONTEXT_MISSING
+  | typeof TENANT_MISMATCH
+  | typeof INVALID_TENANT_TABLE
+  | typeof TENANT_HOST_UNRESOLVED;
+
+export class TenantError extends Error {
+  code: TenantErrorCode;
+
+  constructor(code: TenantErrorCode, message: string) {
+    super(message);
+    this.name = 'TenantError';
+    this.code = code;
+  }
+}
+
+/**
+ * Tenant mode of this deployment:
+ * - `single` (default, blocklet server legacy): tenant context falls back to the deployment's own app DID
+ * - `multi`: no fallback — missing tenant context is a fail-closed error
+ *
+ * Source of the mode is the existing env mechanism for now; Phase 12 converges it into the config slot.
+ */
+export function getTenantMode(): TenantMode {
+  // Phase 8: mode-source reads the injected config (libs/env boundary), falling
+  // back to process.env. Not request-tamperable — config is set once at factory
+  // init, never from request input.
+  return tenantModeRaw() === 'multi' ? 'multi' : 'single';
+}
+
+/**
+ * Single source of truth for "this deployment's app DID" (single-tenant default tenant).
+ * Phase 2 backfill values and Phase 10 `tenancy.instanceDid` must reuse this getter.
+ */
+// Phase 10: the single-mode tenancy slot value, when the host supplies one via
+// createEmbeddedPaymentService({ tenancy: { mode:'single', instanceDid } }).
+// Preferred over the env snapshot so a host can declare its single-tenant
+// identity explicitly (and so the slot is not silently ignored).
+let overrideDefaultInstanceDid: string | undefined;
+
+/** Wire the single-mode tenancy slot value (factory only). Pass undefined to clear. */
+export function setDefaultInstanceDid(did: string | undefined): void {
+  if (did !== undefined) assertValidInstanceDid(did);
+  overrideDefaultInstanceDid = did;
+}
+
+export function getDefaultInstanceDid(): string {
+  // explicit tenancy slot value wins; otherwise the app DID from the injected
+  // config (libs/env boundary), which itself falls back to process.env's
+  // BLOCKLET_APP_PID (the value @blocklet/sdk's env.appPid wrapped before Phase 8).
+  const did = overrideDefaultInstanceDid || blockletAppPid() || '';
+  if (!did) {
+    throw new TenantError(TENANT_CONTEXT_MISSING, 'app DID is not configured for this deployment');
+  }
+  return did;
+}
+
+// Deliberately loose: deployments use both bare addresses (z8iZ...) and
+// did:abt: URIs, so we only reject values that cannot be a DID at all
+// (non-strings, empty/whitespace, embedded whitespace). Strict format
+// enforcement belongs to the identity slot (Phase 10), which resolves
+// Host -> instanceDid from a trusted source.
+/**
+ * Tenant of a loaded row, fail-closed: rows written since Phase 2 always
+ * carry instance_did; a NULL means pre-backfill data, which is only legal in
+ * single mode (where it can only belong to the default tenant).
+ */
+export function resolveRowTenant(row: { instance_did?: string | null } | null | undefined): string {
+  const fromRow = row?.instance_did;
+  if (fromRow) return fromRow;
+  if (getTenantMode() === 'single') return getDefaultInstanceDid();
+  throw new TenantError(TENANT_CONTEXT_MISSING, 'row has no tenant and deployment is in multi mode');
+}
+
+export function assertValidInstanceDid(instanceDid: unknown): asserts instanceDid is string {
+  if (typeof instanceDid !== 'string' || !/^\S{3,}$/.test(instanceDid)) {
+    throw new TenantError(TENANT_CONTEXT_MISSING, `invalid instanceDid: ${JSON.stringify(instanceDid)}`);
+  }
+}

package/api/src/libs/url.ts

@@ -30,7 +30,7 @@ export async function formatToShortUrl({
   validUntil?: string;
   maxVisits?: number;
 }): Promise<string> {
-  const apiKey = shortUrlApiKey;
+  const apiKey = shortUrlApiKey();
 
   if (!apiKey) {
     return url;
@@ -43,14 +43,14 @@ export async function formatToShortUrl({
       maxVisits,
       tags: [],
       shortCodeLength: 8,
-      domain: shortUrlDomain,
+      domain: shortUrlDomain(),
       findIfExists: true,
       validateUrl: true,
       forwardQuery: true,
       crawlable: true,
     };
 
-    const response = await fetch(`https://${shortUrlDomain}/rest/v3/short-urls`, {
+    const response = await fetch(`https://${shortUrlDomain()}/rest/v3/short-urls`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',

package/api/src/libs/util.ts

@@ -10,10 +10,10 @@ import type { LiteralUnion } from 'type-fest';
 import { joinURL, withQuery, withTrailingSlash } from 'ufo';
 
 import axios from 'axios';
-import { ethers } from 'ethers';
 import { fromUnitToToken } from '@ocap/util';
 import get from 'lodash/get';
 import trimEnd from 'lodash/trimEnd';
+import { googlePlayWebhookUrl, blockletAppUrl, blockletMountPoints, blockletAppId, blockletAppName } from './env';
 import dayjs from './dayjs';
 import { blocklet, wallet } from './auth';
 import type { PaymentCurrency, PaymentMethod, Subscription } from '../store/models';
@@ -37,7 +37,7 @@ export const STRIPE_ENDPOINT: string = getUrl('/api/integrations/stripe/webhook'
 // Lazy-eval (function not constant) because dotenv loads env AFTER this module
 // is imported — a constant captured at module-load would only see BLOCKLET_APP_URL.
 export const googlePlayEndpoint = (): string =>
-  process.env.GOOGLE_PLAY_WEBHOOK_URL || getUrl('/api/integrations/google-play/webhook');
+  googlePlayWebhookUrl() || getUrl('/api/integrations/google-play/webhook');
 
 // Back-compat constant for any caller that captures it at module-load.
 // Prefer googlePlayEndpoint() going forward.
@@ -262,7 +262,7 @@ const cachedBlockletJsonResult = new Map<string, { data: any; expiry: number }>(
 const CACHE_TTL = 60 * 60 * 1000; // 1 hour
 
 export async function getBlockletJson(url?: string) {
-  const blockletKey = url || process.env.BLOCKLET_APP_URL || 'default';
+  const blockletKey = url || blockletAppUrl() || 'default';
   const now = Date.now();
 
   if (cachedBlockletJsonResult.has(blockletKey)) {
@@ -271,7 +271,7 @@ export async function getBlockletJson(url?: string) {
       return cached.data;
     }
   }
-  const baseUrl = url || process.env.BLOCKLET_APP_URL;
+  const baseUrl = url || blockletAppUrl();
   if (!baseUrl) {
     return null;
   }
@@ -282,14 +282,14 @@ export async function getBlockletJson(url?: string) {
     return blockletMeta;
   } catch (err) {
     logger.error(`getBlockletJson error for ${scriptUrl}`, err);
-    if (process.env.BLOCKLET_MOUNT_POINTS) {
-      const BLOCKLET_MOUNT_POINTS = safeJsonParse(process.env.BLOCKLET_MOUNT_POINTS, []);
+    if (blockletMountPoints()) {
+      const BLOCKLET_MOUNT_POINTS = safeJsonParse(blockletMountPoints(), []);
       return {
         componentMountPoints: BLOCKLET_MOUNT_POINTS,
-        appId: process.env.BLOCKLET_APP_ID,
-        appName: process.env.BLOCKLET_APP_NAME,
+        appId: blockletAppId(),
+        appName: blockletAppName(),
         appLogo: '/.well-known/service/blocklet/logo',
-        appUrl: process.env.BLOCKLET_APP_URL,
+        appUrl: blockletAppUrl(),
       };
     }
     return null;
@@ -313,9 +313,9 @@ export async function getUserOrAppInfo(
     if (appInfo) {
       return {
         name: appInfo.name,
-        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}`),
         type: 'dapp',
-        url: joinURL(process.env.BLOCKLET_APP_URL!, appInfo.mountPoint),
+        url: joinURL(blockletAppUrl()!, appInfo.mountPoint),
       };
     }
   }
@@ -324,7 +324,7 @@ export async function getUserOrAppInfo(
     const locale = get(user, 'locale', 'en');
     return {
       name: user?.fullName,
-      avatar: joinURL(process.env.BLOCKLET_APP_URL!, user?.avatar),
+      avatar: joinURL(blockletAppUrl()!, user?.avatar),
       type: 'user',
       url: getCustomerProfileUrl({ userDid: address, locale }),
     };
@@ -608,7 +608,15 @@ export async function isUserInBlocklist(did: string, paymentMethod: PaymentMetho
 }
 
 export function resolveAddressChainTypes(address: string): LiteralUnion<'ethereum' | 'base' | 'arcblock', string>[] {
-  if (ethers.isAddress(address)) {
+  // Phase 13b2: lazy ethers. An eager top-level `import 'ethers'` loaded ethers
+  // during createEmbeddedPaymentService assembly (libs/util is pulled in at factory
+  // time), so a host that force-resolves an incompatible @noble/hashes (e.g. arc's
+  // `@noble/hashes:^2.2.0` override vs ethers@6.16's declared 1.3.2) crashed ethers
+  // at require. Deferring to call time keeps the factory + rpc.entitlements.check
+  // ethers-free; this fn runs only on EVM address resolution.
+  // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+  const { isAddress } = require('ethers');
+  if (isAddress(address)) {
     return ['ethereum', 'base', 'arcblock'];
   }
   return ['arcblock'];

package/api/src/middlewares/hono/cdn.ts

@@ -0,0 +1,63 @@
+// Phase 1 (express→hono) — hono fork of @blocklet/sdk/lib/middlewares/cdn.js.
+//
+// The express version monkeypatches res.send to rewrite asset URLs to the CDN
+// host on outgoing HTML. hono responses are built differently, so this fork
+// rewrites in the RESPONSE phase: run the handler, then if the response is HTML
+// (production GET/HEAD, non-resource, html-accepting), read it once and rebuild
+// the Response with rewritten URLs. The transform core (AssetHostTransformer) is
+// REUSED VERBATIM from the SDK — byte-identical rewriting. Inert for JSON /api
+// routes (content-type is not text/html), which is the only surface in Phases
+// 1-3; it becomes load-bearing when SPA HTML serving moves off the bridge.
+import type { MiddlewareHandler } from 'hono';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { AssetHostTransformer } from '@blocklet/sdk/lib/util/asset-host-transformer';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { env } from '@blocklet/sdk/lib/config';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { BLOCKLET_PROXY_PATH_PREFIX } from '@abtnode/constant';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { RESOURCE_PATTERN } from '@blocklet/constant';
+import { nodeEnv, readConfig } from '../../libs/env';
+
+function isProductionRuntime(): boolean {
+  return nodeEnv() === 'production' || readConfig('ABT_NODE_SERVICE_ENV') === 'production';
+}
+
+// Parity with express req.accepts(['html', ...]) for the html family.
+function acceptsHtml(accept: string): boolean {
+  if (!accept) return true; // express treats a missing Accept as accept-all
+  return accept.includes('text/html') || accept.includes('application/xhtml+xml') || accept.includes('*/*');
+}
+
+function shouldProcess(method: string, path: string, accept: string): boolean {
+  if (!isProductionRuntime()) return false;
+  if (method !== 'GET' && method !== 'HEAD') return false;
+  if (path.includes('/.well-known/service/')) return false;
+  if (RESOURCE_PATTERN.test(path)) return false;
+  return acceptsHtml(accept);
+}
+
+export function cdn(): MiddlewareHandler {
+  // Lazy + skip-if-absent: a bare/embedded host without componentDid never
+  // rewrites (the SDK throws "did is required" eagerly; the fork stays inert).
+  let transformer: AssetHostTransformer | undefined;
+  return async (c, next) => {
+    await next();
+    const assetHost = (env as any).assetCdnHost;
+    const did = (env as any).componentDid;
+    if (!assetHost || !did) return;
+    if (!shouldProcess(c.req.method.toUpperCase(), c.req.path, c.req.header('accept') || '')) return;
+
+    const contentType = c.res.headers.get('content-type') || '';
+    if (!contentType.includes('text/html')) return;
+
+    transformer ??= new AssetHostTransformer(`${BLOCKLET_PROXY_PATH_PREFIX}/${did}/`);
+    const html = await c.res.text();
+    const transformed = transformer.transform(html, assetHost);
+    const rebuilt = new Response(transformed, c.res);
+    rebuilt.headers.delete('content-length'); // body length changed; let the server derive it
+    c.res = rebuilt;
+  };
+}
+
+export default cdn;

package/api/src/middlewares/hono/context.ts

@@ -0,0 +1,80 @@
+// Phase 1 (express→hono) — hono fork of api/src/libs/middleware.ts
+// (ensureI18n + contextMiddleware). Behavior is identical to the express
+// version; only the req/res plumbing changes:
+//   - req.query.locale / req.t=      → c.req.query('locale') / c.set('t', ...)
+//   - req.get('x-component-sig')      → c.req.header('x-component-sig')
+//   - req.body (component sig verify) → c.get('sanitizedBody') (xss is the single
+//                                       body read-point, already ran upstream)
+//   - req.headers.host (tenant)       → c.req.header('host') (raw Host only, never
+//                                       a proxy header — single tenant resolution)
+//   - res.status(400).json(...)       → c.json(..., 400) (fail-closed on unknown
+//                                       host in multi mode)
+//   - context.run(..., next)          → context.run(..., () => next()) (same ALS)
+import type { MiddlewareHandler } from 'hono';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { verify } from '@blocklet/sdk/lib/util/verify-sign';
+import { translate } from '../../locales';
+import { context } from '../../libs/context';
+import { TenantError, TENANT_HOST_UNRESOLVED } from '../../libs/tenant';
+import { resolveTenantForHost } from '../../libs/drivers/identity';
+import { warmTenantIdentity } from '../../libs/did-connect/tenant-identity';
+
+export function ensureI18n(): MiddlewareHandler {
+  return (c, next) => {
+    c.set('locale', String(c.req.query('locale') || 'en'));
+    c.set('t', translate);
+    return next();
+  };
+}
+
+export function contextMiddleware(): MiddlewareHandler {
+  return async (c, next) => {
+    const requestId = c.req.header('x-request-id') || `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    let requestedBy = 'system';
+
+    // component signature — verify against the SANITIZED body (xss ran first)
+    const sig = c.req.header('x-component-sig');
+    const componentDid = c.req.header('x-component-did');
+    if (sig && componentDid) {
+      const data = c.get('sanitizedBody') ?? {};
+      const verified = await verify(data, sig);
+      if (verified) {
+        requestedBy = componentDid;
+      }
+    }
+
+    // user DID from headers
+    const userDid = c.req.header('x-user-did');
+    if (userDid) {
+      requestedBy = userDid;
+    }
+
+    // authenticated user (security middleware set this upstream)
+    const user = c.get('user');
+    if (user?.did) {
+      requestedBy = user.did;
+    }
+
+    // Resolve tenant from the raw Host (single point). Multi-mode unknown host →
+    // 4xx fail-closed, no default-tenant fallback.
+    let instanceDid: string;
+    try {
+      instanceDid = await resolveTenantForHost(c.req.header('host'));
+    } catch (err) {
+      if (err instanceof TenantError && err.code === TENANT_HOST_UNRESOLVED) {
+        return c.json({ error: { code: err.code, message: err.message } }, 400);
+      }
+      throw err;
+    }
+
+    return context.run({ requestId, requestedBy, instanceDid }, async () => {
+      // Warm the tenant's signing identity (arc/CF dynamic runtime only — no-op on
+      // blocklet-server) so the synchronous business wallet proxies (libs/auth.ts:
+      // `wallet`/`ethWallet`) resolve to THIS tenant's wallet inside the handler.
+      // Best-effort: a request that never touches a wallet is not blocked; one that
+      // does fails-closed at getCachedTenantIdentity.
+      await warmTenantIdentity(instanceDid);
+      await next();
+    });
+  };
+}

package/api/src/middlewares/hono/csrf.ts

@@ -0,0 +1,83 @@
+// Phase 1 (express→hono) — hono fork of @blocklet/sdk/lib/middlewares/csrf.js.
+//
+// The crypto core (sign / verify / getCsrfSecret) is framework-agnostic and is
+// REUSED VERBATIM from the SDK — tokens are byte-identical and interchangeable
+// across the express and hono engines (proven in spikes/csrf-parity.mjs, §3.2).
+// Only the express plumbing (req.cookies / res.cookie / res.status().send) is
+// replaced with hono/cookie helpers + c.text(403). The shouldGenerateToken
+// (GET) / shouldVerifyToken (mutating + cookie present + non-/mcp + non-didwallet)
+// semantics are preserved faithfully.
+import type { MiddlewareHandler } from 'hono';
+import { getCookie, setCookie } from 'hono/cookie';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { sign, verify, getCsrfSecret } from '@blocklet/sdk/lib/util/csrf';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { isDidWalletConnect } from '@blocklet/sdk/lib/util/wallet';
+import { readConfig } from '../../libs/env';
+
+const isEmpty = (v: unknown): boolean => v === undefined || v === null || v === '';
+
+// The CSRF secret is HOST-GLOBAL, not per-tenant: this middleware runs BEFORE the
+// tenant context is established (pipeline order cors→xss→csrf→…→context), so it
+// has no instanceDid, and it binds the host-global login_token anyway. An embedded
+// host (arc) that has no BLOCKLET_APP_SK env injects a dedicated secret via the
+// config slot (`PAYMENT_CSRF_SECRET`); the standard blocklet server falls back to
+// the SDK's env-based secret. See docs/architecture/payment-credential-sourcing.md.
+function csrfSecret(): string {
+  return readConfig('PAYMENT_CSRF_SECRET') || getCsrfSecret();
+}
+
+// Express SDK: shouldGenerateToken === GET; shouldVerifyToken === mutating
+// method AND an x-csrf-token cookie already exists AND path is not /mcp AND the
+// caller is not a DID Wallet connect request.
+const MUTATING = ['POST', 'PUT', 'PATCH', 'DELETE'];
+
+/**
+ * hono csrf middleware. Faithful to the SDK express version:
+ *  - GET: if a login_token cookie exists, (re)issue x-csrf-token = sign(secret,
+ *    login_token) when it differs from the current cookie. {sameSite:'Strict',
+ *    secure:true} matches the express res.cookie attributes.
+ *  - mutating: only ENFORCED when a login_token AND an x-csrf-token cookie are
+ *    both present and the path is not /mcp and the caller is not a DID Wallet
+ *    (parity with the SDK — absent cookie => skip, never reject). The header
+ *    must equal the cookie and verify() against the login_token, else 403.
+ */
+export function csrf(): MiddlewareHandler {
+  // async (no await): the SDK crypto core is synchronous, but the handler mixes a
+  // sync Response (c.text 403) with next()'s promise — async unifies the return
+  // type to the MiddlewareHandler contract.
+  // eslint-disable-next-line require-await
+  return async (c, next) => {
+    const method = c.req.method.toUpperCase();
+    const loginToken = getCookie(c, 'login_token');
+    const existingCsrf = getCookie(c, 'x-csrf-token');
+
+    if (method === 'GET') {
+      if (loginToken) {
+        const newCsrf = sign(csrfSecret(), loginToken);
+        if (newCsrf !== existingCsrf) {
+          setCookie(c, 'x-csrf-token', newCsrf, { sameSite: 'Strict', secure: true });
+        }
+      }
+      return next();
+    }
+
+    if (MUTATING.includes(method)) {
+      // shouldVerifyToken parity: skip (do NOT reject) when the SDK would skip.
+      if (c.req.path.includes('/mcp')) return next();
+      if (isEmpty(loginToken)) return next();
+      if (isEmpty(existingCsrf)) return next();
+      if (isDidWalletConnect(c.req.header())) return next();
+
+      const headerCsrf = c.req.header('x-csrf-token');
+      if (existingCsrf === headerCsrf && verify(csrfSecret(), existingCsrf as string, loginToken as string)) {
+        return next();
+      }
+      return c.text('Invalid request: csrf token mismatch, please refresh the page try again', 403);
+    }
+
+    return next();
+  };
+}
+
+export default csrf;