payment-kit 1.29.1 → 1.29.3

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

@@ -0,0 +1,245 @@
+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-a-'));
+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 — first batch (phase 5)', () => {
+  beforeEach(async () => {
+    await sequelize.query('DELETE FROM customers');
+    await sequelize.query('DELETE FROM jobs');
+  });
+
+  describe('happy path', () => {
+    it('push stamps the active tenant into the payload, job row included, handler runs in that tenant', async () => {
+      const seen: string[] = [];
+      const queue = createQueue({
+        name: `tm-happy-${Date.now()}`,
+        onJob: async (job: any) => {
+          // eslint-disable-next-line global-require
+          const { getInstanceDid } = require('../../src/libs/context');
+          seen.push(job.instance_did, getInstanceDid());
+        },
+      });
+
+      const handle = await withTenant(TENANT_A, async () => queue.push({ job: { businessId: 'x1' }, persist: true }));
+      await waitFor(handle, ['finished', 'failed']);
+      expect(seen).toEqual([TENANT_A, TENANT_A]);
+    });
+
+    it('handler object guard passes for matching tenants', async () => {
+      const customer = await withTenant(TENANT_A, () =>
+        models.Customer.create({ livemode: false, did: 'z-m-a', delinquent: false, instance_did: TENANT_A })
+      );
+      await withTenant(TENANT_A, async () => {
+        expect(() => assertJobObjectTenant(customer)).not.toThrow();
+      });
+    });
+  });
+
+  describe('bad input', () => {
+    it('multi mode push without tenant context is rejected at the gate', async () => {
+      process.env.PAYMENT_TENANT_MODE = 'multi';
+      try {
+        const queue = createQueue({ name: `tm-bad-${Date.now()}`, onJob: async () => {} });
+        expect(() => queue.push({ job: { businessId: 'x' } })).toThrow(
+          expect.objectContaining({ code: TENANT_CONTEXT_MISSING })
+        );
+      } finally {
+        delete process.env.PAYMENT_TENANT_MODE;
+      }
+    });
+
+    it('illegal tenant DID in the payload is refused', () => {
+      const queue = createQueue({ name: `tm-bad2-${Date.now()}`, onJob: async () => {} });
+      expect(() => queue.push({ job: { businessId: 'x', instance_did: 'a b' } })).toThrow(
+        expect.objectContaining({ code: TENANT_CONTEXT_MISSING })
+      );
+    });
+  });
+
+  describe('security: forged payload tenant vs object tenant', () => {
+    it('handler refuses to act on another tenant object; the object is untouched', async () => {
+      const victim = await withTenant(TENANT_B, () =>
+        models.Customer.create({ livemode: false, did: 'z-victim', delinquent: false, instance_did: TENANT_B })
+      );
+
+      let observedError: any;
+      const queue = createQueue({
+        name: `tm-forged-${Date.now()}`,
+        onJob: async (job: any) => {
+          // handlers load the tenant-stamped object cross-tenant (system) then
+          // enforce its tenant — mirrors the real queue handlers so a forged
+          // payload surfaces an observable TENANT_MISMATCH rather than folding
+          // into a scoped null (tenant-design §10).
+          const row: any = await systemFindByPk(models.Customer, job.customerId);
+          assertJobObjectTenant(row); // throws TENANT_MISMATCH
+          await row.update({ name: 'pwned' });
+        },
+      });
+      // forge: payload claims TENANT_A but targets B's customer
+      const handle = await withTenant(TENANT_A, async () =>
+        queue.push({ job: { customerId: victim.id }, persist: true })
+      );
+      const outcome = await waitFor(handle, ['failed', 'finished']);
+      observedError = (outcome.data as any).error;
+
+      expect(outcome.event).toBe('failed');
+      expect(observedError?.code).toBe(TENANT_MISMATCH);
+      const reloaded: any = await systemFindByPk(models.Customer, victim.id);
+      expect(reloaded.name).toBeNull(); // not 'pwned'
+      expect(reloaded.instance_did).toBe(TENANT_B);
+    });
+  });
+
+  describe('data loss: refused jobs surface as failures, not silence', () => {
+    it('the failed event fires with the tenant error attached', async () => {
+      const queue = createQueue({
+        name: `tm-fail-${Date.now()}`,
+        onJob: async () => {
+          const err: any = new Error('refused');
+          err.code = TENANT_MISMATCH;
+          err.nonRetryable = true;
+          throw err;
+        },
+      });
+      const handle = await withTenant(TENANT_A, async () => queue.push({ job: { businessId: 'x' }, persist: true }));
+      const outcome = await waitFor(handle, ['failed', 'finished']);
+      expect(outcome.event).toBe('failed');
+      expect((outcome.data as any).error?.code).toBe(TENANT_MISMATCH);
+    });
+  });
+
+  describe('data damage: retries keep the original tenant', () => {
+    it('a retried job re-executes under the same tenant, never a different one', async () => {
+      const tenantsSeen: string[] = [];
+      const queue = createQueue({
+        name: `tm-retry-${Date.now()}`,
+        onJob: async (job: any) => {
+          tenantsSeen.push(job.instance_did);
+          if (tenantsSeen.length < 2) throw new Error('transient');
+        },
+        options: { maxRetries: 2, retryDelay: 1 },
+      });
+      const handle = await withTenant(TENANT_B, async () => queue.push({ job: { businessId: 'r1' }, persist: true }));
+      await waitFor(handle, ['finished', 'failed']);
+      expect(tenantsSeen.length).toBeGreaterThanOrEqual(2);
+      expect(new Set(tenantsSeen)).toEqual(new Set([TENANT_B]));
+    });
+  });
+
+  // NOTE: spec's "channel-identifier job id prefix" row converts to a no-op
+  // for Phase 5 queues — all job ids are internal globally-unique business
+  // ids (see queue-matrix.md); channel-identifier dedup moves to Phase 6
+  // integrations as (instance_did, identifier) composite keys.
+  describe('data leak: legacy job strategy', () => {
+    it('a pre-tenant job (no instance_did) executes under the default tenant in single mode', async () => {
+      const seen: string[] = [];
+      const queue = createQueue({
+        name: `tm-legacy-${Date.now()}`,
+        onJob: async () => {
+          // eslint-disable-next-line global-require
+          const { getInstanceDid } = require('../../src/libs/context');
+          seen.push(getInstanceDid());
+        },
+      });
+      // simulate a legacy row: bypass push's injection by writing the store directly
+      await queue.store.addJob('legacy-1', { businessId: 'legacy' }, {});
+      const row = await queue.get('legacy-1');
+      expect(row.instance_did).toBeUndefined();
+      // re-deliver it the way startup recovery does (push with persist=false keeps payload as-is? no — push injects)
+      // execution path: runJobWithTenant falls back to the default tenant
+      const handle = queue.push({
+        job: row,
+        id: 'legacy-1',
+        persist: false,
+        skipDuplicateCheck: true,
+        fromStore: true,
+      });
+      await waitFor(handle, ['finished', 'failed']);
+      // eslint-disable-next-line global-require
+      const { getDefaultInstanceDid } = require('../../src/libs/tenant');
+      expect(seen).toEqual([getDefaultInstanceDid()]);
+    });
+
+    it('a legacy job is refused permanently in multi mode (structured, non-retryable)', async () => {
+      const queue = createQueue({
+        name: `tm-legacy-multi-${Date.now()}`,
+        onJob: async () => 'should-not-run',
+      });
+      process.env.PAYMENT_TENANT_MODE = 'multi';
+      try {
+        const handle = queue.push({
+          job: { businessId: 'legacy-multi' },
+          id: 'legacy-multi-1',
+          persist: false,
+          fromStore: true, // store re-delivery path: gate skipped, execution-side refuses
+        });
+        const outcome = await waitFor(handle, ['failed', 'finished']);
+        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);
+      } finally {
+        delete process.env.PAYMENT_TENANT_MODE;
+      }
+    });
+  });
+});

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/service/didconnect-storage-slot.spec.ts

@@ -0,0 +1,60 @@
+// S3-CF Phase 1 inversion ③ — DID-Connect token storage slot.
+//
+// The DID-Connect token handshake store is now a host-injected slot (same
+// reversal as db/queue/cron). The CF worker injects a D1-backed store so the
+// token state lands in PAYMENT_DB; node hosts omit it and keep the file-backed
+// nedb default. This spec locks the factory→libs/auth wiring and the default.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { Sequelize } from 'sequelize';
+
+import * as auth from '../../src/libs/auth';
+import { createEmbeddedPaymentService } from '../../src/service';
+
+function freshSequelize(): Sequelize {
+  const dbFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'pay-storage-slot-')), 'test.db');
+  return new Sequelize({ dialect: 'sqlite', storage: dbFile, logging: false });
+}
+
+const baseConfig = { BLOCKLET_APP_PID: 'zMOCK_STORAGE_SLOT' };
+
+describe('Phase 1 (S3-CF) ③ — DID-Connect token storage slot', () => {
+  afterEach(() => {
+    // reset the module-level injection so specs don't leak into each other
+    auth.setDidConnectTokenStorage(null);
+    jest.restoreAllMocks();
+  });
+
+  it('wires a host-provided storage slot into libs/auth (setDidConnectTokenStorage)', () => {
+    const spy = jest.spyOn(auth, 'setDidConnectTokenStorage');
+    const sentinel: auth.DidConnectTokenStorage = {
+      read: async () => null,
+      create: async () => undefined,
+      update: async () => undefined,
+      delete: async () => undefined,
+    };
+
+    createEmbeddedPaymentService({
+      config: baseConfig,
+      db: { sequelize: freshSequelize() },
+      tenancy: { mode: 'single', instanceDid: 'zMOCK_STORAGE_SLOT' },
+      storage: sentinel,
+    });
+
+    expect(spy).toHaveBeenCalledWith(sentinel);
+  });
+
+  it('omitting the slot leaves the node nedb default (setter never called)', () => {
+    const spy = jest.spyOn(auth, 'setDidConnectTokenStorage');
+
+    createEmbeddedPaymentService({
+      config: baseConfig,
+      db: { sequelize: freshSequelize() },
+      tenancy: { mode: 'single', instanceDid: 'zMOCK_STORAGE_SLOT' },
+    });
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+});