payment-kit 1.29.1 → 1.29.2

package/api/tests/store/tenant-model-spike.spec.ts

@@ -0,0 +1,177 @@
+// SPIKE: validate the TenantModel base-class mechanism against BOTH query
+// engines in one run — real Sequelize (Node) and the sequelize-d1 shim
+// (worker). Go/No-Go for `TENANT-ISOLATION-DESIGN.md` §12.
+//
+// Proves: (a) static override + super works on both bases; (b) `this`
+// resolves to the concrete model through the extra inheritance layer (shim);
+// (c) scopeWhere idempotency absorbs the findByPk->findOne->findAll double
+// injection; (d) cross-tenant read/write/aggregate are isolated; (e) the
+// worker reads the tenant via ALS (withTenant).
+import { DatabaseSync } from 'node:sqlite';
+import { DataTypes, Model as RealModel, Sequelize } from 'sequelize';
+
+import { withTenant } from '../../src/libs/context';
+import { makeTenantModel } from '../../src/store/tenant-model';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+// 'coupons' is a real tenant table (in TENANT_TABLES) -> _isTenantTable() true.
+// We give it a minimal schema we fully control, on a throwaway DB.
+const TABLE = 'coupons';
+
+// ---------------------------------------------------------------------------
+// Base 1: real Sequelize (Node runtime)
+// ---------------------------------------------------------------------------
+describe('TenantModel over real Sequelize', () => {
+  let sequelize: Sequelize;
+  let Widget: any;
+
+  beforeAll(async () => {
+    sequelize = new Sequelize({ dialect: 'sqlite', storage: ':memory:', logging: false });
+    Widget = class extends makeTenantModel(RealModel) {};
+    Widget.init(
+      {
+        id: { type: DataTypes.STRING, primaryKey: true },
+        instance_did: { type: DataTypes.STRING },
+        name: { type: DataTypes.STRING },
+        qty: { type: DataTypes.INTEGER },
+      },
+      { sequelize, modelName: 'Widget', tableName: TABLE, timestamps: false }
+    );
+    await sequelize.sync();
+  });
+
+  afterAll(async () => {
+    await sequelize.close();
+  });
+
+  beforeEach(async () => {
+    await sequelize.query(`DELETE FROM ${TABLE}`);
+    await withTenant(TENANT_A, () => Widget.create({ id: 'a1', name: 'a-one', qty: 10 }));
+    await withTenant(TENANT_A, () => Widget.create({ id: 'a2', name: 'a-two', qty: 5 }));
+    await withTenant(TENANT_B, () => Widget.create({ id: 'b1', name: 'b-one', qty: 100 }));
+  });
+
+  it('findAll returns only the active tenant', async () => {
+    const a = await withTenant(TENANT_A, () => Widget.findAll());
+    expect(a.map((r: any) => r.id).sort()).toEqual(['a1', 'a2']);
+    const b = await withTenant(TENANT_B, () => Widget.findAll());
+    expect(b.map((r: any) => r.id)).toEqual(['b1']);
+  });
+
+  it('findByPk across tenants returns null (delegation + idempotent double-scope)', async () => {
+    expect(await withTenant(TENANT_A, () => Widget.findByPk('a1'))).not.toBeNull();
+    expect(await withTenant(TENANT_A, () => Widget.findByPk('b1'))).toBeNull();
+  });
+
+  it('create stamps the active tenant', async () => {
+    const row = await withTenant(TENANT_A, () => Widget.findByPk('a1'));
+    expect(row.instance_did).toBe(TENANT_A);
+  });
+
+  it('sum aggregates only the active tenant', async () => {
+    expect(await withTenant(TENANT_A, () => Widget.sum('qty'))).toBe(15);
+    expect(await withTenant(TENANT_B, () => Widget.sum('qty'))).toBe(100);
+  });
+
+  it('update never crosses tenants', async () => {
+    await withTenant(TENANT_A, () => Widget.update({ name: 'a-upd' }, { where: {} }));
+    const b1 = await withTenant(TENANT_B, () => Widget.findByPk('b1'));
+    expect(b1.name).toBe('b-one');
+  });
+
+  it('explicit matching instance_did is idempotent; conflicting fails closed', async () => {
+    await expect(withTenant(TENANT_A, () => Widget.findAll({ where: { instance_did: TENANT_A } }))).resolves.toHaveLength(2);
+    await expect(withTenant(TENANT_A, () => Widget.findAll({ where: { instance_did: TENANT_B } }))).rejects.toThrow(/conflicts with the active tenant/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Base 2: sequelize-d1 shim (worker runtime), backed by node:sqlite as a
+// minimal D1-compatible fake.
+// ---------------------------------------------------------------------------
+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('TenantModel over sequelize-d1 shim', () => {
+  let ShimModel: any;
+  let setDB: any;
+  let Widget: any;
+
+  beforeAll(() => {
+    // eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
+    const shim = require('../../../cloudflare/shims/sequelize-d1');
+    ShimModel = shim.Model;
+    setDB = shim.setDB;
+
+    const db = new DatabaseSync(':memory:');
+    db.exec(`CREATE TABLE ${TABLE} (id TEXT PRIMARY KEY, instance_did TEXT, name TEXT, qty INTEGER)`);
+    setDB(makeFakeD1(db));
+
+    Widget = class extends makeTenantModel(ShimModel) {};
+    Widget.init(
+      { id: {}, instance_did: {}, name: {}, qty: {} },
+      { sequelize: { models: {} }, modelName: 'Widget', tableName: TABLE }
+    );
+  });
+
+  beforeEach(async () => {
+    await withTenant(TENANT_A, () => Widget.destroy({ where: {} }));
+    await withTenant(TENANT_B, () => Widget.destroy({ where: {} }));
+    await withTenant(TENANT_A, () => Widget.create({ id: 'a1', name: 'a-one', qty: 10 }));
+    await withTenant(TENANT_A, () => Widget.create({ id: 'a2', name: 'a-two', qty: 5 }));
+    await withTenant(TENANT_B, () => Widget.create({ id: 'b1', name: 'b-one', qty: 100 }));
+  });
+
+  it('findAll returns only the active tenant', async () => {
+    const a = await withTenant(TENANT_A, () => Widget.findAll());
+    expect(a.map((r: any) => r.id).sort()).toEqual(['a1', 'a2']);
+    const b = await withTenant(TENANT_B, () => Widget.findAll());
+    expect(b.map((r: any) => r.id)).toEqual(['b1']);
+  });
+
+  it('findByPk across tenants returns null (this-resolution + delegation through extra layer)', async () => {
+    expect(await withTenant(TENANT_A, () => Widget.findByPk('a1'))).not.toBeNull();
+    expect(await withTenant(TENANT_A, () => Widget.findByPk('b1'))).toBeNull();
+  });
+
+  it('create stamps the active tenant', async () => {
+    const row = await withTenant(TENANT_A, () => Widget.findByPk('a1'));
+    expect(row.instance_did).toBe(TENANT_A);
+  });
+
+  it('update never crosses tenants', async () => {
+    await withTenant(TENANT_A, () => Widget.update({ name: 'a-upd' }, { where: {} }));
+    const b1 = await withTenant(TENANT_B, () => Widget.findByPk('b1'));
+    expect(b1.name).toBe('b-one');
+  });
+
+  it('conflicting explicit instance_did fails closed', async () => {
+    await expect(withTenant(TENANT_A, () => Widget.findAll({ where: { instance_did: TENANT_B } }))).rejects.toThrow(/conflicts with the active tenant/);
+  });
+});

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

@@ -0,0 +1,162 @@
+// Phase 3 (W1′) — TenantModel landed on the REAL models.
+//
+// The spike (tenant-model-spike.spec.ts) proved the mechanism on controlled
+// same-named tables against both engines. This proves the PRODUCTION wiring:
+// the real Coupon class (with its init/associations/hooks) extends TenantModel
+// and is transparently tenant-scoped across the full 6-class matrix.
+import { Sequelize } from 'sequelize';
+
+import { withTenant } from '../../src/libs/context';
+import { TENANT_MISMATCH } from '../../src/libs/tenant';
+import { Coupon, initialize } from '../../src/store/models';
+import { isTenantTable, scopeWhere, stampTenant } from '../../src/store/scoped-core';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+const sequelize = new Sequelize('sqlite::memory:', { logging: false });
+initialize(sequelize);
+
+beforeAll(async () => {
+  await sequelize.sync({ force: true });
+});
+afterAll(() => sequelize.close());
+
+beforeEach(async () => {
+  // truncate between tests so counts are deterministic
+  await sequelize.query('DELETE FROM coupons');
+});
+
+function makeCoupon(overrides: Record<string, any> = {}) {
+  return {
+    livemode: false,
+    duration: 'once',
+    name: 'spring-sale',
+    created_via: 'api',
+    ...overrides,
+  };
+}
+
+describe('TenantModel on the real Coupon model', () => {
+  describe('Happy path', () => {
+    it('findAll under tenant A returns only A rows; create stamps instance_did', async () => {
+      await withTenant(TENANT_A, () => Coupon.create(makeCoupon({ name: 'a-1' }) as any));
+      await withTenant(TENANT_B, () => Coupon.create(makeCoupon({ name: 'b-1' }) as any));
+
+      const aRows = await withTenant(TENANT_A, () => Coupon.findAll());
+      expect(aRows.map((r: any) => r.name)).toEqual(['a-1']);
+      expect(aRows.every((r: any) => r.instance_did === TENANT_A)).toBe(true);
+    });
+  });
+
+  describe('Bad input', () => {
+    it('explicit conflicting where.instance_did fails closed (reject, not resolve)', async () => {
+      await expect(
+        withTenant(TENANT_A, () => Coupon.findOne({ where: { instance_did: TENANT_B } as any }))
+      ).rejects.toMatchObject({ code: TENANT_MISMATCH });
+    });
+
+    it('undefined / empty where does not crash', async () => {
+      await withTenant(TENANT_A, () => Coupon.create(makeCoupon() as any));
+      await expect(withTenant(TENANT_A, () => Coupon.findAll())).resolves.toBeDefined();
+      await expect(withTenant(TENANT_A, () => Coupon.findOne({}))).resolves.toBeDefined();
+    });
+  });
+
+  describe('Security', () => {
+    it('prototype-pollution keys in a where payload do not poison scope injection', async () => {
+      // scopeWhere spreads the caller where into a fresh object; a malicious
+      // __proto__ own-key must not leak onto Object.prototype.
+      const malicious = JSON.parse('{"__proto__": {"polluted": true}, "name": "x"}');
+      const scoped = await withTenant(TENANT_A, async () => scopeWhere(malicious));
+      expect(({} as any).polluted).toBeUndefined();
+      expect(scoped.instance_did).toBe(TENANT_A);
+      expect(scoped.name).toBe('x');
+    });
+
+    it('create cannot stamp a foreign tenant via explicit instance_did', async () => {
+      await expect(
+        withTenant(TENANT_A, () => Coupon.create(makeCoupon({ instance_did: TENANT_B }) as any))
+      ).rejects.toMatchObject({ code: TENANT_MISMATCH });
+    });
+  });
+
+  describe('Data loss', () => {
+    it('update/destroy never cross tenants', async () => {
+      await withTenant(TENANT_A, () => Coupon.create(makeCoupon({ name: 'keep' }) as any));
+      await withTenant(TENANT_B, () => Coupon.create(makeCoupon({ name: 'victim' }) as any));
+
+      // A updates "everything" — must not touch B's row
+      await withTenant(TENANT_A, () => Coupon.update({ name: 'renamed' }, { where: {} }));
+      const bRow = await withTenant(TENANT_B, () => Coupon.findOne());
+      expect(bRow!.name).toBe('victim');
+
+      // A destroys "everything" — B's row survives
+      await withTenant(TENANT_A, () => Coupon.destroy({ where: {} }));
+      const bCount = await withTenant(TENANT_B, () => Coupon.count());
+      const aCount = await withTenant(TENANT_A, () => Coupon.count());
+      expect({ aCount, bCount }).toEqual({ aCount: 0, bCount: 1 });
+    });
+  });
+
+  describe('Data damage', () => {
+    it('roundtrip create -> findByPk preserves unicode name + metadata', async () => {
+      const created: any = await withTenant(TENANT_A, () =>
+        Coupon.create(makeCoupon({ name: '春季促销 🎉', metadata: { k: 'välue', n: 1 } }) as any)
+      );
+      const fetched: any = await withTenant(TENANT_A, () => Coupon.findByPk(created.id));
+      expect(fetched.name).toBe('春季促销 🎉');
+      expect(fetched.metadata).toEqual({ k: 'välue', n: 1 });
+    });
+  });
+
+  describe('Data leak', () => {
+    it('cross-tenant findByPk returns null; aggregates do not cross', async () => {
+      const bRow: any = await withTenant(TENANT_B, () => Coupon.create(makeCoupon({ name: 'b-only' }) as any));
+      await withTenant(TENANT_A, () => Coupon.create(makeCoupon({ name: 'a-only' }) as any));
+
+      // A cannot fetch B's row by its (globally unique) id
+      const leaked = await withTenant(TENANT_A, () => Coupon.findByPk(bRow.id));
+      expect(leaked).toBeNull();
+
+      // findAndCountAll count excludes the other tenant
+      const { count } = await withTenant(TENANT_A, () => Coupon.findAndCountAll());
+      expect(count).toBe(1);
+
+      const aCount = await withTenant(TENANT_A, () => Coupon.count());
+      expect(aCount).toBe(1);
+    });
+
+    it('sum/max aggregates never cross tenants', async () => {
+      // A: two coupons (10 + 30 = 40, max 30); B: one coupon (99)
+      await withTenant(TENANT_A, () => Coupon.create(makeCoupon({ name: 'a-10', percent_off: 10 }) as any));
+      await withTenant(TENANT_A, () => Coupon.create(makeCoupon({ name: 'a-30', percent_off: 30 }) as any));
+      await withTenant(TENANT_B, () => Coupon.create(makeCoupon({ name: 'b-99', percent_off: 99 }) as any));
+
+      const aSum = await withTenant(TENANT_A, () => Coupon.sum('percent_off'));
+      const aMax = await withTenant(TENANT_A, () => Coupon.max('percent_off'));
+      const bSum = await withTenant(TENANT_B, () => Coupon.sum('percent_off'));
+
+      // A's aggregates exclude B's 99 entirely
+      expect(aSum).toBe(40);
+      expect(aMax).toBe(30);
+      expect(bSum).toBe(99);
+    });
+  });
+});
+
+describe('scoped-core is engine-agnostic (Phase 3 cross-engine import assertion)', () => {
+  // The same scopeWhere/stampTenant/isTenantTable the worker shim imports.
+  // No Node-only dependency is required to inject the tenant.
+  it('scopeWhere injects instance_did for tenant tables under withTenant', async () => {
+    await withTenant(TENANT_A, async () => {
+      expect(isTenantTable('coupons')).toBe(true);
+      expect(scopeWhere({ name: 'x' })).toEqual({ name: 'x', instance_did: TENANT_A });
+      expect(stampTenant({ name: 'x' })).toEqual({ name: 'x', instance_did: TENANT_A });
+    });
+  });
+
+  it('scopeWhere fails closed on a conflicting explicit tenant', async () => {
+    await expect(withTenant(TENANT_A, async () => scopeWhere({ instance_did: TENANT_B }))).rejects.toMatchObject({
+      code: TENANT_MISMATCH,
+    });
+  });
+});

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

@@ -0,0 +1,196 @@
+// Phase 4 (W1′) — residual-hole closure on top of Phase 3's TenantModel.
+//
+// Covers the three Phase 4 deliverables that close the escapes the base class
+// can't reach on its own:
+//   - 洞 G: raw sequelize.query on tenant tables is instance_did-guarded.
+//   - 洞 H observability: a forged cross-tenant job emits a structured
+//     TENANT_VIOLATION alert (not a silent scoped null).
+//   - system* security: the cross-tenant bypass is explicit-only — a normal
+//     route/tenant context can never read across tenants.
+import { Sequelize } from 'sequelize';
+
+import { context, isSystemContext, withTenant } from '../../src/libs/context';
+import { assertJobObjectTenant } from '../../src/libs/queue';
+import { TENANT_CONTEXT_MISSING, TENANT_MISMATCH } from '../../src/libs/tenant';
+import logger from '../../src/libs/logger';
+import { Coupon, MeterEvent, PromotionCode, initialize } from '../../src/store/models';
+import { systemFindByPk } from '../../src/store/scoped';
+import { TENANT_A, TENANT_B } from '../fixtures/tenants';
+
+jest.mock('../../src/libs/logger');
+
+const sequelize = new Sequelize('sqlite::memory:', { logging: false });
+initialize(sequelize);
+
+beforeAll(async () => {
+  await sequelize.sync({ force: true });
+});
+afterAll(() => sequelize.close());
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  await sequelize.query('DELETE FROM meter_events');
+  await sequelize.query('DELETE FROM coupons');
+  await sequelize.query('DELETE FROM promotion_codes');
+});
+
+describe('洞 G — raw query instance_did guard (MeterEvent.getEventStats)', () => {
+  let seq = 0;
+  const seedEvent = (tenant: string, value: number) => {
+    seq += 1;
+    return withTenant(tenant, () =>
+      MeterEvent.create({
+        event_name: 'api.calls',
+        identifier: `evt-${tenant}-${seq}`,
+        timestamp: 1700000000 + seq,
+        created_via: 'api',
+        livemode: true,
+        status: 'completed',
+        payload: { value: String(value), customer_id: 'c-1' },
+      } as any)
+    );
+  };
+
+  it('the raw SUM aggregate never crosses tenants', async () => {
+    await seedEvent(TENANT_A, 10);
+    await seedEvent(TENANT_A, 30);
+    await seedEvent(TENANT_B, 999);
+
+    const aStats = await withTenant(TENANT_A, () => MeterEvent.getEventStats('api.calls'));
+    const bStats = await withTenant(TENANT_B, () => MeterEvent.getEventStats('api.calls'));
+
+    // A's total_value (raw SUM) excludes B's 999 entirely
+    expect(Number(aStats.total_value)).toBe(40);
+    expect(aStats.total_events).toBe(2);
+    expect(Number(bStats.total_value)).toBe(999);
+  });
+
+  it('Bad input: a guarded read fails closed with no tenant context (multi mode) — never full-scans', async () => {
+    // The raw guards bind getInstanceDid() into the WHERE; that same getter is
+    // the fail-closed foundation. In multi mode with no withTenant context it
+    // throws TENANT_CONTEXT_MISSING, so the guarded query is REFUSED rather than
+    // run unbound (which would scan every tenant's rows). Proven here on a single
+    // scoped op (no Promise.all fan-out -> no orphaned rejections).
+    const saved = process.env.PAYMENT_TENANT_MODE;
+    process.env.PAYMENT_TENANT_MODE = 'multi';
+    try {
+      await expect(Coupon.count()).rejects.toMatchObject({ code: TENANT_CONTEXT_MISSING });
+    } finally {
+      if (saved === undefined) delete process.env.PAYMENT_TENANT_MODE;
+      else process.env.PAYMENT_TENANT_MODE = saved;
+    }
+  });
+});
+
+describe('洞 H observability — assertJobObjectTenant emits TENANT_VIOLATION', () => {
+  it('a forged cross-tenant job logs a structured violation AND throws', async () => {
+    await withTenant(TENANT_A, () => {
+      // row belongs to B, job is running under A -> forged
+      let thrown: any;
+      try {
+        assertJobObjectTenant({ instance_did: TENANT_B });
+      } catch (err) {
+        thrown = err;
+      }
+      expect(thrown?.code).toBe(TENANT_MISMATCH);
+      expect((thrown as any)?.nonRetryable).toBe(true);
+      expect(logger.error).toHaveBeenCalledWith(
+        'TENANT_VIOLATION',
+        expect.objectContaining({ code: TENANT_MISMATCH, rowTenant: TENANT_B, jobTenant: TENANT_A })
+      );
+    });
+  });
+
+  it('a same-tenant job neither logs nor throws', async () => {
+    await withTenant(TENANT_A, () => {
+      expect(() => assertJobObjectTenant({ instance_did: TENANT_A })).not.toThrow();
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+  });
+
+  it('an absent object is the handler no-op path (no violation)', async () => {
+    await withTenant(TENANT_A, () => {
+      expect(() => assertJobObjectTenant(null)).not.toThrow();
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe('system* security — the bypass is explicit-only', () => {
+  it('a normal tenant context is NOT a system context', async () => {
+    await withTenant(TENANT_A, () => {
+      expect(isSystemContext()).toBe(false);
+    });
+  });
+
+  it('a normal context query stays scoped (cannot read cross-tenant)', async () => {
+    const bRow: any = await withTenant(TENANT_B, () =>
+      Coupon.create({ livemode: false, duration: 'once', name: 'b', created_via: 'api' } as any)
+    );
+    // bare findByPk under A -> scoped -> null (no leak)
+    const leaked = await withTenant(TENANT_A, () => Coupon.findByPk(bRow.id));
+    expect(leaked).toBeNull();
+  });
+
+  it('only the system* helper enters runAsSystem; it restores afterwards', async () => {
+    const bRow: any = await withTenant(TENANT_B, () =>
+      Coupon.create({ livemode: false, duration: 'once', name: 'b2', created_via: 'api' } as any)
+    );
+    await withTenant(TENANT_A, async () => {
+      // inside systemFindByPk the bypass is active -> cross-tenant row loads
+      const viaSystem = await systemFindByPk(Coupon, bRow.id);
+      expect(viaSystem).not.toBeNull();
+      // and the flag is restored the moment the helper settles
+      expect(isSystemContext()).toBe(false);
+      // so a subsequent bare read is scoped again
+      const leaked = await Coupon.findByPk(bRow.id);
+      expect(leaked).toBeNull();
+    });
+  });
+
+  it('runAsSystem is reentrant-safe and does not leak across withTenant siblings', async () => {
+    let insideFlag = false;
+    await context.runAsSystem(async () => {
+      insideFlag = isSystemContext();
+    });
+    expect(insideFlag).toBe(true);
+    // outside the span, flag is gone
+    expect(isSystemContext()).toBe(false);
+  });
+});
+
+describe('洞 F — eager include transitive safety (scoped root => same-tenant children)', () => {
+  // Base-class override does not fire for the JOIN itself, but the ROOT query is
+  // scoped, and associations join by globally-unique FK ids that belong to one
+  // tenant, so children follow the (scoped) root — no cross-tenant child rows.
+  const seedPromo = async (tenant: string, name: string) =>
+    withTenant(tenant, async () => {
+      const coupon: any = await Coupon.create({
+        livemode: false,
+        duration: 'once',
+        name,
+        created_via: 'api',
+      } as any);
+      return PromotionCode.create({
+        livemode: false,
+        active: true,
+        code: `CODE-${name}`,
+        coupon_id: coupon.id,
+      } as any);
+    });
+
+  it('findAll with include returns only the active tenant rows + their own coupon', async () => {
+    await seedPromo(TENANT_A, 'a');
+    await seedPromo(TENANT_B, 'b');
+
+    const aRows: any = await withTenant(TENANT_A, () =>
+      PromotionCode.findAll({ include: [{ model: Coupon, as: 'coupon' }] })
+    );
+    expect(aRows).toHaveLength(1);
+    expect(aRows[0].code).toBe('CODE-a');
+    expect(aRows[0].instance_did).toBe(TENANT_A);
+    // the eager-loaded child belongs to the same tenant (FK-consistent)
+    expect(aRows[0].coupon.instance_did).toBe(TENANT_A);
+    expect(aRows[0].coupon.name).toBe('a');
+  });
+});

package/api/third.d.ts

@@ -14,6 +14,10 @@ declare module 'flat';
 
 declare module '@abtnode/cron';
 
+declare module '@abtnode/constant';
+
+declare module '@abtnode/util/lib/get-token-from-req';
+
 declare module 'sql-where-parser';
 
 declare module 'cls-hooked';

package/blocklet.yml

@@ -14,7 +14,7 @@ repository:
   type: git
   url: git+https://github.com/blocklet/payment-kit.git
 specVersion: 1.2.8
-version: 1.29.0
+version: 1.29.2
 logo: logo.png
 files:
   - dist

package/cloudflare/README.md

@@ -8,7 +8,7 @@
 Payment Kit Worker
   ├── D1 Database           # 业务数据（customers/invoices/subscriptions ...）
   ├── KV: DID_CONNECT_KV    # DID Connect session 临时存储
-  ├── CF Queue              # 任务队列（fastq → CF Queue 适配）
+  ├── CF Queue              # 可选 executor 绑定；队列引擎是 api/src/libs/queue（node 引擎）
   ├── Hyperdrive            # （可选）连接 Postgres，仅在启用时使用
   ├── Service Binding
   │    ├── AUTH_SERVICE → blocklet-service (BlockletServiceRPC)
@@ -20,9 +20,29 @@ Payment Kit Worker
 
 - **Hono** 替代 Express（路由 + 中间件适配层）
 - **Sequelize-D1 shim** 替代 SQLite，表结构自动 sync
-- **CF Queue** 替代 fastq，加 D1-native cron fallback
 - **wrapAsyncListener** 追踪 `EventEmitter` async listener 的 Promise，防止 CF runtime 提前回收
 
+### worker 是 host adapter（Phase 12，2026-06）
+
+worker **不再自带**一套业务引擎。它只是一个 host adapter：
+
+- **业务 `/api` 入口统一经 `createEmbeddedPaymentService({ config, db, slots })`**，worker 只挂载
+  `svc.http.resourceRoutes`，DID-Connect 走 worker 自己的 Hono shell。worker **绝不**访问 `svc.handler`
+  （那是 node-only Express app 壳）——`ensurePaymentService` 用 Proxy 把 `.handler` 访问 trap 成 hard error。
+- **队列只有一套引擎** = `api/src/libs/queue`（node 引擎）。worker 不再用已删除的 `shims/queue.ts`。host 只替换
+  trigger / executor / flush：executor = `shims/fastq`，trigger = `scheduled()` 调 `dispatchDueJobs()`，
+  flush = `flushQueueWork()`，全部经 `api/src/libs/queue/runtime.ts` 这个 host-facing surface 驱动。
+  workerd 模式下 node 引擎的后台 `loop()` 被禁用（冻结的 isolate 不能跑后台 timer）。
+- **config 经 config slot 授权**：`envToPaymentCoreConfig(env)` → `setCoreConfig`，HTTP 与 scheduled/queue 两条
+  路径都不再有 `process.env` mirror。
+- **构建**：**`run-build.js` 是 standalone 的 CF deploy build**（`node run-build.js` → `wrangler deploy`），
+  带全部 bundle 优化（stripe-cf、axios-lite、native fetch、cbor-only、ethers wordlists drop、noop packages、
+  node builtin shims；见 `docs/2026-06-10-bundle-size-analysis.md`，gzip ~1 MiB，实测部署 + 支付路由验证过）。
+  Phase 12b/12c 只从中移除了两个已死的 plugin：`queue-shim`（option A：队列引擎统一为 `api/src/libs/queue`，
+  `shims/queue.ts` 已删）和 `lock-shim`（lock 已改成 Phase 8 driver，`shims/lock.ts` 已删）。
+  **`build.ts` 是 diagnostic/backup 构建**（`npx tsx build.ts`，arc-integration 诊断用）——它**不**带上述优化、
+  用不同的 node-builtin 策略，**不是** deploy build，部署一律用 `run-build.js`。
+
 ---
 
 ## ⚠️ 必须先部署的前置服务
@@ -465,8 +485,9 @@ wrangler d1 execute payment-kit-prod --remote \
 ```
 blocklets/core/cloudflare/
   ├── worker.ts              # Worker 入口（Hono 路由 + Express 适配）
-  ├── run-build.js           # esbuild 构建脚本
-  ├── build.ts               # 构建配置 + shim 别名映射
+  ├── run-build.js           # standalone CF deploy build（esbuild + 全部 bundle 优化）← 部署用这个
+  ├── build.ts               # diagnostic/backup 构建（更少优化；不是 deploy build）
+  ├── queue-runtime-mode.ts  # 把 core 队列引擎 pin 成 workerd（在业务队列加载前）
   ├── vite.config.ts         # 前端 Vite 构建配置
   ├── did-connect-auth.ts    # DID Connect 登录路由（挂载需要 APP_SK + DID_CONNECT_KV）
   ├── wrangler.jsonc         # 生产配置模板
@@ -480,8 +501,7 @@ blocklets/core/cloudflare/
   │   │   ├── verify-sign.ts #   组件签名验证（委托 AUTH_SERVICE）
   │   │   └── ...
   │   ├── sequelize-d1/      #   Sequelize → D1 适配
-  │   ├── queue.ts           #   fastq → CF Queue 适配
-  │   ├── lock.ts            #   分布式锁（D1 实现）
+  │   ├── fastq.ts           #   fastq executor 替身（队列引擎仍是 api/src/libs/queue）
   │   ├── cron.ts            #   定时任务
   │   └── ...
   └── test-aigne-hub/        # Gateway 集成参考实现