payment-kit 1.29.1 → 1.29.3

package/api/src/libs/did-connect/runtime-did-connect-js.ts

@@ -0,0 +1,88 @@
+// S3-CF (DID convergence) — the REAL @arcblock/did-connect-js runtime, SHARED by
+// the non-blocklet-server hosts (CF + arc-node embedded).
+//
+// Both build the same authenticator/handlers; they differ ONLY in the host adapter
+// passed in here (tokenStorage, chain config, txEncoder, timeout). The signing
+// wallet + appInfo are FUNCTION-VALUED and resolved per-request, per-tenant through
+// the shared `resolveTenantIdentity` (AUTH_SERVICE.getInstanceAppIdentity) — never
+// a fixed isolate key — so one isolate serves every tenant with its own appSk.
+//
+// @arcblock/did-connect-js supports function-valued `wallet` (base.js: typeof
+// wallet === 'function' → resolved via getWalletInfo with a timeout before each
+// sign), so per-tenant signing is safe.
+
+import type { DidConnectRuntime, DidConnectTokenStorage } from '../auth';
+import { resolveTenantIdentity } from './tenant-identity';
+
+/** Chain config for the DID-Connect authenticator (id/type/host), or a resolver. */
+export type ChainInfoOption =
+  | { id: string; type: string; host: string }
+  | ((params: any) => { id: string; type: string; host: string } | Promise<{ id: string; type: string; host: string }>);
+
+export interface DidConnectJsRuntimeOptions {
+  /** Host-injected token store (CF: D1 tenant-aware adapter). Omit to let
+   *  buildTokenStorage fall back to the file-backed nedb default (arc-node). */
+  tokenStorage?: DidConnectTokenStorage;
+  /** Chain config for `signature`/`prepareTx` claims (omit on chain-less hosts). */
+  chainInfo?: ChainInfoOption;
+  /** On-chain tx encoder (CF: @ocap/client/encode CBOR encoder). Omit to disable tx claims. */
+  txEncoder?: (params: { type: string; data: any; wallet: any; chainHost: string }) => Promise<Buffer>;
+  /** Authenticator timeout (CF chain RPC can exceed the 8s default; worker used 30s). */
+  timeout?: number;
+  /** Branding fallback when an instance's getInstanceAppIdentity omits appInfo. */
+  defaultAppInfo?: { name?: string; description?: string; icon?: string };
+}
+
+const DEFAULT_APP_INFO = {
+  name: 'Payment Kit',
+  description: 'Payment Kit',
+  icon: 'https://www.arcblock.io/favicon.ico',
+};
+
+/**
+ * Build a DID-Connect runtime backed by the real @arcblock/did-connect-js stack.
+ * Used by `createCloudflareDidConnectRuntime` (CF) and the arc-node embedded host.
+ */
+export function createDidConnectJsRuntime(opts: DidConnectJsRuntimeOptions): DidConnectRuntime {
+  const fallbackAppInfo = { ...DEFAULT_APP_INFO, ...(opts.defaultAppInfo ?? {}) };
+
+  return {
+    tokenStorage: opts.tokenStorage,
+
+    createAuthenticator() {
+      // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+      const { WalletAuthenticator } = require('@arcblock/did-connect-js');
+
+      const config: Record<string, any> = {
+        // Function-valued, per-tenant: resolve the signing wallet from the host
+        // IdentityDriver.getInstanceAppIdentity each time the authenticator signs.
+        // `.toJSON()` matches the standalone worker (the SDK reconstructs the full
+        // wallet — incl. sk — via fromJSON before signing).
+        wallet: async () => {
+          const { wallet } = await resolveTenantIdentity();
+          return wallet.toJSON();
+        },
+        appInfo: async ({ baseUrl }: { baseUrl?: string } = {}) => {
+          const { appInfo } = await resolveTenantIdentity();
+          return {
+            name: appInfo.name || fallbackAppInfo.name,
+            description: appInfo.description || fallbackAppInfo.description,
+            icon: appInfo.icon || fallbackAppInfo.icon,
+            link: appInfo.link || baseUrl,
+          };
+        },
+        timeout: opts.timeout ?? 30000,
+      };
+      if (opts.chainInfo) config.chainInfo = opts.chainInfo;
+      if (opts.txEncoder) config.txEncoder = opts.txEncoder;
+
+      return new WalletAuthenticator(config);
+    },
+
+    createHandlers({ authenticator, tokenStorage }) {
+      // eslint-disable-next-line global-require, import/no-extraneous-dependencies
+      const { WalletHandlers } = require('@arcblock/did-connect-js');
+      return new WalletHandlers({ authenticator, tokenStorage });
+    },
+  };
+}

package/api/src/libs/did-connect/tenant-identity.ts

@@ -0,0 +1,221 @@
+// S3-CF (DID convergence) — the SHARED per-tenant DID-Connect identity resolver.
+//
+// Both non-blocklet-server runtimes (CF + arc-node embedded) build their REAL
+// `@arcblock/did-connect-js` WalletAuthenticator from a per-tenant signing wallet
+// resolved HERE — never from a fixed isolate-level APP_SK. The signing identity
+// comes from the host IdentityDriver's `getInstanceAppIdentity(instanceDid)`
+// (AUTH_SERVICE-backed), which already resolves the arc run-mode (instance app:sk
+// → instance identity; else auth-service root; else fail-closed), so payment-core
+// never reimplements "instance ?? root" and never reads connect-service internals.
+//
+// The wallet is derived from the returned `appSk` with @ocap/wallet (a stable
+// public API) — the same ROLE_APPLICATION/ED25519/SHA3 wallet type the standalone
+// CF worker used. The blocklet-server runtime does NOT use this resolver (it keeps
+// the @blocklet/sdk wallet wrapper); only the AUTH_SERVICE/did-connect-js runtimes do.
+//
+// eslint-disable-next-line import/no-extraneous-dependencies
+import * as Mcrypto from '@ocap/mcrypto';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { fromSecretKey, WalletType } from '@ocap/wallet';
+import type { WalletObject } from '@ocap/wallet';
+
+import { getInstanceDid } from '../context';
+import { getIdentityDriver, type InstanceAppInfo, type BlockletDirectory } from '../drivers';
+import logger from '../logger';
+
+const walletType = {
+  role: Mcrypto.types.RoleType.ROLE_APPLICATION,
+  pk: Mcrypto.types.KeyType.ED25519,
+  hash: Mcrypto.types.HashType.SHA3,
+};
+
+// The ethereum business wallet is derived from the SAME instance appSk as the
+// arcblock wallet, mirroring @blocklet/sdk getWallet('ethereum', appSk): the
+// secp256k1/keccak WalletType('ethereum') over the first 66 chars of the appSk.
+// Using @ocap/wallet directly (not the SDK) keeps this CF-worker-safe — the CF
+// build shims the SDK wallet-* modules, but @ocap/wallet is a stable public API.
+const ethWalletType = WalletType('ethereum');
+
+export interface ResolvedTenantIdentity {
+  instanceDid: string;
+  /** App signing wallet derived from the instance appSk (the DID-Connect signer). */
+  wallet: WalletObject;
+  /** Ethereum business wallet derived from the same appSk (EVM chains / refunds). */
+  ethWallet: WalletObject;
+  /** Permanent app signing wallet (when keys rotated); falls back to `wallet`. */
+  permanentWallet: WalletObject;
+  /** Branding for DID-Connect prompts (name/description/icon/link). */
+  appInfo: InstanceAppInfo;
+}
+
+// Per-instance TTL cache of the DERIVED identity (Layer 2 of
+// wallet-authenticator-dynamic.md). The business wallet proxies (libs/auth.ts)
+// read it SYNCHRONOUSLY via getCachedTenantIdentity, so resolveTenantIdentity
+// (async — it RPCs getInstanceAppIdentity) must run first per request/job (the
+// HTTP contextMiddleware and queue runJobWithTenant warm it). TTL bounds key-
+// rotation staleness; for a single-tenant deployment this holds exactly one entry.
+// A hard size cap (insertion-order eviction via Map iteration) keeps a host with
+// many tenants from growing the map unbounded — expired entries are pruned on
+// read but never proactively, so the cap is the only growth bound.
+const IDENTITY_TTL_MS = 5 * 60 * 1000;
+const IDENTITY_CACHE_MAX = 512;
+const identityCache = new Map<string, { value: ResolvedTenantIdentity; expiry: number }>();
+
+function cacheIdentity(instanceDid: string, value: ResolvedTenantIdentity): void {
+  identityCache.set(instanceDid, { value, expiry: Date.now() + IDENTITY_TTL_MS });
+  // evict the oldest entry (Map preserves insertion order) once over the cap
+  if (identityCache.size > IDENTITY_CACHE_MAX) {
+    const oldest = identityCache.keys().next().value;
+    if (oldest !== undefined) identityCache.delete(oldest);
+  }
+}
+
+/** Drop a tenant's cached identity (or all) — key rotation / test isolation. */
+export function clearTenantIdentityCache(instanceDid?: string): void {
+  if (instanceDid) identityCache.delete(instanceDid);
+  else identityCache.clear();
+}
+
+/**
+ * Whether the active host runtime resolves app identity dynamically per tenant
+ * (arc-node embedded + CF, via AUTH_SERVICE.getInstanceAppIdentity) vs the
+ * blocklet-server runtime, which keeps the @blocklet/sdk env wallet. The
+ * business wallet proxies branch on this so blocklet-server stays byte-for-byte
+ * unchanged (it never touches the resolver / cache).
+ */
+export function hasDynamicIdentity(): boolean {
+  return typeof getIdentityDriver().getInstanceAppIdentity === 'function';
+}
+
+/**
+ * Resolve the current (or given) tenant's DID-Connect signing identity. Throws a
+ * clear error — never silently falls back to a fixed key — when:
+ *   - the active IdentityDriver does not implement getInstanceAppIdentity (a
+ *     non-SDK runtime reached an SDK-only driver), or
+ *   - the instance has no app signing key (fail-closed; AUTH_SERVICE 4.0.3 itself
+ *     fails closed when neither instance app:sk nor root APP_SK exists).
+ */
+export async function resolveTenantIdentity(instanceDidArg?: string): Promise<ResolvedTenantIdentity> {
+  const instanceDid = instanceDidArg ?? getInstanceDid();
+
+  const cached = identityCache.get(instanceDid);
+  if (cached && cached.expiry > Date.now()) return cached.value;
+
+  const driver = getIdentityDriver();
+  if (typeof driver.getInstanceAppIdentity !== 'function') {
+    throw new Error(
+      'resolveTenantIdentity: the active IdentityDriver does not implement getInstanceAppIdentity — ' +
+        'a non-blocklet-server DID-Connect runtime requires an AUTH_SERVICE-backed identity driver'
+    );
+  }
+  const identity = await driver.getInstanceAppIdentity(instanceDid);
+  if (!identity || !identity.appSk) {
+    throw new Error(`resolveTenantIdentity: no app signing key for instance "${instanceDid}" (fail-closed)`);
+  }
+  // A too-short appSk would silently yield a WRONG ethereum address (slice below)
+  // and thus a wrong receiving/signing wallet — fail closed instead. A real
+  // ED25519 app sk is 128 hex chars; the eth slice needs at least 66.
+  if (identity.appSk.length < 66) {
+    throw new Error(
+      `resolveTenantIdentity: appSk for instance "${instanceDid}" is too short ` +
+        `(${identity.appSk.length} chars) to derive a wallet (fail-closed)`
+    );
+  }
+  const wallet = fromSecretKey(identity.appSk, walletType) as WalletObject;
+  // Mirror @blocklet/sdk getWallet('ethereum', appSk): secp256k1 over appSk[0..66].
+  const ethWallet = fromSecretKey(identity.appSk.slice(0, 66), ethWalletType) as WalletObject;
+  const permanentWallet = identity.appPsk ? (fromSecretKey(identity.appPsk, walletType) as WalletObject) : wallet;
+  const value: ResolvedTenantIdentity = {
+    instanceDid,
+    wallet,
+    ethWallet,
+    permanentWallet,
+    appInfo: identity.appInfo ?? {},
+  };
+  cacheIdentity(instanceDid, value);
+  return value;
+}
+
+/**
+ * SYNCHRONOUS accessor for the current (or given) tenant's resolved identity —
+ * the business wallet proxies (libs/auth.ts) call this on every `wallet.address`
+ * / `wallet.sign(...)`. It NEVER resolves (no RPC): it reads the cache that
+ * `warmTenantIdentity` populated earlier in the request/job. A miss means the
+ * identity was never warmed (fail-closed): throw rather than silently fall back
+ * to a wrong/default key.
+ */
+export function getCachedTenantIdentity(instanceDidArg?: string): ResolvedTenantIdentity {
+  const instanceDid = instanceDidArg ?? getInstanceDid();
+  const cached = identityCache.get(instanceDid);
+  if (!cached || cached.expiry <= Date.now()) {
+    throw new Error(
+      `tenant identity for "${instanceDid}" is not resolved (fail-closed) — ` +
+        'warmTenantIdentity must run in the request/job scope before any wallet access'
+    );
+  }
+  return cached.value;
+}
+
+/**
+ * Best-effort warm of the current tenant's identity into the cache so later
+ * SYNCHRONOUS wallet access resolves. No-op for the blocklet-server runtime
+ * (env wallet, no dynamic driver). Errors are swallowed (logged): a request that
+ * never touches a wallet must not be blocked by an identity hiccup, while one
+ * that DOES touch it still fails-closed at getCachedTenantIdentity.
+ */
+export async function warmTenantIdentity(instanceDidArg?: string): Promise<void> {
+  if (!hasDynamicIdentity()) return;
+  try {
+    await resolveTenantIdentity(instanceDidArg);
+  } catch (err: unknown) {
+    logger.warn('[tenant-identity] warm failed — wallet access will fail-closed', {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+// The host user directory for the embedded runtime. In the DID-Connect world the
+// user's DID IS the wallet DID, so getUser echoes it as a connected wallet account
+// (so getWalletDid(user) resolves to the user's own DID); the rest are no-ops. This
+// is the shared semantics the CF build-alias shim also implements
+// (cloudflare/shims/blocklet-sdk/auth-service.ts).
+const EMBEDDED_DIRECTORY: BlockletDirectory = {
+  getUser(did: string) {
+    if (!did) return { user: null };
+    return {
+      user: { did, fullName: did, email: '', phone: '', remark: '', connectedAccounts: [{ provider: 'wallet', did }] },
+    };
+  },
+  getUsers() {
+    return { users: [] };
+  },
+  getVault() {
+    return null;
+  },
+  getBlocklet() {
+    return { id: '', site: { id: '' } };
+  },
+};
+
+/**
+ * The embedded host identity services — the AUTH_SERVICE-backed implementations of
+ * the optional IdentityDriver methods, derived entirely from getInstanceAppIdentity
+ * (so a host need not reimplement them). arc-node spreads BOTH into its identity
+ * driver; CF spreads `getBusinessWallet` only (it keeps its build-alias directory
+ * shim). Stateless — every call reads the active driver via resolveTenantIdentity /
+ * getCachedTenantIdentity, so one instance serves every tenant.
+ */
+export function createEmbeddedIdentityServices(): {
+  getBusinessWallet(chain: 'arcblock' | 'ethereum'): WalletObject;
+  directory(): BlockletDirectory;
+} {
+  return {
+    getBusinessWallet(chain: 'arcblock' | 'ethereum'): WalletObject {
+      const identity = getCachedTenantIdentity();
+      return chain === 'ethereum' ? identity.ethWallet : identity.wallet;
+    },
+    directory(): BlockletDirectory {
+      return EMBEDDED_DIRECTORY;
+    },
+  };
+}

package/api/src/libs/drivers/auth-storage.ts

@@ -0,0 +1,118 @@
+// Phase 8 (W2-1a): DID Connect token storage on the db driver.
+//
+// In Blocklet Server the real @arcblock/did-connect-storage-nedb (file-backed)
+// is used unchanged. In the CF worker that package was aliased to a NO-OP stub
+// (cloudflare/shims/nedb-storage.ts) — DID Connect state was silently dropped.
+// This is the from-scratch persistent implementation on top of the db driver
+// contract, so the same code runs on the node (sqlite) and d1 backends and is
+// covered by the driver consistency suite.
+//
+// Records are flexible JSON documents keyed by `token` (the DID-Auth session
+// token, globally unique — no instance_did column needed; isolation is by the
+// unguessable token, matching the original file store's scope).
+
+import type { DbDriver } from './db';
+
+const { EventEmitter } = require('events');
+
+const TABLE = 'did_auth_records';
+
+export interface AuthRecord {
+  token: string;
+  [key: string]: any;
+}
+
+export class DbAuthStorage extends EventEmitter {
+  private driver: DbDriver;
+  private ready: Promise<void> | null = null;
+
+  constructor(driver: DbDriver) {
+    super();
+    if (!driver) throw new Error('DbAuthStorage requires a db driver');
+    this.driver = driver;
+  }
+
+  // idempotent lazy schema — the original file store self-managed its db file
+  // (it was never part of the Umzug/D1 migration chain), so we keep that here.
+  private ensureTable(): Promise<void> {
+    if (!this.ready) {
+      this.ready = this.driver
+        .exec(
+          `CREATE TABLE IF NOT EXISTS ${TABLE} (` +
+            'token TEXT PRIMARY KEY, ' +
+            'doc TEXT NOT NULL, ' +
+            'created_at INTEGER NOT NULL, ' +
+            'updated_at INTEGER NOT NULL)'
+        )
+        .then(() => undefined)
+        .catch((err) => {
+          // reset so a transient failure can be retried on next call
+          this.ready = null;
+          throw err;
+        });
+    }
+    return this.ready;
+  }
+
+  async read(token: string): Promise<AuthRecord | null> {
+    if (!token) throw new Error('token is required to read auth record');
+    await this.ensureTable();
+    const row = await this.driver.get<{ doc: string }>(`SELECT doc FROM ${TABLE} WHERE token = ?`, [token]);
+    if (!row) return null;
+    return JSON.parse(row.doc) as AuthRecord;
+  }
+
+  async create(token: string, status = 'created'): Promise<AuthRecord> {
+    if (!token) throw new Error('token is required to create auth record');
+    await this.ensureTable();
+    const now = Date.now();
+    const doc: AuthRecord = { token, status, createdAt: now, updatedAt: now };
+    await this.driver.exec(`INSERT INTO ${TABLE} (token, doc, created_at, updated_at) VALUES (?, ?, ?, ?)`, [
+      token,
+      JSON.stringify(doc),
+      now,
+      now,
+    ]);
+    this.emit('create', doc);
+    return doc;
+  }
+
+  async update(token: string, updates: Record<string, any> = {}): Promise<AuthRecord | null> {
+    if (!token) throw new Error('token is required to update auth record');
+    await this.ensureTable();
+    const current = await this.read(token);
+    if (!current) return null;
+    const now = Date.now();
+    const merged: AuthRecord = { ...current, ...updates, token, updatedAt: now };
+    await this.driver.exec(`UPDATE ${TABLE} SET doc = ?, updated_at = ? WHERE token = ?`, [
+      JSON.stringify(merged),
+      now,
+      token,
+    ]);
+    this.emit('update', merged);
+    return merged;
+  }
+
+  async delete(token: string): Promise<number> {
+    if (!token) throw new Error('token is required to delete auth record');
+    await this.ensureTable();
+    const res = await this.driver.exec(`DELETE FROM ${TABLE} WHERE token = ?`, [token]);
+    this.emit('destroy', token);
+    return res.changes;
+  }
+
+  async exist(token: string, did: any): Promise<boolean> {
+    if (!token) throw new Error('token is required to check auth record');
+    const doc = await this.read(token);
+    return !!doc && doc.did === did;
+  }
+
+  async clear(): Promise<void> {
+    await this.ensureTable();
+    await this.driver.exec(`DELETE FROM ${TABLE}`);
+  }
+}
+
+export function createAuthStorage(driver: DbDriver): DbAuthStorage {
+  return new DbAuthStorage(driver);
+}