payment-kit 1.29.1 → 1.29.3

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/embedded/embedded-multi-mode-d3.spec.ts

@@ -0,0 +1,257 @@
+// D3 (S3.0) — embedded multi-mode background harness. Builds a REAL embedded
+// payment service (createEmbeddedPaymentService) over a file-backed sqlite with
+// the full 46-table schema (applyPaymentCoreMigrations) and tenancy:{mode:'multi'}
+// + every slot, then exercises the background engine the way an arc-node host
+// drives it: queue retry, delayed-job restart recovery, cross-tenant isolation,
+// and slot-misconfig fail-closed.
+//
+// The engine-level retry/dispatch parity lives in queue-runtime-surface.spec;
+// this harness proves the SAME behavior holds through the assembled multi-mode
+// service (models bound by the factory, tenant carried in the payload).
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+
+import { withTenant, getInstanceDid } from '../../src/libs/context';
+import { createNodeDbDriver } from '../../src/libs/drivers/db';
+import {
+  applyPaymentCoreMigrations,
+  createMemoryLocksDriver,
+  createCronRegistry,
+  createKeyringSecretsDriver,
+  nodeQueueHostHooks,
+} from '../../src/libs/drivers';
+import { setQueueRuntimeMode, __test__ as runtimeTest } from '../../src/libs/queue/runtime';
+import { createEmbeddedPaymentService, PaymentCoreSlotError } from '../../src/service';
+
+jest.setTimeout(60000);
+
+jest.mock('../../src/libs/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+}));
+
+const TENANT_A = 'did:abt:zD3TENANTA';
+const TENANT_B = 'did:abt:zD3TENANTB';
+const HOST_A = 'a.example.com';
+const HOST_B = 'b.example.com';
+
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'embedded-multi-d3-'));
+const dbFile = path.join(dir, 'payment.db');
+const sequelize = new Sequelize({ dialect: 'sqlite', storage: dbFile, logging: false, pool: { max: 5 } });
+
+// multi-tenant identity: Host -> tenant, plus a per-tenant EK for the keyring.
+const identity = {
+  resolveInstanceDidForHost(host: string | undefined) {
+    if (host === HOST_A) return TENANT_A;
+    if (host === HOST_B) return TENANT_B;
+    return null; // unknown host fails closed at the resolver
+  },
+  getAppEk(instanceDid: string) {
+    // distinct per-tenant key material (hex) — the keyring isolates by this
+    return instanceDid === TENANT_A ? 'a'.repeat(64) : 'b'.repeat(64);
+  },
+};
+
+const baseSlots = () => ({
+  config: { BLOCKLET_APP_PID: TENANT_A, PAYMENT_LIVEMODE: 'true' },
+  db: { sequelize: sequelize as any },
+  tenancy: { mode: 'multi' as const },
+  identity,
+  secrets: createKeyringSecretsDriver(identity),
+  queue: nodeQueueHostHooks,
+  cron: createCronRegistry('node-cron'),
+  locks: createMemoryLocksDriver(),
+});
+
+let svc: ReturnType<typeof createEmbeddedPaymentService>;
+let createQueue: any;
+let createQueueStore: any;
+let tableCount = 0;
+
+const settle = (emitter: any): Promise<string> =>
+  new Promise((resolve) => {
+    ['finished', 'failed', 'cancelled'].forEach((e) => emitter.on(e, () => resolve(e)));
+  });
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+beforeAll(async () => {
+  // provision the full embedded schema (9 SQL migrations -> 46 tables)
+  const driver = createNodeDbDriver(sequelize);
+  await applyPaymentCoreMigrations(driver);
+  // canonical embedded-schema count (task 13 / D4): 46 tables INCLUDING the
+  // _sql_migrations tracker row table.
+  const rows = await driver.all<{ name: string }>(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"
+  );
+  tableCount = rows.length;
+
+  // assemble the multi-mode embedded service (binds models to OUR sequelize)
+  svc = createEmbeddedPaymentService(baseSlots());
+  setQueueRuntimeMode('node');
+  createQueue = require('../../src/libs/queue').default;
+  createQueueStore = require('../../src/libs/queue/store').default;
+}, 120000);
+
+afterAll(async () => {
+  // exercise the D2 lifecycle teardown contract (no-op here since we never
+  // called lifecycle.start(), but it must not throw and clears any driver state)
+  await svc.lifecycle.stop();
+  runtimeTest.reset();
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  runtimeTest.reset();
+  setQueueRuntimeMode('node');
+});
+
+describe('D3 happy path — multi service assembles + a job runs under its tenant', () => {
+  it('the embedded schema has 46 tables and the rpc surface is present', () => {
+    expect(tableCount).toBe(46);
+    expect(typeof svc.rpc.entitlements.check).toBe('function');
+    expect(typeof svc.rpc.meterEvents.report).toBe('function');
+  });
+
+  it('a job enqueued under tenant A executes under tenant A', async () => {
+    let observed = '';
+    const q = createQueue({
+      name: `d3-happy-${Date.now()}`,
+      onJob: async () => {
+        observed = getInstanceDid();
+      },
+    });
+    const ev = await withTenant(TENANT_A, async () => q.push({ job: { v: 1, instance_did: TENANT_A } }));
+    expect(await settle(ev)).toBe('finished');
+    expect(observed).toBe(TENANT_A);
+  });
+});
+
+describe('D3 bad input — slot misconfig fails closed (no silent single)', () => {
+  it('multi without a secrets slot throws PaymentCoreSlotError', () => {
+    const slots: any = baseSlots();
+    delete slots.secrets;
+    expect(() => createEmbeddedPaymentService(slots)).toThrow(PaymentCoreSlotError);
+  });
+
+  it('multi without an identity slot throws PaymentCoreSlotError', () => {
+    const slots: any = baseSlots();
+    delete slots.identity;
+    expect(() => createEmbeddedPaymentService(slots)).toThrow(PaymentCoreSlotError);
+  });
+
+  it('multi without cron/queue/locks still assembles (safe Node defaults, not a degrade)', () => {
+    // identity + secrets are the ONLY slots whose absence silently degrades to
+    // single-tenant (D1), so they fail closed. cron/queue/locks have correct
+    // Node defaults (node-cron registry, no-op flush, memory locks) for a
+    // single-process daemon, so their absence is NOT an error — it must not be
+    // conflated with the identity/secrets fail-closed case.
+    const slots: any = baseSlots();
+    delete slots.cron;
+    delete slots.queue;
+    delete slots.locks;
+    expect(() => createEmbeddedPaymentService(slots)).not.toThrow();
+  });
+});
+
+describe('D3 security — cross-tenant job object is fail-closed', () => {
+  it('a job whose loaded object tenant != payload tenant is rejected (structured)', async () => {
+    const { assertJobObjectTenant } = require('../../src/libs/queue');
+    let leaked = false;
+    let observed = '';
+    const q = createQueue({
+      name: `d3-xtenant-${Date.now()}`,
+      onJob: async () => {
+        observed = getInstanceDid();
+        // payload says A; an object loaded cross-tenant belongs to B
+        assertJobObjectTenant({ instance_did: TENANT_B });
+        leaked = true; // unreachable — assert throws first
+      },
+    });
+    const ev = await withTenant(TENANT_A, async () => q.push({ job: { tag: 'x', instance_did: TENANT_A } }));
+    expect(await settle(ev)).toBe('failed');
+    expect(observed).toBe(TENANT_A);
+    expect(leaked).toBe(false);
+  });
+});
+
+describe('D3 data loss — delayed/persisted job recovers on restart', () => {
+  it('a persisted row left by a prior queue is recovered + executed by a fresh queue (same id)', async () => {
+    const name = `d3-recover-${Date.now()}`;
+    const jobId = `recover-${Date.now()}`;
+    // simulate a prior process: a persisted immediate row sits in the store,
+    // never executed (no live queue ran it)
+    const store = createQueueStore(name);
+    await store.addJob(jobId, { v: 1, instance_did: TENANT_A }, {});
+
+    // "restart": a fresh queue with the same name boots and recovers the row.
+    // Capture the RECOVERED row's id from the runtime's finished event (the
+    // job payload carries no id, so this is the only faithful source — proving
+    // the recovered id is the original, not a freshly generated one).
+    let ranId = '';
+    let executions = 0;
+    const q = createQueue({
+      name,
+      onJob: async () => {
+        executions += 1;
+      },
+    });
+    q.on('finished', (data: { id: string }) => {
+      ranId = data.id;
+    });
+    // loadExisting runs on process.nextTick; give it room to recover + execute
+    await wait(400);
+    const remaining = await store.getJobs();
+    expect(ranId).toBe(jobId); // the RECOVERED row's id is the original (not regenerated)
+    expect(executions).toBe(1); // executed exactly once on recovery
+    expect(remaining.find((r: any) => r.id === jobId)).toBeUndefined(); // consumed, not duplicated
+  });
+});
+
+describe('D3 data damage — retry does not double-execute (idempotent)', () => {
+  it('a job that fails then succeeds runs its success side-effect exactly once', async () => {
+    let attempts = 0;
+    let successes = 0;
+    const q = createQueue({
+      name: `d3-retry-${Date.now()}`,
+      onJob: async () => {
+        attempts += 1;
+        if (attempts < 3) throw new Error('transient');
+        successes += 1; // only on the successful attempt
+      },
+      options: { maxRetries: 5, retryDelay: 1 },
+    });
+    const ev = await withTenant(TENANT_A, async () => q.push({ job: { v: 1, instance_did: TENANT_A } }));
+    expect(await settle(ev)).toBe('finished');
+    expect(attempts).toBe(3); // 2 failures + 1 success, no infinite loop
+    expect(successes).toBe(1); // side-effect exactly once, not per attempt
+  });
+});
+
+describe('D3 data leak — tenant A and tenant B background jobs do not bleed', () => {
+  it('A and B jobs each run strictly under their own tenant scope', async () => {
+    const seen: Record<string, string> = {};
+    const qa = createQueue({
+      name: `d3-leak-a-${Date.now()}`,
+      onJob: async () => {
+        seen.a = getInstanceDid();
+      },
+    });
+    const qb = createQueue({
+      name: `d3-leak-b-${Date.now()}`,
+      onJob: async () => {
+        seen.b = getInstanceDid();
+      },
+    });
+    const ea = await withTenant(TENANT_A, async () => qa.push({ job: { instance_did: TENANT_A } }));
+    const eb = await withTenant(TENANT_B, async () => qb.push({ job: { instance_did: TENANT_B } }));
+    expect(await settle(ea)).toBe('finished');
+    expect(await settle(eb)).toBe('finished');
+    expect(seen.a).toBe(TENANT_A);
+    expect(seen.b).toBe(TENANT_B);
+    expect(seen.a).not.toBe(seen.b); // no cross-tenant bleed
+  });
+});

package/api/tests/fixtures/bare-query-violation.ts

@@ -0,0 +1,13 @@
+// Deliberately violating fixture for the tenant query scanner self-test.
+// NOT part of the CI scan scope (api/tests is excluded); the scanner is
+// pointed at this file explicitly in scoped.spec.ts.
+//
+// W1′ Phase 5: a bare `Customer.findAll()` is now SAFE (Customer extends
+// TenantModel — auto-scoped), so the violation the scanner must catch is a raw
+// `.query(...)` on a tenant table with NO $instance_did bind (assertion ②).
+import { sequelize } from '../../src/store/sequelize';
+
+export function rawQueryViolation() {
+  // raw read on a tenant table (coupons) with no tenant bind — scanner flags it
+  return sequelize.query('SELECT * FROM coupons WHERE livemode = 1');
+}

package/api/tests/fixtures/core-env-violation.ts

@@ -0,0 +1,10 @@
+// Phase 12 (W2-4a) negative fixture — core code reading process.env / the CF env
+// mirror directly, which the core-env scanner must reject (config must flow
+// through the env/config boundary). Not in the CI scan scope; passed explicitly
+// to the scanner in tests to prove the rule fires.
+/* eslint-disable */
+export function badConfigRead() {
+  const a = process.env.SOME_SECRET; // VIOLATION: direct process.env read in core
+  const b = (globalThis as any).__CF_ENV__?.APP_URL; // VIOLATION: CF env mirror read
+  return { a, b };
+}

package/api/tests/fixtures/host-read-violation.ts

@@ -0,0 +1,19 @@
+// Phase 10 (W2-2) negative fixture — a route reading the Host directly, which
+// the tenant-scan rule must reject (tenant may only be resolved at the single
+// middleware point). Not part of the CI scan scope; passed explicitly to the
+// scanner in tests to prove the rule fires.
+/* eslint-disable */
+// Minimal req/res shapes — this is a STATIC-SCAN fixture (the tenant-query scanner
+// reads the source text for Host reads); the handlers are never executed, so the
+// express types are unnecessary (core is express-free post Phase 4).
+type AnyReq = { headers: Record<string, any>; hostname?: string };
+type AnyRes = { json: (body: any) => any };
+
+export function badHandlerA(req: AnyReq, res: AnyRes) {
+  const host = req.headers.host; // VIOLATION: host read outside the tenant middleware
+  res.json({ host });
+}
+
+export function badHandlerB(req: AnyReq, res: AnyRes) {
+  res.json({ h: req.hostname }); // VIOLATION: req.hostname read outside the tenant middleware
+}

package/api/tests/fixtures/tenants.ts

@@ -0,0 +1,4 @@
+// Two distinct tenant instanceDids used by all multi-tenant isolation tests.
+// Built on top of the Phase 0 test injection helper (`withTenant`).
+export const TENANT_A = 'did:abt:zTenantAAAAAAAAAAAAAAAAAAAAAAA';
+export const TENANT_B = 'did:abt:zTenantBBBBBBBBBBBBBBBBBBBBBBB';