payment-kit 1.29.1 → 1.29.2

package/api/tests/queues/tenant-matrix-b.spec.ts

@@ -0,0 +1,168 @@
+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 { systemFindByPk } from '../../src/store/scoped';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+jest.mock('../../src/libs/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+}));
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tenant-matrix-b-'));
+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 models: any;
+let createQueue: any;
+let assertJobObjectTenant: any;
+
+beforeAll(async () => {
+  await umzug.up();
+  // eslint-disable-next-line global-require
+  models = require('../../src/store/models');
+  models.initialize(sequelize);
+  // eslint-disable-next-line global-require
+  const queueModule = require('../../src/libs/queue');
+  createQueue = queueModule.default;
+  assertJobObjectTenant = queueModule.assertJobObjectTenant;
+}, 120000);
+
+afterAll(async () => {
+  await sequelize.close();
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const waitFor = (emitter: any, events: string[]): Promise<{ event: string; data: any }> =>
+  new Promise((resolve) => {
+    for (const event of events) {
+      emitter.on(event, (data: any) => resolve({ event, data }));
+    }
+  });
+
+describe('queue tenant layer — remaining queues (phase 6)', () => {
+  beforeEach(async () => {
+    await sequelize.query('DELETE FROM coupons');
+    await sequelize.query('DELETE FROM jobs');
+  });
+
+  describe('happy path + data damage: phase 6 object-bound handler pattern', () => {
+    it('a coupon-bound job (discount-status shape) executes only for its own tenant', async () => {
+      const coupon = await withTenant(TENANT_B, () =>
+        models.Coupon.create({
+          livemode: false,
+          instance_did: TENANT_B,
+          name: 'b-coupon',
+          duration: 'once',
+          valid: true,
+          created_via: 'api',
+          percent_off: 10,
+        })
+      );
+
+      const executed: string[] = [];
+      const queue = createQueue({
+        name: `tmb-coupon-${Date.now()}`,
+        onJob: async (job: any) => {
+          // load cross-tenant (system) then enforce — mirrors real handlers
+          const row: any = await systemFindByPk(models.Coupon, job.id);
+          assertJobObjectTenant(row);
+          executed.push(row.id);
+        },
+      });
+
+      // same tenant: executes
+      const ok = await withTenant(TENANT_B, async () => queue.push({ job: { id: coupon.id }, persist: true }));
+      const okOutcome = await waitFor(ok, ['finished', 'failed']);
+      expect(okOutcome.event).toBe('finished');
+      expect(executed).toEqual([coupon.id]);
+
+      // forged tenant: refused
+      const forged = await withTenant(TENANT_A, async () =>
+        queue.push({ job: { id: coupon.id }, id: `forged-${coupon.id}`, persist: true })
+      );
+      const forgedOutcome = await waitFor(forged, ['finished', 'failed']);
+      expect(forgedOutcome.event).toBe('failed');
+      expect((forgedOutcome.data as any).error?.code).toBe(TENANT_MISMATCH);
+      expect(executed).toHaveLength(1);
+    });
+  });
+
+  describe('data loss: in-flight legacy jobs across an upgrade window', () => {
+    it('single mode consumes a pre-tenant job normally (default tenant)', async () => {
+      const seen: string[] = [];
+      const queue = createQueue({
+        name: `tmb-legacy-${Date.now()}`,
+        onJob: async () => {
+          // eslint-disable-next-line global-require
+          const { getInstanceDid } = require('../../src/libs/context');
+          seen.push(getInstanceDid());
+        },
+      });
+      await queue.store.addJob('legacy-b-1', { anything: true }, {});
+      const row = await queue.get('legacy-b-1');
+      const handle = queue.push({
+        job: row,
+        id: 'legacy-b-1',
+        persist: false,
+        skipDuplicateCheck: true,
+        fromStore: true,
+      });
+      const outcome = await waitFor(handle, ['finished', 'failed']);
+      expect(outcome.event).toBe('finished');
+      // eslint-disable-next-line global-require
+      const { getDefaultInstanceDid } = require('../../src/libs/tenant');
+      expect(seen).toEqual([getDefaultInstanceDid()]);
+    });
+  });
+
+  describe('data leak: multi mode never falls back to a default tenant', () => {
+    it('a legacy job is refused with a structured non-retryable error and never executes', async () => {
+      const executed: any[] = [];
+      const queue = createQueue({
+        name: `tmb-legacy-multi-${Date.now()}`,
+        onJob: async (job: any) => {
+          executed.push(job);
+        },
+      });
+      process.env.PAYMENT_TENANT_MODE = 'multi';
+      try {
+        const handle = queue.push({
+          job: { anything: true },
+          id: 'legacy-multi-b',
+          persist: false,
+          fromStore: true,
+        });
+        const outcome = await waitFor(handle, ['finished', 'failed']);
+        expect(outcome.event).toBe('failed');
+        expect((outcome.data as any).error?.code).toBe(TENANT_CONTEXT_MISSING);
+        expect((outcome.data as any).error?.nonRetryable).toBe(true);
+        expect(executed).toHaveLength(0);
+      } finally {
+        delete process.env.PAYMENT_TENANT_MODE;
+      }
+    });
+  });
+});

package/api/tests/routes/connect/hono-attach.spec.ts

@@ -0,0 +1,107 @@
+// Phase 2 (express→hono) — DID-Connect surface migration. Proves the SAME
+// @blocklet/sdk WalletHandlers attach to a hono app via did-connect-js v4 native
+// attachHono (isHonoApp dispatch, design §3.3): all routes register and a request
+// is dispatched to the generateSession handler over app.fetch. The 14 handlers
+// are unchanged (framework-agnostic CallbackArgs); only the app type changes.
+//
+// NOTE: the session-DEPENDENT spec-table categories (Security ensureSignedJson,
+// Data-loss deep-link, Data-damage appInfo, Data-leak token isolation) and the
+// happy-path session SHAPE are validated over a REAL socket in
+// scripts/e2e-hono-s2.ts (10 self-validating checks, logs/s2-e2e.log). They
+// cannot run in jest: generateSession needs a valid appInfo.icon URI, which jest's
+// bare blocklet env does not provide (the SDK authenticator rejects it). The E2E
+// uses the spike's testSetup env (parsed blocklet.yml → valid appInfo).
+import { buildConnectRoutesHono } from '../../../src/service';
+
+const PREFIX = '/api/did';
+// a representative subset of the 14 actions
+const ACTIONS = ['collect', 'payment', 'subscription'];
+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',
+];
+
+let connectApp: ReturnType<typeof buildConnectRoutesHono>;
+
+beforeAll(() => {
+  connectApp = buildConnectRoutesHono();
+});
+
+const registeredPaths = (): Set<string> => new Set(((connectApp as any).routes || []).map((r: any) => r.path));
+
+describe('Phase 2 — attachHono route registration (all 14 handlers)', () => {
+  it('registers token/status/timeout/auth/auth-submit for each action', () => {
+    const paths = registeredPaths();
+    for (const action of ACTIONS) {
+      for (const sub of ['token', 'status', 'timeout', 'auth', 'auth/submit']) {
+        expect(paths.has(`${PREFIX}/${action}/${sub}`)).toBe(true);
+      }
+    }
+  });
+
+  it('registers the full route set (token/status/timeout/auth/auth-submit) for ALL 14 actions', () => {
+    const paths = registeredPaths();
+    expect(ALL_ACTIONS.length).toBe(14);
+    for (const action of ALL_ACTIONS) {
+      for (const sub of ['token', 'status', 'timeout', 'auth', 'auth/submit']) {
+        expect(paths.has(`${PREFIX}/${action}/${sub}`)).toBe(true);
+      }
+    }
+  });
+
+  it('a POST to /auth is registered (the signed authInfo endpoint) and dispatched to the handler', async () => {
+    const paths = registeredPaths();
+    expect(paths.has(`${PREFIX}/payment/auth`)).toBe(true); // POST exists too
+    // an unsigned POST with a forged token reaches the handler (500/4xx, never a
+    // hono 404) — proving attachHono wired the POST body adapter; the actual
+    // ensureSignedJson rejection on a VALID session is in the E2E.
+    const res = await connectApp.fetch(
+      new Request(`http://app.local${PREFIX}/payment/auth?_t_=deadbeef`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ userDid: 'did:abt:zForged', claims: [] }),
+      })
+    );
+    expect(res.status).not.toBe(404);
+    const body = await res.text();
+    expect(body).not.toContain('"status":"created"'); // never resolves a session for a forged token
+  });
+});
+
+describe('Phase 2 — attachHono dispatches GET .../token to the handler (over app.fetch)', () => {
+  it('reaches the generateSession handler (200 JSON), not a hono 404', async () => {
+    // The full successful session (valid appInfo) is validated over a real socket
+    // in scripts/e2e-hono-s2.ts (a valid appInfo.icon URI is an env detail jest's
+    // bare blocklet env lacks). Here we prove attachHono ROUTED the request to the
+    // did-connect handler: a 200 JSON response, never hono's 404 Not Found.
+    const res = await connectApp.fetch(new Request(`http://app.local${PREFIX}/collect/token`));
+    expect(res.status).toBe(200);
+    const body = await res.json(); // handler output is JSON (session OR a did-connect error)
+    expect(typeof body).toBe('object');
+  });
+});
+
+describe('Phase 2 — bad input: an invalid/forged session token does not resolve', () => {
+  it('GET .../payment/auth with a non-existent _t_ does not return a valid authInfo/session', async () => {
+    const res = await connectApp.fetch(
+      new Request(`http://app.local${PREFIX}/payment/auth?_t_=deadbeef-not-a-session`)
+    );
+    // attachHono surfaces the did-connect error path (4xx or an error-status body),
+    // never a created session for a forged token.
+    const body = await res.json().catch(() => ({}));
+    const looksLikeValidSession = res.status === 200 && (body.status === 'created' || body.authInfo);
+    expect(looksLikeValidSession).toBe(false);
+  });
+});

package/api/tests/service/collapse.spec.ts

@@ -0,0 +1,96 @@
+// Phase 4 (express→hono) — adapter collapse.
+//
+// The loopback http.Server + express app shell are gone: svc.http.fetch is now a
+// thin base-strip wrapper over honoApp.fetch, and the full node app is the hono
+// app itself. This spec locks the two things the collapse must preserve byte-for-
+// byte (the arc consumer contract): the base-strip semantics and raw-body
+// fidelity through the strip, plus the hono app's healthz + onError.
+import { Hono } from 'hono';
+import crypto from 'crypto';
+import { createFetchHandler } from '../../src/libs/http-fetch-adapter';
+import { buildHonoApp } from '../../src/service';
+
+// A stand-in "core" hono app: echoes the internal path + the raw body bytes so we
+// can assert exactly what the adapter forwarded after base-stripping.
+function buildEchoApp(): Hono {
+  const app = new Hono();
+  app.get('/api/echo', (c) => c.json({ path: new URL(c.req.url).pathname }));
+  app.post('/api/raw', async (c) => {
+    const buf = Buffer.from(await c.req.arrayBuffer());
+    return c.json({ len: buf.length, sig: crypto.createHmac('sha256', 'k').update(buf).digest('hex') });
+  });
+  return app;
+}
+
+describe('Phase 4 collapse — svc.http.fetch base-strip over app.fetch', () => {
+  const handler = createFetchHandler(buildEchoApp());
+
+  it('happy: strips the host mount prefix to reach the internal /api/*', async () => {
+    const res = await handler(new Request('http://app.local/.well-known/payment/api/echo'), {
+      basePath: '/.well-known/payment',
+    });
+    expect(res.status).toBe(200);
+    expect((await res.json()).path).toBe('/api/echo');
+  });
+
+  it('happy: no basePath → request passes through unchanged', async () => {
+    const res = await handler(new Request('http://app.local/api/echo'));
+    expect((await res.json()).path).toBe('/api/echo');
+  });
+
+  it('bad input: exact segment-boundary strip — basePath itself maps to "/"', async () => {
+    // /.well-known/payment (=== basePath) → "/", which the echo app 404s; the
+    // point is the strip is applied (not left as the prefix).
+    const res = await handler(new Request('http://app.local/.well-known/payment'), {
+      basePath: '/.well-known/payment',
+    });
+    expect(res.status).toBe(404); // "/" has no route — strip happened, didn't match
+  });
+
+  it('bad input: segment-boundary negative — "/mntbeta" is NOT stripped by basePath "/mnt"', async () => {
+    // a naive startsWith would wrongly strip "/mnt" from "/mntbeta/..."; the precise
+    // === / "+ /" check must leave it intact (→ /mntbeta/api/echo, 404).
+    const res = await handler(new Request('http://app.local/mntbeta/api/echo'), { basePath: '/mnt' });
+    expect(res.status).toBe(404);
+    // the correctly-prefixed twin strips to /api/echo and resolves
+    const ok = await handler(new Request('http://app.local/mnt/api/echo'), { basePath: '/mnt' });
+    expect(ok.status).toBe(200);
+    expect((await ok.json()).path).toBe('/api/echo');
+  });
+
+  it('security/data loss: raw body bytes survive the strip intact (Stripe webhook fidelity)', async () => {
+    const payload = JSON.stringify({ evt: 'x', nested: { a: 1, b: '<b>' } });
+    const res = await handler(
+      new Request('http://app.local/.well-known/payment/api/raw', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: payload,
+      }),
+      { basePath: '/.well-known/payment' }
+    );
+    const body = await res.json();
+    expect(body.len).toBe(Buffer.byteLength(payload)); // every byte forwarded
+    expect(body.sig).toBe(crypto.createHmac('sha256', 'k').update(payload).digest('hex'));
+  });
+});
+
+describe('Phase 4 collapse — buildHonoApp surface', () => {
+  const app = buildHonoApp();
+
+  it('serves /api/healthz natively (was on the express resource router)', async () => {
+    const res = await app.fetch(new Request('http://app.local/api/healthz'));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it('onError maps a thrown error to 500 JSON (express-async-errors equivalent)', async () => {
+    const a = buildHonoApp((native) => {
+      native.get('/api/boom', () => {
+        throw new Error('kaboom');
+      });
+    });
+    const res = await a.fetch(new Request('http://app.local/api/boom'));
+    expect(res.status).toBe(500);
+    expect((await res.json()).error).toBe('kaboom');
+  });
+});

package/api/tests/store/tenant-crosscut.spec.ts

@@ -0,0 +1,202 @@
+// Phase 6 (W1′) — cross-cutting tenant isolation CI (two engines, blocking).
+//
+// Not per-route: assert the SAME read-isolation invariant over the WHOLE tenant
+// model surface generically, on BOTH engines:
+//   - real Sequelize (Node): every one of the 38 tenant models — a bare
+//     findAll returns only the active tenant's rows, and a cross-tenant
+//     findByPk returns null (§13.1). Rows are seeded with a raw INSERT (driven
+//     by PRAGMA table_info) so the crosscut is model-agnostic — it exercises
+//     the scoping, not each model's business validators/hooks.
+//   - sequelize-d1 shim (worker): the same invariant on the shim base.
+//   - index hit: a WHERE instance_did = ? equality predicate uses the
+//     idx_<table>_instance_did index (SEARCH), not a full SCAN.
+import { DatabaseSync } from 'node:sqlite';
+import { DataTypes, Sequelize } from 'sequelize';
+
+import { getDefaultInstanceDid, withTenant } from '../../src/libs/context';
+import { makeTenantModel } from '../../src/store/tenant-model';
+import realModels, { Coupon, initialize } from '../../src/store/models';
+import { TENANT_TABLES } from '../../src/store/tenant-tables';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+const TENANT_TABLE_SET = new Set(TENANT_TABLES);
+const sequelize = new Sequelize('sqlite::memory:', { logging: false });
+initialize(sequelize);
+
+beforeAll(async () => {
+  await sequelize.sync({ force: true });
+  // raw seeding uses dummy FK values; this test exercises tenant scoping, not
+  // referential integrity, so disable FK enforcement for the inserts.
+  await sequelize.query('PRAGMA foreign_keys = OFF');
+});
+afterAll(() => sequelize.close());
+
+function dummyForSqlType(type: string, seed: string): string | number {
+  const t = (type || '').toUpperCase();
+  if (/INT/.test(t)) return 0;
+  if (/REAL|FLOA|DOUB|DEC|NUM/.test(t)) return 0;
+  if (/BOOL|TINYINT/.test(t)) return 0;
+  if (/DATE|TIME/.test(t)) return '2024-01-01 00:00:00.000 +00:00';
+  if (/JSON/.test(t)) return '{}';
+  // unique per row+column so a standalone UNIQUE column can't collide across the
+  // two tenant rows we insert.
+  return seed;
+}
+
+// raw-insert one row for `tenant` into `table`. Returns the value of the
+// single-column `id` PK (null when the table has a composite PK — those skip
+// the findByPk assertion and rely on findAll isolation).
+async function seedRaw(table: string, tenant: string, idVal: string): Promise<string | null> {
+  const cols = (await sequelize.query(`PRAGMA table_info("${table}")`, {
+    type: (DataTypes as any).SELECT ?? 'SELECT',
+  })) as any[];
+  const pkCols = cols.filter((c) => c.pk).map((c) => c.name);
+  const values: Record<string, any> = { instance_did: tenant };
+  for (const c of cols) {
+    if (c.name === 'instance_did') continue;
+    const required = c.notnull === 1 && c.dflt_value === null;
+    if (c.pk) values[c.name] = idVal;
+    else if (required) values[c.name] = dummyForSqlType(c.type, `${idVal}-${c.name}`);
+  }
+  const names = Object.keys(values);
+  await sequelize.query(
+    `INSERT INTO "${table}" (${names.map((n) => `"${n}"`).join(',')}) VALUES (${names.map((n) => `:${n}`).join(',')})`,
+    { replacements: values }
+  );
+  return pkCols.length === 1 && pkCols[0] === 'id' ? idVal : null;
+}
+
+const tenantModels = Object.values<any>(realModels).filter((m) => TENANT_TABLE_SET.has(m.tableName));
+
+describe('cross-cut read isolation over all tenant models (real Sequelize)', () => {
+  it('covers all 38 tenant tables', () => {
+    expect(tenantModels.length).toBe(38);
+  });
+
+  it.each(tenantModels.map((m) => [m.tableName, m]))(
+    '%s: bare findAll returns only active tenant rows; cross-tenant findByPk -> null',
+    async (table: string, Model: any) => {
+      const idA = await seedRaw(table, TENANT_A, `a-${table}`);
+      const idB = await seedRaw(table, TENANT_B, `b-${table}`);
+
+      // bare findAll under A returns ONLY A's rows — no B row leaks
+      const aRows: any[] = await withTenant(TENANT_A, () => Model.findAll());
+      expect(aRows.length).toBeGreaterThan(0);
+      expect(aRows.every((r) => r.instance_did === TENANT_A)).toBe(true);
+
+      // cross-tenant findByPk -> null (not-found, §13.1); same-tenant works.
+      // composite-PK tables (idA/idB null) rely on the findAll isolation above.
+      if (idA && idB) {
+        expect(await withTenant(TENANT_A, () => Model.findByPk(idB))).toBeNull();
+        expect(await withTenant(TENANT_A, () => Model.findByPk(idA))).not.toBeNull();
+      }
+    }
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Second engine: the sequelize-d1 shim (worker runtime) over a node:sqlite fake
+// D1 — the SAME makeTenantModel mechanism on the OTHER base class.
+// ---------------------------------------------------------------------------
+function makeFakeD1(db: DatabaseSync) {
+  const prepare = (sql: string) => {
+    let bound: any[] = [];
+    const stmt: any = {
+      __sql: sql,
+      bind: (...vals: any[]) => {
+        bound = vals;
+        return stmt;
+      },
+      all: () => ({ results: db.prepare(sql).all(...bound), meta: {} }),
+      run: () => {
+        const r = db.prepare(sql).run(...bound);
+        return { meta: { changes: Number(r.changes), last_row_id: Number(r.lastInsertRowid) } };
+      },
+      first: () => db.prepare(sql).get(...bound) ?? null,
+    };
+    return stmt;
+  };
+  return {
+    prepare,
+    batch: async (stmts: any[]) =>
+      stmts.map((s) => {
+        if (/^\s*SELECT/i.test(s.__sql)) return s.all();
+        s.run();
+        return { results: [], meta: {} };
+      }),
+  };
+}
+
+describe('cross-cut read isolation on the sequelize-d1 shim engine', () => {
+  let ShimWidget: any;
+  const TABLE = 'coupons'; // a real tenant table so isTenantTable() is true and the shim scopes
+
+  beforeAll(() => {
+    // eslint-disable-next-line global-require, import/no-dynamic-require, @typescript-eslint/no-var-requires
+    const shim = require('../../../cloudflare/shims/sequelize-d1');
+    const db = new DatabaseSync(':memory:');
+    db.exec(`CREATE TABLE ${TABLE} (id TEXT PRIMARY KEY, instance_did TEXT, name TEXT)`);
+    shim.setDB(makeFakeD1(db));
+    ShimWidget = class extends makeTenantModel(shim.Model) {};
+    ShimWidget.init(
+      { id: {}, instance_did: {}, name: {} },
+      { sequelize: { models: {} }, modelName: 'CrosscutWidget', tableName: TABLE }
+    );
+  });
+
+  it('shim: bare findAll returns only active tenant; cross-tenant findByPk -> null', async () => {
+    await withTenant(TENANT_A, () => ShimWidget.create({ id: 'a1', name: 'a' }));
+    await withTenant(TENANT_B, () => ShimWidget.create({ id: 'b1', name: 'b' }));
+
+    const aRows: any[] = await withTenant(TENANT_A, () => ShimWidget.findAll());
+    expect(aRows.map((r) => r.id)).toEqual(['a1']);
+    expect(aRows.every((r) => r.instance_did === TENANT_A)).toBe(true);
+
+    expect(await withTenant(TENANT_A, () => ShimWidget.findByPk('b1'))).toBeNull();
+    expect(await withTenant(TENANT_A, () => ShimWidget.findByPk('a1'))).not.toBeNull();
+  });
+});
+
+describe('single mode is NOT a passthrough — it injects instance_did = APP_PID', () => {
+  // The single-tenant blocklet-server safety rope: single mode does not "let
+  // bare queries through because there is only one tenant" — it scopes every
+  // query to the default tenant (BLOCKLET_APP_PID). A row stamped with a
+  // DIFFERENT instance_did must NOT be visible in single mode.
+  it('single-mode bare findAll only returns default-tenant rows, not a foreign-stamped row', async () => {
+    const savedMode = process.env.PAYMENT_TENANT_MODE;
+    process.env.PAYMENT_TENANT_MODE = 'single';
+    try {
+      const appPid = getDefaultInstanceDid(); // BLOCKLET_APP_PID in the test env
+      expect(appPid).toBeTruthy();
+      await sequelize.query('DELETE FROM coupons');
+      // one row in the default tenant, one foreign-stamped row (raw, bypassing stamp)
+      await sequelize.query(
+        `INSERT INTO coupons (id, instance_did, livemode, duration, name, created_via, created_at, updated_at)
+         VALUES ('own', :pid, 0, 'once', 'own', 'api', :ts, :ts), ('foreign', :other, 0, 'once', 'foreign', 'api', :ts, :ts)`,
+        { replacements: { pid: appPid, other: TENANT_B, ts: '2024-01-01 00:00:00.000 +00:00' } }
+      );
+      // no withTenant -> single mode default fill = APP_PID, NOT a passthrough
+      const rows: any[] = await Coupon.findAll();
+      expect(rows.map((r) => r.id)).toEqual(['own']);
+      expect(await Coupon.findByPk('foreign')).toBeNull();
+    } finally {
+      if (savedMode === undefined) delete process.env.PAYMENT_TENANT_MODE;
+      else process.env.PAYMENT_TENANT_MODE = savedMode;
+    }
+  });
+});
+
+describe('index hit: instance_did equality uses an index, not a full scan', () => {
+  it('EXPLAIN QUERY PLAN on WHERE instance_did = ? uses the idx_<table>_instance_did index', async () => {
+    // sync() does not create the migration index; create it as the Phase 2
+    // backfill migration does (idx_<table>_instance_did) and prove it is used.
+    await sequelize.query('CREATE INDEX IF NOT EXISTS idx_subscriptions_instance_did ON subscriptions(instance_did)');
+    const plan = (await sequelize.query('EXPLAIN QUERY PLAN SELECT * FROM subscriptions WHERE instance_did = :did', {
+      replacements: { did: TENANT_A },
+      type: (DataTypes as any).SELECT ?? 'SELECT',
+    })) as any[];
+    const text = JSON.stringify(plan);
+    expect(text).toMatch(/USING (COVERING )?INDEX idx_subscriptions_instance_did/);
+    expect(text).not.toMatch(/SCAN subscriptions(?! USING)/);
+  });
+});