@jskit-ai/payments-core 0.1.1

package/test/checkout.test.js

@@ -0,0 +1,229 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createHmac } from 'node:crypto';
+import knex from 'knex';
+import Stripe from 'stripe';
+import { Paddle, Environment } from '@paddle/paddle-node-sdk';
+import migration from '../migrations/payments_core_initial.cjs';
+import { createKnexPaymentStore } from '../src/server/knexStore.js';
+import { createPaymentService } from '../src/server/service.js';
+import { createPaymentCheckoutService } from '../src/server/checkout.js';
+import { createStripePaymentAdapter } from '../src/server/stripe.js';
+import { createPaddlePaymentAdapter } from '../src/server/paddle.js';
+
+const scope = { applicationId: 'app', integrationId: 'billing', providerAccountId: 'acct_a', environment: 'sandbox' };
+const secret = 'test-signing-secret';
+
+test('official SDK signature verification rejects mutation and expired delivery for both providers', async () => {
+  const stripeClient = new Stripe('sk_test_fixture', { maxNetworkRetries: 0 });
+  const stripe = createStripePaymentAdapter({ client: stripeClient, webhookSecret: secret, environment: 'sandbox', providerAccountId: 'acct_a', priceBindings: { pro: 'price_a' } });
+  const raw = Buffer.from(JSON.stringify({ id: 'evt_a', type: 'customer.created', livemode: false, data: { object: { id: 'cus_a' } } }));
+  const header = stripeClient.webhooks.generateTestHeaderString({ payload: raw.toString(), secret });
+  assert.equal((await stripe.verifyEvent(raw, header)).id, 'evt_a');
+  await assert.rejects(stripe.verifyEvent(Buffer.concat([raw, Buffer.from(' ')]), header), { code: 'payment_signature_invalid' });
+  await assert.rejects(stripe.verifyEvent(raw, stripeClient.webhooks.generateTestHeaderString({ payload: raw.toString(), secret, timestamp: 1 })), { code: 'payment_signature_invalid' });
+  await assert.rejects(stripe.verifyEvent(raw.toString(), header), { code: 'payment_signature_invalid' });
+  const paddleClient = new Paddle('test-fixture', { environment: Environment.sandbox });
+  const paddle = createPaddlePaymentAdapter({ client: paddleClient, webhookSecret: secret, environment: 'sandbox', priceBindings: { pro: 'pri_a' } });
+  const paddleRaw = Buffer.from(JSON.stringify({ event_id: 'evt_a', event_type: 'customer.created', occurred_at: new Date().toISOString(), data: { id: 'ctm_a', email: 'test@example.com', status: 'active', marketing_consent: false, custom_data: null, import_meta: null } }));
+  const signature = (ts) => `ts=${ts};h1=${createHmac('sha256', secret).update(`${ts}:${paddleRaw.toString()}`).digest('hex')}`;
+  const currentSignature = signature(Math.floor(Date.now() / 1000));
+  assert.equal((await paddle.verifyEvent(paddleRaw, currentSignature)).eventId, 'evt_a');
+  await assert.rejects(paddle.verifyEvent(Buffer.concat([paddleRaw, Buffer.from(' ')]), currentSignature), { code: 'payment_signature_invalid' });
+  await assert.rejects(paddle.verifyEvent(paddleRaw, signature(1)), { code: 'payment_signature_invalid' });
+});
+
+test('checkout authorizes before provider access, persists intent, deduplicates requests and needs explicit recovery', async () => {
+  const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
+  await migration.up(db);
+  const store = createKnexPaymentStore({ knex: db });
+  let creates = 0;
+  let fails = false;
+  const adapter = {
+    validatePlan(planId) { assert.equal(planId, 'pro'); },
+    async createCustomer() { creates++; return 'cus_a'; },
+    async createCheckout() {
+      creates++;
+      assert.equal((await store.inspect({ ...scope, subjectId: 'tenant-a' })).pendingPaymentOperation.action, 'checkout');
+      if (fails) throw new Error('uncertain provider timeout');
+      return { id: 'cs_a', url: 'https://checkout.stripe.com/example' };
+    },
+    async createPortal() { return { id: 'portal_a', url: 'https://billing.stripe.com/example' }; }
+  };
+  const service = createPaymentCheckoutService({ adapter, store, payments: { inspect: async () => ({ balance: 0, features: [], subscriptions: [] }) }, merchantScope: scope, returnUrl: 'https://app.example/billing', authorize: async (actor, { subjectId }) => actor === subjectId });
+  const input = { actor: 'tenant-a', subjectId: 'tenant-a', email: 'tenant@example.com', planId: 'pro', requestId: 'request-1' };
+  try {
+    await assert.rejects(service.checkout({ ...input, actor: 'tenant-b' }), { code: 'payment_forbidden' });
+    assert.equal(creates, 0);
+    await assert.rejects(service.reconcilePending({ actor: 'tenant-b', subjectId: 'tenant-a', inspectProvider: async () => { assert.fail('denied recovery cannot inspect the provider'); } }), { code: 'payment_forbidden' });
+    assert.equal((await db('payment_accounts')).length, 0, 'denied operations create no account state');
+    await assert.rejects(service.account({ actor: 'tenant-b', subjectId: 'tenant-a' }), { code: 'payment_forbidden' });
+    assert.deepEqual(await service.account({ actor: 'tenant-a', subjectId: 'tenant-a' }), { balance: 0, features: [], subscriptions: [], hasCustomer: false });
+    assert.equal((await service.checkout(input)).id, 'cs_a');
+    assert.equal((await service.checkout(input)).id, 'cs_a');
+    assert.equal(creates, 2);
+    assert.equal((await service.account({ actor: 'tenant-a', subjectId: 'tenant-a' })).hasCustomer, true);
+    assert.equal(await store.resolveCustomer(scope, 'cus_a'), 'tenant-a');
+    await assert.rejects(service.portal({ actor: 'tenant-b', subjectId: 'tenant-a' }), { code: 'payment_forbidden' });
+    fails = true;
+    await assert.rejects(service.checkout({ ...input, requestId: 'request-2' }), { code: 'payment_operation_uncertain' });
+    await assert.rejects(service.checkout({ ...input, requestId: 'request-2' }), { code: 'payment_operation_uncertain' });
+    assert.equal(creates, 3);
+    await assert.rejects(service.reconcilePending({ actor: 'tenant-a', subjectId: 'tenant-a', inspectProvider: async () => ({}) }), { code: 'payment_reconciliation_required' });
+    await service.reconcilePending({ actor: 'tenant-a', subjectId: 'tenant-a', inspectProvider: async () => ({ result: { id: 'cs_recovered', url: 'https://checkout.stripe.com/recovered' } }) });
+    assert.equal((await service.checkout({ ...input, requestId: 'request-2' })).id, 'cs_recovered');
+    await store.withAccount({ ...scope, subjectId: 'tenant-a' }, async (tx) => {
+      tx.state.subscriptions.sub_a = { id: 'sub_a', status: 'past_due', planId: 'pro', periodEnd: 0 };
+    });
+    await assert.rejects(service.checkout({ ...input, requestId: 'request-3' }), { code: 'payment_subscription_exists' });
+    // A lost response can still be recovered using its original intent identity.
+    assert.equal((await service.checkout(input)).id, 'cs_a');
+    assert.equal(creates, 3);
+  } finally { await migration.down(db); await db.destroy(); }
+});
+
+test('Stripe reconciliation loads current subscription and validates invoice account, quantity and price', async () => {
+  const subscription = { id: 'sub_a', customer: 'cus_a', livemode: false, status: 'active', items: { has_more: false, data: [{ quantity: 1, price: { id: 'price_a' }, current_period_end: 20000 }] } };
+  const invoice = { id: 'in_a', customer: 'cus_a', livemode: false, status: 'paid', billing_reason: 'subscription_cycle', parent: { subscription_details: { subscription: 'sub_a' } }, lines: { has_more: false, data: [{ quantity: 1, parent: { subscription_item_details: { proration: false } }, pricing: { price_details: { price: 'price_a' } }, period: { end: 20000 } }] } };
+  const client = { accounts: { retrieve: async () => ({ id: 'acct_a' }) }, balance: { retrieve: async () => ({ livemode: false }) }, subscriptions: { retrieve: async () => subscription }, invoices: { retrieve: async () => invoice } };
+  const adapter = createStripePaymentAdapter({ client, webhookSecret: secret, environment: 'sandbox', providerAccountId: 'acct_a', priceBindings: { pro: 'price_a' } });
+  const event = { type: 'invoice.paid', data: { object: { id: 'in_a' } } };
+  assert.equal((await adapter.loadEvent(event)).renewal.planId, 'pro');
+  invoice.status = 'open';
+  subscription.status = 'past_due';
+  event.type = 'invoice.payment_failed';
+  const failed = await adapter.loadEvent(event);
+  assert.equal(failed.subscription.status, 'past_due');
+  assert.equal(failed.renewal, undefined);
+  // A delayed failure delivery reads current provider state after recovery.
+  invoice.status = 'paid';
+  subscription.status = 'active';
+  assert.equal((await adapter.loadEvent(event)).renewal.id, 'in_a');
+  subscription.status = 'canceled';
+  assert.equal((await adapter.loadEvent(event)).subscription.status, 'canceled');
+  invoice.billing_reason = 'subscription_update';
+  assert.equal((await adapter.loadEvent(event)).renewal, undefined);
+  invoice.customer = 'cus_other';
+  await assert.rejects(adapter.loadEvent(event), { code: 'payment_provider_result_invalid' });
+});
+
+test('signed standalone Stripe invoices are ignored before customer lookup; malformed and tampered events fail', async () => {
+  const client = new Stripe('sk_test_fixture', { maxNetworkRetries: 0 });
+  const adapter = createStripePaymentAdapter({ client, webhookSecret: secret, environment: 'sandbox', providerAccountId: 'acct_a', priceBindings: {} });
+  let reconciliations = 0;
+  const service = createPaymentCheckoutService({ adapter, merchantScope: scope, returnUrl: 'https://app.example/billing', authorize: async () => false,
+    payments: { async reconcileEvent() { reconciliations++; } } });
+  const event = { id: 'evt_oneoff', type: 'invoice.paid', livemode: false, data: { object: { id: 'in_oneoff', customer: 'cus_unrelated', parent: null } } };
+  const rawBody = Buffer.from(JSON.stringify(event));
+  const signature = client.webhooks.generateTestHeaderString({ payload: rawBody.toString(), secret });
+  assert.deepEqual(await service.webhook({ rawBody, signature }), { ignored: true });
+  assert.equal(reconciliations, 0);
+  await assert.rejects(service.webhook({ rawBody: Buffer.concat([rawBody, Buffer.from(' ')]), signature }), { code: 'payment_signature_invalid' });
+  delete event.data.object.parent;
+  assert.throws(() => adapter.eventIdentity(event), { code: 'payment_provider_result_invalid' });
+  event.type = 'invoice.payment_failed';
+  event.data.object.parent = { subscription_details: { subscription: 'sub_a' } };
+  assert.deepEqual(adapter.eventIdentity(event), { eventId: 'evt_oneoff', customerId: 'cus_unrelated' });
+});
+
+test('Paddle event identity separates standalone transactions from subscription updates', () => {
+  const adapter = createPaddlePaymentAdapter({ client: {}, webhookSecret: secret, environment: 'sandbox', priceBindings: {} });
+  const event = { eventId: 'evt_a', eventType: 'transaction.completed', data: { subscriptionId: null, customerId: 'ctm_a' } };
+  assert.equal(adapter.eventIdentity(event), null);
+  delete event.data.subscriptionId;
+  assert.throws(() => adapter.eventIdentity(event), { code: 'payment_provider_result_invalid' });
+  event.data.subscriptionId = 'sub_a';
+  assert.deepEqual(adapter.eventIdentity(event), { eventId: 'evt_a', customerId: 'ctm_a' });
+  event.eventType = 'subscription.past_due';
+  assert.deepEqual(adapter.eventIdentity(event), { eventId: 'evt_a', customerId: 'ctm_a' });
+  event.eventType = 'customer.created';
+  assert.equal(adapter.eventIdentity(event), null);
+});
+
+test('Paddle reconciliation uses current status and grants only qualifying completed renewals', async () => {
+  const subscription = { id: 'sub_a', customerId: 'ctm_a', status: 'active', items: [{ quantity: 1, price: { id: 'pri_a' } }], currentBillingPeriod: { endsAt: '2030-01-01T00:00:00Z' } };
+  const transaction = { id: 'txn_a', customerId: 'ctm_a', subscriptionId: 'sub_a', status: 'completed', origin: 'subscription_recurring', items: [{ quantity: 1, price: { id: 'pri_a' }, proration: null }], billingPeriod: { endsAt: '2030-01-01T00:00:00Z' } };
+  const client = { subscriptions: { get: async () => subscription }, transactions: { get: async () => transaction } };
+  const adapter = createPaddlePaymentAdapter({ client, webhookSecret: secret, environment: 'sandbox', priceBindings: { pro: 'pri_a' } });
+  const event = { eventType: 'transaction.completed', data: { id: 'txn_a' } };
+  assert.equal((await adapter.loadEvent(event)).renewal.id, 'txn_a');
+  transaction.origin = 'subscription_update';
+  assert.equal((await adapter.loadEvent(event)).renewal, undefined);
+  subscription.status = 'paused';
+  subscription.currentBillingPeriod = null;
+  const paused = await adapter.loadEvent({ eventType: 'subscription.updated', data: { id: 'sub_a' } });
+  assert.equal(paused.subscription.status, 'paused');
+  assert.equal(paused.subscription.periodEnd, 0);
+  assert.equal(paused.renewal, undefined);
+  transaction.customerId = 'ctm_other';
+  await assert.rejects(adapter.loadEvent(event), { code: 'payment_provider_result_invalid' });
+});
+
+
+test('signed subscription lifecycle updates app access without crossing subjects or environments', async () => {
+  const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
+  await migration.up(db);
+  const store = createKnexPaymentStore({ knex: db });
+  const stripeSdk = new Stripe('sk_test_fixture', { maxNetworkRetries: 0 });
+  const paddleSdk = new Paddle('test-fixture', { environment: Environment.sandbox });
+  try {
+    for (const provider of ['stripe', 'paddle']) {
+      const merchant = { ...scope, applicationId: provider };
+      const subject = { ...merchant, subjectId: 'tenant-a' };
+      let now = Date.parse('2030-01-01T00:00:00Z');
+      const end = Date.parse('2030-02-01T00:00:00Z');
+      let status = 'active';
+      let customerId = 'customer_a';
+      let loads = 0;
+      const payments = createPaymentService({ store, clock: () => now, configuration: {
+        environments: { sandbox: { integrationId: merchant.integrationId, providerAccountId: merchant.providerAccountId } },
+        plans: { pro: { features: ['export'], renewalCredits: 100 } }
+      } });
+      const adapter = provider === 'stripe'
+        ? createStripePaymentAdapter({ webhookSecret: secret, environment: 'sandbox', providerAccountId: 'acct_a', priceBindings: { pro: 'price_a' }, client: {
+          webhooks: stripeSdk.webhooks,
+          accounts: { retrieve: async () => ({ id: 'acct_a' }) }, balance: { retrieve: async () => ({ livemode: false }) },
+          subscriptions: { retrieve: async () => { loads++; return { id: 'sub_a', customer: customerId, livemode: false, status, items: { has_more: false, data: [{ quantity: 1, price: { id: 'price_a' }, current_period_end: end / 1000 }] } }; } }
+        } })
+        : createPaddlePaymentAdapter({ webhookSecret: secret, environment: 'sandbox', priceBindings: { pro: 'pri_a' }, client: {
+          webhooks: paddleSdk.webhooks,
+          subscriptions: { get: async () => { loads++; return { id: 'sub_a', customerId, status, items: [{ quantity: 1, price: { id: 'pri_a' } }], currentBillingPeriod: { endsAt: new Date(end).toISOString() } }; } }
+        } });
+      const checkout = createPaymentCheckoutService({ adapter, store, payments, merchantScope: merchant, returnUrl: 'https://app.example/billing', authorize: async () => false });
+      await store.bindCustomer(merchant, 'customer_a', 'tenant-a');
+      const deliver = async (id, eventCustomer = 'customer_a') => {
+        const payload = provider === 'stripe'
+          ? { id, type: 'customer.subscription.updated', livemode: false, data: { object: { id: 'sub_a', customer: eventCustomer } } }
+          : { event_id: id, event_type: 'subscription.updated', occurred_at: new Date().toISOString(), data: { id: 'sub_a', customer_id: eventCustomer, billing_cycle: { interval: 'month', frequency: 1 }, items: [] } };
+        const rawBody = Buffer.from(JSON.stringify(payload));
+        const ts = Math.floor(Date.now() / 1000);
+        const signature = provider === 'stripe'
+          ? stripeSdk.webhooks.generateTestHeaderString({ payload: rawBody.toString(), secret })
+          : `ts=${ts};h1=${createHmac('sha256', secret).update(`${ts}:${rawBody.toString()}`).digest('hex')}`;
+        return checkout.webhook({ rawBody, signature });
+      };
+      for (const [index, next] of ['active', 'past_due', 'active', 'paused', 'canceled'].entries()) {
+        status = next;
+        await deliver(`event_${index}`);
+        const state = await payments.inspect(subject);
+        assert.deepEqual(state.features, next === 'active' ? ['export'] : [], `${provider}: ${next}`);
+        assert.equal(state.balance, 0, 'a subscription event alone never grants renewal credits');
+        assert.equal((await payments.inspect({ ...subject, subjectId: 'tenant-b' })).subscriptions.length, 0);
+        assert.equal((await store.inspect({ ...subject, environment: 'live' })).subscriptions.sub_a, undefined);
+      }
+      const previousLoads = loads;
+      assert.equal((await deliver('event_4')).duplicate, true);
+      assert.equal(loads, previousLoads, 'duplicate delivery does not call the provider again');
+      customerId = 'customer_other';
+      await assert.rejects(deliver('event_foreign'), { code: 'payment_provider_result_invalid' });
+      assert.equal((await payments.inspect(subject)).subscriptions[0].status, 'canceled');
+      customerId = 'customer_a';
+      status = 'active';
+      await deliver('event_foreign'); // failed verification must not commit a receipt
+      await payments.requireFeature(subject, 'export');
+      now = end;
+      await assert.rejects(payments.requireFeature(subject, 'export'), { code: 'payment_feature_required' });
+      await assert.rejects(deliver('event_unbound', 'customer_unbound'), { code: 'payment_customer_unbound' });
+    }
+  } finally { await migration.down(db); await db.destroy(); }
+});

package/test/conformance.test.js

@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import Ajv from 'ajv';
+import knex from 'knex';
+import migration from '../migrations/payments_core_initial.cjs';
+import { validatePaymentConfiguration } from '../src/shared/configuration.js';
+import { createPaymentService } from '../src/server/service.js';
+import { createKnexPaymentStore } from '../src/server/knexStore.js';
+
+const fixture = JSON.parse(await readFile(new URL('../contracts/conformance.json', import.meta.url), 'utf8'));
+const schema = JSON.parse(await readFile(new URL('../contracts/configuration.schema.json', import.meta.url), 'utf8'));
+
+test('portable configuration fixtures distinguish JSON Schema from cross-reference validation', () => {
+  const validate = new Ajv({ strict: true }).compile(schema);
+  for (const item of fixture.configurationCases) {
+    assert.equal(validate(item.document.extensions.payments), item.schemaValid, item.id);
+    if (item.configurationValid) assert.deepEqual(validatePaymentConfiguration(item.document), item.document.extensions.payments, item.id);
+    else assert.throws(() => validatePaymentConfiguration(item.document), { code: 'payment_configuration_invalid' }, item.id);
+  }
+});
+
+test('payment binding errors identify the field to repair without returning credentials', () => {
+  const cases = [
+    ['missing-connection', 'integrationId', /shared Stripe or Paddle/],
+    ['inline-api-key', 'integrationId', /Env reference/],
+    ['paddle-environment-mismatch', 'integrationId', /configured for sandbox/],
+    ['paddle-client-token-missing', 'publicClientTokenRef', /public client token/]
+  ];
+  for (const [id, field, message] of cases) {
+    const item = fixture.configurationCases.find((entry) => entry.id === id);
+    assert.throws(() => validatePaymentConfiguration(item.document), (error) => {
+      assert.equal(error.code, 'payment_configuration_invalid');
+      assert.equal(error.statusCode, 422);
+      assert.ok(error.fieldErrors.some((entry) => entry.path === `extensions.payments/environments/sandbox/${field}` && message.test(entry.message)), id);
+      assert.doesNotMatch(JSON.stringify(error.fieldErrors), /not-an-env-reference/);
+      return true;
+    });
+  }
+  const document = structuredClone(fixture.configurationCases.find((entry) => entry.id === 'paddle-sandbox').document);
+  delete document.extensions.payments.environments.sandbox.taxCategory;
+  delete document.extensions.payments.environments.sandbox.publicClientTokenRef;
+  assert.throws(() => validatePaymentConfiguration(document), (error) => {
+    assert.deepEqual(error.fieldErrors.map((entry) => entry.path), [
+      'extensions.payments/environments/sandbox/taxCategory',
+      'extensions.payments/environments/sandbox/publicClientTokenRef'
+    ]);
+    return true;
+  });
+});
+
+test('portable account sequence defines actual credit, renewal, expiry and subject-isolation outcomes', async () => {
+  const scenario = fixture.accountScenario;
+  const db = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
+  await migration.up(db);
+  const store = createKnexPaymentStore({ knex: db });
+  let now = scenario.clock;
+  const service = createPaymentService({ store, configuration: validatePaymentConfiguration(scenario.document), clock: () => now });
+  const { subjectId, ...merchant } = scenario.scope;
+  // Expected objects assert the listed fields recursively; arrays are exact.
+  const compare = (actual, expected) => {
+    if (!expected || typeof expected !== 'object' || Array.isArray(expected)) return assert.deepEqual(actual, expected);
+    for (const [key, value] of Object.entries(expected)) compare(actual[key], value);
+  };
+  try {
+    await store.bindCustomer(merchant, scenario.customerId, subjectId);
+    for (const step of scenario.steps) {
+      if (step.clock !== undefined) now = step.clock;
+      const scope = { ...scenario.scope, subjectId: step.subjectId ?? subjectId };
+      const run = () => step.operation === 'reconcileEvent'
+        ? service.reconcileEvent(merchant, { ...step.input, load: async () => structuredClone(step.facts) })
+        : service[step.operation](scope, step.input);
+      if (step.error) await assert.rejects(run(), { code: step.error });
+      else compare(await run(), step.expect);
+    }
+  } finally { await migration.down(db); await db.destroy(); }
+});

package/test/history.test.js

@@ -0,0 +1,105 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createPaymentCheckoutService } from '../src/server/checkout.js';
+import { createStripePaymentAdapter } from '../src/server/stripe.js';
+import { createPaddlePaymentAdapter } from '../src/server/paddle.js';
+
+const merchant = { applicationId: 'app', integrationId: 'billing', providerAccountId: 'acct_a', environment: 'sandbox' };
+
+test('every subject billing entry point requires explicit authorization before touching state', async () => {
+  const touched = [];
+  const forbidden = new Proxy({}, { get(_target, key) { touched.push(key); throw new Error('Unauthorized dependency access'); } });
+  const actions = { account: 'account', history: 'history', checkout: 'checkout', portal: 'portal', reconcilePending: 'reconcile' };
+  for (const decision of [false, undefined, null, 'true', 1, { allowed: true }]) {
+    const requests = [];
+    const service = createPaymentCheckoutService({ merchantScope: merchant, returnUrl: 'https://example.com/billing',
+      store: forbidden, adapter: forbidden, payments: forbidden,
+      authorize: async (actor, request) => { requests.push({ actor, ...request }); return decision; }
+    });
+    for (const [method, action] of Object.entries(actions)) {
+      await assert.rejects(service[method]({ actor: 'editor-owner', subjectId: 'tenant-a',
+        collection: 'transactions', email: 'person@example.com', planId: 'pro', requestId: 'request-a',
+        inspectProvider: async () => { touched.push('provider-inspection'); }
+      }), { code: 'payment_forbidden' });
+      assert.deepEqual(requests.at(-1), { actor: 'editor-owner', subjectId: 'tenant-a', action });
+    }
+  }
+  assert.deepEqual(touched, [], 'denied calls cannot read state, contact providers or inspect recovery');
+});
+
+test('history authorizes the subject before storage or network and never accepts a caller customer ID', async () => {
+  const reads = [];
+  let boundCustomer = 'cus_owned';
+  const service = createPaymentCheckoutService({ merchantScope: merchant, returnUrl: 'https://example.com/billing',
+    authorize: async (actor, request) => actor === 'billing-admin' && request.subjectId === 'tenant-a' && request.action === 'history',
+    store: { async inspect(scope) { reads.push(scope); return { customerId: boundCustomer }; } },
+    adapter: { async readHistory(query) { reads.push(query); return { collection: query.collection, items: [], nextCursor: null }; } }
+  });
+  await assert.rejects(service.history({ actor: 'tenant-b', subjectId: 'tenant-a', collection: 'transactions' }), { code: 'payment_forbidden' });
+  await assert.rejects(service.history({ actor: 'billing-admin', subjectId: 'tenant-b', collection: 'transactions' }), { code: 'payment_forbidden' });
+  assert.equal(reads.length, 0);
+  const input = { actor: 'billing-admin', subjectId: 'tenant-a', collection: 'transactions' };
+  await assert.rejects(service.history({ ...input, after: 'https://attacker.example' }), { code: 'payment_input_invalid' });
+  await assert.rejects(service.history({ ...input, collection: 'customers' }), { code: 'payment_input_invalid' });
+  assert.equal(reads.length, 0);
+  await service.history({ ...input, customerId: 'cus_attacker', after: 'in_previous' });
+  assert.deepEqual(reads, [{ ...merchant, subjectId: 'tenant-a' }, { customerId: 'cus_owned', collection: 'transactions', after: 'in_previous' }]);
+  boundCustomer = null;
+  reads.length = 0;
+  assert.deepEqual(await service.history(input), { collection: 'transactions', items: [], nextCursor: null });
+  assert.equal(reads.length, 1);
+});
+
+test('history errors do not expose provider credentials or diagnostics', async () => {
+  const service = createPaymentCheckoutService({ merchantScope: merchant, returnUrl: 'https://example.com/billing', authorize: async () => true,
+    store: { inspect: async () => ({ customerId: 'cus_a' }) }, adapter: { readHistory: async () => { throw new Error('sk_secret customer_private@example.com'); } } });
+  await assert.rejects(service.history({ actor: 'admin', subjectId: 'a', collection: 'transactions' }), (error) => {
+    assert.equal(error.code, 'payment_history_unavailable');
+    assert.doesNotMatch(error.message, /sk_secret|customer_private/);
+    return true;
+  });
+});
+
+test('Stripe history uses customer-filtered single pages, includes canceled subscriptions, and projects billing facts only', async () => {
+  const queries = [];
+  const invoice = { id: 'in_a', customer: 'cus_a', livemode: false, created: 1700000000, status: 'open', total: 1200, amount_paid: 0, currency: 'usd', customer_email: 'private@example.com', metadata: { secret: 'hidden' }, hosted_invoice_url: 'https://private.example' };
+  let accountId = 'acct_a';
+  const client = { accounts: { retrieve: async () => ({ id: accountId }) }, balance: { retrieve: async () => ({ livemode: false }) },
+    invoices: { list: async (query) => { queries.push(query); return { data: [invoice], has_more: true }; } },
+    subscriptions: { list: async (query) => { queries.push(query); return { data: [{ id: 'sub_a', customer: 'cus_a', livemode: false, created: 1700000000, status: 'canceled', metadata: { hidden: true } }], has_more: false }; } } };
+  const adapter = createStripePaymentAdapter({ client, webhookSecret: 'fixture', environment: 'sandbox', providerAccountId: 'acct_a', priceBindings: {} });
+  const result = await adapter.readHistory({ customerId: 'cus_a', collection: 'transactions', after: 'in_previous' });
+  assert.deepEqual(queries[0], { customer: 'cus_a', limit: 20, starting_after: 'in_previous' });
+  assert.deepEqual(result, { collection: 'transactions', items: [{ id: 'in_a', kind: 'invoice', status: 'open', createdAt: '2023-11-14T22:13:20.000Z', currency: 'USD', totalMinor: '1200', paidMinor: '0' }], nextCursor: 'in_a' });
+  assert.equal((await adapter.readHistory({ customerId: 'cus_a', collection: 'subscriptions' })).items[0].status, 'canceled');
+  assert.deepEqual(queries[1], { customer: 'cus_a', limit: 20, status: 'all' });
+  invoice.customer = 'cus_other';
+  await assert.rejects(adapter.readHistory({ customerId: 'cus_a', collection: 'transactions' }), { code: 'payment_provider_result_invalid' });
+  invoice.customer = 'cus_a';
+  invoice.livemode = true;
+  await assert.rejects(adapter.readHistory({ customerId: 'cus_a', collection: 'transactions' }), { code: 'payment_provider_result_invalid' });
+  accountId = 'acct_other';
+  const prior = queries.length;
+  await assert.rejects(adapter.readHistory({ customerId: 'cus_a', collection: 'transactions' }), { code: 'payment_provider_result_invalid' });
+  assert.equal(queries.length, prior);
+});
+
+test('Paddle history preserves amount strings, distinguishes unpaid totals and fetches one customer-filtered page', async () => {
+  let pages = 0;
+  const queries = [];
+  const record = { id: 'txn_a', customerId: 'ctm_a', status: 'billed', createdAt: '2030-01-01T00:00:00Z', currencyCode: 'USD', details: { totals: { total: '9007199254740993' } }, checkout: { url: 'https://private.example' }, customData: { secret: 'hidden' } };
+  const list = (query) => { queries.push(query); return { hasMore: true, async next() { pages++; return [record]; } }; };
+  const adapter = createPaddlePaymentAdapter({ client: { transactions: { list }, subscriptions: { list } }, webhookSecret: 'fixture', environment: 'sandbox', priceBindings: {} });
+  assert.deepEqual(await adapter.readHistory({ customerId: 'ctm_a', collection: 'transactions', after: 'txn_previous' }), {
+    collection: 'transactions', items: [{ id: 'txn_a', kind: 'transaction', status: 'billed', createdAt: '2030-01-01T00:00:00.000Z', currency: 'USD', totalMinor: '9007199254740993', paidMinor: null }], nextCursor: 'txn_a'
+  });
+  assert.equal(pages, 1);
+  assert.deepEqual(queries[0], { customerId: ['ctm_a'], perPage: 20, after: 'txn_previous' });
+  record.details = null;
+  assert.equal((await adapter.readHistory({ customerId: 'ctm_a', collection: 'transactions' })).items[0].totalMinor, null);
+  record.id = 'sub_a';
+  record.status = 'canceled';
+  assert.deepEqual((await adapter.readHistory({ customerId: 'ctm_a', collection: 'subscriptions' })).items[0], { id: 'sub_a', kind: 'subscription', status: 'canceled', createdAt: '2030-01-01T00:00:00.000Z' });
+  record.customerId = 'ctm_other';
+  await assert.rejects(adapter.readHistory({ customerId: 'ctm_a', collection: 'transactions' }), { code: 'payment_provider_result_invalid' });
+});

package/test/readiness.test.js

@@ -0,0 +1,55 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createPaymentReadiness } from '../src/server/readiness.js';
+
+const scope = { environment: 'live', providerAccountId: 'acct_a' };
+const catalogue = { preview: async () => ({ environment: 'live', providerAccountId: 'acct_a', changes: [], drift: [], removed: [], pending: null }) };
+const byId = (report) => Object.fromEntries(report.checks.map((check) => [check.id, check]));
+
+test('readiness distinguishes provider facts, explicit app evidence and unknown checks without mutation', async () => {
+  const adapter = { verifyAccount: async () => ({ environment: 'live', accountId: 'acct_a', chargesEnabled: true, payoutsEnabled: false }) };
+  const readiness = createPaymentReadiness({ adapter, catalogue, scope,
+    inspectApplication: async () => ({ webhook: { status: 'passed', detail: 'The configured route passed the signed fixture check.' } }) });
+  const report = await readiness.inspect();
+  assert.equal(report.providerAccountId, 'acct_a');
+  const checks = byId(report);
+  assert.equal(checks.credentials.status, 'passed');
+  assert.equal(checks.account.status, 'passed');
+  assert.equal(checks.charges.status, 'passed');
+  assert.equal(checks.payouts.status, 'failed');
+  assert.equal(checks.catalogue.status, 'passed');
+  assert.equal(checks.webhook.status, 'passed');
+  assert.equal(checks.checkout.status, 'unknown');
+  assert.equal(checks.site.status, 'manual');
+  assert.equal(checks.deployment.status, 'unknown');
+  assert.equal(Object.hasOwn(report, 'ready'), false);
+});
+
+test('Paddle-style verification does not infer merchant approval; failed inspection does not leak provider errors', async () => {
+  let catalogueReads = 0;
+  const adapter = { verifyAccount: async () => ({ environment: 'live', credentialsVerified: true, accountIdentityVerified: false }) };
+  const readiness = createPaymentReadiness({ adapter, catalogue: { preview: async () => { catalogueReads++; return { ...(await catalogue.preview()), changes: [{}] }; } }, scope });
+  let checks = byId(await readiness.inspect());
+  assert.equal(checks.credentials.status, 'passed');
+  assert.equal(checks.account.status, 'manual');
+  assert.equal(checks.charges.status, 'manual');
+  assert.equal(checks.catalogue.status, 'failed');
+  adapter.verifyAccount = async () => { throw new Error('sk_secret_must_not_escape'); };
+  const failed = await readiness.inspect();
+  checks = byId(failed);
+  assert.equal(checks.credentials.status, 'failed');
+  assert.equal(checks.catalogue.status, 'unknown');
+  assert.equal(catalogueReads, 1);
+  assert.doesNotMatch(JSON.stringify(failed), /sk_secret/);
+});
+
+test('readiness rejects merchant/environment substitution and malformed app evidence', async () => {
+  const adapter = { verifyAccount: async () => ({ environment: 'sandbox', accountId: 'acct_a' }) };
+  await assert.rejects(createPaymentReadiness({ adapter, catalogue, scope }).inspect(), { code: 'payment_scope_invalid' });
+  adapter.verifyAccount = async () => ({ environment: 'live', accountId: 'acct_other' });
+  await assert.rejects(createPaymentReadiness({ adapter, catalogue, scope }).inspect(), { code: 'payment_scope_invalid' });
+  adapter.verifyAccount = async () => ({ environment: 'live' });
+  assert.equal(byId(await createPaymentReadiness({ adapter, catalogue, scope }).inspect()).credentials.status, 'unknown');
+  await assert.rejects(createPaymentReadiness({ adapter, catalogue, scope,
+    inspectApplication: async () => ({ site: { status: 'approved', detail: 'Everything is fine' } }) }).inspect(), { code: 'payment_readiness_invalid' });
+});

package/test/service.test.js

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knex from "knex";
+import migration from "../migrations/payments_core_initial.cjs";
+import { createKnexPaymentStore } from "../src/server/knexStore.js";
+import { createPaymentService } from "../src/server/service.js";
+import { validatePaymentConfiguration } from "../src/shared/configuration.js";
+
+const document = {
+  integrations: {
+    billing: { provider: "stripe", accountMode: "shared", authentication: { method: "api-key", secretRef: "env:STRIPE_KEY" } },
+    production: { provider: "stripe", accountMode: "shared", authentication: { method: "api-key", secretRef: "env:STRIPE_LIVE_KEY" } }
+  },
+  extensions: { payments: {
+    version: 1,
+    environments: {
+      sandbox: { integrationId: "billing", providerAccountId: "acct_test", webhookSecretRef: "env:STRIPE_WEBHOOK_SECRET", returnUrlRef: "env:APP_URL" },
+      live: { integrationId: "production", providerAccountId: "acct_live", webhookSecretRef: "env:STRIPE_LIVE_WEBHOOK_SECRET", returnUrlRef: "env:APP_URL" }
+    },
+    plans: { pro: { name: "Pro", amount: 1200, currency: "USD", interval: "month", features: ["export"], renewalCredits: 100 } }
+  } }
+};
+const scope = { applicationId: "app", integrationId: "billing", providerAccountId: "acct_test", environment: "sandbox", subjectId: "tenant-a" };
+
+test("portable configuration rejects secret literals, invalid prices and mismatched connector environments", () => {
+  assert.equal(validatePaymentConfiguration(document).plans.pro.amount, 1200);
+  for (const change of [
+    (value) => { value.extensions.payments.plans.pro.amount = 0.5; },
+    (value) => { value.extensions.payments.environments.sandbox.webhookSecretRef = "whsec_private"; },
+    (value) => { value.integrations.billing.accountMode = "per-user"; },
+    (value) => { value.integrations.billing.provider = "paddle"; value.integrations.billing.settings = { environment: "live" }; },
+    (value) => { value.extensions.payments.plans.pro.features.push("export"); }
+  ]) {
+    const value = structuredClone(document); change(value);
+    assert.throws(() => validatePaymentConfiguration(value), { code: "payment_configuration_invalid" });
+  }
+});
+
+test("configuration accepts reactive objects and returns an independent plain snapshot", () => {
+  const input = structuredClone(document);
+  input.extensions.payments = new Proxy(input.extensions.payments, {});
+  const configuration = validatePaymentConfiguration(input);
+  assert.equal(configuration.plans.pro.amount, 1200);
+  input.extensions.payments.plans.pro.amount = 2400;
+  assert.equal(configuration.plans.pro.amount, 1200);
+  assert.doesNotThrow(() => structuredClone(configuration));
+});
+
+test("transactional payment state isolates subjects, grants once, prevents overspend and reconciles current facts", async (t) => {
+  const db = knex({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true, pool: { min: 1, max: 1 } });
+  await migration.up(db);
+  const store = createKnexPaymentStore({ knex: db });
+  let now = 1000;
+  const service = createPaymentService({ store, configuration: validatePaymentConfiguration(document), clock: () => now });
+  try {
+    await t.test("read-only inspection creates no rows and refuses a foreign merchant", async () => {
+      assert.equal((await service.inspect(scope)).balance, 0);
+      assert.equal((await db("payment_accounts")).length, 0);
+      await assert.rejects(service.inspect({ ...scope, providerAccountId: "someone-else" }), { code: "payment_scope_invalid" });
+    });
+    await t.test("duplicate grants and concurrent debits preserve the balance", async () => {
+      const grant = { reference: "topup-1", units: 10, expiresAt: 5000 };
+      assert.equal((await service.grantCredits(scope, grant)).duplicate, false);
+      assert.equal((await service.grantCredits(scope, grant)).duplicate, true);
+      await assert.rejects(service.grantCredits(scope, { ...grant, units: 11 }), { code: "payment_reference_conflict" });
+      const results = await Promise.allSettled(["job-1", "job-2"].map((id) => service.debitCredits(scope, { reference: id, units: 7 })));
+      assert.equal(results.filter((result) => result.status === "fulfilled").length, 1);
+      assert.equal((await service.inspect(scope)).balance, 3);
+      assert.equal((await service.inspect({ ...scope, subjectId: "tenant-b" })).balance, 0);
+      assert.equal((await service.inspect({ ...scope, applicationId: "another-app" })).balance, 0);
+      assert.equal((await service.inspect({ ...scope, integrationId: "production", providerAccountId: "acct_live", environment: "live" })).balance, 0);
+      const id = results[0].status === "fulfilled" ? "job-1" : "job-2";
+      assert.equal((await service.debitCredits(scope, { reference: id, units: 7 })).duplicate, true);
+      assert.equal((await service.refundDebit(scope, { debitReference: id })).restored, 7);
+      assert.equal((await service.refundDebit(scope, { debitReference: id })).duplicate, true);
+    });
+    await t.test("refunds do not resurrect expired grants", async () => {
+      await service.debitCredits(scope, { reference: "expired-job", units: 4 });
+      now = 6000;
+      const result = await service.refundDebit(scope, { debitReference: "expired-job" });
+      assert.equal(result.restored, 0);
+      assert.equal(result.expired, 4);
+      assert.equal((await service.inspect(scope)).balance, 0);
+    });
+    await t.test("customer bindings cannot be stolen or resolved across environments", async () => {
+      await store.bindCustomer(scope, "cus_a", "tenant-a");
+      await assert.rejects(store.bindCustomer(scope, "cus_a", "tenant-b"), /already bound/);
+      await assert.rejects(service.reconcileEvent(scope, { eventId: "evt_unbound", customerId: "cus_b", load: async () => {} }), { code: "payment_customer_unbound" });
+    });
+    await t.test("event failure rolls back; retries grant once per renewal rather than event", async () => {
+      const subscription = { id: "sub_a", status: "active", planId: "pro", periodEnd: 10000 };
+      const renewal = { id: "invoice_a", planId: "pro", periodEnd: 10000 };
+      const event = { eventId: "evt_a", customerId: "cus_a", load: async () => ({ subscription, renewal }) };
+      await assert.rejects(service.reconcileEvent(scope, { ...event, load: async () => { throw new Error("provider unavailable"); } }), /unavailable/);
+      assert.equal((await service.reconcileEvent(scope, event)).duplicate, false);
+      assert.equal((await service.reconcileEvent(scope, event)).duplicate, true);
+      await service.reconcileEvent(scope, { ...event, eventId: "evt_b" });
+      assert.equal((await service.inspect(scope)).balance, 100);
+      await service.requireFeature(scope, "export");
+      // A late delivery loads current canceled state, not the old event payload.
+      await service.reconcileEvent(scope, { ...event, eventId: "evt_older", load: async () => ({ subscription: { ...subscription, status: "canceled" } }) });
+      await assert.rejects(service.requireFeature(scope, "export"), { code: "payment_feature_required" });
+      assert.equal((await service.inspect(scope)).balance, 100);
+    });
+    await t.test("transaction interruption leaves neither receipt nor mutated balance", async () => {
+      await assert.rejects(store.withAccount(scope, async (tx) => {
+        tx.state.lots[0].remaining = 100000;
+        await tx.record("interrupted", { invalid: true });
+        throw new Error("abort");
+      }), /abort/);
+      assert.equal(await store.withAccount(scope, (tx) => tx.find("interrupted")), null);
+      assert.equal((await service.inspect(scope)).balance, 100);
+    });
+  } finally {
+    await migration.down(db);
+    await db.destroy();
+  }
+});