payment-kit 1.29.1 → 1.29.3

package/api/tests/libs/lock-tenant.spec.ts

@@ -0,0 +1,66 @@
+// Phase 8 (W2-1a): the libs/lock facade — tenant prefix + fail-closed.
+//
+// The driver-level semantics live in packages/payment-core/tests/drivers; this
+// spec covers the facade behavior that the call sites depend on: tenant
+// prefixing, the global-scope exemption, and multi-mode fail-closed.
+//
+// Dynamic require() is required: each case re-imports lock.ts after setting the
+// tenant-mode env + jest.resetModules so the module-level driver is fresh.
+/* eslint-disable global-require, import/no-dynamic-require */
+
+describe('getLock facade — tenant prefix + fail-closed', () => {
+  const ORIGINAL_MODE = process.env.PAYMENT_TENANT_MODE;
+
+  afterEach(() => {
+    if (ORIGINAL_MODE === undefined) delete process.env.PAYMENT_TENANT_MODE;
+    else process.env.PAYMENT_TENANT_MODE = ORIGINAL_MODE;
+    jest.resetModules();
+  });
+
+  it('rejects an empty lock name', () => {
+    const { getLock } = require('../../src/libs/lock');
+    expect(() => getLock('')).toThrow(/non-empty lock name/);
+  });
+
+  it('multi mode: tenant-scoped getLock without context fails closed', () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { getLock } = require('../../src/libs/lock');
+    let code: string | undefined;
+    try {
+      getLock('payment-intent-1');
+    } catch (e: any) {
+      code = e.code;
+    }
+    expect(code).toBe('TENANT_CONTEXT_MISSING');
+  });
+
+  it('multi mode: global-scoped getLock needs no tenant', () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { getLock } = require('../../src/libs/lock');
+    const lock = getLock('startInvoiceQueue', { scope: 'global' });
+    expect(lock.name).toBe('startInvoiceQueue');
+  });
+
+  it('multi mode: tenant-scoped getLock inside withTenant carries the prefix', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { getLock } = require('../../src/libs/lock');
+    const { withTenant } = require('../../src/libs/context');
+    await withTenant('did:abt:TENANT_A', () => {
+      const lock = getLock('payment-intent-1');
+      expect(lock.name).toBe('tenant:did:abt:TENANT_A::payment-intent-1');
+    });
+  });
+
+  it('single mode: tenant-scoped getLock falls back to the deployment app DID prefix', () => {
+    process.env.PAYMENT_TENANT_MODE = 'single';
+    jest.resetModules();
+    const { getLock } = require('../../src/libs/lock');
+    const lock = getLock('payment-intent-1');
+    // single mode never fails closed — name is prefixed with the constant default tenant
+    expect(lock.name.startsWith('tenant:')).toBe(true);
+    expect(lock.name.endsWith('::payment-intent-1')).toBe(true);
+  });
+});

package/api/tests/libs/scoped.spec.ts

@@ -0,0 +1,222 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+
+import { withTenant } from '../../src/libs/context';
+import { TENANT_CONTEXT_MISSING, TENANT_MISMATCH } from '../../src/libs/tenant';
+import {
+  scopedAggregate,
+  scopedCount,
+  scopedCreate,
+  scopedDestroy,
+  scopedFindAll,
+  scopedFindByPk,
+  scopedFindOne,
+  scopedQuery,
+  scopedSum,
+  scopedUpdate,
+} from '../../src/store/scoped';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+
+// real DB: full migration chain on a temp file, then bind the model
+// singletons to it (order matters — initialize() after DDL, see
+// tenant-columns-model.spec.ts for why)
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scoped-spec-'));
+const sequelize = new Sequelize({ dialect: 'sqlite', storage: path.join(dir, 'test.db'), logging: false });
+const umzug = new Umzug({
+  migrations: {
+    glob: ['migrations/*.ts', { cwd: STORE_DIR }],
+    resolve: ({ name, path: p, context }) => {
+      // eslint-disable-next-line import/no-dynamic-require, global-require
+      const migration = require(p!);
+      return {
+        name: name.replace(/\.ts$/, '.js'),
+        up: () => migration.up({ context }),
+        down: () => migration.down({ context }),
+      };
+    },
+  },
+  context: sequelize.getQueryInterface(),
+  storage: new SequelizeStorage({ sequelize }),
+  logger: undefined,
+});
+
+let Customer: any;
+
+beforeAll(async () => {
+  await umzug.up();
+  // eslint-disable-next-line global-require
+  const models = require('../../src/store/models');
+  models.initialize(sequelize);
+  Customer = models.Customer;
+}, 120000);
+
+afterAll(async () => {
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const seedCustomer = (tenant: string, did: string) =>
+  withTenant(tenant, () => scopedCreate(Customer, { livemode: false, did, delinquent: false }));
+
+describe('scoped helpers (phase 3)', () => {
+  beforeEach(async () => {
+    await sequelize.query('DELETE FROM customers');
+  });
+
+  describe('happy path', () => {
+    it('scoped find returns only the active tenant rows; create stamps the tenant', async () => {
+      await seedCustomer(TENANT_A, 'z-user-a');
+      await seedCustomer(TENANT_B, 'z-user-b');
+
+      const aRows = await withTenant(TENANT_A, () => scopedFindAll(Customer));
+      expect(aRows.map((r: any) => r.did)).toEqual(['z-user-a']);
+      expect((aRows[0] as any).instance_did).toBe(TENANT_A);
+
+      const bRows = await withTenant(TENANT_B, () => scopedFindAll(Customer));
+      expect(bRows.map((r: any) => r.did)).toEqual(['z-user-b']);
+    });
+  });
+
+  describe('bad input', () => {
+    it('multi mode without context fails closed', async () => {
+      process.env.PAYMENT_TENANT_MODE = 'multi';
+      try {
+        await expect(scopedFindAll(Customer)).rejects.toMatchObject({ code: TENANT_CONTEXT_MISSING });
+      } finally {
+        delete process.env.PAYMENT_TENANT_MODE;
+      }
+    });
+
+    it('raw SQL without an instance_did binding is refused', async () => {
+      await withTenant(TENANT_A, async () => {
+        expect(() => scopedQuery(sequelize, 'SELECT * FROM customers')).toThrow(
+          expect.objectContaining({ code: TENANT_MISMATCH })
+        );
+      });
+    });
+
+    it('raw SQL with the binding is auto-supplied the active tenant', async () => {
+      await seedCustomer(TENANT_A, 'z-user-a');
+      await seedCustomer(TENANT_B, 'z-user-b');
+      const [rows] = await withTenant(TENANT_A, () =>
+        scopedQuery(sequelize, 'SELECT did FROM customers WHERE instance_did = $instance_did')
+      );
+      expect((rows as any[]).map((r) => r.did)).toEqual(['z-user-a']);
+    });
+  });
+
+  describe('security', () => {
+    it('explicit foreign where.instance_did is rejected, not silently overridden', async () => {
+      await withTenant(TENANT_A, async () => {
+        await expect(scopedFindAll(Customer, { where: { instance_did: TENANT_B } as any })).rejects.toMatchObject({
+          code: TENANT_MISMATCH,
+        });
+      });
+    });
+
+    it('explicit foreign instance_did on create is rejected', async () => {
+      await withTenant(TENANT_A, async () => {
+        await expect(
+          scopedCreate(Customer, { livemode: false, did: 'z-x', delinquent: false, instance_did: TENANT_B })
+        ).rejects.toMatchObject({ code: TENANT_MISMATCH });
+      });
+    });
+
+    it('scanner flags the deliberately-violating fixture file (raw query, no $instance_did)', () => {
+      const fixture = path.join(__dirname, '../fixtures/bare-query-violation.ts');
+      let failed = false;
+      let output = '';
+      try {
+        execFileSync('node', [path.join(__dirname, '../../../scripts/scan-tenant-queries.js'), '--json', fixture], {
+          encoding: 'utf8',
+        });
+      } catch (err: any) {
+        failed = true;
+        output = err.stdout || '';
+      }
+      expect(failed).toBe(true);
+      const result = JSON.parse(output);
+      expect(result.violations.length).toBeGreaterThan(0);
+      expect(result.violations[0].file).toContain('bare-query-violation.ts');
+      expect(result.violations[0].line).toBeGreaterThan(0);
+    });
+  });
+
+  describe('data loss', () => {
+    it('scoped destroy/update only touch the active tenant rows', async () => {
+      await seedCustomer(TENANT_A, 'z-user-a');
+      await seedCustomer(TENANT_B, 'z-user-b');
+
+      await withTenant(TENANT_A, () => scopedDestroy(Customer, { where: {} }));
+      const [allRows] = await sequelize.query('SELECT did, instance_did FROM customers');
+      expect(allRows).toHaveLength(1);
+      expect((allRows as any[])[0].instance_did).toBe(TENANT_B);
+
+      await withTenant(TENANT_B, () => scopedUpdate(Customer, { name: 'renamed' }, { where: {} }));
+      const [updated] = await sequelize.query('SELECT name FROM customers');
+      expect((updated as any[])[0].name).toBe('renamed');
+    });
+  });
+
+  describe('data damage', () => {
+    it('findByPk on another tenant row returns null (cross-tenant = not-found, §13.1)', async () => {
+      // Customer now extends TenantModel: scopedFindByPk delegates to the
+      // scoped override, so a cross-tenant pk resolves to null (not-found)
+      // rather than throwing — the unified §13.1 semantics (404, not 403).
+      const created: any = await seedCustomer(TENANT_B, 'z-user-b');
+      await withTenant(TENANT_A, async () => {
+        await expect(scopedFindByPk(Customer, created.id)).resolves.toBeNull();
+      });
+      // same pk under the right tenant works
+      const found: any = await withTenant(TENANT_B, () => scopedFindByPk(Customer, created.id));
+      expect(found.did).toBe('z-user-b');
+    });
+
+    it('scopedUpdate refuses to change instance_did (rows never change tenant)', async () => {
+      await seedCustomer(TENANT_A, 'z-user-a');
+      await withTenant(TENANT_A, async () => {
+        await expect(scopedUpdate(Customer, { instance_did: TENANT_B } as any, { where: {} })).rejects.toMatchObject({
+          code: TENANT_MISMATCH,
+        });
+      });
+    });
+  });
+
+  describe('data leak', () => {
+    it('findOne/count never see the other tenant even with identical data', async () => {
+      await seedCustomer(TENANT_A, 'z-same-shape');
+      await withTenant(TENANT_B, () =>
+        scopedCreate(Customer, { livemode: false, did: 'z-same-shape-b', delinquent: false, name: 'same' })
+      );
+
+      await withTenant(TENANT_A, async () => {
+        expect(await scopedCount(Customer)).toBe(1);
+        const one: any = await scopedFindOne(Customer, { where: { livemode: false } });
+        expect(one.did).toBe('z-same-shape');
+        expect(await scopedFindOne(Customer, { where: { did: 'z-same-shape-b' } })).toBeNull();
+      });
+    });
+
+    it('sum/aggregate are tenant-isolated too', async () => {
+      await withTenant(TENANT_A, () =>
+        scopedCreate(Customer, { livemode: false, did: 'z-sum-a', delinquent: false, next_invoice_sequence: 5 })
+      );
+      await withTenant(TENANT_B, () =>
+        scopedCreate(Customer, { livemode: false, did: 'z-sum-b', delinquent: false, next_invoice_sequence: 11 })
+      );
+      await withTenant(TENANT_A, async () => {
+        expect(await scopedSum(Customer, 'next_invoice_sequence' as any)).toBe(5);
+        expect(await scopedAggregate(Customer, 'next_invoice_sequence' as any, 'max')).toBe(5);
+      });
+      await withTenant(TENANT_B, async () => {
+        expect(await scopedSum(Customer, 'next_invoice_sequence' as any)).toBe(11);
+      });
+    });
+  });
+});

package/api/tests/libs/secrets-facade.spec.ts

@@ -0,0 +1,52 @@
+// Phase 11 (W2-3): the tenant-aware secrets facade resolves the tenant from
+// TenantContext and fails closed in multi mode without context.
+/* eslint-disable global-require */
+
+describe('secrets facade — tenant resolution + fail-closed', () => {
+  const ORIGINAL_MODE = process.env.PAYMENT_TENANT_MODE;
+
+  afterEach(() => {
+    if (ORIGINAL_MODE === undefined) delete process.env.PAYMENT_TENANT_MODE;
+    else process.env.PAYMENT_TENANT_MODE = ORIGINAL_MODE;
+    jest.resetModules();
+  });
+
+  it('multi mode: encryptSecret without tenant context fails closed', () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { encryptSecret } = require('../../src/libs/secrets');
+    let code: string | undefined;
+    try {
+      encryptSecret('value');
+    } catch (e: any) {
+      code = e.code;
+    }
+    expect(code).toBe('TENANT_CONTEXT_MISSING');
+  });
+
+  it('single mode: encryptSecret/decryptSecret roundtrip via the default (process) key', () => {
+    process.env.PAYMENT_TENANT_MODE = 'single';
+    jest.resetModules();
+    const { encryptSecret, decryptSecret } = require('../../src/libs/secrets');
+    const ct = encryptSecret('stripe-secret');
+    expect(decryptSecret(ct)).toBe('stripe-secret');
+  });
+
+  it('multi mode: inside withTenant, the facade resolves and uses that tenant', async () => {
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    jest.resetModules();
+    const { withTenant } = require('../../src/libs/context');
+    const { setSecretsDriver, createKeyringSecretsDriver } = require('../../src/libs/drivers');
+    const { encryptSecret, decryptSecret, warmupSecrets } = require('../../src/libs/secrets');
+    const identity = {
+      resolveInstanceDidForHost: () => null,
+      getAppEk: (did: string) => `ek-${did}`,
+    };
+    setSecretsDriver(createKeyringSecretsDriver(identity));
+    await withTenant('did:abt:zFACADE_A', async () => {
+      await warmupSecrets(); // warm current tenant for the sync hot path
+      const ct = encryptSecret('per-tenant');
+      expect(decryptSecret(ct)).toBe('per-tenant');
+    });
+  });
+});

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

package/api/tests/libs/tenancy-slot-authority.spec.ts

@@ -0,0 +1,209 @@
+// D1 (S3.0) — TenancySlot is the authoritative source for PAYMENT_TENANT_MODE.
+//
+// The factory derives effectiveConfig.PAYMENT_TENANT_MODE from slots.tenancy.mode
+// (so getTenantMode(), which reads the libs/env config boundary, sees the slot
+// mode without any env). A config PAYMENT_TENANT_MODE that disagrees with the
+// slot is a fail-fast. Intending multi must never silently degrade to single:
+// the default identity/secrets drivers ARE single-tenant behaviors, so a
+// multi-mode host that omits them fails closed. The legacy single path (no
+// tenancy slot + BLOCKLET_APP_PID) stays valid.
+
+import { Sequelize } from 'sequelize';
+import { setCoreConfig, getCoreConfig, readConfig } from '../../src/libs/env';
+import { getTenantMode, setDefaultInstanceDid } from '../../src/libs/tenant';
+import {
+  createDefaultIdentityDriver,
+  setIdentityDriver,
+  createDefaultSecretsDriver,
+  setSecretsDriver,
+} from '../../src/libs/drivers';
+import { createEmbeddedPaymentService, PaymentCoreSlotError, TenancySlotError } from '../../src/service';
+
+const ORIG_MODE = process.env.PAYMENT_TENANT_MODE;
+const ORIG_PID = process.env.BLOCKLET_APP_PID;
+
+// minimal slot stubs — only presence matters for D1 (the factory wires them,
+// it does not exercise their methods at construction time).
+const identityStub = { resolveInstanceDidForHost: () => null } as any;
+const secretsStub = createDefaultSecretsDriver();
+// a real in-memory sqlite sequelize: the factory's initialize() defines models
+// on it (no queries at construction), so it must be a genuine Sequelize, not a
+// stub. The data-damage/bad-input cases throw BEFORE initialize() so they never
+// touch it, but the happy/leak cases run the factory to completion.
+const db = { sequelize: new Sequelize({ dialect: 'sqlite', storage: ':memory:', logging: false }) as any };
+
+afterEach(() => {
+  setCoreConfig(undefined);
+  setDefaultInstanceDid(undefined);
+  // restore module-level driver singletons to their defaults so the multi
+  // tests do not leak an injected identity/secrets driver into later specs.
+  setIdentityDriver(createDefaultIdentityDriver());
+  setSecretsDriver(createDefaultSecretsDriver());
+  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('D1 — happy path: tenancy slot drives getTenantMode without env', () => {
+  it('tenancy.mode=multi makes getTenantMode() === "multi" with no env', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    createEmbeddedPaymentService({
+      config: {},
+      db,
+      tenancy: { mode: 'multi' },
+      identity: identityStub,
+      secrets: secretsStub,
+    });
+    expect(getTenantMode()).toBe('multi');
+  });
+
+  it('tenancy.mode=single makes getTenantMode() === "single" with no env', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    createEmbeddedPaymentService({
+      config: {},
+      db,
+      tenancy: { mode: 'single', instanceDid: 'did:abt:zSINGLEAPP' },
+    });
+    expect(getTenantMode()).toBe('single');
+  });
+});
+
+describe('D1 — bad input: invalid tenancy.mode fails fast', () => {
+  it('an unknown tenancy.mode throws at construction with the legal enum in the message', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    let thrown: any;
+    try {
+      createEmbeddedPaymentService({
+        config: {},
+        db,
+        tenancy: { mode: 'foo' } as any,
+      });
+      throw new Error('expected a TenancySlotError');
+    } catch (err: any) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(TenancySlotError);
+    expect(thrown.message).toMatch(/single/);
+    expect(thrown.message).toMatch(/multi/);
+    // fail-fast: it did not silently write a mode into the config boundary
+    expect(getCoreConfig()).toBeUndefined();
+  });
+});
+
+describe('D1 — security: intending multi never silently degrades to single', () => {
+  it('multi mode without an identity slot fails closed', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    expect(() =>
+      createEmbeddedPaymentService({
+        config: {},
+        db,
+        tenancy: { mode: 'multi' },
+        secrets: secretsStub,
+        // identity omitted
+      })
+    ).toThrow(PaymentCoreSlotError);
+  });
+
+  it('multi mode without a secrets slot fails closed', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    expect(() =>
+      createEmbeddedPaymentService({
+        config: {},
+        db,
+        tenancy: { mode: 'multi' },
+        identity: identityStub,
+        // secrets omitted
+      })
+    ).toThrow(PaymentCoreSlotError);
+  });
+
+  it('multi mode with both slots does NOT fall back to single', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    createEmbeddedPaymentService({
+      config: {},
+      db,
+      tenancy: { mode: 'multi' },
+      identity: identityStub,
+      secrets: secretsStub,
+    });
+    expect(getTenantMode()).toBe('multi');
+    expect(getTenantMode()).not.toBe('single');
+  });
+});
+
+describe('D1 — data loss surrogate: legacy single compat preserved', () => {
+  it('no tenancy slot + BLOCKLET_APP_PID present resolves as a valid single deployment', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    process.env.BLOCKLET_APP_PID = 'did:abt:zLEGACYAPP';
+    expect(() =>
+      createEmbeddedPaymentService({
+        config: { BLOCKLET_APP_PID: 'did:abt:zLEGACYAPP' },
+        db,
+      })
+    ).not.toThrow();
+    expect(getTenantMode()).toBe('single');
+  });
+});
+
+describe('D1 — data damage: config<->slot conflict fails fast with no half config', () => {
+  it('config.PAYMENT_TENANT_MODE that disagrees with tenancy.mode throws and writes nothing', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    let thrown: any;
+    try {
+      createEmbeddedPaymentService({
+        config: { PAYMENT_TENANT_MODE: 'single' },
+        db,
+        tenancy: { mode: 'multi' },
+        identity: identityStub,
+        secrets: secretsStub,
+      });
+      throw new Error('expected a TenancySlotError');
+    } catch (err: any) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(TenancySlotError);
+    // no mode was written into the config boundary (setCoreConfig never ran)
+    expect(getCoreConfig()).toBeUndefined();
+  });
+
+  it('a config that AGREES with the slot is accepted (no false conflict)', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    createEmbeddedPaymentService({
+      config: { PAYMENT_TENANT_MODE: 'multi' },
+      db,
+      tenancy: { mode: 'multi' },
+      identity: identityStub,
+      secrets: secretsStub,
+    });
+    expect(getTenantMode()).toBe('multi');
+  });
+});
+
+describe('D1 — data leak surrogate: mode has a single source (the config boundary)', () => {
+  it('setDefaultInstanceDid does not flip the resolved tenant mode', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    createEmbeddedPaymentService({
+      config: {},
+      db,
+      tenancy: { mode: 'multi' },
+      identity: identityStub,
+      secrets: secretsStub,
+    });
+    expect(getTenantMode()).toBe('multi');
+    setDefaultInstanceDid('did:abt:zSOMEONE'); // the only other tenancy setter
+    expect(getTenantMode()).toBe('multi'); // mode is unaffected — config is the one source
+  });
+
+  it('effectiveConfig carries the slot mode through the readConfig boundary', () => {
+    delete process.env.PAYMENT_TENANT_MODE;
+    createEmbeddedPaymentService({
+      config: {},
+      db,
+      tenancy: { mode: 'multi' },
+      identity: identityStub,
+      secrets: secretsStub,
+    });
+    expect(readConfig('PAYMENT_TENANT_MODE')).toBe('multi');
+  });
+});

package/api/tests/libs/tenant-middleware.spec.ts

@@ -0,0 +1,42 @@
+// Phase 10 (W2-2): libs/tenant default-tenant + row-tenant resolution.
+//
+// The HTTP-driven tenant-middleware scenarios (single mode, multi-mode Host→tenant,
+// fail-closed, X-Forwarded-Host security, malformed Host) moved to the hono
+// middlewares/hono/context.spec.ts when the express contextMiddleware was deleted
+// (express→hono Phase 4). What remains here is the framework-agnostic libs/tenant
+// unit coverage that has no HTTP surface.
+import { getDefaultInstanceDid, setDefaultInstanceDid, resolveRowTenant } from '../../src/libs/tenant';
+
+const ORIGINAL_MODE = process.env.PAYMENT_TENANT_MODE;
+
+// Data damage — the single-mode tenancy slot value drives the default tenant, and
+// pre-backfill (null instance_did) rows resolve to it (upgrade path intact).
+describe('single-mode tenancy slot value (no "tenant swap" on upgrade)', () => {
+  const ORIG = (() => {
+    const saved = process.env.PAYMENT_TENANT_MODE;
+    process.env.PAYMENT_TENANT_MODE = 'single';
+    const v = getDefaultInstanceDid();
+    if (saved === undefined) delete process.env.PAYMENT_TENANT_MODE;
+    else process.env.PAYMENT_TENANT_MODE = saved;
+    return v;
+  })();
+
+  beforeEach(() => {
+    process.env.PAYMENT_TENANT_MODE = 'single';
+  });
+  afterEach(() => {
+    setDefaultInstanceDid(ORIG); // restore to the env-derived default
+    if (ORIGINAL_MODE === undefined) delete process.env.PAYMENT_TENANT_MODE;
+    else process.env.PAYMENT_TENANT_MODE = ORIGINAL_MODE;
+  });
+
+  it('the configured instanceDid becomes the default tenant and old null rows map to it', () => {
+    setDefaultInstanceDid('did:abt:zCONFIGURED');
+    expect(getDefaultInstanceDid()).toBe('did:abt:zCONFIGURED');
+    // a pre-backfill row (instance_did = null) resolves to the configured default,
+    // not some other tenant — old data stays visible, no corruption
+    expect(resolveRowTenant({ instance_did: null })).toBe('did:abt:zCONFIGURED');
+    // a row that already carries a tenant is unaffected
+    expect(resolveRowTenant({ instance_did: 'did:abt:zEXISTING' })).toBe('did:abt:zEXISTING');
+  });
+});