payment-kit 1.29.2 → 1.29.4

package/api/tests/bootstrap/bootstrap.spec.ts

@@ -0,0 +1,162 @@
+// P2 — runtime-neutral bootstrap helper (README D2 / F2).
+//
+// Pure-function unit tests (no network). Covers the 6 test classes from
+// tasks.md P2: happy / bad-input / security / data-loss / data-damage /
+// data-leak, plus the T2.3 reserved-prefix regression lock.
+import { buildBootstrap, mergeRemote, buildBootstrapScript, PAYMENT_KIT_DID } from '../../../scripts/bootstrap-inject';
+
+const baseOpts = {
+  uiPrefix: '/.well-known/payment',
+  componentId: PAYMENT_KIT_DID,
+  remoteBlockletUrl: '/__blocklet__.js?type=json',
+  serviceHost: '/.well-known/service',
+  localOnly: ['prefix', 'navigation', 'componentMountPoints'],
+};
+
+describe('P2 bootstrap helper — buildBootstrap', () => {
+  it('happy: returns prefix/componentId/serviceHost/remoteBlockletUrl skeleton', () => {
+    const wb = buildBootstrap(baseOpts);
+    expect(wb.prefix).toBe('/.well-known/payment');
+    expect(wb.componentId).toBe(PAYMENT_KIT_DID); // getPrefix() precondition (TM-2)
+    expect(wb.serviceHost).toBe('/.well-known/service');
+    expect(wb.remoteBlockletUrl.startsWith('/__blocklet__.js')).toBe(true); // root-exact, no uiPrefix
+  });
+
+  it('security/regression (T2.3): throws when remoteBlockletUrl falls under uiPrefix', () => {
+    expect(() =>
+      buildBootstrap({ ...baseOpts, remoteBlockletUrl: '/.well-known/payment/__blocklet__.js' })
+    ).toThrow();
+  });
+
+  it('bad-input: throws when remoteBlockletUrl is not root-exact', () => {
+    expect(() => buildBootstrap({ ...baseOpts, remoteBlockletUrl: '/foo/__blocklet__.js' })).toThrow();
+  });
+
+  it('data-leak: bakes no per-tenant data — appName/logo absent until runtime merge', () => {
+    const wb = buildBootstrap(baseOpts);
+    expect(wb.appName).toBeUndefined();
+    expect(wb.appLogo).toBeUndefined();
+    // Two distinct tenants merging different remote branding onto the SAME helper
+    // output keep an IDENTICAL prefix/componentId — no per-tenant value leaks into
+    // the local (build-baked) skeleton.
+    const tenantA = mergeRemote(buildBootstrap(baseOpts), { appName: 'Tenant A', prefix: '/a' });
+    const tenantB = mergeRemote(buildBootstrap(baseOpts), { appName: 'Tenant B', prefix: '/b' });
+    expect(tenantA.appName).toBe('Tenant A');
+    expect(tenantB.appName).toBe('Tenant B');
+    expect(tenantA.prefix).toBe(tenantB.prefix); // '/.well-known/payment' for both
+    expect(tenantA.componentId).toBe(tenantB.componentId);
+  });
+});
+
+describe('P2 bootstrap helper — mergeRemote', () => {
+  it('happy: appName/logo/theme come from remote, localOnly preserved', () => {
+    const wb = buildBootstrap(baseOpts);
+    const merged = mergeRemote(wb, { appName: 'Acme', appLogo: 'https://x/y.png?a=1&b=2', theme: { primary: '#000' } });
+    expect(merged.appName).toBe('Acme');
+    expect(merged.appLogo).toBe('https://x/y.png?a=1&b=2'); // URL & not corrupted
+    expect(merged.theme).toEqual({ primary: '#000' });
+  });
+
+  it('data-loss: localOnly fields keep their (local) values after merge', () => {
+    const wb = buildBootstrap({ ...baseOpts, extra: { navigation: [{ id: 'a' }] } });
+    // remote tries to override prefix + navigation; both are localOnly → ignored,
+    // the local values survive (navigation defaults to [] and is set via extra here).
+    const merged = mergeRemote(wb, { prefix: '/', navigation: [{ id: 'REMOTE' }], componentMountPoints: [{ x: 1 }] });
+    expect(merged.prefix).toBe('/.well-known/payment');
+    expect(merged.navigation).toEqual([{ id: 'a' }]); // local nav kept, remote skipped
+    expect(merged.componentMountPoints).toEqual([]); // local default kept (extra didn't set it)
+  });
+
+  it('data-damage: componentId/prefix stay constant regardless of remote', () => {
+    const wb = buildBootstrap(baseOpts);
+    const merged = mergeRemote(wb, { componentId: 'zEVIL', prefix: '/' });
+    expect(merged.componentId).toBe(PAYMENT_KIT_DID);
+    expect(merged.prefix).toBe('/.well-known/payment');
+  });
+
+  it('security: rejects prototype pollution (__proto__/constructor/prototype)', () => {
+    const wb = buildBootstrap(baseOpts);
+    const merged = mergeRemote(wb, JSON.parse('{"__proto__":{"polluted":1},"constructor":2,"safe":3}'));
+    expect(({} as any).polluted).toBeUndefined();
+    expect((merged as any).polluted).toBeUndefined();
+    expect(merged.safe).toBe(3);
+  });
+
+  it('security: angle-bracket escapes string values (XSS)', () => {
+    const wb = buildBootstrap(baseOpts);
+    const merged = mergeRemote(wb, { appName: '<svg onload=alert(1)>' });
+    expect(merged.appName).not.toContain('<svg');
+    expect(merged.appName).toContain('&lt;svg');
+  });
+
+  it('security: refuses oversized payload (>256KB)', () => {
+    const wb = buildBootstrap(baseOpts);
+    expect(() => mergeRemote(wb, { appName: 'x'.repeat(300 * 1024) })).toThrow();
+  });
+
+  it('bad-input: empty/undefined remote does not throw, keeps base intact', () => {
+    const wb = buildBootstrap(baseOpts);
+    expect(mergeRemote(wb, {} as any).prefix).toBe('/.well-known/payment');
+    expect(mergeRemote(wb, undefined as any).componentId).toBe(PAYMENT_KIT_DID);
+  });
+});
+
+describe('P2 bootstrap helper — buildBootstrapScript', () => {
+  it('happy: emits a <script> with the baked window.blocklet + embedded mergeRemote', () => {
+    const script = buildBootstrapScript(baseOpts);
+    expect(script).toContain('window.blocklet =');
+    expect(script).toContain(PAYMENT_KIT_DID);
+    expect(script).toContain('/__blocklet__.js?type=json');
+    // the runtime merge is the same mergeRemote source (single source of truth)
+    expect(script).toContain('refusing merge');
+  });
+
+  it('data-damage: emitted script references the root-exact remote url, never under uiPrefix', () => {
+    const script = buildBootstrapScript(baseOpts);
+    expect(script).not.toContain('/.well-known/payment/__blocklet__');
+  });
+});
+
+// Dynamic (Layer 2) — run the EMITTED <script> body in a node vm with a stubbed
+// browser window + synchronous XHR, proving it is valid browser JS and that the
+// runtime merge (the embedded mergeRemote) preserves every invariant against a
+// hostile remote __blocklet__.js. Committed + reproducible (replaces the former
+// throwaway `tsx -e` smoke).
+describe('P2 bootstrap helper — emitted script runtime behavior (vm)', () => {
+  function runEmittedScript(remote: Record<string, any>) {
+    // eslint-disable-next-line global-require
+    const vm = require('node:vm');
+    const script = buildBootstrapScript(baseOpts);
+    // tolerate any <script ...> attributes, not just the bare tag
+    const body = script.replace(/^<script[^>]*>/, '').replace(/<\/script>\s*$/, '');
+    const win: any = { location: { origin: 'https://t1.example' } };
+    const ctx: any = {
+      window: win,
+      XMLHttpRequest: function (this: any) {
+        this.open = () => {};
+        this.send = () => {
+          this.status = 200;
+          this.responseText = JSON.stringify(remote);
+        };
+      },
+    };
+    ctx.global = ctx;
+    vm.createContext(ctx);
+    vm.runInContext(body, ctx);
+    return win.blocklet;
+  }
+
+  it('runs as valid browser JS and merges a hostile remote while protecting invariants', () => {
+    const wb = runEmittedScript({
+      appName: '<svg onload=alert(1)>',
+      prefix: '/',
+      componentId: 'zEVIL',
+      appLogo: 'https://cdn/x.png?a=1&b=2',
+    });
+    expect(wb.prefix).toBe('/.well-known/payment'); // localOnly protected
+    expect(wb.componentId).toBe(PAYMENT_KIT_DID); // structural invariant
+    expect(wb.appName).not.toContain('<svg'); // XSS escaped
+    expect(wb.appLogo).toBe('https://cdn/x.png?a=1&b=2'); // URL query not corrupted
+    expect(wb.env.appName).toBe(wb.appName); // env mirror populated
+  });
+});

package/api/tests/crons/tenant-fanout.spec.ts

@@ -0,0 +1,158 @@
+// Phase 7 (S3 arc-payment-embed) — multi-tenant cron fan-out.
+//
+// Background crons that issue a top-level tenant-scoped query have no request
+// to carry a tenant, so in multi mode getInstanceDid() throws
+// TENANT_CONTEXT_MISSING and the pass does nothing. perTenant() wraps such a
+// cron's fn so it runs once per provisioned tenant inside withTenant; single
+// mode runs it as-is (the default tenant auto-resolves).
+//
+// Dynamic require() + jest.resetModules so each case re-reads the tenant mode.
+/* eslint-disable global-require, import/no-dynamic-require */
+
+describe('perTenant — multi-tenant cron fan-out', () => {
+  const ORIGINAL_MODE = process.env.PAYMENT_TENANT_MODE;
+  const ORIGINAL_PID = process.env.BLOCKLET_APP_PID;
+
+  afterEach(() => {
+    if (ORIGINAL_MODE === undefined) delete process.env.PAYMENT_TENANT_MODE;
+    else process.env.PAYMENT_TENANT_MODE = ORIGINAL_MODE;
+    if (ORIGINAL_PID === undefined) delete process.env.BLOCKLET_APP_PID;
+    else process.env.BLOCKLET_APP_PID = ORIGINAL_PID;
+    jest.resetModules();
+  });
+
+  // Happy path — multi mode runs the fn once per provisioned tenant, each
+  // inside its own tenant context.
+  it('multi mode: runs fn once per tenant inside withTenant', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { perTenant } = require('../../src/crons/tenant-fanout');
+    const { getInstanceDid } = require('../../src/libs/context');
+
+    const seen: string[] = [];
+    const wrapped = perTenant(
+      'test.cron',
+      () => seen.push(getInstanceDid()),
+      () => Promise.resolve(['did:abt:TENANT_A', 'did:abt:TENANT_B'])
+    );
+    await wrapped();
+
+    expect(seen).toEqual(['did:abt:TENANT_A', 'did:abt:TENANT_B']);
+  });
+
+  // Single mode — no fan-out: the fn runs exactly once (the default tenant
+  // auto-resolves in getInstanceDid). Idempotent: not N times.
+  it('single mode: runs fn exactly once (no fan-out, no enumeration)', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'single';
+    process.env.BLOCKLET_APP_PID = 'did:abt:DEFAULT';
+    jest.resetModules();
+    const { perTenant } = require('../../src/crons/tenant-fanout');
+
+    let calls = 0;
+    const listTenants = jest.fn(() => Promise.resolve(['did:abt:A', 'did:abt:B']));
+    const wrapped = perTenant(
+      'test.cron',
+      () => {
+        calls += 1;
+      },
+      listTenants
+    );
+    await wrapped();
+
+    expect(calls).toBe(1);
+    expect(listTenants).not.toHaveBeenCalled(); // single mode never enumerates
+  });
+
+  // Data loss / error isolation — one tenant's failure must not abort the pass;
+  // every other tenant still runs.
+  it('multi mode: one tenant failing does not stop the others', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { perTenant } = require('../../src/crons/tenant-fanout');
+    const { getInstanceDid } = require('../../src/libs/context');
+
+    const ran: string[] = [];
+    const wrapped = perTenant(
+      'test.cron',
+      () => {
+        const did = getInstanceDid();
+        if (did === 'did:abt:B') throw new Error('boom for B');
+        ran.push(did);
+      },
+      () => Promise.resolve(['did:abt:A', 'did:abt:B', 'did:abt:C'])
+    );
+
+    // the pass itself resolves (errors isolated), not rejects
+    await expect(wrapped()).resolves.toBeUndefined();
+    expect(ran).toEqual(['did:abt:A', 'did:abt:C']);
+  });
+
+  // Bad input — empty tenant list is a clean no-op (no throw).
+  it('multi mode: empty tenant list is a no-op', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { perTenant } = require('../../src/crons/tenant-fanout');
+
+    let calls = 0;
+    const wrapped = perTenant(
+      'test.cron',
+      () => {
+        calls += 1;
+      },
+      () => Promise.resolve([])
+    );
+    await expect(wrapped()).resolves.toBeUndefined();
+    expect(calls).toBe(0);
+  });
+
+  // Data leak — each pass is scoped to exactly its tenant; the fn never sees
+  // another tenant's id leaking across iterations.
+  it('multi mode: each pass sees only its own tenant id', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { perTenant } = require('../../src/crons/tenant-fanout');
+    const { getInstanceDid } = require('../../src/libs/context');
+
+    const pairs: Array<[string, string]> = [];
+    const wrapped = perTenant(
+      'test.cron',
+      () => {
+        // capture the tenant twice within the same pass — must be stable
+        pairs.push([getInstanceDid(), getInstanceDid()]);
+      },
+      () => Promise.resolve(['did:abt:A', 'did:abt:B'])
+    );
+    await wrapped();
+
+    expect(pairs).toEqual([
+      ['did:abt:A', 'did:abt:A'],
+      ['did:abt:B', 'did:abt:B'],
+    ]);
+  });
+});
+
+describe('listProvisionedTenants — DISTINCT instance_did from payment-core store', () => {
+  afterEach(() => {
+    jest.resetModules();
+    jest.restoreAllMocks();
+  });
+
+  it('dedupes and filters empty/null instance_did from a cross-tenant read', async () => {
+    jest.resetModules();
+    // mock the cross-tenant system read so this stays a pure unit test (no DB)
+    jest.doMock('../../src/store/scoped', () => ({
+      systemFindAll: jest.fn(() =>
+        Promise.resolve([
+          { instance_did: 'did:abt:A' },
+          { instance_did: 'did:abt:B' },
+          { instance_did: 'did:abt:A' }, // duplicate
+          { instance_did: null }, // unprovisioned / null
+          { instance_did: '' }, // empty
+        ])
+      ),
+    }));
+    const { listProvisionedTenants } = require('../../src/crons/tenant-fanout');
+    const dids = await listProvisionedTenants();
+    expect(dids.sort()).toEqual(['did:abt:A', 'did:abt:B']);
+  });
+});

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/);
+  });
+});

package/api/tests/libs/service-host.spec.ts

@@ -0,0 +1,37 @@
+// P5 T5.1 / TM-8 — resolveServiceHost regression lock.
+//
+// The full P5 login E2E (DID Connect against arc /.well-known/service) is blocked
+// on D-4 (arc endpoint) + P4 (arc wiring), so these are the in-workspace locks
+// that DON'T depend on D-4: the blocklet-server fallback (TM-8) and the arc path.
+import { resolveServiceHost } from '../../../src/libs/service-host';
+
+describe('P5 T5.1 — resolveServiceHost', () => {
+  const realWindow = (global as any).window;
+  afterEach(() => {
+    (global as any).window = realWindow;
+  });
+
+  it('TM-8 (regression): blocklet-server form (no injected serviceHost) → prefix, unchanged', () => {
+    (global as any).window = { blocklet: { prefix: '/' } };
+    expect(resolveServiceHost('/')).toBe('/');
+    (global as any).window = { blocklet: { prefix: '/payment' } };
+    expect(resolveServiceHost('/payment')).toBe('/payment');
+  });
+
+  it('arc form: injected window.blocklet.serviceHost wins over prefix', () => {
+    (global as any).window = { blocklet: { serviceHost: '/.well-known/service' } };
+    expect(resolveServiceHost('/.well-known/payment')).toBe('/.well-known/service');
+  });
+
+  it('bad-input: empty/missing serviceHost falls back to prefix (not undefined/empty)', () => {
+    (global as any).window = { blocklet: { serviceHost: '' } };
+    expect(resolveServiceHost('/.well-known/payment')).toBe('/.well-known/payment');
+    (global as any).window = {};
+    expect(resolveServiceHost('/x')).toBe('/x');
+  });
+
+  it('no window at all (SSR/test) → prefix, no throw', () => {
+    delete (global as any).window;
+    expect(resolveServiceHost('/y')).toBe('/y');
+  });
+});