payment-kit 1.29.0 → 1.29.2

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

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

@@ -0,0 +1,161 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { SequelizeStorage, Umzug } from 'umzug';
+
+import { TENANT_TABLES } from '../../src/store/tenant-tables';
+
+const STORE_DIR = path.join(__dirname, '../../src/store');
+const TENANT_MIGRATION = '20260610-tenant-columns';
+// pin the chain to phase 1: phase 2 (tenant backfill) intentionally rebuilds
+// some tables with NOT NULL + composite uniques, which this spec must not see
+const upToPhase1 = (umzug: Umzug<any>) => umzug.up({ to: `${TENANT_MIGRATION}.js` } as any);
+
+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 };
+}
+
+async function tableColumns(sequelize: Sequelize, table: string): Promise<Record<string, any>[]> {
+  const [rows] = await sequelize.query(`PRAGMA table_info(${table})`);
+  return rows as Record<string, any>[];
+}
+
+describe('tenant columns migration (phase 1)', () => {
+  let dir: string;
+  let dbPath: string;
+  let harness: ReturnType<typeof createHarness>;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tenant-columns-'));
+    dbPath = path.join(dir, 'test.db');
+    harness = createHarness(dbPath);
+  });
+
+  afterEach(async () => {
+    await harness.sequelize.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  describe('happy path', () => {
+    it('adds a nullable instance_did column to all 38 tenant tables', async () => {
+      await upToPhase1(harness.umzug);
+      for (const table of TENANT_TABLES) {
+        // eslint-disable-next-line no-await-in-loop
+        const columns = await tableColumns(harness.sequelize, table);
+        const column = columns.find((c) => c.name === 'instance_did');
+        expect({ table, found: Boolean(column) }).toEqual({ table, found: true });
+        expect({ table, notnull: column!.notnull }).toEqual({ table, notnull: 0 });
+        expect({ table, dflt: column!.dflt_value ?? null }).toEqual({ table, dflt: null });
+      }
+    }, 60000);
+
+    // "model layer exposes instance_did" lives in tenant-columns-model.spec.ts:
+    // initializing the model singletons here would mutate GENESIS_ATTRIBUTES
+    // (associations add FK clauses) and corrupt the migration harness below.
+  });
+
+  describe('bad input: re-running up is idempotent', () => {
+    it('skips existing columns without error and without duplicating them', async () => {
+      await upToPhase1(harness.umzug);
+      // call the migration's up() directly a second time, bypassing umzug bookkeeping
+      // eslint-disable-next-line import/no-dynamic-require, global-require
+      const migration = require(path.join(STORE_DIR, 'migrations', `${TENANT_MIGRATION}.ts`));
+      await migration.up({ context: harness.sequelize.getQueryInterface() });
+      const columns = await tableColumns(harness.sequelize, 'customers');
+      expect(columns.filter((c) => c.name === 'instance_did')).toHaveLength(1);
+    }, 60000);
+  });
+
+  describe('security: migration is built from static literals only', () => {
+    it('contains no env/config interpolation into SQL identifiers', () => {
+      const migrationSource = fs.readFileSync(path.join(STORE_DIR, 'migrations', `${TENANT_MIGRATION}.ts`), 'utf8');
+      expect(migrationSource).not.toContain('process.env');
+      expect(migrationSource).not.toContain('globalThis');
+      const listSource = fs.readFileSync(path.join(STORE_DIR, 'tenant-tables.ts'), 'utf8');
+      expect(listSource).not.toContain('process.env');
+      // every table entry is a quoted literal
+      const entries = listSource.match(/^\s*'[a-z_]+',$/gm) || [];
+      expect(entries.length).toBe(38);
+    });
+  });
+
+  describe('data loss / data damage: existing rows survive up and down', () => {
+    it('preserves pre-existing rows and their values through up, and through down', async () => {
+      // migrate to just before the tenant migration, then seed
+      await upToPhase1(harness.umzug);
+      await harness.umzug.down(); // revert the tenant column migration
+
+      const qi = harness.sequelize.getQueryInterface();
+      const now = new Date().toISOString();
+      await qi.bulkInsert('customers', [
+        {
+          id: 'cus_phase1_test1',
+          livemode: 0,
+          did: 'z-did-phase1-1',
+          delinquent: 0,
+          created_at: now,
+          updated_at: now,
+        },
+      ]);
+
+      // up: row survives, all original values intact, instance_did = NULL
+      await upToPhase1(harness.umzug);
+      const [afterUp] = await harness.sequelize.query(
+        "SELECT id, livemode, did, delinquent, instance_did FROM customers WHERE id = 'cus_phase1_test1'"
+      );
+      expect(afterUp).toHaveLength(1);
+      const row = (afterUp as any[])[0];
+      expect(row.did).toBe('z-did-phase1-1');
+      expect(row.livemode).toBe(0);
+      expect(row.instance_did).toBeNull();
+
+      // down: column removed, row and non-tenant values still intact
+      await harness.umzug.down();
+      const columns = await tableColumns(harness.sequelize, 'customers');
+      expect(columns.find((c) => c.name === 'instance_did')).toBeUndefined();
+      const [afterDown] = await harness.sequelize.query("SELECT id, did FROM customers WHERE id = 'cus_phase1_test1'");
+      expect(afterDown).toHaveLength(1);
+      expect((afterDown as any[])[0].did).toBe('z-did-phase1-1');
+    }, 120000);
+  });
+
+  describe('data leak: the new column is never auto-filled', () => {
+    it('defaults to NULL for rows written without an explicit tenant', async () => {
+      await upToPhase1(harness.umzug);
+      const qi = harness.sequelize.getQueryInterface();
+      const now = new Date().toISOString();
+      await qi.bulkInsert('products', [
+        {
+          id: 'prod_phase1_leak',
+          livemode: 0,
+          active: 1,
+          name: 'leak-check',
+          type: 'service',
+          created_at: now,
+          updated_at: now,
+        },
+      ]);
+      const [rows] = await harness.sequelize.query("SELECT instance_did FROM products WHERE id = 'prod_phase1_leak'");
+      expect((rows as any[])[0].instance_did).toBeNull();
+    }, 60000);
+  });
+});

package/api/tests/queues/credit-consume-batch.spec.ts

@@ -68,7 +68,14 @@ jest.mock('../../src/libs/queue', () => {
     delete: jest.fn().mockResolvedValue(undefined),
     on: jest.fn(),
   };
-  return jest.fn().mockReturnValue(mockQueue);
+  const factory: any = jest.fn().mockReturnValue(mockQueue);
+  return {
+    __esModule: true,
+    default: factory,
+    // phase 5/6: tenant invariant helper — pass-through in these unit tests
+    // (tenant enforcement has its own suites: tenant-matrix-a/b)
+    assertJobObjectTenant: jest.fn(),
+  };
 });
 
 jest.mock('../../src/store/models', () => ({

package/api/tests/queues/credit-consume.spec.ts

@@ -71,7 +71,14 @@ jest.mock('../../src/libs/queue', () => {
     delete: jest.fn().mockResolvedValue(undefined),
     on: jest.fn(),
   };
-  return jest.fn().mockReturnValue(mockQueue);
+  const factory: any = jest.fn().mockReturnValue(mockQueue);
+  return {
+    __esModule: true,
+    default: factory,
+    // phase 5/6: tenant invariant helper — pass-through in these unit tests
+    // (tenant enforcement has its own suites: tenant-matrix-a/b)
+    assertJobObjectTenant: jest.fn(),
+  };
 });
 
 jest.mock('../../src/store/models', () => ({