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

package/src/plugins/webhook-manager.ts

@@ -0,0 +1,270 @@
+import { createHash } from 'node:crypto'
+import type Stripe from 'stripe'
+import { makeSecurityHelper } from '@owlmeans/config'
+import type { CommonServiceRoute } from '@owlmeans/route'
+import { normalizePath } from '@owlmeans/route'
+import { WebhookSetupError } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import {
+  paymentGate, STRIPE_OWNER_KEY, STRIPE_OWNER_VALUE, STRIPE_PAYGATE_ALIAS, WEBHOOK_EVENTS,
+} from '../consts.js'
+import { apiVersionOf, isDuplicateKey, isMissingObject, paymentWebhooks, stripeConfig } from '../utils.js'
+import type { PaymentWebhookRecord } from '../types.js'
+
+/** The path the webhook route answers for one paygate: `/<base>/webhook/<paygate>`. */
+export const webhookPathOf = (paygate: string): string =>
+  '/' + normalizePath(normalizePath(paymentGate.base.route.route.path) + '/'
+    + normalizePath(paymentGate.webhook.route.route.path).replace(':paygate', paygate))
+
+/** This deployment's public webhook URL for a paygate. */
+export const webhookUrlOf = (ctx: ApiContext, paygate: string = STRIPE_PAYGATE_ALIAS): string => {
+  const route = ctx.cfg.services?.[ctx.cfg.service] as CommonServiceRoute | undefined
+  if (route == null) {
+    throw new WebhookSetupError(`service:${ctx.cfg.service}`)
+  }
+
+  return makeSecurityHelper(ctx as never).makeUrl(route, webhookPathOf(paygate))
+}
+
+/** A URL a paygate can deliver to: https on a public, dotted host name. */
+export const isDeliverableUrl = (url: string): boolean => {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return false
+  }
+  const host = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase()
+
+  return parsed.protocol === 'https:' && host !== 'localhost' && host !== '127.0.0.1' && host !== '::1'
+    && !host.endsWith('.local') && host.includes('.')
+}
+
+/** An operator's label on an endpoint this package created — never evidence of which deployment owns it. */
+const ownerMetadata = (service: string): Record<string, string> =>
+  ({ [STRIPE_OWNER_KEY]: STRIPE_OWNER_VALUE, service })
+
+const hashOf = (url: string, apiVersion: string, events: string[]): string =>
+  createHash('sha256').update(JSON.stringify({ url, apiVersion, events })).digest('hex')
+
+const listEndpoints = async (stripe: Stripe): Promise<Stripe.WebhookEndpoint[]> => {
+  const endpoints: Stripe.WebhookEndpoint[] = []
+  let startingAfter: string | undefined
+  for (;;) {
+    const page = await stripe.webhookEndpoints.list({
+      limit: 100, ...(startingAfter != null ? { starting_after: startingAfter } : {}),
+    })
+    endpoints.push(...page.data)
+    if (!page.has_more || page.data.length === 0) {
+      return endpoints
+    }
+    startingAfter = page.data[page.data.length - 1].id
+  }
+}
+
+const dropEndpoint = async (stripe: Stripe, id: string): Promise<void> => {
+  try {
+    await stripe.webhookEndpoints.del(id)
+  } catch (error) {
+    if (!isMissingObject(error)) {
+      throw error
+    }
+  }
+}
+
+/** Field-encrypt the secret where the database is configured for it; store it plain otherwise. */
+const sealed = async (row: Partial<PaymentWebhookRecord>, ctx: ApiContext): Promise<Partial<PaymentWebhookRecord>> => {
+  const resource = paymentWebhooks(ctx)
+  if (typeof resource.lock !== 'function') {
+    return row
+  }
+  try {
+    return await resource.lock(row, ['secret']) as Partial<PaymentWebhookRecord>
+  } catch {
+    return row
+  }
+}
+
+const opened = async (row: PaymentWebhookRecord, ctx: ApiContext): Promise<string> => {
+  const resource = paymentWebhooks(ctx)
+  if (typeof resource.unlock !== 'function') {
+    return row.secret
+  }
+  try {
+    return (await resource.unlock(row, ['secret']) as PaymentWebhookRecord).secret
+  } catch {
+    return row.secret
+  }
+}
+
+export interface EnsureWebhookOptions {
+  /** Verify the stored endpoint still exists even when nothing changed locally. */
+  force?: boolean
+}
+
+/**
+ * Delete the endpoints this deployment created at URLs it has left: each `payment-webhook` row of
+ * this paygate and service at another URL drops the endpoint it names (one already gone is fine),
+ * then the row itself. `live` — the endpoint just put in place — is never dropped.
+ */
+const pruneFormerUrls = async (
+  ctx: ApiContext, stripe: Stripe, service: string, url: string, live: string,
+): Promise<void> => {
+  const resource = paymentWebhooks(ctx)
+  const { items } = await resource.list(
+    { paygate: STRIPE_PAYGATE_ALIAS, service, url: { $ne: url } }, { size: 0 },
+  )
+  for (const row of items) {
+    if (row.externalId !== live) {
+      await dropEndpoint(stripe, row.externalId)
+    }
+    await resource.delete(row.id as string)
+  }
+}
+
+/**
+ * Keep exactly one Stripe webhook endpoint for this deployment at its own URL, subscribed to
+ * `WEBHOOK_EVENTS` on the client's API version, and persist its signing secret — which Stripe
+ * returns only when an endpoint is created.
+ *
+ * A deployment's identity is its webhook URL. Several deployments of one service may share a Stripe
+ * account — a test-mode account commonly serves every non-production deployment — each with its own
+ * database and URL, so a deployment deletes only the endpoints its own `payment-webhook` rows name.
+ *
+ * - A URL Stripe cannot deliver to (not https, a loopback or dotless host) is skipped.
+ * - An unchanged `{ url, apiVersion, events }` fingerprint makes no paygate call at all.
+ * - `force` first verifies the stored endpoint still exists; one deleted from outside loses its row
+ *   and is created again.
+ * - Changed events on the same API version update the endpoint in place.
+ * - A changed API version (create-only on an endpoint) deletes and recreates it.
+ * - An endpoint already at this exact URL that no row names is replaced: its secret is unknown here.
+ * - A row of this paygate and service at another URL is a URL this deployment has left: once the
+ *   endpoint at the current URL is in place, the endpoint that row names is deleted (already gone is
+ *   fine), then the row.
+ * - An endpoint at another URL that no row of this deployment names belongs to another deployment
+ *   and is never deleted — whatever its metadata says.
+ * - Replicas racing to persist one row: the endpoint created last is the live one.
+ * - A created endpoint carries `{ owlmeans: 'payment', service }` metadata for operators.
+ */
+export const ensureWebhookEndpoint = async (
+  ctx: ApiContext, stripe: Stripe, opts: EnsureWebhookOptions = {},
+): Promise<PaymentWebhookRecord | null> => {
+  const url = webhookUrlOf(ctx)
+  if (!isDeliverableUrl(url)) {
+    console.info(`[payment] webhook endpoint not managed: "${url}" is not a public https URL`)
+    return null
+  }
+  const service = ctx.cfg.service
+  const apiVersion = apiVersionOf(stripe)
+  const events = [...WEBHOOK_EVENTS].sort()
+  const hash = hashOf(url, apiVersion, events)
+  const resource = paymentWebhooks(ctx)
+  const description = `owlmeans:${service}`
+  const metadata = ownerMetadata(service)
+  const now = new Date()
+
+  let stored = await resource.load({ paygate: STRIPE_PAYGATE_ALIAS, service, url })
+  if (stored != null && opts.force === true) {
+    try {
+      await stripe.webhookEndpoints.retrieve(stored.externalId)
+    } catch (error) {
+      if (!isMissingObject(error)) {
+        throw error
+      }
+      await resource.delete(stored.id as string)
+      stored = null
+    }
+  }
+  if (stored != null && stored.hash === hash && opts.force !== true) {
+    return stored
+  }
+
+  let live: PaymentWebhookRecord | null = null
+  if (stored != null && stored.apiVersion === apiVersion) {
+    try {
+      await stripe.webhookEndpoints.update(stored.externalId, {
+        url, enabled_events: events as Stripe.WebhookEndpointUpdateParams.EnabledEvent[],
+        description, metadata, disabled: false,
+      })
+      live = await resource.update({ ...stored, events, hash, updatedAt: now })
+    } catch (error) {
+      if (!isMissingObject(error)) {
+        throw error
+      }
+    }
+  }
+
+  if (live == null) {
+    if (stored != null) {
+      await dropEndpoint(stripe, stored.externalId)
+    }
+    for (const endpoint of await listEndpoints(stripe)) {
+      if (endpoint.url === url) {
+        await dropEndpoint(stripe, endpoint.id)
+      }
+    }
+
+    const created = await stripe.webhookEndpoints.create({
+      url, enabled_events: events as Stripe.WebhookEndpointCreateParams.EnabledEvent[],
+      api_version: apiVersion as Stripe.WebhookEndpointCreateParams.ApiVersion, description, metadata,
+    })
+    if (created.secret == null || created.secret === '') {
+      throw new WebhookSetupError('secret-missing')
+    }
+
+    const row = await sealed({
+      paygate: STRIPE_PAYGATE_ALIAS, service, url, externalId: created.id, secret: created.secret,
+      apiVersion, events, hash, createdAt: stored?.createdAt ?? now, updatedAt: now,
+    }, ctx)
+    try {
+      live = stored != null
+        ? await resource.update({ ...row, id: stored.id } as PaymentWebhookRecord)
+        : await resource.create(row)
+    } catch (error) {
+      if (!isDuplicateKey(error)) {
+        throw error
+      }
+      // Another replica persisted its endpoint meanwhile; the one created last is the live one.
+      const winner = await resource.load({ paygate: STRIPE_PAYGATE_ALIAS, service, url })
+      live = await resource.update({ ...row, id: winner?.id } as PaymentWebhookRecord)
+    }
+  }
+
+  await pruneFormerUrls(ctx, stripe, service, url, live.externalId)
+
+  return live
+}
+
+/**
+ * The secrets a Stripe signature may be verified with, in order: the configured file secret (an
+ * override), then the one stored for the managed endpoint.
+ */
+export const stripeWebhookSecrets = async (ctx: ApiContext): Promise<string[]> => {
+  const secrets: string[] = []
+  const configured = await stripeConfig(ctx).then(config => config.webhook, () => undefined)
+  if (typeof configured === 'string' && configured.trim() !== '') {
+    secrets.push(configured.trim())
+  }
+  const stored = await paymentWebhooks(ctx).load(
+    { paygate: STRIPE_PAYGATE_ALIAS, service: ctx.cfg.service },
+    { sort: [{ field: 'updatedAt', order: 'desc' }] },
+  )
+  if (stored != null) {
+    const secret = await opened(stored, ctx)
+    if (secret !== '' && !secrets.includes(secret)) {
+      secrets.push(secret)
+    }
+  }
+
+  return secrets
+}
+
+/** The secret a Stripe signature is verified with. @throws WebhookSetupError('secret') */
+export const stripeWebhookSecret = async (ctx: ApiContext): Promise<string> => {
+  const [secret] = await stripeWebhookSecrets(ctx)
+  if (secret == null) {
+    throw new WebhookSetupError('secret')
+  }
+
+  return secret
+}

package/src/reconcile.ts

@@ -0,0 +1,103 @@
+import { PlanRequired } from '@owlmeans/payment'
+import type { EntitlementView } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { entitlements, gateway, subscriptions, usageEvents } from './utils.js'
+import type { ReconcileAllOptions, ReconcileAllResult, ReconcileEntityOptions } from './types.js'
+
+/** Grant the free plan when the entity holds no entitling subscription. @returns whether it granted */
+const backfillFreePlan = async (ctx: ApiContext, entityId: string, freePlanSku: string): Promise<boolean> => {
+  try {
+    const { subscription } = await entitlements(ctx).effectivePlan(entityId)
+    if (subscription != null) {
+      return false
+    }
+  } catch (error) {
+    if (!(error instanceof PlanRequired)) {
+      throw error
+    }
+  }
+  await gateway(ctx).grantInternalPlan(ctx, entityId, freePlanSku)
+
+  return true
+}
+
+const resyncEntity = async (ctx: ApiContext, entityId: string): Promise<void> => {
+  const service = gateway(ctx)
+  if (!service.managed) {
+    return
+  }
+  try {
+    await service.resyncSubscription(ctx, { entityId })
+  } catch (error) {
+    console.error(`[payment] reconcile: resync of "${entityId}" failed`, error)
+  }
+}
+
+/**
+ * Repair one entity: optionally re-read its paygate subscriptions, grant the free plan when it holds
+ * nothing entitling, recompute its limit counters from the ledger, and return its view.
+ */
+export const reconcileEntity = async (
+  ctx: ApiContext, entityId: string, opts: ReconcileEntityOptions = {},
+): Promise<EntitlementView> => {
+  if (opts.resync === true) {
+    await resyncEntity(ctx, entityId)
+  }
+  if (opts.freePlanSku != null) {
+    await backfillFreePlan(ctx, entityId, opts.freePlanSku)
+  }
+  await entitlements(ctx).reconcileCounters(entityId)
+
+  return await entitlements(ctx).entitlements(entityId)
+}
+
+type Distinct = { collection: { distinct: (field: string, filter: object) => Promise<unknown[]> } }
+
+const knownEntities = async (ctx: ApiContext): Promise<Set<string>> => {
+  const ids = new Set<string>()
+  for (const resource of [subscriptions(ctx), usageEvents(ctx)] as unknown as Distinct[]) {
+    for (const id of await resource.collection.distinct('entityId', {})) {
+      if (typeof id === 'string' && id !== '') {
+        ids.add(id)
+      }
+    }
+  }
+
+  return ids
+}
+
+/**
+ * Repair every entity the payment store knows, plus `entities`: counters from the ledger in one
+ * pass, then per entity the optional resync and the free-plan backfill. A failing entity is counted
+ * and logged, never fatal.
+ */
+export const reconcileAll = async (
+  ctx: ApiContext, opts: ReconcileAllOptions = {},
+): Promise<ReconcileAllResult> => {
+  const ids = await knownEntities(ctx)
+  if (opts.entities != null) {
+    for await (const id of opts.entities) {
+      ids.add(id)
+    }
+  }
+
+  const result: ReconcileAllResult = { entities: ids.size, granted: 0, counters: 0, repaired: 0, failed: 0 }
+  for (const entityId of ids) {
+    try {
+      if (opts.resync === true) {
+        await resyncEntity(ctx, entityId)
+      }
+      if (opts.freePlanSku != null && await backfillFreePlan(ctx, entityId, opts.freePlanSku)) {
+        result.granted++
+      }
+      const counters = await entitlements(ctx).reconcileCounters(entityId)
+      result.counters += counters.counters
+      result.repaired += counters.repaired
+    } catch (error) {
+      result.failed++
+      console.error(`[payment] reconcile of "${entityId}" failed`, error)
+    }
+  }
+
+  return result
+}

package/src/resource.ts

@@ -1,10 +1,22 @@
 import type { ResourceMaker } from '@owlmeans/resource'
 import { makeMongoResource } from '@owlmeans/mongo-resource'
-import { RES_PAYGATE_CUSTOMER, RES_PAYMENT_FINGERPRINT, RES_PAYMENT_SUBSCRIPTION } from './consts.js'
-import { FingerprintSchema, PaygateCustomerSchema, PaymentSubscriptionSchema } from './model.js'
+import {
+  RES_BILLING_PROFILE, RES_CONSUMER_CONSENT, RES_CONSUMER_DECLARATION, RES_CONSUMER_EVENT, RES_PAYGATE_CUSTOMER,
+  RES_PAYMENT_FINGERPRINT, RES_PAYMENT_FULFILLMENT, RES_PAYMENT_PURCHASE, RES_PAYMENT_SUBSCRIPTION,
+  RES_PAYMENT_USAGE, RES_PAYMENT_USAGE_COUNTER, RES_PAYMENT_WEBHOOK,
+} from './consts.js'
+import {
+  BillingProfileSchema, ConsumerConsentSchema, ConsumerDeclarationSchema, ConsumerEventSchema, FingerprintSchema,
+  PaygateCustomerSchema, PaymentFulfillmentSchema, PaymentSubscriptionSchema, PaymentUsageCounterSchema,
+  PaymentUsageSchema, PaymentWebhookSchema, PurchaseSchema,
+} from './model.js'
 import type {
+  BillingProfileRecord, BillingProfileResource, ConsumerConsentRecord, ConsumerConsentResource,
+  ConsumerDeclarationRecord, ConsumerDeclarationResource, ConsumerEventRecord, ConsumerEventResource,
   FingerprintRecord, FingerprintResource, PaygateCustomerRecord, PaygateCustomerResource,
-  PaymentSubscriptionRecord, PaymentSubscriptionResource,
+  PaymentFulfillmentRecord, PaymentFulfillmentResource, PaymentSubscriptionRecord,
+  PaymentSubscriptionResource, PaymentUsageCounterRecord, PaymentUsageCounterResource, PaymentUsageRecord,
+  PaymentUsageResource, PaymentWebhookRecord, PaymentWebhookResource, PurchaseRecord, PurchaseResource,
 } from './types.js'
 
 export const makePaygateCustomerResource: ResourceMaker<PaygateCustomerRecord, PaygateCustomerResource> = (
@@ -29,11 +41,65 @@ export const makeSubscriptionResource: ResourceMaker<PaymentSubscriptionRecord,
     RES_PAYMENT_SUBSCRIPTION, dbAlias, serviceAlias,
   )
   resource.byExternalId = async (externalId, paygate) => await resource.load({ externalId, paygate })
+  resource.byItemId = async (itemId, paygate) => await resource.load({ itemId, paygate })
   resource.schema = PaymentSubscriptionSchema
-  resource.index('entity', { entityId: 1 })
-  resource.index('entitySku', { entityId: 1, sku: 1 })
-  resource.index('external', { externalId: 1, paygate: 1 }, { unique: true })
-  resource.index('status', { status: 1 })
+  resource.index('external', { paygate: 1, externalId: 1 }, { unique: true })
+  resource.index('entityStatusRank', { entityId: 1, status: 1, rank: -1 })
+  resource.index('entityPlan', { entityId: 1, planSku: 1 })
+  resource.index('customer', { paygate: 1, customerId: 1 })
+  resource.index('item', { paygate: 1, itemId: 1 }, { sparse: true })
+  resource.index('statusUpdated', { paygate: 1, status: 1, updatedAt: 1 })
+  return resource
+}
+
+export const makeFulfillmentResource: ResourceMaker<PaymentFulfillmentRecord, PaymentFulfillmentResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<PaymentFulfillmentRecord, PaymentFulfillmentResource>(
+    RES_PAYMENT_FULFILLMENT, dbAlias, serviceAlias,
+  )
+  resource.byExternalId = async (externalId, paygate) => await resource.load({ externalId, paygate })
+  resource.schema = PaymentFulfillmentSchema
+  resource.index('external', { paygate: 1, externalId: 1 }, { unique: true })
+  resource.index('paymentIntent', { paygate: 1, paymentIntentId: 1 }, { sparse: true })
+  resource.index('charge', { paygate: 1, chargeId: 1 }, { sparse: true })
+  resource.index('entityCreated', { entityId: 1, createdAt: -1 })
+  return resource
+}
+
+export const makeWebhookResource: ResourceMaker<PaymentWebhookRecord, PaymentWebhookResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<PaymentWebhookRecord, PaymentWebhookResource>(
+    RES_PAYMENT_WEBHOOK, dbAlias, serviceAlias,
+  )
+  resource.schema = PaymentWebhookSchema
+  resource.index('endpoint', { paygate: 1, service: 1, url: 1 }, { unique: true })
+  return resource
+}
+
+export const makeUsageResource: ResourceMaker<PaymentUsageRecord, PaymentUsageResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<PaymentUsageRecord, PaymentUsageResource>(
+    RES_PAYMENT_USAGE, dbAlias, serviceAlias,
+  )
+  resource.schema = PaymentUsageSchema
+  resource.index('event', { entityId: 1, limitKey: 1, eventKey: 1 }, { unique: true })
+  resource.index('window', { entityId: 1, limitKey: 1, window: 1 })
+  resource.index('ref', { entityId: 1, limitKey: 1, ref: 1 }, { sparse: true })
+  resource.index('entityCreated', { entityId: 1, createdAt: -1 })
+  return resource
+}
+
+export const makeUsageCounterResource: ResourceMaker<PaymentUsageCounterRecord, PaymentUsageCounterResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<PaymentUsageCounterRecord, PaymentUsageCounterResource>(
+    RES_PAYMENT_USAGE_COUNTER, dbAlias, serviceAlias,
+  )
+  resource.schema = PaymentUsageCounterSchema
+  resource.index('window', { entityId: 1, limitKey: 1, window: 1 }, { unique: true })
   return resource
 }
 
@@ -49,3 +115,82 @@ export const makeFingerprintResource: ResourceMaker<FingerprintRecord, Fingerpri
   resource.index('sku', { sku: 1 }, { unique: true })
   return resource
 }
+
+export const makeBillingProfileResource: ResourceMaker<BillingProfileRecord, BillingProfileResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<BillingProfileRecord, BillingProfileResource>(
+    RES_BILLING_PROFILE, dbAlias, serviceAlias,
+  )
+  resource.byEntity = async entityId => await resource.load({ entityId })
+  resource.schema = BillingProfileSchema
+  // One profile per organization: the unique index is what makes the first lock the only one.
+  resource.index('entity', { entityId: 1 }, { unique: true })
+  resource.index('customer', { paygate: 1, customerId: 1 }, { sparse: true })
+  return resource
+}
+
+export const makePurchaseResource: ResourceMaker<PurchaseRecord, PurchaseResource> = (dbAlias, serviceAlias) => {
+  const resource = makeMongoResource<PurchaseRecord, PurchaseResource>(RES_PAYMENT_PURCHASE, dbAlias, serviceAlias)
+  resource.byPurchaseId = async purchaseId => await resource.load({ purchaseId })
+  resource.schema = PurchaseSchema
+  resource.index('purchase', { purchaseId: 1 }, { unique: true })
+  resource.index('contract', { contractRef: 1 }, { unique: true })
+  resource.index('entityDeadline', { entityId: 1, deadline: -1 })
+  resource.index('entityPurchased', { entityId: 1, purchasedAt: -1 })
+  // Single-field on purpose: a compound sparse index still indexes rows missing only `sessionId`
+  // (subscription purchases before their checkout is captured), and unique would collide on them.
+  resource.index('session', { sessionId: 1 }, { unique: true, sparse: true })
+  resource.index('subscription', { paygate: 1, subscriptionId: 1 }, { sparse: true })
+  resource.index('invoice', { invoiceId: 1 }, { sparse: true })
+  resource.index('invoiceNumber', { invoiceNumber: 1 }, { sparse: true })
+  resource.index('paymentIntent', { paygate: 1, paymentIntentId: 1 }, { sparse: true })
+  return resource
+}
+
+export const makeConsumerConsentResource: ResourceMaker<ConsumerConsentRecord, ConsumerConsentResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<ConsumerConsentRecord, ConsumerConsentResource>(
+    RES_CONSUMER_CONSENT, dbAlias, serviceAlias,
+  )
+  resource.schema = ConsumerConsentSchema
+  resource.index('entityDecided', { entityId: 1, decidedAt: -1 })
+  resource.index('kindPlan', { kind: 1, entityId: 1, planSku: 1, decidedAt: -1 })
+  return resource
+}
+
+export const makeConsumerDeclarationResource: ResourceMaker<ConsumerDeclarationRecord, ConsumerDeclarationResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<ConsumerDeclarationRecord, ConsumerDeclarationResource>(
+    RES_CONSUMER_DECLARATION, dbAlias, serviceAlias,
+  )
+  resource.schema = ConsumerDeclarationSchema
+  resource.index('kindReceived', { kind: 1, receivedAt: -1 })
+  resource.index('entityReceived', { entityId: 1, receivedAt: -1 }, { sparse: true })
+  resource.index('purchase', { purchaseId: 1 }, { sparse: true })
+  return resource
+}
+
+export const makeConsumerEventResource: ResourceMaker<ConsumerEventRecord, ConsumerEventResource> = (
+  dbAlias, serviceAlias,
+) => {
+  const resource = makeMongoResource<ConsumerEventRecord, ConsumerEventResource>(
+    RES_CONSUMER_EVENT, dbAlias, serviceAlias,
+  )
+  resource.schema = ConsumerEventSchema
+  resource.index('record', { recordId: 1, at: 1 })
+  resource.index('entityAt', { entityId: 1, at: -1 }, { sparse: true })
+  resource.index('actionOk', { action: 1, ok: 1, at: 1 })
+  return resource
+}
+
+/** The consumer-rights resources, alias → maker — registered by the gateway, each only when absent. */
+export const CONSUMER_RIGHTS_RESOURCE_MAKERS = [
+  [RES_BILLING_PROFILE, makeBillingProfileResource],
+  [RES_PAYMENT_PURCHASE, makePurchaseResource],
+  [RES_CONSUMER_CONSENT, makeConsumerConsentResource],
+  [RES_CONSUMER_DECLARATION, makeConsumerDeclarationResource],
+  [RES_CONSUMER_EVENT, makeConsumerEventResource],
+] as const