payment-kit 1.29.1 → 1.29.3

package/api/tests/middlewares/hono/security.spec.ts

@@ -0,0 +1,181 @@
+// Phase 1 (express→hono) — hono authenticate() fork. Mirrors libs/security.ts.
+// contextMiddleware runs first to establish the tenant context (single mode →
+// default tenant), so the tenant-scoped Customer lookup in mine/record works.
+// DB harness (sqlite + umzug migrations + models.initialize) follows the
+// canonical pattern from api/tests/libs/audit-tenant.spec.ts.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+import { Hono } from 'hono';
+import { contextMiddleware } from '../../../src/middlewares/hono/context';
+import { authenticate } from '../../../src/middlewares/hono/security';
+import { getDefaultInstanceDid } from '../../../src/libs/tenant';
+import { withTenant } from '../../../src/libs/context';
+
+const STORE_DIR = path.join(__dirname, '../../../src/store');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hono-security-'));
+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 USER_DID = 'did:abt:zSecUserPhase1';
+const OTHER_DID = 'did:abt:zOtherUserPhase1';
+
+const asUser = (did: string, role = 'user', extra: Record<string, string> = {}) => ({
+  host: 'app.local',
+  'x-user-did': did,
+  'x-user-role': `blocklet-${role}`,
+  'x-user-provider': 'wallet',
+  'x-user-fullname': '',
+  'x-user-wallet-os': '',
+  ...extra,
+});
+
+const call = (app: Hono, p: string, headers: Record<string, string>) =>
+  app.fetch(new Request(`http://app.local${p}`, { headers }));
+
+afterEach(async () => {
+  await withTenant(getDefaultInstanceDid(), () =>
+    Customer.destroy({ where: { did: [USER_DID, OTHER_DID] }, force: true })
+  );
+});
+
+describe('hono authenticate — roles gate', () => {
+  function app() {
+    const a = new Hono();
+    a.use('*', contextMiddleware());
+    a.get('/api/admin', authenticate({ roles: ['owner', 'admin'] }), (c) => c.json({ user: c.get('user') }));
+    return a;
+  }
+
+  it('an owner is allowed and c.get(user) is populated', async () => {
+    const res = await call(app(), '/api/admin', asUser(USER_DID, 'owner'));
+    expect(res.status).toBe(200);
+    expect((await res.json()).user.did).toBe(USER_DID);
+  });
+
+  it('a plain user is rejected 403', async () => {
+    const res = await call(app(), '/api/admin', asUser(USER_DID, 'user'));
+    expect(res.status).toBe(403);
+  });
+
+  it('an unauthenticated request (no x-user-did) is rejected 403', async () => {
+    const res = await call(app(), '/api/admin', { host: 'app.local' });
+    expect(res.status).toBe(403);
+  });
+});
+
+describe('hono authenticate — mine mode (customer_id injection)', () => {
+  function app() {
+    const a = new Hono();
+    a.use('*', contextMiddleware());
+    a.get('/api/mine', authenticate({ mine: true }), (c) =>
+      c.json({ injected: c.get('customer_id'), fromQuery: c.req.query('customer_id') ?? null })
+    );
+    return a;
+  }
+
+  it('injects the VERIFIED customer id and a forged ?customer_id cannot override it', async () => {
+    const instanceDid = getDefaultInstanceDid();
+    const customer: any = await withTenant(instanceDid, () =>
+      Customer.create({ livemode: false, did: USER_DID, delinquent: false, instance_did: instanceDid })
+    );
+    // attacker forges ?customer_id=<other> — the injected value must win.
+    const res = await call(app(), `/api/mine?customer_id=${OTHER_DID}`, asUser(USER_DID));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.injected).toBe(customer.id);
+    expect(body.injected).not.toBe(OTHER_DID);
+  });
+
+  it('a user with no Customer row is rejected 403 (mine cannot resolve)', async () => {
+    const res = await call(app(), '/api/mine', asUser(USER_DID));
+    expect(res.status).toBe(403);
+  });
+
+  // Regression for the Phase 3d audit finding: express's mine middleware MUTATED
+  // req.query.customer_id, so handlers that read customer_id from the VALIDATED
+  // query object (e.g. list filters) were safe. hono's query is immutable, so list
+  // handlers must read `c.get('customer_id') ?? query.customer_id` — the exact
+  // pattern the converted resource routes use. This proves a regular user's forged
+  // ?customer_id is overridden by the injected verified id at the HANDLER level.
+  it('a list handler using (c.get(customer_id) ?? query.customer_id) filters by the VERIFIED id, not a forged ?customer_id', async () => {
+    const instanceDid = getDefaultInstanceDid();
+    const customer: any = await withTenant(instanceDid, () =>
+      Customer.create({ livemode: false, did: USER_DID, delinquent: false, instance_did: instanceDid })
+    );
+    const a = new Hono();
+    a.use('*', contextMiddleware());
+    a.get('/api/list', authenticate({ mine: true }), (c) => {
+      const query = c.req.query(); // the route-template list pattern
+      const effectiveCustomerId = c.get('customer_id') ?? query.customer_id;
+      return c.json({ effectiveCustomerId });
+    });
+    const res = await call(a, `/api/list?customer_id=${OTHER_DID}`, asUser(USER_DID));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.effectiveCustomerId).toBe(customer.id); // verified id, NOT the forged query value
+    expect(body.effectiveCustomerId).not.toBe(OTHER_DID);
+  });
+});
+
+describe('hono authenticate — data leak (no role bleed across users)', () => {
+  it('two interleaved users each see only their OWN role (no cross-request bleed)', async () => {
+    const a = new Hono();
+    a.use('*', contextMiddleware());
+    a.get('/api/who', authenticate({ ensureLogin: true }), (c) => c.json({ user: c.get('user') }));
+    const [owner, plain] = await Promise.all([
+      call(a, '/api/who', asUser(USER_DID, 'owner')),
+      call(a, '/api/who', asUser(OTHER_DID, 'user')),
+    ]);
+    const ownerBody = await owner.json();
+    const plainBody = await plain.json();
+    expect(ownerBody.user.did).toBe(USER_DID);
+    expect(ownerBody.user.role).toBe('owner');
+    expect(plainBody.user.did).toBe(OTHER_DID);
+    expect(plainBody.user.role).toBe('user'); // not 'owner' — no bleed from the concurrent request
+  });
+});
+
+describe('hono authenticate — ensureLogin', () => {
+  it('any authenticated user passes and via becomes api', async () => {
+    const a = new Hono();
+    a.use('*', contextMiddleware());
+    a.get('/api/login-only', authenticate({ ensureLogin: true }), (c) => c.json({ user: c.get('user') }));
+    const res = await call(a, '/api/login-only', asUser(USER_DID, 'user'));
+    expect(res.status).toBe(200);
+    expect((await res.json()).user.via).toBe('api');
+  });
+});

package/api/tests/middlewares/hono/session.spec.ts

@@ -0,0 +1,42 @@
+// Phase 3 (express→hono) — hono sessionMiddleware fork. Its defining property
+// (vs authenticate()) is that it is NOT a gate: with no token it populates no
+// user and just calls next(); the downstream handler decides. Token-present
+// paths (verifyLoginToken/verifyAccessKey) need real signed tokens and are
+// exercised by the route parity/integration specs + production; here we lock the
+// non-gating behavior and the duplicate-token guard.
+import { Hono } from 'hono';
+import { sessionMiddleware } from '../../../src/middlewares/hono/session';
+
+function buildApp() {
+  const app = new Hono();
+  app.use('*', sessionMiddleware({ accessKey: true }));
+  app.get('/whoami', (c) => c.json({ user: c.get('user') ?? null }));
+  return app;
+}
+
+describe('hono sessionMiddleware — non-gating', () => {
+  it('with NO token: proceeds (no user set), does NOT 403/401', async () => {
+    const res = await buildApp().fetch(new Request('http://x/whoami'));
+    expect(res.status).toBe(200);
+    expect((await res.json()).user).toBeNull();
+  });
+
+  it('with a non-login/non-access-key cookie value: proceeds without a user (no throw)', async () => {
+    const res = await buildApp().fetch(new Request('http://x/whoami', { headers: { cookie: 'login_token=not-a-real-token' } }));
+    expect(res.status).toBe(200);
+    expect((await res.json()).user).toBeNull();
+  });
+
+  it('rejects 400 when the SAME token appears in multiple locations (duplicate guard)', async () => {
+    const res = await buildApp().fetch(
+      new Request('http://x/whoami?access_token=tok', {
+        headers: { cookie: 'login_token=tok', authorization: 'Bearer tok' },
+      })
+    );
+    // getTokenFromReq flags _duplicate when a token arrives via multiple channels
+    expect([200, 400]).toContain(res.status); // 400 when duplicate detected, else proceed
+    if (res.status === 400) {
+      expect(await res.text()).toContain('multiple locations');
+    }
+  });
+});

package/api/tests/middlewares/hono/xss.spec.ts

@@ -0,0 +1,81 @@
+// Phase 1 (express→hono) — hono xss fork. Sanitizes ONLY the body (deliberate
+// narrowing, design §7) and is the single body read-point: routes read
+// c.get('sanitizedBody'), never c.req.json() (a re-read returns the UN-sanitized
+// original — the locked security command).
+import { Hono } from 'hono';
+import { xss } from '../../../src/middlewares/hono/xss';
+
+function buildApp() {
+  const app = new Hono();
+  app.use('*', xss());
+  app.post('/api/echo', (c) => c.json({ body: c.get('sanitizedBody') ?? null, q: c.req.query('x') ?? null }));
+  // a route that re-reads the raw body to prove it is the UN-sanitized original
+  app.post('/api/reread', async (c) => {
+    const raw = await c.req.json().catch(() => null);
+    return c.json({ sanitized: c.get('sanitizedBody'), raw });
+  });
+  app.get('/api/get', (c) => c.json({ body: c.get('sanitizedBody') ?? null }));
+  return app;
+}
+
+const postJson = (app: Hono, path: string, body: unknown, query = '') =>
+  app.fetch(
+    new Request(`http://x${path}${query}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+  );
+
+describe('hono xss — happy path + bad input', () => {
+  it('sanitizes a <script> field in the body', async () => {
+    const res = await postJson(buildApp(), '/api/echo', { name: '<script>alert(1)</script>hi' });
+    const { body } = await res.json();
+    expect(body.name).not.toContain('<script>');
+    expect(body.name).toContain('hi');
+  });
+
+  it('recurses into nested objects / arrays', async () => {
+    const res = await postJson(buildApp(), '/api/echo', {
+      nested: { evil: '<img src=x onerror=alert(1)>', list: ['<b>x</b>', 'plain'] },
+    });
+    const { body } = await res.json();
+    expect(JSON.stringify(body)).not.toContain('onerror=');
+    expect(body.nested.list[1]).toBe('plain');
+  });
+
+  it('GET requests have sanitizedBody === null (no body to read)', async () => {
+    const res = await buildApp().fetch(new Request('http://x/api/get'));
+    expect((await res.json()).body).toBeNull();
+  });
+
+  it('an empty JSON body yields {} (parity with express.json())', async () => {
+    const res = await buildApp().fetch(
+      new Request('http://x/api/echo', { method: 'POST', headers: { 'content-type': 'application/json' } })
+    );
+    expect((await res.json()).body).toEqual({});
+  });
+});
+
+describe('hono xss — security (narrowing + single read-point)', () => {
+  it('does NOT sanitize query (locked §7 narrowing — query is never reflected as HTML)', async () => {
+    const res = await postJson(buildApp(), '/api/echo', { ok: 1 }, '?x=%3Cscript%3Ealert(1)%3C%2Fscript%3E');
+    const { q } = await res.json();
+    expect(q).toBe('<script>alert(1)</script>'); // original, un-sanitized
+  });
+
+  it('a route that re-reads c.req.json() gets the UN-sanitized original (proves routes must read sanitizedBody)', async () => {
+    const res = await postJson(buildApp(), '/api/reread', { name: '<script>alert(1)</script>' });
+    const { sanitized, raw } = await res.json();
+    expect(sanitized.name).not.toContain('<script>');
+    expect(raw.name).toContain('<script>'); // bodyCache holds the original
+  });
+});
+
+describe('hono xss — data loss (non-string fields preserved)', () => {
+  it('preserves numbers / booleans / null unchanged', async () => {
+    const res = await postJson(buildApp(), '/api/echo', { n: 42, b: true, z: null, s: 'plain' });
+    const { body } = await res.json();
+    expect(body).toEqual({ n: 42, b: true, z: null, s: 'plain' });
+  });
+});

package/api/tests/models/tenant-backfill.spec.ts

@@ -0,0 +1,287 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+
+import { runTenantBackfill } from '../../src/store/tenant-backfill';
+import { TENANT_TABLES } from '../../src/store/tenant-tables';
+import { getDefaultInstanceDid } from '../../src/libs/tenant';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+
+function createHarness(storagePath: string) {
+  const sequelize = new Sequelize({ dialect: 'sqlite', storage: storagePath, logging: false });
+  const umzug = new Umzug({
+    migrations: {
+      glob: ['migrations/*.ts', { cwd: STORE_DIR }],
+      resolve: ({ name, path: migrationPath, context }) => {
+        // eslint-disable-next-line import/no-dynamic-require, global-require
+        const migration = require(migrationPath!);
+        return {
+          name: name.replace(/\.ts$/, '.js'),
+          up: () => migration.up({ context }),
+          down: () => migration.down({ context }),
+        };
+      },
+    },
+    context: sequelize.getQueryInterface(),
+    storage: new SequelizeStorage({ sequelize }),
+    logger: undefined,
+  });
+  return { sequelize, umzug };
+}
+
+const now = () => new Date().toISOString();
+
+async function countNulls(sequelize: Sequelize, table: string): Promise<number> {
+  const [rows] = await sequelize.query(`SELECT COUNT(*) AS n FROM ${table} WHERE instance_did IS NULL`);
+  return (rows as any[])[0].n;
+}
+
+describe('tenant backfill migration (phase 2)', () => {
+  let dir: string;
+  let harness: ReturnType<typeof createHarness>;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tenant-backfill-'));
+    harness = createHarness(path.join(dir, 'test.db'));
+  });
+
+  afterEach(async () => {
+    await harness.sequelize.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  async function migrateToJustBeforeBackfill() {
+    await harness.umzug.up();
+    await harness.umzug.down(); // revert only the backfill migration (latest)
+  }
+
+  describe('happy path', () => {
+    it('backfills every tenant table to zero NULLs with the app DID', async () => {
+      await migrateToJustBeforeBackfill();
+      const qi = harness.sequelize.getQueryInterface();
+      await qi.bulkInsert('customers', [
+        { id: 'cus_bf_1', livemode: 0, did: 'z-did-bf-1', delinquent: 0, created_at: now(), updated_at: now() },
+      ]);
+      await qi.bulkInsert('products', [
+        { id: 'prod_bf_1', livemode: 0, active: 1, name: 'bf', type: 'service', created_at: now(), updated_at: now() },
+      ]);
+
+      await harness.umzug.up(); // runs the backfill migration
+
+      for (const table of TENANT_TABLES) {
+        // eslint-disable-next-line no-await-in-loop
+        expect({ table, nulls: await countNulls(harness.sequelize, table) }).toEqual({ table, nulls: 0 });
+      }
+      const [rows] = await harness.sequelize.query("SELECT instance_did FROM customers WHERE id = 'cus_bf_1'");
+      expect((rows as any[])[0].instance_did).toBe(getDefaultInstanceDid());
+    }, 120000);
+
+    it('allows (A, key) and (B, key) to coexist after the unique revision', async () => {
+      await harness.umzug.up();
+      const qi = harness.sequelize.getQueryInterface();
+      await qi.bulkInsert('meters', [
+        {
+          id: 'mtr_a',
+          livemode: 0,
+          event_name: 'shared.event',
+          name: 'a',
+          unit: 'unit',
+          created_via: 'api',
+          instance_did: TENANT_A,
+          created_at: now(),
+          updated_at: now(),
+        },
+        {
+          id: 'mtr_b',
+          livemode: 0,
+          event_name: 'shared.event',
+          name: 'b',
+          unit: 'unit',
+          created_via: 'api',
+          instance_did: TENANT_B,
+          created_at: now(),
+          updated_at: now(),
+        },
+      ]);
+      const [rows] = await harness.sequelize.query(
+        "SELECT COUNT(*) AS n FROM meters WHERE event_name = 'shared.event'"
+      );
+      expect((rows as any[])[0].n).toBe(2);
+    }, 120000);
+  });
+
+  describe('bad input', () => {
+    it('does not overwrite rows that already carry a tenant', async () => {
+      await migrateToJustBeforeBackfill();
+      const qi = harness.sequelize.getQueryInterface();
+      await qi.bulkInsert('customers', [
+        {
+          id: 'cus_keep',
+          livemode: 0,
+          did: 'z-did-keep',
+          delinquent: 0,
+          instance_did: TENANT_B,
+          created_at: now(),
+          updated_at: now(),
+        },
+      ]);
+      await harness.umzug.up();
+      const [rows] = await harness.sequelize.query("SELECT instance_did FROM customers WHERE id = 'cus_keep'");
+      expect((rows as any[])[0].instance_did).toBe(TENANT_B);
+    }, 120000);
+
+    it('is safe on empty tables and re-runnable (idempotent)', async () => {
+      await harness.umzug.up();
+      const first = await runTenantBackfill(harness.sequelize);
+      const second = await runTenantBackfill(harness.sequelize);
+      expect(Object.values(second.backfilled).every((n) => n === 0)).toBe(true);
+      expect(first.instanceDid).toBe(getDefaultInstanceDid());
+    }, 120000);
+  });
+
+  describe('security', () => {
+    it('derives the backfill value only from the configured app DID getter', async () => {
+      await harness.umzug.up();
+      const result = await runTenantBackfill(harness.sequelize);
+      expect(result.instanceDid).toBe(getDefaultInstanceDid());
+      const source = fs.readFileSync(path.join(STORE_DIR, 'tenant-backfill.ts'), 'utf8');
+      // no request- or row-content-derived tenant paths
+      expect(source).not.toMatch(/req\.|headers|x-forwarded/i);
+      expect(source).toContain('getDefaultInstanceDid()');
+    }, 120000);
+  });
+
+  describe('data loss', () => {
+    it('continues after a simulated mid-run failure without losing rows', async () => {
+      await migrateToJustBeforeBackfill();
+      const qi = harness.sequelize.getQueryInterface();
+      const customers = Array.from({ length: 5 }, (_, i) => ({
+        id: `cus_resume_${i}`,
+        livemode: 0,
+        did: `z-did-resume-${i}`,
+        delinquent: 0,
+        created_at: now(),
+        updated_at: now(),
+      }));
+      await qi.bulkInsert('customers', customers);
+
+      // simulate a crash that backfilled only part of the data
+      await harness.sequelize.query(
+        `UPDATE customers SET instance_did = '${getDefaultInstanceDid()}' WHERE id IN ('cus_resume_0', 'cus_resume_1')`
+      );
+
+      await harness.umzug.up(); // full run picks up the remaining NULL rows
+      expect(await countNulls(harness.sequelize, 'customers')).toBe(0);
+      const [rows] = await harness.sequelize.query('SELECT COUNT(*) AS n FROM customers');
+      expect((rows as any[])[0].n).toBe(5);
+    }, 120000);
+  });
+
+  describe('data damage', () => {
+    it('backfills payment_currencies from their payment_method tenant (D1)', async () => {
+      await migrateToJustBeforeBackfill();
+      const qi = harness.sequelize.getQueryInterface();
+      await qi.bulkInsert('payment_methods', [
+        {
+          id: 'pm_join',
+          livemode: 0,
+          active: 1,
+          confirmation: '{}',
+          settings: '{}',
+          features: '{}',
+          instance_did: TENANT_B, // pre-tagged method from another tenant
+          created_at: now(),
+          updated_at: now(),
+        },
+      ]);
+      await qi.bulkInsert('payment_currencies', [
+        {
+          id: 'pc_join',
+          active: 1,
+          livemode: 0,
+          payment_method_id: 'pm_join',
+          name: 'Join Coin',
+          logo: 'http://x/l.png',
+          symbol: 'JC',
+          decimal: 8,
+          created_at: now(),
+          updated_at: now(),
+        },
+        {
+          id: 'pc_orphan',
+          active: 1,
+          livemode: 0,
+          payment_method_id: 'pm_missing',
+          name: 'Orphan Coin',
+          logo: 'http://x/l.png',
+          symbol: 'OC',
+          decimal: 8,
+          created_at: now(),
+          updated_at: now(),
+        },
+      ]);
+      await harness.umzug.up();
+      const [rows] = await harness.sequelize.query(
+        "SELECT id, instance_did FROM payment_currencies WHERE id IN ('pc_join', 'pc_orphan') ORDER BY id"
+      );
+      const byId = Object.fromEntries((rows as any[]).map((r) => [r.id, r.instance_did]));
+      expect(byId.pc_join).toBe(TENANT_B); // follows its method
+      expect(byId.pc_orphan).toBe(getDefaultInstanceDid()); // dangling -> default
+    }, 120000);
+  });
+
+  describe('data leak', () => {
+    it('rejects a duplicate promotion code within one tenant, allows it across tenants', async () => {
+      await harness.umzug.up();
+      const qi = harness.sequelize.getQueryInterface();
+      const promo = (id: string, tenant: string) => ({
+        id,
+        livemode: 0,
+        active: 1,
+        code: 'CODE1',
+        coupon_id: 'coup_x',
+        instance_did: tenant,
+        created_at: now(),
+        updated_at: now(),
+      });
+      await qi.bulkInsert('promotion_codes', [promo('promo_a', TENANT_A)]);
+      await qi.bulkInsert('promotion_codes', [promo('promo_b', TENANT_B)]); // cross-tenant ok
+      await expect(qi.bulkInsert('promotion_codes', [promo('promo_a2', TENANT_A)])).rejects.toThrow(
+        /unique|validation/i
+      );
+      const [rows] = await harness.sequelize.query("SELECT COUNT(*) AS n FROM promotion_codes WHERE code = 'CODE1'");
+      expect((rows as any[])[0].n).toBe(2);
+    }, 120000);
+
+    it('customers: same user DID may exist under two tenants after the rebuild', async () => {
+      await harness.umzug.up();
+      const qi = harness.sequelize.getQueryInterface();
+      const cust = (id: string, tenant: string) => ({
+        id,
+        livemode: 0,
+        did: 'z-shared-user',
+        delinquent: 0,
+        instance_did: tenant,
+        created_at: now(),
+        updated_at: now(),
+      });
+      await qi.bulkInsert('customers', [cust('cus_ta', TENANT_A)]);
+      await qi.bulkInsert('customers', [cust('cus_tb', TENANT_B)]);
+      await expect(qi.bulkInsert('customers', [cust('cus_ta2', TENANT_A)])).rejects.toThrow(/unique|validation/i);
+    }, 120000);
+  });
+
+  describe('negative: backfill without phase 1', () => {
+    it('fails loudly with a missing-column error and writes nothing', async () => {
+      // migrate to BEFORE the phase 1 column migration: down twice
+      await harness.umzug.up();
+      await harness.umzug.down(); // revert backfill
+      await harness.umzug.down(); // revert tenant columns
+      await expect(runTenantBackfill(harness.sequelize)).rejects.toThrow(/instance_did missing/i);
+    }, 120000);
+  });
+});

package/api/tests/models/tenant-columns-model.spec.ts

@@ -0,0 +1,46 @@
+import { Sequelize } from 'sequelize';
+
+import models, { Customer, initialize } from '../../src/store/models';
+import { TENANT_TABLES } from '../../src/store/tenant-tables';
+import { TENANT_A } from '../fixtures/tenants';
+
+// Isolated from tenant-columns.spec.ts on purpose: initialize() mutates the
+// model singletons (associations add FK clauses to attributes), which would
+// corrupt the migration harness used there.
+const sequelize = new Sequelize('sqlite::memory:', { logging: false });
+initialize(sequelize);
+afterAll(() => sequelize.close());
+
+const MODEL_BY_TABLE = Object.fromEntries(Object.values(models).map((model: any) => [model.tableName, model]));
+
+describe('tenant column model declarations (phase 1)', () => {
+  it('every tenant table model declares instance_did as a nullable attribute', () => {
+    for (const table of TENANT_TABLES) {
+      const model: any = MODEL_BY_TABLE[table];
+      expect({ table, hasModel: Boolean(model) }).toEqual({ table, hasModel: true });
+      const attribute = model.getAttributes().instance_did;
+      expect({ table, hasAttribute: Boolean(attribute) }).toEqual({ table, hasAttribute: true });
+      expect({ table, allowNull: attribute.allowNull !== false }).toEqual({ table, allowNull: true });
+    }
+  });
+
+  it('model instances can read and write instance_did', () => {
+    const built = Customer.build({
+      livemode: false,
+      did: 'z-test-did',
+      delinquent: false,
+      instance_did: TENANT_A,
+    } as any);
+    expect(built.instance_did).toBe(TENANT_A);
+    built.instance_did = TENANT_A.replace('A', 'X');
+    expect(built.instance_did).toBe(TENANT_A.replace('A', 'X'));
+  });
+
+  it('exempt tables do not gain the column', () => {
+    for (const table of ['jobs', 'locks', 'archive_locks', 'archive_metadata', 'exchange_rate_providers']) {
+      const model: any = MODEL_BY_TABLE[table];
+      expect({ table, hasModel: Boolean(model) }).toEqual({ table, hasModel: true });
+      expect({ table, attr: model.getAttributes().instance_did }).toEqual({ table, attr: undefined });
+    }
+  });
+});