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

package/src/consumer/capture.ts

@@ -0,0 +1,362 @@
+import type Stripe from 'stripe'
+import {
+  billingLanguageOf, ConsentKind, CONSUMER_RIGHTS_COPY_VERSION, inScope, PurchaseKind, regionOf,
+  withdrawalDeadlineOf,
+} from '@owlmeans/payment'
+import type { ConsumerRightsPolicy } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_PAYGATE_ALIAS } from '../consts.js'
+import {
+  billingProfiles, compact, conditionalSet, consumerConsents, dateOf, idOf, isMissingObject, payment, purchases,
+} from '../utils.js'
+import { sendConsumerMail } from './mail.js'
+import {
+  createPurchase, hasEvent, lockProfile, patchPurchase, purchaseIdOf,
+} from './records.js'
+import type { PurchaseDraft } from './records.js'
+import type { BillingProfileRecord, PaymentSubscriptionRecord, PurchaseRecord } from '../types.js'
+
+/** What a completed Checkout Session says about its buyer and totals. */
+export interface SessionEvidence {
+  country?: string
+  email?: string
+  name?: string
+  business?: boolean
+  currency: string
+  subtotalMinor: number
+  taxMinor: number
+  totalMinor: number
+  presentmentCurrency?: string
+  presentmentAmountMinor?: number
+  termsAccepted?: boolean
+}
+
+/**
+ * The buyer and totals of a Checkout Session. `presentment_details` (Adaptive Pricing) is not typed
+ * by the pinned SDK, hence the narrow accessor.
+ */
+export const sessionEvidenceOf = (session: Stripe.Checkout.Session): SessionEvidence => {
+  const details = session.customer_details
+  const presentment = (session as unknown as {
+    presentment_details?: { presentment_amount?: number, presentment_currency?: string } | null
+  }).presentment_details
+  const subtotal = session.amount_subtotal ?? 0
+  const tax = session.total_details?.amount_tax ?? 0
+
+  return compact({
+    country: details?.address?.country?.toUpperCase() ?? undefined,
+    email: details?.email ?? undefined,
+    name: details?.name ?? undefined,
+    business: (details?.tax_ids?.length ?? 0) > 0 || details?.tax_exempt === 'reverse' ? true : undefined,
+    currency: (session.currency ?? '').toLowerCase(),
+    subtotalMinor: subtotal,
+    taxMinor: tax,
+    totalMinor: session.amount_total ?? subtotal + tax,
+    presentmentCurrency: presentment?.presentment_currency?.toLowerCase(),
+    presentmentAmountMinor: presentment?.presentment_amount,
+    termsAccepted: session.consent?.terms_of_service === 'accepted' ? true
+      : session.consent?.terms_of_service != null ? false : undefined,
+  }) as SessionEvidence
+}
+
+/** What an invoice adds to a purchase: its number, its line and the payment behind it. */
+export interface InvoiceEvidence {
+  invoiceNumber?: string
+  invoiceLineId?: string
+  paymentIntentId?: string
+  country?: string
+  subtotalMinor?: number
+  taxMinor?: number
+  totalMinor?: number
+  currency?: string
+}
+
+/**
+ * An invoice's evidence, best effort: an unreachable invoice is logged and yields nothing — the
+ * withdrawal reads it again when it needs it. `invoice.payment_intent` is top-level on the pinned
+ * API version.
+ */
+export const invoiceEvidenceOf = async (stripe: Stripe | null | undefined, invoiceId: string | undefined): Promise<InvoiceEvidence> => {
+  if (stripe == null || invoiceId == null) {
+    return {}
+  }
+  try {
+    const invoice = await stripe.invoices.retrieve(invoiceId)
+    const typed = invoice as unknown as { payment_intent?: string | { id?: string } | null, tax?: number | null }
+
+    return compact({
+      invoiceNumber: invoice.number ?? undefined,
+      invoiceLineId: invoice.lines?.data?.[0]?.id,
+      paymentIntentId: idOf(typed.payment_intent),
+      country: invoice.customer_address?.country?.toUpperCase() ?? undefined,
+      subtotalMinor: invoice.subtotal ?? undefined,
+      taxMinor: typed.tax ?? undefined,
+      totalMinor: invoice.total ?? undefined,
+      currency: invoice.currency ?? undefined,
+    }) as InvoiceEvidence
+  } catch (error) {
+    if (!isMissingObject(error)) {
+      console.warn(`[payment] invoice "${invoiceId}" unreadable for its purchase`, error)
+    }
+    return {}
+  }
+}
+
+const deadlineOf = (policy: ConsumerRightsPolicy, scoped: boolean, purchasedAt: Date): Date | undefined =>
+  scoped ? withdrawalDeadlineOf(purchasedAt, policy) : undefined
+
+/** Lock the entity's billing country from a completed checkout, when the policy locks countries. */
+const lockFromSession = async (
+  ctx: ApiContext, policy: ConsumerRightsPolicy, entityId: string, session: Stripe.Checkout.Session,
+  evidence: SessionEvidence,
+): Promise<BillingProfileRecord | null> => {
+  const metadata = session.metadata ?? {}
+  const country = evidence.country ?? metadata.country
+  if (!policy.mechanisms.countryLock || country == null || country === '') {
+    return null
+  }
+  const { record } = await lockProfile(ctx, policy, {
+    entityId, country, source: 'checkout', customerId: idOf(session.customer), sessionId: session.id,
+    ipCountry: metadata.ipCountry, email: evidence.email, name: evidence.name, business: evidence.business,
+    currency: evidence.currency, language: metadata.language,
+  })
+
+  return record
+}
+
+/**
+ * Mail the purchase confirmation once per purchase: only the delivery that claims the purchase's
+ * `confirmationMailAt` (a conditional write — concurrent deliveries in several processes, a
+ * redelivery, the checkout refining a subscription) sends it; one that failed is retried by
+ * `reconcile`, never here. A purchase mailed before the claim existed is recognised by its event.
+ */
+const confirmPurchase = async (ctx: ApiContext, policy: ConsumerRightsPolicy, purchase: PurchaseRecord): Promise<void> => {
+  if (!policy.mechanisms.purchaseConfirmation || !purchase.inScope) {
+    return
+  }
+  if (await hasEvent(ctx, purchase.purchaseId, 'mail', 'purchase')) {
+    return
+  }
+  const claimed = await conditionalSet(purchases(ctx), { purchaseId: purchase.purchaseId, confirmationMailAt: null }, {
+    confirmationMailAt: new Date(),
+  })
+  if (!claimed) {
+    return
+  }
+  await sendConsumerMail(ctx, policy, 'purchase', purchase.purchaseId)
+}
+
+export interface CapturedPurchase {
+  purchase: PurchaseRecord
+  created: boolean
+}
+
+/**
+ * A completed, paid ONE-TIME checkout as a purchase — the window and the contract registry. Runs
+ * BEFORE the credits are granted: the billing country is locked first (first write wins; another
+ * country is a `lock-mismatch` event), then the purchase row is written, then its confirmation is
+ * mailed. `null` when no consumer-rights policy is declared.
+ */
+export const capturePaymentPurchase = async (
+  ctx: ApiContext, stripe: Stripe | null, session: Stripe.Checkout.Session,
+  extra: { netAmountMinor?: number, amountCurrency?: string, units?: number, taxBehavior?: string, at?: Date } = {},
+  opts: { mail?: boolean } = {},
+): Promise<CapturedPurchase | null> => {
+  const policy = await payment(ctx).consumerRightsPolicy()
+  if (policy == null) {
+    return null
+  }
+  const metadata = session.metadata ?? {}
+  const entityId = metadata.entityId
+  if (entityId == null || metadata.productSku == null) {
+    return null
+  }
+  const evidence = sessionEvidenceOf(session)
+  const profile = await lockFromSession(ctx, policy, entityId, session, evidence)
+  const existing = await purchases(ctx).byPurchaseId(purchaseIdOf(session.id))
+  if (existing != null) {
+    if (opts.mail !== false) await confirmPurchase(ctx, policy, existing)
+    return { purchase: existing, created: false }
+  }
+
+  const country = evidence.country ?? metadata.country ?? profile?.country
+  const region = regionOf(country, policy)
+  // Protected when either the buyer's own address or the organization's locked country is in scope.
+  const scoped = inScope(region, country, policy) || (profile != null && inScope(profile.region, profile.country, policy))
+  const invoice = await invoiceEvidenceOf(stripe, idOf(session.invoice))
+  const purchasedAt = extra.at ?? new Date()
+  const draft = compact({
+    purchaseId: purchaseIdOf(session.id),
+    entityId,
+    kind: PurchaseKind.TopUp,
+    paygate: STRIPE_PAYGATE_ALIAS,
+    sessionId: session.id,
+    paymentIntentId: idOf(session.payment_intent) ?? invoice.paymentIntentId,
+    invoiceId: idOf(session.invoice),
+    invoiceNumber: invoice.invoiceNumber,
+    invoiceLineId: invoice.invoiceLineId,
+    productSku: metadata.productSku,
+    planSku: metadata.planSku,
+    profileId: metadata.profileId,
+    country,
+    region: region ?? undefined,
+    ipCountry: metadata.ipCountry,
+    inScope: scoped,
+    language: profile?.language ?? metadata.language ?? billingLanguageOf(country, policy),
+    email: evidence.email,
+    name: evidence.name,
+    business: evidence.business,
+    currency: evidence.currency,
+    amountSubtotalMinor: evidence.subtotalMinor,
+    amountTaxMinor: evidence.taxMinor,
+    amountTotalMinor: evidence.totalMinor,
+    presentmentCurrency: evidence.presentmentCurrency,
+    presentmentAmountMinor: evidence.presentmentAmountMinor,
+    netAmountMinor: extra.netAmountMinor,
+    amountCurrency: extra.amountCurrency,
+    units: extra.units,
+    taxBehavior: extra.taxBehavior,
+    termsAccepted: evidence.termsAccepted,
+    textVersion: metadata.termsVersion ?? policy.textVersion,
+    copyVersion: metadata.copyVersion ?? CONSUMER_RIGHTS_COPY_VERSION,
+    purchasedAt,
+    deadline: deadlineOf(policy, scoped, purchasedAt),
+  }) as PurchaseDraft
+  const { record, created } = await createPurchase(ctx, draft)
+  if (opts.mail !== false) await confirmPurchase(ctx, policy, record)
+
+  return { purchase: record, created }
+}
+
+/** The start request a subscription's metadata names, when it is a real start request of that entity. */
+const startRequestOf = async (ctx: ApiContext, entityId: string, id: string | undefined) => {
+  if (id == null || id === '') {
+    return null
+  }
+  const consent = await consumerConsents(ctx).load(id).catch(() => null)
+
+  return consent != null && consent.kind === ConsentKind.SubscriptionStart && consent.entityId === entityId ? consent : null
+}
+
+/**
+ * A subscription's FIRST invoice as a purchase — called while the subscription is committed, BEFORE
+ * the `created` observers grant anything, so the window exists before the bundle can be spent. The
+ * buyer's country and totals are refined when the checkout completes. The start request (when the
+ * metadata names one) is the purchase's consent: `servicesStartedAt` and `consentedAt`.
+ */
+export const captureSubscriptionPurchase = async (
+  ctx: ApiContext, stripe: Stripe | null, subscription: Stripe.Subscription, row: PaymentSubscriptionRecord,
+): Promise<CapturedPurchase | null> => {
+  const policy = await payment(ctx).consumerRightsPolicy()
+  if (policy == null) {
+    return null
+  }
+  const purchaseId = purchaseIdOf(subscription.id)
+  const existing = await purchases(ctx).byPurchaseId(purchaseId)
+  if (existing != null) {
+    return { purchase: existing, created: false }
+  }
+  const metadata = subscription.metadata ?? {}
+  const item = subscription.items?.data?.[0]
+  const invoiceId = idOf(subscription.latest_invoice)
+  const invoice = await invoiceEvidenceOf(stripe, invoiceId)
+  const profile = await billingProfiles(ctx).byEntity(row.entityId)
+  const country = invoice.country ?? profile?.country ?? metadata.country
+  const region = regionOf(country, policy)
+  const scoped = inScope(region, country, policy) || (profile != null && inScope(profile.region, profile.country, policy))
+  const start = await startRequestOf(ctx, row.entityId, metadata.startRequestId)
+  const subtotal = invoice.subtotalMinor ?? (item?.price?.unit_amount ?? 0) * (item?.quantity ?? 1)
+  const tax = invoice.taxMinor ?? 0
+  const purchasedAt = dateOf(subscription.created) ?? new Date()
+  const draft = compact({
+    purchaseId,
+    entityId: row.entityId,
+    kind: PurchaseKind.Subscription,
+    paygate: STRIPE_PAYGATE_ALIAS,
+    subscriptionId: subscription.id,
+    paymentIntentId: invoice.paymentIntentId,
+    invoiceId,
+    invoiceNumber: invoice.invoiceNumber,
+    invoiceLineId: invoice.invoiceLineId,
+    productSku: row.productSku,
+    planSku: row.planSku,
+    profileId: metadata.profileId,
+    country,
+    region: region ?? undefined,
+    ipCountry: metadata.ipCountry,
+    inScope: scoped,
+    language: profile?.language ?? metadata.language ?? billingLanguageOf(country, policy),
+    currency: (invoice.currency ?? subscription.currency ?? item?.price?.currency ?? 'usd').toLowerCase(),
+    amountSubtotalMinor: subtotal,
+    amountTaxMinor: tax,
+    amountTotalMinor: invoice.totalMinor ?? subtotal + tax,
+    taxBehavior: item?.price?.tax_behavior ?? undefined,
+    textVersion: metadata.termsVersion ?? policy.textVersion,
+    copyVersion: metadata.copyVersion ?? CONSUMER_RIGHTS_COPY_VERSION,
+    startRequestId: start?.id,
+    servicesStartedAt: start?.decidedAt,
+    consentId: start?.id,
+    consentedAt: start?.decidedAt,
+    purchasedAt,
+    deadline: deadlineOf(policy, scoped, purchasedAt),
+  }) as PurchaseDraft
+  const { record, created } = await createPurchase(ctx, draft)
+
+  return { purchase: record, created }
+}
+
+/**
+ * Refine a subscription purchase with its completed checkout: the buyer's own country (and so the
+ * scope and deadline), e-mail, the charged totals, the terms acceptance and the session id; lock
+ * the billing country; mail the confirmation once.
+ */
+export const completeSubscriptionPurchase = async (
+  ctx: ApiContext, stripe: Stripe | null, session: Stripe.Checkout.Session, purchase: PurchaseRecord,
+  opts: { mail?: boolean } = {},
+): Promise<PurchaseRecord> => {
+  const policy = await payment(ctx).consumerRightsPolicy()
+  if (policy == null) {
+    return purchase
+  }
+  const evidence = sessionEvidenceOf(session)
+  const profile = await lockFromSession(ctx, policy, purchase.entityId, session, evidence)
+  const country = evidence.country ?? purchase.country ?? profile?.country
+  const region = regionOf(country, policy)
+  const scoped = inScope(region, country, policy) || (profile != null && inScope(profile.region, profile.country, policy))
+  const invoice = purchase.invoiceLineId == null || purchase.paymentIntentId == null
+    ? await invoiceEvidenceOf(stripe, purchase.invoiceId ?? idOf(session.invoice)) : {}
+  const purchasedAt = new Date(purchase.purchasedAt)
+  const fields = compact({
+    sessionId: session.id,
+    invoiceId: purchase.invoiceId ?? idOf(session.invoice),
+    invoiceNumber: purchase.invoiceNumber ?? invoice.invoiceNumber,
+    invoiceLineId: purchase.invoiceLineId ?? invoice.invoiceLineId,
+    paymentIntentId: purchase.paymentIntentId ?? invoice.paymentIntentId,
+    country,
+    region: region ?? undefined,
+    inScope: scoped,
+    deadline: scoped ? purchase.deadline ?? withdrawalDeadlineOf(purchasedAt, policy) : undefined,
+    email: evidence.email ?? purchase.email,
+    name: evidence.name ?? purchase.name,
+    business: evidence.business ?? purchase.business,
+    currency: evidence.currency !== '' ? evidence.currency : purchase.currency,
+    amountSubtotalMinor: evidence.subtotalMinor,
+    amountTaxMinor: evidence.taxMinor,
+    amountTotalMinor: evidence.totalMinor,
+    presentmentCurrency: evidence.presentmentCurrency,
+    presentmentAmountMinor: evidence.presentmentAmountMinor,
+    termsAccepted: evidence.termsAccepted,
+    ipCountry: purchase.ipCountry ?? session.metadata?.ipCountry,
+    language: profile?.language ?? purchase.language,
+  }) as Partial<PurchaseRecord>
+  await patchPurchase(ctx, purchase.purchaseId, fields)
+  const updated = { ...purchase, ...fields } as PurchaseRecord
+  if (!scoped && purchase.deadline != null) {
+    // Out of scope after all (the buyer's own country): no window.
+    await patchPurchase(ctx, purchase.purchaseId, { deadline: null as unknown as undefined })
+    delete updated.deadline
+  }
+  if (opts.mail !== false) await confirmPurchase(ctx, policy, updated)
+
+  return updated
+}

package/src/consumer/format.ts

@@ -0,0 +1,90 @@
+import { randomInt } from 'node:crypto'
+import { lastWithdrawalDayOf } from '@owlmeans/payment'
+import { CONTRACT_REF_ALPHABET, RESERVED_MAIL_TLDS } from '../consts.js'
+
+/** `CR-YYMMDD-XXXXXX` — the purchase's UTC date and six characters of an unambiguous alphabet. */
+export const makeContractRef = (at: Date = new Date()): string => {
+  const date = [at.getUTCFullYear() % 100, at.getUTCMonth() + 1, at.getUTCDate()]
+    .map(part => String(part).padStart(2, '0')).join('')
+  const suffix = Array.from({ length: 6 }, () => CONTRACT_REF_ALPHABET[randomInt(CONTRACT_REF_ALPHABET.length)]).join('')
+
+  return `CR-${date}-${suffix}`
+}
+
+/** A contract reference as a person may type it: trimmed, upper-cased, look-alike dashes unified. */
+export const normalizeContractRef = (value: string): string =>
+  value.trim().toUpperCase().replace(/[‐-―−\s]+/g, '-')
+
+export const normalizeEmail = (value: string | null | undefined): string => (value ?? '').trim().toLowerCase()
+
+/**
+ * Whether an address is on a reserved top-level domain (`.test`, `.example`, `.invalid`,
+ * `.localhost` — RFC 2606 / 6761), any subdomain included: `a@shop.test`, `a@mail.shop.test`,
+ * `a@localhost`. Case, surrounding spaces, a display-name form (`Name <a@shop.test>`) and a
+ * trailing root dot are all read through.
+ */
+export const isReservedAddress = (address: string): boolean => {
+  const bare = normalizeEmail(address).replace(/^.*<([^>]*)>.*$/, '$1')
+  const domain = (bare.split('@').pop() ?? '').trim().replace(/\.+$/, '')
+  const tld = domain.split('.').pop() ?? ''
+
+  return RESERVED_MAIL_TLDS.includes(tld)
+}
+
+export const escapeHtml = (value: string): string => value
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+const fractionDigitsOf = (currency: string): number => {
+  try {
+    return new Intl.NumberFormat('en', { style: 'currency', currency: currency.toUpperCase() })
+      .resolvedOptions().maximumFractionDigits ?? 2
+  } catch {
+    return 2
+  }
+}
+
+/** Minor units as a localized amount with its currency (`12,56 €`, `$12.56`). */
+export const formatMoney = (amountMinor: number, currency: string, lng: string): string => {
+  const digits = fractionDigitsOf(currency)
+  const major = amountMinor / 10 ** digits
+  try {
+    return new Intl.NumberFormat(lng, { style: 'currency', currency: currency.toUpperCase() }).format(major)
+  } catch {
+    return `${major.toFixed(digits)} ${currency.toUpperCase()}`
+  }
+}
+
+/** A date and time in UTC, localized (`23 September 2026, 14:05`). */
+export const formatDateTime = (at: Date, lng: string): string => {
+  try {
+    return new Intl.DateTimeFormat(lng, { dateStyle: 'long', timeStyle: 'short', timeZone: 'UTC' }).format(at)
+  } catch {
+    return at.toISOString().replace('T', ' ').slice(0, 16)
+  }
+}
+
+/** A calendar date in UTC, localized. */
+export const formatDate = (at: Date, lng: string): string => {
+  try {
+    return new Intl.DateTimeFormat(lng, { dateStyle: 'long', timeZone: 'UTC' }).format(at)
+  } catch {
+    return at.toISOString().slice(0, 10)
+  }
+}
+
+/**
+ * The last included day of a window whose deadline is EXCLUSIVE (the first instant it is over),
+ * as a UTC date — the copy says "until the end of <date>": 13 October 00:00 UTC is "12 October".
+ */
+export const formatDeadline = (deadline: Date, lng: string): string =>
+  formatDate(lastWithdrawalDayOf(deadline), lng)
+
+/** A country's name in a language, else its code. */
+export const countryName = (country: string, lng: string): string => {
+  try {
+    return new Intl.DisplayNames([lng], { type: 'region' }).of(country.toUpperCase()) ?? country
+  } catch {
+    return country
+  }
+}

package/src/consumer/handlers.ts

@@ -0,0 +1,211 @@
+import { randomBytes } from 'node:crypto'
+import { AuthForbidden } from '@owlmeans/auth'
+import type { AbstractRequest, EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import { ConsumerRightsError, DeclarationChannel } from '@owlmeans/payment'
+import type {
+  CheckoutReadProtocols, ConsumerRightsAccountProtocols, ConsumerRightsPublicProtocols, ConsumerRightsPublicView,
+  DeclarationReceipt,
+} from '@owlmeans/payment'
+import { handlers } from '@owlmeans/server-api'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { bind } from '@owlmeans/server-entrypoint'
+import type { ServerProtocolEntrypoint } from '@owlmeans/server-entrypoint'
+import { CONSUMER_RIGHTS_SERVICE, GATEWAY_SERVICE } from '../consts.js'
+import { payment } from '../utils.js'
+import { requestOriginOf } from './origin.js'
+import { unlockedProfileView } from './records.js'
+import type {
+  CheckoutReadHandlerOptions, ConsumerRightsHandlerOptions, ConsumerRightsService, ConsumerSubject, Context,
+  GatewayService, RequestOrigin,
+} from '../types.js'
+
+type Bound = ServerProtocolEntrypoint<EntrypointProtocolDeclaration>
+
+/** The protocol tree `makeConsumerRightsProtocols` builds, with or without its public subtree. */
+export type ConsumerRightsTree = ConsumerRightsAccountProtocols & { public?: ConsumerRightsPublicProtocols }
+
+const defaultEntity = (req: AbstractRequest, _ctx?: ApiContext): string | null => req.entity?.id ?? null
+
+const DEFAULT_PUBLIC_MIN_MS = 1000
+
+const sleep = async (ms: number): Promise<void> => await new Promise(resolve => setTimeout(resolve, ms))
+
+/** Answer no sooner than `minMs` after the start — a matched declaration takes as long as an unmatched one. */
+const padded = async <T>(minMs: number, run: () => Promise<T>): Promise<T> => {
+  const started = Date.now()
+  try {
+    return await run()
+  } finally {
+    const left = minMs - (Date.now() - started)
+    if (left > 0) await sleep(left)
+  }
+}
+
+/** The public answer: what was declared and when — never a status, an amount or a match. */
+const publicPart = (receipt: DeclarationReceipt): DeclarationReceipt => ({
+  declarationId: receipt.declarationId, receivedAt: receipt.receivedAt, content: receipt.content, mailed: receipt.mailed,
+})
+
+/** A form a bot filled (the honeypot) gets the same shape of answer, and nothing is recorded or sent. */
+const decoyReceipt = (content: Record<string, string>): DeclarationReceipt => ({
+  declarationId: randomBytes(12).toString('hex'), receivedAt: new Date(), content, mailed: false,
+})
+
+const typed = (fields: Record<string, string | undefined>): Record<string, string> =>
+  Object.fromEntries(Object.entries(fields).filter((entry): entry is [string, string] =>
+    typeof entry[1] === 'string' && entry[1].trim() !== ''))
+
+/**
+ * Server bindings of `makeConsumerRightsProtocols`' tree over the consumer-rights service. The
+ * account routes act for the request's organization (`resolveEntity`, default `req.entity.id`);
+ * the money-moving acts (consent, start request, withdrawal, cancellation) pass `guardMoney` first
+ * (refuse an API key there). The public routes — the statutory functions without a login — need
+ * `throttle` (a wiring error otherwise), drop a filled honeypot silently, and answer every
+ * declaration with the same receipt shape after at least `publicMinMs`, matched or not. Every hook
+ * gets the request's context as its last argument.
+ *
+ * @throws SyntaxError when the tree has a public subtree and no `throttle` is given
+ */
+export const consumerRightsEntrypoints = (
+  protocols: ConsumerRightsTree, opts: ConsumerRightsHandlerOptions = {},
+): Bound[] => {
+  if (protocols.public != null && opts.throttle == null) {
+    throw new SyntaxError('consumer-rights: the public routes need a throttle')
+  }
+  const api = handlers<Context>()
+  const serviceOf = (ctx: Context): ConsumerRightsService =>
+    ctx.service<ConsumerRightsService>(opts.serviceAlias ?? CONSUMER_RIGHTS_SERVICE)
+  const apiCtx = (ctx: Context): ApiContext => ctx as unknown as ApiContext
+  const entityOf = (req: AbstractRequest, ctx: Context): string => {
+    const entityId = (opts.resolveEntity ?? defaultEntity)(req, apiCtx(ctx))
+    if (entityId == null || entityId === '') {
+      throw new AuthForbidden('entity')
+    }
+
+    return entityId
+  }
+  const subjectFor = async (req: AbstractRequest, ctx: Context): Promise<ConsumerSubject> => ({
+    ...(await opts.subjectOf?.(req, apiCtx(ctx)) ?? {}),
+    entityId: entityOf(req, ctx),
+    channel: DeclarationChannel.InApp,
+  })
+  const metaOf = (req: AbstractRequest, ctx: Context): RequestOrigin =>
+    opts.metaOf != null ? opts.metaOf(req, apiCtx(ctx)) : requestOriginOf(req)
+  const guard = async (req: AbstractRequest, action: string, ctx: Context): Promise<void> => {
+    await opts.guardMoney?.(req, action, apiCtx(ctx))
+  }
+  const minMs = opts.publicMinMs ?? DEFAULT_PUBLIC_MIN_MS
+
+  const bound: Bound[] = [
+    bind(protocols.base),
+    bind(protocols.profile, api.request(protocols.profile, async (req, ctx) =>
+      await serviceOf(ctx).profile(entityOf(req, ctx))
+        ?? unlockedProfileView(await payment(ctx as unknown as ApiContext).consumerRightsPolicy()))),
+    bind(protocols.purchases, api.request(protocols.purchases, async (req, ctx) =>
+      ({ purchases: await serviceOf(ctx).purchases(entityOf(req, ctx)) }))),
+    bind(protocols.consent, api.request(protocols.consent, async (req, ctx) =>
+      await serviceOf(ctx).consentView(entityOf(req, ctx)))),
+    bind(protocols.giveConsent, api.body(protocols.giveConsent, async (body, ctx, req) => {
+      await guard(req, 'consent', ctx)
+      return await serviceOf(ctx).recordConsent(await subjectFor(req, ctx), body, metaOf(req, ctx))
+    })),
+    bind(protocols.start, api.request(protocols.start, async (req, ctx) =>
+      await serviceOf(ctx).startView(entityOf(req, ctx), String(req.query.planSku)))),
+    bind(protocols.requestStart, api.body(protocols.requestStart, async (body, ctx, req) => {
+      await guard(req, 'start', ctx)
+      const plan = await opts.planNameOf?.(body.planSku, body.language, req, apiCtx(ctx))
+      return await serviceOf(ctx).recordStartRequest(await subjectFor(req, ctx), body, metaOf(req, ctx), plan != null ? { plan } : {})
+    })),
+    bind(protocols.withdrawals, api.request(protocols.withdrawals, async (req, ctx) => {
+      const subject = await subjectFor(req, ctx)
+      return await serviceOf(ctx).withdrawalCandidates(subject.entityId, subject)
+    })),
+    bind(protocols.withdraw, api.body(protocols.withdraw, async (body, ctx, req) => {
+      await guard(req, 'withdraw', ctx)
+      return await serviceOf(ctx).withdraw(await subjectFor(req, ctx), body, metaOf(req, ctx))
+    })),
+    bind(protocols.cancel, api.body(protocols.cancel, async (body, ctx, req) => {
+      await guard(req, 'cancel', ctx)
+      return await serviceOf(ctx).cancel(await subjectFor(req, ctx), body, metaOf(req, ctx))
+    })),
+  ] as Bound[]
+
+  const pub = protocols.public
+  if (pub == null) {
+    return bound
+  }
+  const throttle = opts.throttle as NonNullable<ConsumerRightsHandlerOptions['throttle']>
+
+  return [
+    ...bound,
+    bind(pub.base),
+    bind(pub.policy, api.request(pub.policy, async (_req, ctx) => {
+      const policy = await payment(ctx as unknown as ApiContext).consumerRightsPolicy()
+      if (policy == null) {
+        throw new ConsumerRightsError('policy:none')
+      }
+      const view: ConsumerRightsPublicView = {
+        mechanisms: { withdrawal: policy.mechanisms.withdrawal, cancellation: policy.mechanisms.cancellation },
+        languages: Object.keys(policy.links),
+        links: policy.links,
+        textVersion: policy.textVersion,
+      }
+      return view
+    })),
+    bind(pub.withdraw, api.body(pub.withdraw, async (body, ctx, req) => {
+      const origin = metaOf(req, ctx)
+      await throttle(req, { action: 'withdrawal', email: body.email, ...(origin.ip != null ? { ip: origin.ip } : {}) }, apiCtx(ctx))
+      return await padded(minMs, async () => {
+        const content = typed({ name: body.name, contract: body.contractRef, email: body.email })
+        if (body.honeypot != null && body.honeypot !== '') {
+          return decoyReceipt(content)
+        }
+        return publicPart(await serviceOf(ctx).withdraw(null, body, origin))
+      })
+    })),
+    bind(pub.cancel, api.body(pub.cancel, async (body, ctx, req) => {
+      const origin = metaOf(req, ctx)
+      await throttle(req, { action: 'cancellation', email: body.email, ...(origin.ip != null ? { ip: origin.ip } : {}) }, apiCtx(ctx))
+      return await padded(minMs, async () => {
+        const content = typed({
+          name: body.name, contract: body.contractRef, email: body.email, kind: body.kind, reason: body.reason,
+          date: body.effective === 'date' ? body.date : undefined,
+        })
+        if (body.honeypot != null && body.honeypot !== '') {
+          return decoyReceipt(content)
+        }
+        return publicPart(await serviceOf(ctx).cancel(null, body, origin))
+      })
+    })),
+  ] as Bound[]
+}
+
+/**
+ * Server bindings of `makeCheckoutReadProtocols`' tree: the entity's amount policy as the checkout
+ * plugins narrow it now (the same computation the checkout enforces) and the synced plan prices.
+ */
+export const checkoutReadEntrypoints = (protocols: CheckoutReadProtocols, opts: CheckoutReadHandlerOptions = {}): Bound[] => {
+  const api = handlers<Context>()
+  const gatewayOf = (ctx: Context): GatewayService => ctx.service<GatewayService>(opts.gatewayAlias ?? GATEWAY_SERVICE)
+  const entityOf = (req: AbstractRequest, ctx: Context): string => {
+    const entityId = (opts.resolveEntity ?? defaultEntity)(req, ctx as unknown as ApiContext)
+    if (entityId == null || entityId === '') {
+      throw new AuthForbidden('entity')
+    }
+
+    return entityId
+  }
+
+  return [
+    bind(protocols.base),
+    bind(protocols.amountPolicy, api.request(protocols.amountPolicy, async (req, ctx) => {
+      const { productSku, planSku } = req.query as { productSku: string, planSku?: string }
+      return await gatewayOf(ctx).amountPolicy(ctx as unknown as ApiContext, entityOf(req, ctx), productSku, planSku ?? undefined)
+    })),
+    bind(protocols.planPrices, api.request(protocols.planPrices, async (req, ctx) => {
+      entityOf(req, ctx)
+      const { productSku } = req.query as { productSku: string }
+      return { prices: await gatewayOf(ctx).planPrices(ctx as unknown as ApiContext, productSku) }
+    })),
+  ] as Bound[]
+}

package/src/consumer/index.ts

@@ -0,0 +1,6 @@
+export { requestOriginOf } from './origin.js'
+export { appendConsumerRights, makeConsumerRightsService } from './service.js'
+export { consumerRightsEntrypoints, checkoutReadEntrypoints } from './handlers.js'
+export type { ConsumerRightsTree } from './handlers.js'
+export { traderIdentityOf } from './mail.js'
+export { makeContractRef, isReservedAddress } from './format.js'