payment-kit 1.29.1 → 1.29.3

package/api/tests/libs/core-config.spec.ts

@@ -0,0 +1,115 @@
+// Phase 8 (W2′): the injected-config slot is authoritative. libs/env.ts is the
+// single boundary; the factory wires setCoreConfig(config) and core reads prefer
+// the injected config over process.env (the worker mirror / blocklet server
+// native fallback). getTenantMode's mode-source reads the injected config too.
+
+import { setCoreConfig, readConfig, hasConfig } from '../../src/libs/env';
+import { getTenantMode, getDefaultInstanceDid, setDefaultInstanceDid } from '../../src/libs/tenant';
+import { createDefaultSecretsDriver } from '../../src/libs/drivers';
+import { createEmbeddedPaymentService, MissingConfigError } from '../../src/service';
+
+const ORIG_MODE = process.env.PAYMENT_TENANT_MODE;
+const ORIG_PID = process.env.BLOCKLET_APP_PID;
+
+afterEach(() => {
+  setCoreConfig(undefined); // clear the injected config singleton between tests
+  setDefaultInstanceDid(undefined); // clear any tenancy-slot override
+  if (ORIG_MODE === undefined) delete process.env.PAYMENT_TENANT_MODE;
+  else process.env.PAYMENT_TENANT_MODE = ORIG_MODE;
+  if (ORIG_PID === undefined) delete process.env.BLOCKLET_APP_PID;
+  else process.env.BLOCKLET_APP_PID = ORIG_PID;
+});
+
+describe('Phase 8 — injected config is authoritative (happy path)', () => {
+  it('readConfig prefers injected config over process.env', () => {
+    process.env.PHASE8_FOO = 'from-env';
+    setCoreConfig({ PHASE8_FOO: 'from-config' });
+    expect(readConfig('PHASE8_FOO')).toBe('from-config');
+    delete process.env.PHASE8_FOO;
+  });
+
+  it('readConfig falls back to process.env when the key is absent from injected config', () => {
+    process.env.PHASE8_BAR = 'env-only';
+    setCoreConfig({ OTHER: 'x' });
+    expect(readConfig('PHASE8_BAR')).toBe('env-only');
+    delete process.env.PHASE8_BAR;
+  });
+
+  it('hasConfig is true for injected and env keys, false for absent', () => {
+    setCoreConfig({ PHASE8_PRESENT: 'v' });
+    expect(hasConfig('PHASE8_PRESENT')).toBe(true);
+    expect(hasConfig('PHASE8_DEFINITELY_ABSENT_KEY')).toBe(false);
+  });
+});
+
+describe('Phase 8 — getTenantMode mode-source from injected config (data isolation)', () => {
+  it('reads tenant mode from the injected config', () => {
+    delete process.env.PAYMENT_TENANT_MODE; // no env fallback — prove config is the source
+    setCoreConfig({ PAYMENT_TENANT_MODE: 'multi' });
+    expect(getTenantMode()).toBe('multi');
+    setCoreConfig({ PAYMENT_TENANT_MODE: 'single' });
+    expect(getTenantMode()).toBe('single');
+  });
+
+  it('injected config wins over a conflicting process.env (single source of truth)', () => {
+    process.env.PAYMENT_TENANT_MODE = 'single';
+    setCoreConfig({ PAYMENT_TENANT_MODE: 'multi' });
+    expect(getTenantMode()).toBe('multi'); // config wins, not the env mirror
+  });
+
+  it('SECURITY: getTenantMode takes no request input — only config/env decide the mode', () => {
+    setCoreConfig({ PAYMENT_TENANT_MODE: 'single' });
+    // getTenantMode() has no parameters; there is no request-level surface to tamper.
+    expect(getTenantMode.length).toBe(0);
+    expect(getTenantMode()).toBe('single');
+  });
+
+  it('getDefaultInstanceDid reads the app DID from injected config', () => {
+    delete process.env.BLOCKLET_APP_PID;
+    process.env.PAYMENT_TENANT_MODE = 'single';
+    setCoreConfig({ BLOCKLET_APP_PID: 'did:abt:zCONFIGAPP' });
+    expect(getDefaultInstanceDid()).toBe('did:abt:zCONFIGAPP');
+  });
+});
+
+describe('Phase 8 — fail-fast on a missing required config field (bad input)', () => {
+  it('single-mode factory with no BLOCKLET_APP_PID (config + env both absent) throws MissingConfigError', () => {
+    delete process.env.BLOCKLET_APP_PID;
+    expect(() =>
+      createEmbeddedPaymentService({
+        config: {}, // no BLOCKLET_APP_PID
+        db: { sequelize: {} as any },
+        // no tenancy slot -> defaults to single mode
+      })
+    ).toThrow(MissingConfigError);
+  });
+
+  it('the thrown error names the missing field (not a silent default)', () => {
+    delete process.env.BLOCKLET_APP_PID;
+    try {
+      createEmbeddedPaymentService({ config: {}, db: { sequelize: {} as any } });
+      throw new Error('expected MissingConfigError');
+    } catch (err: any) {
+      expect(err).toBeInstanceOf(MissingConfigError);
+      expect(err.code).toBe('MISSING_CONFIG_FIELD');
+      expect(err.field).toBe('BLOCKLET_APP_PID');
+    }
+  });
+
+  it('multi mode does NOT require BLOCKLET_APP_PID (tenant resolved per request)', () => {
+    delete process.env.BLOCKLET_APP_PID;
+    // multi mode passes the config fail-fast; it fails later on the db slot only
+    // if absent — here we give a truthy sequelize so the config check is what we
+    // assert. D1: multi also requires identity + secrets slots (else it would
+    // silently degrade to single), so provide minimal stubs.
+    expect(() =>
+      createEmbeddedPaymentService({
+        config: { PAYMENT_TENANT_MODE: 'multi' },
+        db: { sequelize: {} as any },
+        tenancy: { mode: 'multi' },
+        identity: { resolveInstanceDidForHost: () => null } as any,
+        secrets: createDefaultSecretsDriver(),
+      })
+    ).not.toThrow(MissingConfigError);
+  });
+});

package/api/tests/libs/cron-driver-d2.spec.ts

@@ -0,0 +1,237 @@
+// D2 (S3.0) — the node-cron driver self-schedules via @abtnode/cron and exposes
+// a teardown surface (stop/dispose). cf-cron stays a passive matcher registry.
+//
+// "Self-schedule" is proven two ways: a runOnInit job runs once at register
+// (the @abtnode/cron live path), and a 1-second cron fires on its own with NO
+// external runDue() tick. Teardown is proven by: after stop() a scheduled job no
+// longer fires, and a stop()/start() cycle re-registers without double-firing.
+
+import fs from 'fs';
+import path from 'path';
+import { createCronRegistry } from '../../src/libs/drivers/cron';
+import { setCoreConfig } from '../../src/libs/env';
+
+const flush = () => new Promise((r) => setTimeout(r, 20));
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// real-timer 1s cron tests give the suite a little headroom
+jest.setTimeout(15000);
+
+describe('D2 — node-cron driver self-schedules (no external tick)', () => {
+  it('a runOnInit job runs once at register via the live @abtnode/cron path', async () => {
+    const driver = createCronRegistry('node-cron');
+    let ran = 0;
+    driver.register([
+      {
+        name: 'd2.init',
+        time: '0 0 0 1 1 *',
+        fn: () => {
+          ran += 1;
+        },
+        options: { runOnInit: true },
+      },
+    ]);
+    await flush();
+    expect(ran).toBe(1);
+    driver.stop();
+  });
+
+  it('a 1-second cron fires by itself with no runDue() call', async () => {
+    const driver = createCronRegistry('node-cron');
+    let ticks = 0;
+    driver.register([
+      {
+        name: 'd2.every-sec',
+        time: '*/1 * * * * *',
+        fn: () => {
+          ticks += 1;
+        },
+        options: { runOnInit: false },
+      },
+    ]);
+    await wait(2200); // ~2 self-scheduled ticks, zero external runDue
+    driver.stop();
+    expect(ticks).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe('D2 — multi mode skips runOnInit (matches CF; avoids tenant-less startup push)', () => {
+  afterEach(() => setCoreConfig(undefined));
+
+  it('a runOnInit job does NOT fire at register in multi mode', async () => {
+    setCoreConfig({ PAYMENT_TENANT_MODE: 'multi' });
+    const driver = createCronRegistry('node-cron');
+    let ran = 0;
+    driver.register([
+      {
+        name: 'm.init',
+        time: '0 0 0 1 1 *',
+        fn: () => {
+          ran += 1;
+        },
+        options: { runOnInit: true },
+      },
+    ]);
+    await flush();
+    expect(ran).toBe(0); // skipped in multi — the job runs on its next scheduled tick
+    driver.stop();
+  });
+
+  it('single mode STILL honors runOnInit (the default tenant is always present)', async () => {
+    setCoreConfig({ PAYMENT_TENANT_MODE: 'single' });
+    const driver = createCronRegistry('node-cron');
+    let ran = 0;
+    driver.register([
+      {
+        name: 's.init',
+        time: '0 0 0 1 1 *',
+        fn: () => {
+          ran += 1;
+        },
+        options: { runOnInit: true },
+      },
+    ]);
+    await flush();
+    expect(ran).toBe(1); // single keeps runOnInit
+    driver.stop();
+  });
+});
+
+describe('D2 — register receives all jobs (conservation)', () => {
+  it('getJobNames lists every registered job in order', () => {
+    const driver = createCronRegistry('node-cron');
+    driver.register([
+      { name: 'a', time: '0 0 0 1 1 *', fn: () => {} },
+      { name: 'b', time: '0 0 0 1 1 *', fn: () => {} },
+      { name: 'c', time: '0 0 0 1 1 *', fn: () => {} },
+    ]);
+    expect(driver.getJobNames().map((s) => s.split(' ')[0])).toEqual(['a', 'b', 'c']);
+    driver.stop();
+  });
+
+  it('SECURITY/conservation: no bare @abtnode/cron import or Cron.init survives in api/src', () => {
+    // the only allowed reference is the lazy require() inside the driver itself.
+    const root = path.resolve(__dirname, '../../src');
+    const offenders: string[] = [];
+    const walk = (dir: string) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.name.endsWith('.ts')) {
+          const src = fs.readFileSync(full, 'utf8');
+          if (/import\s+[^;]*from\s+['"]@abtnode\/cron['"]/.test(src)) offenders.push(`${full}: import`);
+          if (/\bCron\.init\s*\(/.test(src)) offenders.push(`${full}: Cron.init`);
+        }
+      }
+    };
+    walk(root);
+    expect(offenders).toEqual([]);
+  });
+});
+
+describe('D2 — a throwing job routes to onError, does not crash the driver', () => {
+  it('onError receives (err, name); other jobs keep running', async () => {
+    const driver = createCronRegistry('node-cron');
+    const errs: Array<{ name: string; message: string }> = [];
+    let okRan = 0;
+    driver.register(
+      [
+        {
+          name: 'boom',
+          time: '0 0 0 1 1 *',
+          fn: () => {
+            throw new Error('kaboom');
+          },
+          options: { runOnInit: true },
+        },
+        {
+          name: 'ok',
+          time: '0 0 0 1 1 *',
+          fn: () => {
+            okRan += 1;
+          },
+          options: { runOnInit: true },
+        },
+      ],
+      (err, name) => errs.push({ name, message: err.message })
+    );
+    await flush();
+    expect(errs).toEqual([{ name: 'boom', message: 'kaboom' }]);
+    expect(okRan).toBe(1);
+    driver.stop();
+  });
+});
+
+describe('D2 — teardown: stop() kills the timer, start()/stop() is idempotent', () => {
+  it('after stop() a 1-second cron no longer fires', async () => {
+    const driver = createCronRegistry('node-cron');
+    let ticks = 0;
+    driver.register([
+      {
+        name: 'tear',
+        time: '*/1 * * * * *',
+        fn: () => {
+          ticks += 1;
+        },
+      },
+    ]);
+    driver.stop();
+    const before = ticks;
+    await wait(2200);
+    expect(ticks).toBe(before); // no fires after stop — timer was cleared
+  });
+
+  it('stop() then re-register does not double-fire (job set idempotent)', async () => {
+    const driver = createCronRegistry('node-cron');
+    let ran = 0;
+    const jobs = [
+      {
+        name: 'idem',
+        time: '0 0 0 1 1 *',
+        fn: () => {
+          ran += 1;
+        },
+        options: { runOnInit: true },
+      },
+    ];
+    driver.register(jobs);
+    await flush();
+    expect(ran).toBe(1);
+    driver.stop();
+    driver.register(jobs); // restart
+    await flush();
+    expect(ran).toBe(2); // exactly one more — not 3+ (old scheduler was torn down)
+    driver.stop();
+  });
+
+  it('dispose() clears the registry', () => {
+    const driver = createCronRegistry('node-cron');
+    driver.register([{ name: 'x', time: '0 0 0 1 1 *', fn: () => {} }]);
+    expect(driver.getJobNames().length).toBe(1);
+    driver.dispose();
+    expect(driver.getJobNames().length).toBe(0);
+  });
+});
+
+describe('D2 — cf-cron driver stays passive (no self-scheduling timer)', () => {
+  it('cf-cron does not run jobs on register; host drives runDue()', async () => {
+    const driver = createCronRegistry('cf-cron');
+    let ran = 0;
+    driver.register([
+      {
+        name: 'cf',
+        time: '*/1 * * * * *',
+        fn: () => {
+          ran += 1;
+        },
+        options: { runOnInit: true },
+      },
+    ]);
+    await wait(1200);
+    expect(ran).toBe(0); // no self-scheduling, runOnInit skipped on CF
+    const result = await driver.runDue(new Date());
+    expect(result.ran).toContain('cf');
+    driver.stop(); // no-op, must not throw
+    expect(ran).toBe(1);
+  });
+});

package/api/tests/libs/crons-conservation-d2.spec.ts

@@ -0,0 +1,52 @@
+// D2 (S3.0) — conservation: crons/index registers its FULL declared job set
+// through a single getCronDriver().register() call, with no bare @abtnode/cron
+// channel left behind. Verified at the source level (parsing crons/index.ts)
+// rather than by importing it — importing the whole crons graph pulls heavy
+// integration ESM deps outside this test's concern. Combined with the scanner
+// in cron-driver-d2.spec ("no bare @abtnode/cron import / Cron.init anywhere"),
+// this proves: ONE registration channel, carrying the whole declared set.
+
+import fs from 'fs';
+import path from 'path';
+
+const CRONS_SRC = path.resolve(__dirname, '../../src/crons/index.ts');
+
+describe('D2 — crons/index conservation (single driver channel, full job set)', () => {
+  const src = fs.readFileSync(CRONS_SRC, 'utf8');
+
+  it('registers through getCronDriver().register() exactly once (no bare Cron.init)', () => {
+    const registerCalls = src.match(/getCronDriver\(\)\.register\(/g) || [];
+    expect(registerCalls.length).toBe(1);
+    expect(src).not.toMatch(/Cron\.init\s*\(/);
+    expect(src).not.toMatch(/from\s+['"]@abtnode\/cron['"]/);
+  });
+
+  it('the declared job set reaches the driver in full (>=18 distinct named jobs)', () => {
+    const names = [...src.matchAll(/name:\s*'([^']+)'/g)].map((m) => m[1]);
+    // every job declared in the register([...]) array is a name: '...' literal
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'subscription.will.renew',
+        'subscription.trial.will.end',
+        'customer.subscription.will_canceled',
+        'subscription.schedule.retry',
+        'refund.recovery',
+        'checkoutSession.cleanup.expired',
+        'stripe.invoice.sync',
+        'stripe.payment.sync',
+        'stripe.subscription.sync',
+        'customer.stake.revoked',
+        'iap.reconcile',
+        'event.retry',
+        'payment.stat',
+        'payment.daily.report',
+        'deposit.vault',
+        'credit.consumption',
+        'vendor.status.check',
+        'vendor.return.scan',
+      ])
+    );
+    expect(names.length).toBeGreaterThanOrEqual(18);
+    expect(new Set(names).size).toBe(names.length); // no duplicate names
+  });
+});

package/api/tests/libs/did-connect-runtime-js.spec.ts

@@ -0,0 +1,98 @@
+// S3-CF (DID convergence) — the real @arcblock/did-connect-js runtime.
+//
+// Acceptance: when a host injects createDidConnectJsRuntime (CF / arc-node), the
+// core buildConnectRoutesHono registers the 14 payment DID-Connect actions, and
+// the @blocklet/sdk wallet modules are NEVER constructed (no silent SDK fallback).
+//
+// The @blocklet/sdk wallet mocks throw on construct so any accidental SDK use
+// fails this spec loudly (mirrors the CF fail-fast shims; this is the node-side
+// guard the runtime-boundary requires).
+// eslint-disable-next-line import/no-extraneous-dependencies
+import * as Mcrypto from '@ocap/mcrypto';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { fromRandom } from '@ocap/wallet';
+
+jest.mock('@blocklet/sdk/lib/wallet-handler', () => ({
+  WalletHandlers: class {
+    constructor() {
+      throw new Error('SDK wallet-handler must not be constructed under the did-connect-js runtime');
+    }
+  },
+}));
+jest.mock('@blocklet/sdk/lib/wallet-authenticator', () => ({
+  WalletAuthenticator: class {
+    constructor() {
+      throw new Error('SDK wallet-authenticator must not be constructed under the did-connect-js runtime');
+    }
+  },
+}));
+
+const APP_WALLET_TYPE = {
+  role: Mcrypto.types.RoleType.ROLE_APPLICATION,
+  pk: Mcrypto.types.KeyType.ED25519,
+  hash: Mcrypto.types.HashType.SHA3,
+};
+
+const ALL_ACTIONS = [
+  'collect',
+  'collect-batch',
+  'payment',
+  'setup',
+  'subscription',
+  'change-payment',
+  'change-plan',
+  'recharge',
+  'recharge-account',
+  'delegation',
+  'overdraft-protection',
+  're-stake',
+  'auto-recharge-auth',
+  'change-payer',
+];
+
+describe('S3-CF DID convergence — @arcblock/did-connect-js runtime', () => {
+  it('registers the 14 payment DID actions and never constructs @blocklet/sdk wallets', () => {
+    // eslint-disable-next-line global-require
+    const { setDidConnectRuntime: setRuntime } = require('../../src/libs/auth');
+    // eslint-disable-next-line global-require
+    const { setIdentityDriver: setDriver } = require('../../src/libs/drivers');
+    // eslint-disable-next-line global-require
+    const { createDidConnectJsRuntime } = require('../../src/libs/did-connect/runtime-did-connect-js');
+    // eslint-disable-next-line global-require
+    const { buildConnectRoutesHono } = require('../../src/service');
+
+    const signer = fromRandom(APP_WALLET_TYPE);
+    setDriver({
+      resolveInstanceDidForHost: () => 'zMOCK_DIDJS',
+      getInstanceAppIdentity: async () => ({ appSk: signer.secretKey, appInfo: { name: 'T' } }),
+    });
+
+    const memStore: Record<string, any> = {};
+    const tokenStorage = {
+      create: async (token: string, status = 'created') => {
+        memStore[token] = { token, status };
+        return memStore[token];
+      },
+      read: async (token: string) => memStore[token] ?? null,
+      update: async (token: string, u: Record<string, any>) => {
+        memStore[token] = { ...memStore[token], ...u };
+        return memStore[token];
+      },
+      delete: async (token: string) => {
+        delete memStore[token];
+      },
+      on: () => undefined,
+    };
+
+    setRuntime(createDidConnectJsRuntime({ tokenStorage }));
+
+    const connectApp = buildConnectRoutesHono();
+    const paths: Set<string> = new Set(((connectApp as any).routes || []).map((r: any) => r.path));
+
+    // every payment action exposes at least its /token entry under /api/did/<action>
+    for (const action of ALL_ACTIONS) {
+      expect([...paths].some((p) => p.startsWith(`/api/did/${action}/`))).toBe(true);
+    }
+    // no SDK wallet was constructed (the mocks above would have thrown)
+  });
+});

package/api/tests/libs/did-connect-tenant-identity.spec.ts

@@ -0,0 +1,159 @@
+// S3-CF (DID convergence) — the shared per-tenant DID-Connect identity resolver.
+//
+// resolveTenantIdentity is the ONE path both the CF and arc-node AUTH_SERVICE
+// runtimes use to derive their DID-Connect signing wallet from the host
+// IdentityDriver.getInstanceAppIdentity — never a fixed isolate key. This spec
+// locks the happy path + the two fail-closed errors.
+// eslint-disable-next-line import/no-extraneous-dependencies
+import * as Mcrypto from '@ocap/mcrypto';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { fromRandom } from '@ocap/wallet';
+
+import { setIdentityDriver, createDefaultIdentityDriver, type IdentityDriver } from '../../src/libs/drivers';
+import {
+  resolveTenantIdentity,
+  clearTenantIdentityCache,
+  getCachedTenantIdentity,
+  hasDynamicIdentity,
+  warmTenantIdentity,
+} from '../../src/libs/did-connect/tenant-identity';
+
+const INSTANCE = 'zMOCK_TENANT_IDENTITY';
+
+// The DID-Connect signer is a ROLE_APPLICATION/ED25519/SHA3 wallet (the DID
+// encoding depends on the type), so the test must mint source keys with the SAME
+// type for the derived address to round-trip.
+const APP_WALLET_TYPE = {
+  role: Mcrypto.types.RoleType.ROLE_APPLICATION,
+  pk: Mcrypto.types.KeyType.ED25519,
+  hash: Mcrypto.types.HashType.SHA3,
+};
+
+describe('S3-CF DID convergence — resolveTenantIdentity (shared identity resolver)', () => {
+  beforeEach(() => {
+    // resolveTenantIdentity now caches per instanceDid (LRU+TTL). These tests
+    // reuse one INSTANCE did with swapped drivers, so isolate by clearing.
+    clearTenantIdentityCache();
+  });
+  afterEach(() => {
+    setIdentityDriver(createDefaultIdentityDriver()); // reset module-level driver
+    clearTenantIdentityCache();
+  });
+
+  it('derives the signing wallet from the driver getInstanceAppIdentity(appSk) + passes appInfo', async () => {
+    const signer = fromRandom(APP_WALLET_TYPE);
+    const driver: IdentityDriver = {
+      resolveInstanceDidForHost: () => INSTANCE,
+      getInstanceAppIdentity: async (did) => {
+        expect(did).toBe(INSTANCE);
+        return { appSk: signer.secretKey, appInfo: { name: 'Tenant X', icon: 'https://x/i.png' } };
+      },
+    };
+    setIdentityDriver(driver);
+
+    const resolved = await resolveTenantIdentity(INSTANCE);
+    expect(resolved.instanceDid).toBe(INSTANCE);
+    // the derived wallet is the same keypair as the source appSk
+    expect(resolved.wallet.address).toBe(signer.address);
+    // no rotated key → permanentWallet falls back to wallet
+    expect(resolved.permanentWallet.address).toBe(signer.address);
+    expect(resolved.appInfo).toEqual({ name: 'Tenant X', icon: 'https://x/i.png' });
+  });
+
+  it('uses appPsk for the permanent wallet when keys have rotated', async () => {
+    const current = fromRandom(APP_WALLET_TYPE);
+    const permanent = fromRandom(APP_WALLET_TYPE);
+    setIdentityDriver({
+      resolveInstanceDidForHost: () => INSTANCE,
+      getInstanceAppIdentity: async () => ({ appSk: current.secretKey, appPsk: permanent.secretKey }),
+    });
+
+    const resolved = await resolveTenantIdentity(INSTANCE);
+    expect(resolved.wallet.address).toBe(current.address);
+    expect(resolved.permanentWallet.address).toBe(permanent.address);
+  });
+
+  it('throws (no silent fallback) when the driver lacks getInstanceAppIdentity', async () => {
+    setIdentityDriver(createDefaultIdentityDriver()); // default driver has no getInstanceAppIdentity
+    await expect(resolveTenantIdentity(INSTANCE)).rejects.toThrow(/does not implement getInstanceAppIdentity/);
+  });
+
+  it('fails closed when the instance has no app signing key', async () => {
+    setIdentityDriver({
+      resolveInstanceDidForHost: () => INSTANCE,
+      // @ts-expect-error — intentionally returns no appSk to exercise the fail-closed path
+      getInstanceAppIdentity: async () => ({ appInfo: { name: 'no key' } }),
+    });
+    await expect(resolveTenantIdentity(INSTANCE)).rejects.toThrow(/no app signing key.*fail-closed/);
+  });
+
+  // Layer 4 (wallet-authenticator-dynamic.md) — business wallet support.
+  it('derives the ethereum business wallet from the same appSk (secp256k1)', async () => {
+    const signer = fromRandom(APP_WALLET_TYPE);
+    setIdentityDriver({
+      resolveInstanceDidForHost: () => INSTANCE,
+      getInstanceAppIdentity: async () => ({ appSk: signer.secretKey }),
+    });
+    const resolved = await resolveTenantIdentity(INSTANCE);
+    // distinct EVM address (0x-prefixed), not the arcblock DID
+    expect(resolved.ethWallet.address).toMatch(/^0x[0-9a-fA-F]{40}$/);
+    expect(resolved.ethWallet.address).not.toBe(resolved.wallet.address);
+  });
+
+  it('hasDynamicIdentity reflects whether the driver implements getInstanceAppIdentity', () => {
+    setIdentityDriver(createDefaultIdentityDriver());
+    expect(hasDynamicIdentity()).toBe(false);
+    setIdentityDriver({
+      resolveInstanceDidForHost: () => INSTANCE,
+      getInstanceAppIdentity: async () => ({ appSk: 'x' }),
+    });
+    expect(hasDynamicIdentity()).toBe(true);
+  });
+
+  it('getCachedTenantIdentity returns the warmed value, and fails closed before warming', async () => {
+    const signer = fromRandom(APP_WALLET_TYPE);
+    setIdentityDriver({
+      resolveInstanceDidForHost: () => INSTANCE,
+      getInstanceAppIdentity: async () => ({ appSk: signer.secretKey }),
+    });
+    // not warmed yet → fail-closed (no silent default key)
+    expect(() => getCachedTenantIdentity(INSTANCE)).toThrow(/not resolved.*fail-closed/);
+    // warm (what the request/job middleware does), then the sync read resolves
+    await resolveTenantIdentity(INSTANCE);
+    expect(getCachedTenantIdentity(INSTANCE).wallet.address).toBe(signer.address);
+  });
+
+  it('caches the derived identity — a second resolve does not re-call the driver', async () => {
+    let calls = 0;
+    const signer = fromRandom(APP_WALLET_TYPE);
+    setIdentityDriver({
+      resolveInstanceDidForHost: () => INSTANCE,
+      getInstanceAppIdentity: async () => {
+        calls += 1;
+        return { appSk: signer.secretKey };
+      },
+    });
+    await resolveTenantIdentity(INSTANCE);
+    await resolveTenantIdentity(INSTANCE);
+    expect(calls).toBe(1); // second call served from cache
+  });
+
+  it('warmTenantIdentity swallows resolve errors and leaves the cache cold (fail-closed on use)', async () => {
+    setIdentityDriver({
+      resolveInstanceDidForHost: () => INSTANCE,
+      getInstanceAppIdentity: async () => {
+        throw new Error('AUTH_SERVICE down');
+      },
+    });
+    // warm must NOT throw (a non-wallet request is not blocked)
+    await expect(warmTenantIdentity(INSTANCE)).resolves.toBeUndefined();
+    // but the cache stays cold → any wallet access fails closed
+    expect(() => getCachedTenantIdentity(INSTANCE)).toThrow(/not resolved.*fail-closed/);
+  });
+
+  it('warmTenantIdentity is a no-op on the blocklet-server runtime (no dynamic driver)', async () => {
+    setIdentityDriver(createDefaultIdentityDriver()); // no getInstanceAppIdentity
+    await expect(warmTenantIdentity(INSTANCE)).resolves.toBeUndefined();
+    expect(() => getCachedTenantIdentity(INSTANCE)).toThrow(/not resolved.*fail-closed/);
+  });
+});