@owlmeans/server-payment 0.1.18-rc.2 → 0.1.18-rc.21

package/tests/consumer-fixtures.ts

@@ -0,0 +1,132 @@
+import { ConsentKind } from '@owlmeans/payment'
+import { createEventHandler } from '../src/plugins/events.js'
+import { consumerRights, purchases } from '../src/utils.js'
+import type { ConsumerRightsDef, PricingDef, PurchaseRecord, UsageMeter, UsageQuery, UsageReading } from '../src/types.js'
+import { CREDIT_UNIT, CREDITS_PRODUCT, makeFakeContext, PLANS_PRODUCT, PRO } from './fake-stripe.js'
+import type { FakeContext, FakeContextOptions } from './fake-stripe.js'
+
+type Rec = Record<string, any>
+
+export const ENTITY = 'entity-1'
+export const TEXT_VERSION = 'terms-v1'
+export const epoch = (date: Date): number => Math.floor(date.getTime() / 1000)
+
+export const LINKS = {
+  en: {
+    billingTerms: 'https://legal.example.com/en/billing',
+    withdrawalInformation: 'https://legal.example.com/en/withdrawal',
+    withdrawalForm: 'https://legal.example.com/en/withdrawal-form',
+    withdrawalFunction: 'https://app.example.com/legal/withdraw',
+    cancellation: 'https://app.example.com/legal/cancel',
+  },
+  de: { billingTerms: 'https://legal.example.com/de/billing', withdrawalInformation: 'https://legal.example.com/de/withdrawal' },
+  pl: { billingTerms: 'https://legal.example.com/pl/billing', withdrawalInformation: 'https://legal.example.com/pl/withdrawal' },
+}
+
+export const ALL_ON = {
+  countryLock: true, checkoutTerms: false, performanceConsent: true, subscriptionStart: true, withdrawal: true,
+  automaticRefunds: true, cancellation: true, purchaseConfirmation: true,
+}
+
+export const TRADER = {
+  name: 'Example', legalName: 'Example Trading Ltd', address: '1 Example Street, 00-001 Example',
+  email: 'support@example.com',
+}
+
+export const rightsOf = (patch: Partial<ConsumerRightsDef> = {}): ConsumerRightsDef => ({
+  textVersion: TEXT_VERSION,
+  links: LINKS,
+  currencies: { eu: 'eur', other: 'usd' },
+  mechanisms: ALL_ON,
+  trader: TRADER,
+  mail: { from: 'billing@example.com', bcc: ['archive@example.com'] },
+  ...patch,
+})
+
+/** The pricing a EUR-settling account with USD catalogue prices declares. */
+export const EUR_SETTLEMENT: PricingDef = {
+  tax: { automatic: true, collectTaxId: true, estimate: true },
+  currency: { adaptive: true, estimate: false },
+  stripe: { settlementCurrency: 'eur' },
+}
+
+/** 1 USD = 0.9 EUR at the reference rate. */
+export const FX = { usd: { exchangeRate: 0.88, referenceRate: 0.9 } }
+
+export const makeRightsContext = async (opts: FakeContextOptions = {}): Promise<FakeContext> =>
+  await makeFakeContext({
+    pricing: EUR_SETTLEMENT,
+    consumerRights: rightsOf(),
+    ...opts,
+    stripe: { fxRates: FX, ...opts.stripe },
+  })
+
+export interface RecordingMeter extends UsageMeter {
+  queries: UsageQuery[]
+  reading: Partial<UsageReading> & { granted: number }
+}
+
+/** A usage meter answering one fixed reading (mutable through `reading`). */
+export const fixedMeter = (reading: Partial<UsageReading> & { granted: number }): RecordingMeter => {
+  const meter: RecordingMeter = {
+    queries: [],
+    reading,
+    used: async (_ctx, query) => {
+      meter.queries.push(query)
+      return { used: 0, usedAfter: 0, ...meter.reading }
+    },
+  }
+
+  return meter
+}
+
+export const send = async (fake: FakeContext, type: string, object: unknown): Promise<void> => {
+  await createEventHandler(fake.ctx, fake.stripe).process({ id: `evt_${type}_${Math.random()}`, type, created: epoch(new Date()), data: { object } } as never)
+}
+
+/** A completed, paid amount checkout: 10.00 USD of credit charged as 9.19 EUR + 23 % VAT, bought from Poland. */
+export const paidSession = (overrides: Rec = {}): Rec => ({
+  id: 'cs_pl', object: 'checkout.session', mode: 'payment', payment_status: 'paid', status: 'complete',
+  customer: 'cus_1', currency: 'eur', amount_subtotal: 919, amount_total: 1130, total_details: { amount_tax: 211 },
+  payment_intent: 'pi_pl', invoice: 'in_pl', created: epoch(new Date()),
+  customer_details: {
+    address: { country: 'PL' }, email: 'buyer@shop.eu', name: 'Jan Kowalski', tax_ids: [], tax_exempt: 'none',
+  },
+  consent: { terms_of_service: 'accepted' },
+  ...overrides,
+  metadata: {
+    pricingMode: 'amount', amountMinor: '1000', sourceChargeAmountMinor: '1021', amountCurrency: 'usd',
+    chargeAmountMinor: '919', currency: 'eur', entityId: ENTITY, service: 'app', productSku: CREDITS_PRODUCT,
+    planSku: CREDIT_UNIT, country: 'PL', language: 'pl', termsVersion: TEXT_VERSION, ipCountry: 'PL',
+    ...overrides.metadata,
+  },
+})
+
+/** The post-payment invoice of `paidSession`. */
+export const invoiceOf = (id = 'in_pl', overrides: Rec = {}): Rec => ({
+  id, object: 'invoice', number: 'INV-0001', subtotal: 919, tax: 211, total: 1130, currency: 'eur',
+  payment_intent: 'pi_pl', lines: { object: 'list', data: [{ id: 'il_pl', amount: 919 }] },
+  customer_address: { country: 'PL' }, ...overrides,
+})
+
+/** Complete a top-up: the webhook captures the purchase (and locks the country). */
+export const buyTopUp = async (fake: FakeContext, overrides: Rec = {}): Promise<PurchaseRecord> => {
+  const session = paidSession(overrides)
+  fake.state.invoices[session.invoice as string] = fake.state.invoices[session.invoice as string] ?? invoiceOf(session.invoice as string)
+  await send(fake, 'checkout.session.completed', session)
+  const purchase = await purchases(fake.ctx).load({ sessionId: session.id as string })
+  if (purchase == null) throw new Error('no purchase captured')
+
+  return purchase
+}
+
+/** A start request of `ENTITY` for the pro plan. */
+export const requestStart = async (fake: FakeContext, patch: Rec = {}): Promise<string> =>
+  (await consumerRights(fake.ctx).recordStartRequest(
+    { entityId: ENTITY, email: 'owner@shop.eu', name: 'Anna' },
+    { planSku: PRO, textVersion: TEXT_VERSION, language: 'en', acknowledged: true, ...patch },
+    { ip: '203.0.113.7' },
+    { plan: 'Pro' },
+  )).startRequestId
+
+export { ConsentKind, CREDITS_PRODUCT, CREDIT_UNIT, PLANS_PRODUCT, PRO }

package/tests/consumer-ops.spec.ts

@@ -0,0 +1,351 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  makeCheckoutReadProtocols, makeConsumerRightsProtocols, PerformanceConsentRequired, TaxBehavior,
+  WithdrawalStatus,
+} from '@owlmeans/payment'
+import { checkoutReadEntrypoints, consumerRightsEntrypoints } from '../src/consumer/handlers.js'
+import { isReservedAddress } from '../src/consumer/format.js'
+import { requestOriginOf } from '../src/consumer/origin.js'
+import { estimateStripePrice, makeEstimateCache } from '../src/plugins/estimate.js'
+import { ensurePortalConfiguration } from '../src/plugins/portal.js'
+import { syncStripeProducts } from '../src/sync.js'
+import {
+  billingProfiles, consumerEvents, consumerRights, fingerprints, fulfillments, gateway, paygateCustomers, purchases,
+} from '../src/utils.js'
+import {
+  ALL_ON, buyTopUp, CREDITS_PRODUCT, ENTITY, epoch, fixedMeter, makeRightsContext, paidSession, PLANS_PRODUCT, PRO,
+  rightsOf, TEXT_VERSION,
+} from './consumer-fixtures.js'
+import type { FakeContext } from './fake-stripe.js'
+
+const service = (fake: FakeContext) => consumerRights(fake.ctx)
+const subject = { entityId: ENTITY, email: 'owner@shop.eu', name: 'Anna' }
+
+/** Run a server binding the way the transport does. */
+const invoke = async (entrypoint: any, fake: FakeContext, req: Record<string, unknown>): Promise<any> => {
+  fake.ctx.registerEntrypoint(entrypoint)
+  const res: any = { resolve: (value: unknown) => { res.value = value }, reject: (error: Error) => { res.error = error } }
+  await entrypoint.handle({ headers: {}, query: {}, params: {}, path: '/', alias: entrypoint.alias, ...req }, res)
+  if (res.error != null) throw res.error
+  return res.value
+}
+
+describe('reconcile', () => {
+  test('a failed mail is sent again; a sent one never twice', async () => {
+    const fake = await makeRightsContext()
+    const send = fake.mailer.send
+    fake.mailer.send = async () => { throw new Error('smtp down') }
+    const purchase = await buyTopUp(fake)
+    fake.mailer.send = send
+    const failed = await consumerEvents(fake.ctx).load({ recordId: purchase.purchaseId, action: 'mail' })
+    expect(failed).toEqual(expect.objectContaining({ ok: false, step: 'purchase', error: 'smtp down' }))
+
+    expect((await service(fake).reconcile()).mailed).toBe(1)
+    expect(fake.mails.filter(mail => mail.to === 'buyer@shop.eu')).toHaveLength(1)
+    expect((await service(fake).reconcile()).mailed).toBe(0)
+  })
+
+  test('the application renderer may replace a mail or suppress it (recorded as skipped)', async () => {
+    const fake = await makeRightsContext()
+    const kinds: string[] = []
+    service(fake).useMailRenderer((kind, data, rendered) => {
+      kinds.push(kind)
+      if (kind === 'purchase') return { ...rendered, subject: `[Shop] ${rendered.subject}`, to: data.to }
+      return null
+    })
+    const purchase = await buyTopUp(fake)
+    expect(fake.mails.find(mail => mail.to === 'buyer@shop.eu')?.subject).toStartWith('[Shop] ')
+    await service(fake).recordConsent(subject, {
+      purchaseIds: [purchase.purchaseId], textVersion: TEXT_VERSION, language: 'en', acknowledged: true,
+    })
+    expect(kinds).toEqual(['purchase', 'consent'])
+    expect(fake.mails.some(mail => mail.to === 'owner@shop.eu')).toBe(false)
+    const skipped = (await consumerEvents(fake.ctx).list({ action: 'mail', step: 'consent' })).items[0]
+    expect(skipped).toEqual(expect.objectContaining({ ok: true, skipped: true, detail: '{"reason":"renderer"}' }))
+  })
+
+  test('a throwing withdrawal observer is recorded and told again by reconcile, once', async () => {
+    const fake = await makeRightsContext({ meter: fixedMeter({ granted: 1_000, used: 0, usedAfter: 0 }) })
+    const purchase = await buyTopUp(fake)
+    fake.observed.failWithdrawal = 1
+    const receipt = await service(fake).withdraw(subject, { purchaseId: purchase.purchaseId, name: 'Anna', email: 'owner@shop.eu' })
+    expect(receipt.status).toBe(WithdrawalStatus.Refunded)
+    expect(fake.observed.withdrawal).toHaveLength(0)
+    expect((await service(fake).reconcile()).observed).toBe(1)
+    expect(fake.observed.withdrawal).toEqual([expect.objectContaining({
+      withdrawalId: receipt.declarationId, status: WithdrawalStatus.Refunded, units: { granted: 1_000, used: 0, returned: 1_000 },
+    })])
+    await service(fake).reconcile()
+    expect(fake.observed.withdrawal).toHaveLength(1)
+  })
+
+  test('completed checkouts of the last 16 days without a purchase are backfilled, without mail', async () => {
+    const fake = await makeRightsContext()
+    const created = epoch(new Date(Date.now() - 3 * 86_400_000))
+    fake.state.listedSessions = [
+      paidSession({ id: 'cs_missed', created, invoice: null }),
+      paidSession({ id: 'cs_old', created: epoch(new Date(Date.now() - 40 * 86_400_000)), invoice: null }),
+    ]
+    const result = await service(fake).reconcile()
+    expect(result.backfilled).toBe(1)
+    const purchase = await purchases(fake.ctx).load({ sessionId: 'cs_missed' })
+    expect(purchase).toEqual(expect.objectContaining({ purchasedAt: new Date(created * 1000), inScope: true }))
+    expect(fake.mails).toHaveLength(0)
+    expect((await billingProfiles(fake.ctx).byEntity(ENTITY))?.country).toBe('PL')
+  })
+
+  test('an organization that paid before the lock is locked from its paygate customer', async () => {
+    const fake = await makeRightsContext()
+    await paygateCustomers(fake.ctx).create({ paygate: 'stripe', externalId: 'cus_n', entityId: 'entity-n', country: 'NO' })
+    await fulfillments(fake.ctx).create({
+      entityId: 'entity-n', productSku: CREDITS_PRODUCT, service: 'app', paygate: 'stripe', externalId: 'cs_n',
+      mode: 'amount' as never, createdAt: new Date(), fulfilledAt: new Date(),
+    })
+    await paygateCustomers(fake.ctx).create({ paygate: 'stripe', externalId: 'cus_u', entityId: 'entity-u', country: 'US' })
+    expect((await service(fake).reconcile()).locked).toBe(1)
+    expect(await billingProfiles(fake.ctx).byEntity('entity-n')).toEqual(expect.objectContaining({
+      country: 'NO', source: 'customer', region: 'eu',
+    }))
+    expect(await billingProfiles(fake.ctx).byEntity('entity-u')).toBeNull()
+  })
+})
+
+describe('handlers', () => {
+  const account = { base: { alias: 'app:account', path: '/account' } }
+  const protocols = makeConsumerRightsProtocols({ prefix: 'app:consumer', guards: ['guard:default'], public: {} })
+  const req = (extra: Record<string, unknown> = {}) => ({ entity: { id: ENTITY }, ...extra })
+
+  test('a public subtree needs a throttle; the account and public routes are all bound', () => {
+    expect(() => consumerRightsEntrypoints(protocols)).toThrow(SyntaxError)
+    expect(consumerRightsEntrypoints(protocols, { throttle: async () => undefined })).toHaveLength(14)
+    const accountOnly = makeConsumerRightsProtocols({ prefix: 'app:consumer2', guards: ['guard:default'] })
+    expect(consumerRightsEntrypoints(accountOnly)).toHaveLength(10)
+    expect(account.base.alias).toBe('app:account')
+  })
+
+  test('the account routes act for the request organization; money-moving acts pass guardMoney first', async () => {
+    const fake = await makeRightsContext()
+    await buyTopUp(fake)
+    const guarded: string[] = []
+    const contexts = new Set<unknown>()
+    const bound = consumerRightsEntrypoints(protocols, {
+      throttle: async () => undefined, publicMinMs: 0,
+      resolveEntity: (request, ctx) => { contexts.add(ctx); return request.entity?.id },
+      guardMoney: async (_req, action, ctx) => {
+        contexts.add(ctx)
+        guarded.push(action)
+        if (action === 'withdraw') throw new Error('token refused')
+      },
+      metaOf: (request, ctx) => { contexts.add(ctx); return requestOriginOf(request) },
+      subjectOf: () => ({ email: 'owner@shop.eu', name: 'Anna', profileId: 'profile-1' }),
+    })
+    const byAlias = (alias: string) => bound.find(entry => entry.alias === alias)
+    const view = await invoke(byAlias('app:consumer:consent'), fake, req())
+    expect(view.required).toBe(true)
+    const recorded = await invoke(byAlias('app:consumer:consent:give'), fake, req({
+      body: { purchaseIds: view.purchases.map((item: { purchaseId: string }) => item.purchaseId), textVersion: TEXT_VERSION, language: 'pl', acknowledged: true },
+      headers: { 'cf-connecting-ip': '203.0.113.9', 'user-agent': 'browser' },
+    }))
+    expect(recorded.purchaseIds).toHaveLength(1)
+    expect(fake.stores['payment-consumer-consent'].rows[0]).toEqual(expect.objectContaining({
+      ip: '203.0.113.9', userAgent: 'browser', profileId: 'profile-1',
+    }))
+    await expect(invoke(byAlias('app:consumer:withdraw'), fake, req({ body: { purchaseId: 'x', name: 'A', email: 'a@shop.eu' } })))
+      .rejects.toThrow('token refused')
+    expect(guarded).toEqual(['consent', 'withdraw'])
+    const profile = await invoke(byAlias('app:consumer:profile'), fake, req())
+    expect(profile).toEqual(expect.objectContaining({ country: 'PL', locked: true }))
+    await expect(invoke(byAlias('app:consumer:profile'), fake, {})).rejects.toThrow()
+    // Every hook is handed the request's context.
+    expect([...contexts]).toEqual([fake.ctx])
+  })
+
+  test('a start request takes the plan name the application gives, with the context', async () => {
+    const fake = await makeRightsContext()
+    const named: unknown[] = []
+    const bound = consumerRightsEntrypoints(protocols, {
+      throttle: async () => undefined,
+      planNameOf: (planSku, language, _req, ctx) => { named.push([planSku, language, ctx]); return 'Pro' },
+    })
+    const started = await invoke(bound.find(entry => entry.alias === 'app:consumer:start:request'), fake, req({
+      body: { planSku: PRO, textVersion: TEXT_VERSION, language: 'en', acknowledged: true },
+    }))
+    expect(started.startRequestId).toBeString()
+    expect(named).toEqual([[PRO, 'en', fake.ctx]])
+  })
+
+  test('public declarations are throttled, a honeypot records nothing, and the answer takes at least publicMinMs', async () => {
+    const fake = await makeRightsContext()
+    const throttled: unknown[] = []
+    const bound = consumerRightsEntrypoints(protocols, {
+      throttle: async (_req, key, ctx) => { throttled.push(key); expect(ctx).toBe(fake.ctx) }, publicMinMs: 150,
+    })
+    const withdraw = bound.find(entry => entry.alias === 'app:consumer:public:withdraw')
+    const started = Date.now()
+    const receipt = await invoke(withdraw, fake, {
+      body: { contractRef: 'CR-000000-AAAAAA', name: 'Eve', email: 'eve@else.eu' }, headers: { 'x-forwarded-for': '10.0.0.1, 198.51.100.4' },
+    })
+    expect(Date.now() - started).toBeGreaterThanOrEqual(140)
+    expect(Object.keys(receipt).sort()).toEqual(['content', 'declarationId', 'mailed', 'receivedAt'])
+    expect(throttled).toEqual([{ action: 'withdrawal', email: 'eve@else.eu', ip: '198.51.100.4' }])
+    expect(fake.stores['payment-consumer-declaration'].rows).toHaveLength(1)
+
+    const decoy = await invoke(withdraw, fake, { body: { contractRef: 'CR-1', name: 'Bot', email: 'bot@else.eu', honeypot: 'x' } })
+    expect(Object.keys(decoy).sort()).toEqual(['content', 'declarationId', 'mailed', 'receivedAt'])
+    expect(fake.stores['payment-consumer-declaration'].rows).toHaveLength(1)
+
+    const policy = await invoke(bound.find(entry => entry.alias === 'app:consumer:public:policy'), fake, {})
+    expect(policy).toEqual(expect.objectContaining({ mechanisms: { withdrawal: true, cancellation: true }, textVersion: TEXT_VERSION }))
+    expect(policy.languages).toEqual(['en', 'de', 'pl'])
+  })
+
+  test('checkout read routes answer the narrowed amount policy and the synced prices', async () => {
+    const fake = await makeRightsContext()
+    gateway(fake.ctx).use({ alias: 'tier', narrow: async () => ({ maximumMinor: 2_500, reason: 'per-purchase' }) })
+    const read = checkoutReadEntrypoints(makeCheckoutReadProtocols({ prefix: 'app:checkout', guards: ['guard:default'] }))
+    const policy = await invoke(read.find(entry => entry.alias === 'app:checkout:amount-policy'), fake, req({ query: { productSku: CREDITS_PRODUCT } }))
+    expect(policy.limit).toEqual(expect.objectContaining({ maximumMinor: 2_500 }))
+    const prices = await invoke(read.find(entry => entry.alias === 'app:checkout:plan-prices'), fake, req({ query: { productSku: PLANS_PRODUCT } }))
+    expect(prices).toEqual({ prices: [] })
+  })
+
+  test('requestOriginOf: the Cloudflare address first, else the LAST forwarded entry, else x-real-ip, else the socket', () => {
+    expect(requestOriginOf({ headers: { 'cf-connecting-ip': '1.1.1.1', 'x-forwarded-for': '9.9.9.9, 2.2.2.2' } } as never).ip).toBe('1.1.1.1')
+    const origin = requestOriginOf({
+      headers: {
+        'x-forwarded-for': '9.9.9.9, 2.2.2.2', 'user-agent': 'x'.repeat(600), 'cf-ipcountry': 'de', 'accept-language': 'de-DE',
+      },
+    } as never)
+    expect(origin).toEqual({
+      ip: '2.2.2.2', forwardedFor: '9.9.9.9, 2.2.2.2', userAgent: 'x'.repeat(512), ipCountry: 'DE', acceptLanguage: 'de-DE',
+    })
+    expect(requestOriginOf({ headers: { 'x-real-ip': '3.3.3.3' } } as never).ip).toBe('3.3.3.3')
+    expect(requestOriginOf({ headers: {}, original: { socket: { remoteAddress: '4.4.4.4' } } } as never).ip).toBe('4.4.4.4')
+  })
+})
+
+describe('sync, portal and estimate under the policy', () => {
+  const exclusive = { tax: { automatic: true, collectTaxId: true, estimate: true, behavior: TaxBehavior.Exclusive }, currency: { adaptive: true, estimate: false }, stripe: { settlementCurrency: 'eur' } }
+
+  test('a USD catalogue price syncs as EUR with an exact USD option, each with its tax behavior, persisted', async () => {
+    const fake = await makeRightsContext({ pricing: exclusive })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    const pro = fake.state.prices.find(price => price.lookup_key === PRO && price.active)
+    expect(pro).toEqual(expect.objectContaining({ currency: 'eur', unit_amount: 1_800, tax_behavior: 'exclusive' }))
+    expect(pro?.currency_options).toEqual({ usd: { unit_amount: 2_000, tax_behavior: 'exclusive' } })
+    const row = await fingerprints(fake.ctx).bySku(PLANS_PRODUCT)
+    expect(row?.prices?.find(price => price.planSku === PRO)).toEqual(expect.objectContaining({
+      priceId: pro?.id, currency: 'eur', unitAmount: 1_800, options: [{ currency: 'usd', unitAmount: 2_000 }], interval: 'month',
+      sourceUnitAmount: 2_000, sourceCurrency: 'usd',
+    }))
+    expect(await gateway(fake.ctx).planPrices(fake.ctx, PLANS_PRODUCT)).toEqual(expect.arrayContaining([
+      { planSku: PRO, currency: 'eur', unitAmountMinor: 1_800, default: true, taxBehavior: TaxBehavior.Exclusive, interval: 'month' },
+      { planSku: PRO, currency: 'usd', unitAmountMinor: 2_000, default: false, taxBehavior: TaxBehavior.Exclusive, interval: 'month' },
+    ]))
+
+    fake.state.calls.length = 0
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(fake.state.calls.filter(call => call !== 'rawRequest')).toEqual([])
+  })
+
+  test('a changed option replaces the Price, never edits it', async () => {
+    const fake = await makeRightsContext({
+      pricing: exclusive,
+      catalogue: {
+        plans: [{
+          productSku: PLANS_PRODUCT, sku: 'pro-exact', duration: 'monthly' as never, rank: 15, price: 20, recurring: { interval: 'month' },
+          currencyPrices: { usd: 21 },
+        }],
+      },
+    })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    const first = fake.state.prices.find(price => price.lookup_key === 'pro-exact' && price.active)
+    expect(first?.currency_options).toEqual({ usd: { unit_amount: 2_100, tax_behavior: 'exclusive' } })
+    first!.currency_options = { usd: { unit_amount: 1_900, tax_behavior: 'exclusive' } }
+    await fingerprints(fake.ctx).clear()
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    expect(first?.active).toBe(false)
+    expect(fake.state.prices.find(price => price.lookup_key === 'pro-exact' && price.active)?.currency_options)
+      .toEqual({ usd: { unit_amount: 2_100, tax_behavior: 'exclusive' } })
+  })
+
+  test('the portal drops address updates under the country lock', async () => {
+    const fake = await makeRightsContext({ portal: { returnUrl: 'https://app.example.com/billing' } })
+    await ensurePortalConfiguration(fake.ctx, fake.stripe)
+    expect(fake.state.portalConfigurations[0].features.customer_update).toEqual({ enabled: true, allowed_updates: ['email', 'tax_id'] })
+    const open = await makeRightsContext({
+      portal: { returnUrl: 'https://app.example.com/billing' }, consumerRights: rightsOf({ mechanisms: { ...ALL_ON, countryLock: false } }),
+    })
+    await ensurePortalConfiguration(open.ctx, open.stripe)
+    expect(open.state.portalConfigurations[0].features.customer_update.allowed_updates).toEqual(['email', 'address', 'tax_id'])
+  })
+
+  test('a locked profile overrides the requested estimate country; a recurring plan is estimated in the charge currency', async () => {
+    const fake = await makeRightsContext({ pricing: exclusive, stripe: { taxRates: { DE: [{ type: 'vat', percentage: '19' }] } } })
+    await syncStripeProducts(fake.ctx, fake.stripe)
+    await service(fake).lock(ENTITY, 'DE', 'manual')
+    const estimate = await estimateStripePrice(fake.ctx, fake.stripe, {
+      entityId: ENTITY, productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, makeEstimateCache())
+    expect(estimate).toEqual(expect.objectContaining({ country: 'DE', source: 'profile', locked: true, region: 'eu', currency: 'eur' }))
+    expect(estimate.tax).toEqual(expect.objectContaining({ subtotalMinor: 1_800, taxMinor: 342, totalMinor: 2_142 }))
+
+    const other = await makeRightsContext({ pricing: exclusive })
+    await syncStripeProducts(other.ctx, other.stripe)
+    const usd = await estimateStripePrice(other.ctx, other.stripe, {
+      entityId: 'entity-us', productSku: PLANS_PRODUCT, planSku: PRO, country: 'US',
+    }, makeEstimateCache())
+    expect(usd).toEqual(expect.objectContaining({ country: 'US', source: 'request', region: 'other', currency: 'usd' }))
+    expect(usd.tax.subtotalMinor).toBe(2_000)
+    expect(usd.locked).toBeUndefined()
+  })
+})
+
+describe('the declaration', () => {
+  test('a mechanism without a trader, or a malformed archive address, is refused', async () => {
+    const { declareConsumerRights } = await import('../src/config.js')
+    const cfg = { records: [] } as never
+    expect(() => declareConsumerRights(cfg, rightsOf({ trader: undefined }))).toThrow('policy:trader')
+    expect(() => declareConsumerRights(cfg, rightsOf({ mail: { bcc: ['not-an-address'] } }))).toThrow('policy:mail-bcc')
+    const policy = declareConsumerRights(cfg, rightsOf())
+    expect(policy).not.toHaveProperty('trader')
+    expect(policy).not.toHaveProperty('mail')
+    expect(policy.deadline).toEqual({ weekendRollover: true, marginDays: 5 })
+  })
+
+  test('plan withdrawal components must add up to the price', async () => {
+    const { declarePaymentPlan } = await import('../src/config.js')
+    const plan = {
+      productSku: PLANS_PRODUCT, sku: 'split-plan', duration: 'monthly' as never, price: 20, recurring: { interval: 'month' as const },
+    }
+    expect(() => declarePaymentPlan({ records: [] } as never, {
+      ...plan, withdrawal: { components: [{ key: 'services', basis: 'time', shareMinor: 1_000 }] },
+    })).toThrow('withdrawal:split-plan:shares')
+    expect(() => declarePaymentPlan({ records: [] } as never, { ...plan, currencyPrices: { usd: 0 } })).toThrow('currency-prices')
+    const cfg = { records: [] } as { records: Array<Record<string, unknown>> }
+    declarePaymentPlan(cfg as never, {
+      ...plan, currencyPrices: { USD: 20 },
+      withdrawal: { components: [{ key: 'services', basis: 'time', shareMinor: 1_000 }, { key: 'credits', basis: 'units', shareMinor: 1_000 }] },
+    })
+    expect(cfg.records[0]).toEqual(expect.objectContaining({ currencyPrices: { usd: 20 } }))
+  })
+
+  test('reserved mail domains: .test, .example, .invalid, .localhost and every subdomain of them', () => {
+    for (const address of [
+      'a@shop.test', 'a@mail.shop.test', 'A@Shop.EXAMPLE', 'a@x.invalid', 'a@localhost', 'a@app.localhost',
+      ' Jan <a@shop.test> ', 'a@shop.test.',
+    ]) {
+      expect([address, isReservedAddress(address)]).toEqual([address, true])
+    }
+    for (const address of ['a@shop.eu', 'a@test.com', 'a@example.com', 'a@testing', 'a@localhost.com', 'a@test.example.org']) {
+      expect([address, isReservedAddress(address)]).toEqual([address, false])
+    }
+  })
+
+  test('an unmet consent still refuses after a reconcile — reconcile never consents for anyone', async () => {
+    const fake = await makeRightsContext()
+    await buyTopUp(fake)
+    await service(fake).reconcile()
+    await expect(service(fake).assertConsent(ENTITY)).rejects.toBeInstanceOf(PerformanceConsentRequired)
+  })
+})

package/tests/consumer-rights.integration.spec.ts

@@ -0,0 +1,150 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { CancellationKind, PurchaseKind, WithdrawalStatus } from '@owlmeans/payment'
+import { capturePaymentPurchase } from '../src/consumer/capture.js'
+import { lockProfile, recordEvent } from '../src/consumer/records.js'
+import { createEventHandler } from '../src/plugins/events.js'
+import { syncStripeProducts } from '../src/sync.js'
+import {
+  billingProfiles, consumerConsents, consumerDeclarations, consumerEvents, consumerRights, fingerprints,
+  fulfillments, isDuplicateKey, payment, purchases, subscriptions,
+} from '../src/utils.js'
+import { gate, makeSuite } from './context.js'
+import type { Booted } from './context.js'
+import {
+  EUR_SETTLEMENT, FX, fixedMeter, invoiceOf, paidSession, requestStart, rightsOf, TEXT_VERSION,
+} from './consumer-fixtures.js'
+import { eventOf, makeFakeStripe, PRO, subscriptionOf } from './fake-stripe.js'
+
+const { stripe, state } = makeFakeStripe({ fxRates: FX })
+const suite = makeSuite('payconsumer', {
+  consumerRights: rightsOf(), pricing: EUR_SETTLEMENT, stripe, meter: fixedMeter({ granted: 1_000, used: 0, usedAfter: 0 }),
+})
+const it = gate.skip ? test.skip : test
+
+const complete = async (booted: Booted, id: string, entityId: string, extra: Record<string, unknown> = {}) => {
+  state.invoices[`in_${id}`] = invoiceOf(`in_${id}`, { payment_intent: `pi_${id}`, lines: { object: 'list', data: [{ id: `il_${id}` }] } })
+  await createEventHandler(booted.ctx, stripe).process(eventOf('checkout.session.completed', paidSession({
+    id: `cs_${id}`, invoice: `in_${id}`, payment_intent: `pi_${id}`, customer: `cus_${entityId}`,
+    metadata: { entityId }, ...extra,
+  })))
+  const purchase = await purchases(booted.ctx).load({ sessionId: `cs_${id}` })
+  if (purchase == null) throw new Error('not captured')
+  return purchase
+}
+
+describe('@owlmeans/server-payment — consumer-rights records on Mongo', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'mongo gate closed', () => {})
+    return
+  }
+
+  let booted: Booted
+  beforeAll(async () => { booted = await suite.boot() }, 60_000)
+  afterAll(async () => { await suite.teardown() }, 60_000)
+
+  it('stores every consumer-rights record and the new evidence fields through their collection validators', async () => {
+    const { ctx } = booted
+    const purchase = await complete(booted, 'v1', 'org-v')
+    expect(purchase).toEqual(expect.objectContaining({ kind: PurchaseKind.TopUp, inScope: true, invoiceLineId: 'il_v1' }))
+    expect(purchase.deadline).toBeInstanceOf(Date)
+    expect(await billingProfiles(ctx).byEntity('org-v')).toEqual(expect.objectContaining({ country: 'PL', currency: 'eur' }))
+    expect(await fulfillments(ctx).byExternalId('cs_v1', 'stripe')).toEqual(expect.objectContaining({
+      country: 'PL', purchaseId: purchase.purchaseId, termsAccepted: true, amountTotalMinor: 1_130,
+    }))
+
+    const consent = await consumerRights(ctx).recordConsent({ entityId: 'org-v', email: 'owner@shop.eu' }, {
+      purchaseIds: [purchase.purchaseId], textVersion: TEXT_VERSION, language: 'pl', acknowledged: true,
+    }, { ip: '203.0.113.1', userAgent: 'agent', ipCountry: 'PL', acceptLanguage: 'pl' })
+    expect(await consumerConsents(ctx).load(consent.consentId)).toEqual(expect.objectContaining({ kind: 'performance', ip: '203.0.113.1' }))
+    expect((await purchases(ctx).byPurchaseId(purchase.purchaseId))?.consentedAt).toBeInstanceOf(Date)
+
+    const startRequestId = await requestStart({ ctx } as never, { planSku: PRO })
+    expect((await consumerConsents(ctx).load(startRequestId))?.expiresAt).toBeInstanceOf(Date)
+
+    const receipt = await consumerRights(ctx).withdraw({ entityId: 'org-v' }, {
+      purchaseId: purchase.purchaseId, name: 'Jan', email: 'owner@shop.eu',
+    })
+    expect(receipt.status).toBe(WithdrawalStatus.Refunded)
+    expect(await consumerDeclarations(ctx).load(receipt.declarationId)).toEqual(expect.objectContaining({ matched: true }))
+    expect(await consumerEvents(ctx).count({ recordId: receipt.declarationId, action: 'refund', ok: true })).toBe(1)
+
+    const subscription = subscriptionOf({ id: 'sub_v', customer: 'cus_org-v', entityId: 'org-v' }) as unknown as Record<string, any>
+    subscription.currency = 'eur'
+    state.subscriptions.sub_v = subscription as never
+    await createEventHandler(ctx, stripe).process(eventOf('customer.subscription.updated', subscription))
+    const cancelled = await consumerRights(ctx).cancel({ entityId: 'org-v' }, {
+      kind: CancellationKind.Ordinary, name: 'Jan', email: 'owner@shop.eu', effective: 'earliest',
+    })
+    expect(await consumerDeclarations(ctx).load(cancelled.declarationId)).toEqual(expect.objectContaining({ kind: 'cancellation' }))
+    expect((await subscriptions(ctx).byExternalId('sub_v', 'stripe'))?.currency).toBe('eur')
+
+    await syncStripeProducts(ctx, stripe)
+    const row = await fingerprints(ctx).bySku('app-plans')
+    expect(row?.prices?.find(price => price.planSku === PRO)?.options).toEqual([{ currency: 'usd', unitAmount: 2_000 }])
+    expect(await payment(ctx).consumerRightsPolicy()).not.toBeNull()
+  }, 60_000)
+
+  it('keeps one purchase per id and contract reference, one profile per organization', async () => {
+    const { ctx } = booted
+    const purchase = await complete(booted, 'u1', 'org-u')
+    const { id: _id, ...copy } = purchase
+    const again = await purchases(ctx).create({ ...copy, contractRef: 'CR-000000-UNIQUE' }).catch(error => error)
+    expect(isDuplicateKey(again)).toBe(true)
+    const sameRef = await purchases(ctx).create({ ...copy, purchaseId: 'stripe:other', sessionId: 'cs_other' }).catch(error => error)
+    expect(isDuplicateKey(sameRef)).toBe(true)
+    // Subscription purchases have no session yet: the sparse unique index lets them coexist.
+    for (const id of ['sub_a', 'sub_b']) {
+      const { sessionId: _session, invoiceId: _invoice, ...rest } = copy
+      await purchases(ctx).create({ ...rest, purchaseId: `stripe:${id}`, contractRef: `CR-000000-${id.toUpperCase().replace('_', '')}X`, subscriptionId: id })
+    }
+    const profile = await billingProfiles(ctx).byEntity('org-u')
+    const { id: _pid, ...profileCopy } = profile!
+    expect(isDuplicateKey(await billingProfiles(ctx).create(profileCopy).catch(error => error))).toBe(true)
+  }, 60_000)
+
+  it('the first of concurrent locks wins; the others are mismatch events, never relocks', async () => {
+    const { ctx } = booted
+    const policy = await payment(ctx).consumerRightsPolicy()
+    const countries = ['DE', 'FR', 'PL', 'ES', 'IT', 'NL', 'AT', 'BE']
+    const results = await Promise.all(countries.map(country => lockProfile(ctx, policy, { entityId: 'org-race', country, source: 'checkout' })))
+    expect(results.filter(result => result.created)).toHaveLength(1)
+    const winner = (await billingProfiles(ctx).byEntity('org-race'))!.country
+    expect(results.every(result => result.record.country === winner)).toBe(true)
+    expect(await consumerEvents(ctx).count({ recordId: 'org-race', action: 'lock-mismatch' })).toBe(countries.length - 1)
+  }, 60_000)
+
+  it('stores the confirmation claim, an unlock and a terms fallback through their validators', async () => {
+    const { ctx } = booted
+    const purchase = await complete(booted, 'l1', 'org-l')
+    expect(purchase.confirmationMailAt).toBeInstanceOf(Date)
+
+    // Two processes capturing one session: one claim, one mail attempt.
+    state.invoices.in_l2 = invoiceOf('in_l2', { payment_intent: 'pi_l2', lines: { object: 'list', data: [{ id: 'il_l2' }] } })
+    const session = paidSession({ id: 'cs_l2', invoice: 'in_l2', payment_intent: 'pi_l2', customer: 'cus_org-l', metadata: { entityId: 'org-l' } })
+    await Promise.all([capturePaymentPurchase(ctx, stripe, session as never), capturePaymentPurchase(ctx, stripe, session as never)])
+    expect(await consumerEvents(ctx).count({ recordId: 'stripe:cs_l2', action: 'mail', step: 'purchase' })).toBe(1)
+
+    expect(await consumerRights(ctx).unlock('org-l', { by: 'operator', reason: 'integration' }))
+      .toEqual(expect.objectContaining({ country: 'PL' }))
+    expect(await billingProfiles(ctx).byEntity('org-l')).toBeNull()
+    expect(await consumerEvents(ctx).count({ recordId: 'org-l', action: 'unlock', ok: true })).toBe(1)
+
+    await recordEvent(ctx, {
+      recordId: 'org-l', recordKind: 'checkout', entityId: 'org-l', action: 'checkout-terms-fallback', ok: false,
+      externalId: 'cs_l3', detail: '{"param":"consent_collection[terms_of_service]"}',
+    })
+    expect(await consumerEvents(ctx).count({ recordId: 'org-l', action: 'checkout-terms-fallback' })).toBe(1)
+  }, 60_000)
+
+  it('only one of concurrent withdrawals of a purchase closes its window and refunds', async () => {
+    const { ctx } = booted
+    const purchase = await complete(booted, 'r1', 'org-r')
+    const refundsBefore = state.refunds.length
+    const receipts = await Promise.all(Array.from({ length: 5 }, async () => await consumerRights(ctx).withdraw({ entityId: 'org-r' }, {
+      purchaseId: purchase.purchaseId, name: 'Jan', email: 'owner@shop.eu',
+    })))
+    expect(state.refunds.length - refundsBefore).toBe(1)
+    const closed = await purchases(ctx).byPurchaseId(purchase.purchaseId)
+    expect(receipts.every(receipt => receipt.declarationId === closed?.withdrawalId)).toBe(true)
+  }, 60_000)
+})