@happyvertical/smrt-subscriptions 0.60.14 → 0.60.16

package/AGENTS.md

@@ -86,6 +86,51 @@ that reverted to DECIMAL passes every SQLite suite.
   `retainsPaidPeriod`, derived on save from an entitled pre-cancel row.
 - **Recipe `subscriptions.plans`** (`src/recipes.ts`, help in `src/plans.recipe.md`): lists plans, subscriptions, plan versions (read-only, written by `plan-versioning.ts`) and charges (read-only, written by the usage service) for the planner and other catalog hosts. Fields it shows carry `@field({ description })` in plain words, money fields saying "in cents"; keep them when editing the models. Reseller models and pricing rules stay out of it.
 
+## Hosted AI spend caps (#4760)
+
+`src/services/hosted-ai-spend.ts`. Plans cap platform-paid (`source:
+hosted`) inference with ordinary `PlanThreshold`s on two reserved keys, so
+window, amount and enforcement come from the plan (pinned version included):
+`AI_HOSTED_SPEND_METRIC` (`ai.hosted.spend_micros`, the tenant) and
+`AI_HOSTED_USER_SPEND_METRIC` (`ai.hosted.user_spend_micros`, each user).
+
+- `limit` is **integer micro-dollars** (1 USD = 1,000,000; the money rule at
+  per-call precision). `block` blocks at or over the cap, `warn` warns,
+  `observe` never affects a call; `warningRatio` (default 0.8) warns early;
+  a 0 cap blocks every hosted call. A malformed hosted cap (fractional or
+  negative limit, unknown window/enforcement) throws
+  `HostedAiSpendPolicyError` (the gate fails closed); it never reads as "no
+  cap". `resolvePlanThresholds()` returns thresholds unfiltered for this
+  reason (the models' `getThresholds()` drop invalid entries) and throws on
+  non-array JSON.
+- Spend: `createHostedAiSpendReader(db)` sums `_smrt_ai_usage.estimated_cost`
+  (USD, rounded to micro-dollars) by `tenant_id` and `created_at` in the
+  cap's window for rows whose `tags` hold `"source":"hosted"` (and
+  `"userId":"<id>"` for the per-user cap), as exact, case-sensitive JSON
+  fragments (`hostedAiTagFragment()`; `strpos` on the PostgreSQL dialect,
+  `instr` elsewhere, never `LIKE`, which folds ASCII case on SQLite and
+  would merge `Alice` and `alice`); errors only over-count.
+  `operation: 'blocked'` rows and external-agent measurements never count;
+  uncosted rows add nothing (give hosted models a cost rate). The `userId`
+  tag exists only while the hosted gate's ambient-user resolver is
+  registered.
+- `resetsAt`: the calendar window's end; for a blocked `rolling` cap (30
+  days), `HostedAiSpendReader.liftsAt()`: one window-function query (newest
+  first running `SUM(estimated_cost)`, rounded as `summarize()` rounds)
+  returns the row whose expiry first brings the total below the cap, plus
+  30 days (null for a 0 cap). A blocked decision names the blocking cap that
+  lifts last.
+- `HostedAiSpendEvaluator` (`create({ db })`): plan thresholds via
+  `SubscriptionResolver.resolvePlanThresholds()` (entitled terms, no usage
+  meters; memoized per tenant for `termsTtlMs`, 30 s, failures evicted,
+  `invalidate()`), spend read fresh per call; per-user caps only with a
+  user. Errors propagate. smrt-inference's `./gate` consumes it.
+- `resolveEntitlements()` / the tenant usage meter report these keys with
+  quantity 0: only the evaluator meters them. The meter's AI summary (and so
+  `ai.requests`) skips `operation: 'blocked'` rows. `SpendingPolicy` rows stay the
+  billed-charge (cents) policy; hosted AI caps are plan terms because the
+  issue's window and amount come from the plan.
+
 ## Reseller billing (#3059)
 
 - Billing ownership is consumed from `smrt-tenancy`'s
@@ -116,6 +161,84 @@ that reverted to DECIMAL passes every SQLite suite.
   it `currentShortfall()`, so a hook that charges asynchronously can see a
   concurrent top-up (smrt-commerce's `autoTopUpHook()`, #3139).
 
+## Billing host glue (#4786)
+
+`src/billing/` is the reusable Stripe checkout, signed idempotent webhook and
+portal wiring (`createBillingHost()`, `readBillingEnv()`); the recipe and
+environment names are in the README. Invariants:
+
+- **No direct Stripe calls.** The provider is the structural
+  `BillingProviderPort`; `StripeAccountingProvider` from
+  `@happyvertical/accounting` satisfies it (a test pins that). A missing SDK
+  capability is fixed in the SDK first. `@happyvertical/accounting` is a
+  devDependency only (tests run the real provider over a fake `fetch`).
+- **Webhook order is load-bearing:** size cap, signature header, own timestamp
+  tolerance, SDK `verify` on the raw body, parse, handled-type filter,
+  completed-claim pre-check, then (checkout only) the outside-transaction
+  provider read-back, then `runOnce` claiming the event id *and* applying it.
+  All DB access inside that transaction must use the `tx` handle; a read on the
+  base handle deadlocks single-connection SQLite. Never claim before applying.
+- **Trust comes from our own state.** Checkout metadata is HMAC-signed
+  (`smrt_sig`, `signing.ts`) and an unsigned or foreign-signed session never
+  links a tenant or plan.
+- **Checkout is bound to a recorded session (#4814)**, `checkout-sessions.ts`
+  and `models/BillingCheckoutSession.ts` (`_smrt_billing_checkout_sessions`,
+  no API surface; a root export because the manifest advertises it).
+  `createCheckout` records the session id
+  before returning the URL and signs `smrt_exp`; the completion (inside the
+  `runOnce` transaction, after the PostgreSQL `checkout:<id>` lock) checks, in
+  order: record exists, status is not `completed` / `needs_reconciliation`
+  (no-op `ignored`), record tenant equals the signed tenant, `smrt_exp` is
+  well-formed, event time is not after the signed or recorded expiry. A
+  missing, mismatched or expired record never links and never drops: the row
+  becomes `needs_reconciliation` (outcome `needs_reconciliation`, error log).
+  Only `applied` marks a record `completed`. `reconcileCheckout()` (link) and
+  `dismissCheckout()` (terminal `dismissed`, for a payment that is not the
+  tenant's) are the only ways out and are operator-only; reconcile never skips
+  the apply-time conflict checks. The list shows `customerId`,
+  `targetTenantId` and `claimedTenantHasOwnSession`, is paged, and has a count.
+  The expiry is deterministic per idempotency window so a repeated click sends
+  identical provider parameters. Change the table shape only with owner
+  approval. A provider subscription or customer id links to one
+  tenant; a conflicting event is ignored with a reason code, not merged.
+  Verification accepts the signing secret plus `metadataVerificationSecrets`
+  (rotation); a purpose-matching session that fails them logs at error.
+  A price the host cannot map that differs from the recorded one is held
+  (`incomplete`, plan and recorded price kept, `metadata.stripe.held` set so
+  checkout still refuses a second subscription) with an error log, never
+  carried over onto the previous plan.
+  Ignore (2xx, logged) for security refusals; fail (5xx) for configuration or
+  database faults so the provider retries.
+- **Only operator plans are sold by default** (`tenantPlans: 'deny'`); price
+  resolution never lets a tenant-owned plan outrank a global one. Checkout
+  metadata also signs the price and known customer, and the webhook refuses a
+  session whose read-back subscription differs. PostgreSQL events lock the
+  subscription and tenant (advisory, sorted) and re-read before deciding.
+- **Order state lives on the row** (`metadata.stripe.lastEventAt`, `terminal`);
+  a checkout read-back stamps `max(eventCreated, readAt)` so later-delivered
+  older events cannot rewind it. Cancellation caps `currentPeriodEnd` at now.
+- **Plan changes** from the provider use `replacePlanVersion({ policy:
+  'authorized', reason: 'stripe:<eventId>' })`; the provider billed the change,
+  so a mid-period downgrade is honoured and audited. Do not relax the pinning
+  rules for any other caller.
+- **No secrets out.** Responses use fixed messages; logs get ids and reason
+  codes only, errors pass through `safeErrorMessage()`. `readBillingEnv` keeps
+  secrets non-enumerable. Add a named test per new threat in
+  `__tests__/billing-host.test.ts`.
+
+## Vault account restart and supersede (#4841)
+
+`src/vault-account/`. `supersedeVaultAccount`, `unsupersedeVaultAccount` and
+`provisionRestartAccount` take injected ports (`VaultRelayAdminPort`,
+`VaultAccountDirectory`, an audit sink); no HTTP server or relay is needed.
+Order is load-bearing: owner of the tenant and of both accounts (`not_owner`),
+then `requireRecentAuthentication` from `smrt-users/step-up`
+(`step_up_required`, default 300 s), then the `authorized` audit record, then
+exactly one relay call, then the outcome record. Refusals are audited and never
+reach the relay; a member never learns about the step-up. Audit entries carry
+ids and codes only (no session id, key, token or message text). Import only the
+`@happyvertical/smrt-users/step-up` subpath, never the package root.
+
 ## Notes
 
 - Keep Stripe-specific fields as provider binding metadata. Runtime Stripe API
@@ -129,3 +252,32 @@ that reverted to DECIMAL passes every SQLite suite.
   current subscription and plan.
 - Subscription UI components should stay provider-neutral and receive actions
   from the host app.
+- **Feature grants as flags (#4761).** `SubscriptionFeatureSource` implements
+  `smrt-features`' `FeatureGrantSource` structurally (no dependency either
+  way). Build one per request (`SubscriptionFeatureSource.create(options)` or
+  `new SubscriptionFeatureSource({ resolver })`; it memoizes grants per
+  tenant) and pass it as `grantSource`, or register an app-wide one built with
+  `memoize: false` through `registerSubscriptionFeatureSource()`, which writes
+  the features slot key `FEATURE_GRANT_SOURCE_SLOT_KEY`. It reads
+  `SubscriptionResolver.resolveFeatureGrants()`, which shares the
+  version-pinning and entitlement rules of `resolveEntitlements()` but never
+  evaluates thresholds, so a flag check reads no usage meters. Missing
+  subscription tables (`isMissingSubscriptionTableError`) and no entitled
+  subscription report no grants silently; every other error propagates.
+  `findGrantingPlan()` names the first active plan by `sortOrder` visible in
+  the current context.
+- **Entitlement change hook (#4759).** `src/services/entitlement-changes.ts`.
+  The host wraps its billing-webhook write in
+  `trackEntitlementChange({ tenantId, resolver }, apply)`: it snapshots
+  `resolveFeatureGrants()` (keys plus grant `metadata`, no usage reads)
+  before and after, diffs `gained` / `lost` / `changed` (metadata, e.g. a
+  plan budget) and calls listeners registered with
+  `registerEntitlementChangeListener()` (a `Symbol.for` slot) or passed in.
+  Listeners run after `apply`; their failures are returned in `failures`,
+  never thrown, and never undo the write, so listeners must be idempotent.
+  An `apply` error propagates and notifies nobody. A redelivered webhook
+  diffs to no change, so a lost reaction is repaired by the consumer's
+  reconcile entry point (hosted inference: `createHostedInferenceReconciler()`
+  with `snapshotEntitlements()`), run on redelivery or a schedule. Listeners satisfy the
+  structural type (smrt-inference's hosted listener), so this package
+  depends on none of them.

package/README.md

@@ -39,6 +39,17 @@ Create one resolver per request or application unit of work and reuse the
 loaded `EntitlementResolutionContext` when several checks need the same
 subscription and plan.
 
+### Plan grants as feature flags
+
+`SubscriptionFeatureSource` feeds a tenant's plan grants into
+`@happyvertical/smrt-features`, so `FeatureResolver` and its `requireFeature()`
+gate answer from the plan. Build one per request with
+`SubscriptionFeatureSource.create(dbOptions)` and pass it as `grantSource`, or
+register an app-wide one (`memoize: false`) with
+`registerSubscriptionFeatureSource()`. With no subscription tables or no
+entitled subscription it reports no grants. A global feature override still
+outranks a grant (an operator stop), and a tenant override outranks both.
+
 ## Core model
 
 - `SubscriptionPlan` is tenant-scoped by `(tenantId, planKey)` and stores
@@ -350,6 +361,201 @@ keeps its credit ledger (reversible in a system context), and the new parent
 creates its own balance. A parent's `retail` cap counts only what the child owes that
 parent.
 
+## Billing host glue (Stripe)
+
+`createBillingHost()` is the reusable checkout, webhook and customer-portal
+wiring for hosts that sell a `SubscriptionPlan` through Stripe (#4786). A host
+configures it; it does not re-implement it. Every provider call goes through
+`@happyvertical/accounting`; there are no direct Stripe calls here. Web only:
+phone apps never sell a subscription in-app.
+
+### Host configuration
+
+| Variable | Meaning |
+| --- | --- |
+| `STRIPE_SECRET_KEY` | Secret or restricted key (`sk_` / `rk_`). |
+| `STRIPE_WEBHOOK_SECRET` | Webhook endpoint signing secret (`whsec_`). |
+| `STRIPE_WEBHOOK_TOLERANCE` | Optional. Maximum signature age in seconds, 1 to 900, default 300. |
+| `BILLING_METADATA_SECRET` | Optional. Secret that signs new Checkout metadata. Unset: the webhook secret is used, so rotating the webhook secret also rotates this. Set it to a stable value to decouple the two. |
+| `BILLING_METADATA_PREVIOUS_SECRETS` | Optional, comma-separated. Retired metadata secrets still accepted when a completed Checkout is verified. |
+| `STRIPE_PRICE_<PLAN_KEY>` | Price id sold for a plan, for example `STRIPE_PRICE_PRO`. Wins over `SubscriptionPlan.providerPriceId`. |
+| `BILLING_SUCCESS_URL`, `BILLING_CANCEL_URL`, `BILLING_PORTAL_RETURN_URL` | Fixed absolute https destinations (plain http only for localhost). |
+
+`readBillingEnv(process.env, { planKeys })` validates these and keeps the
+secrets in non-enumerable properties, so logging the config does not print
+them. Its errors name the variable, never the value.
+
+**Rotating secrets.** A Checkout session is signed when it is created and
+verified when it completes, which can be days later. If the signing secret
+changes in between (by default it is the webhook secret), a paid session no
+longer verifies and the purchase is dropped. Before rotating, put the outgoing
+secret in `BILLING_METADATA_PREVIOUS_SECRETS` (`metadataVerificationSecrets`)
+and keep it there until sessions created under it have expired. A completed
+session that claims to be ours but does not verify under any accepted secret
+is logged at error level (`billing.webhook.checkout_signature_invalid`), so a
+dropped purchase is visible.
+
+### Recipe (SvelteKit)
+
+```ts
+// src/lib/server/billing.ts
+import { getAccountingProvider } from '@happyvertical/accounting';
+import {
+  createBillingHost,
+  readBillingEnv,
+  TenantSubscriptionCollection,
+} from '@happyvertical/smrt-subscriptions';
+
+const env = readBillingEnv(process.env, { planKeys: ['pro', 'team'] });
+const provider = await getAccountingProvider({
+  type: 'stripe',
+  secretKey: env.stripe.secretKey, // read explicitly: non-enumerable on purpose
+  webhookSecret: env.stripe.webhookSecret,
+  webhookTolerance: env.stripe.webhookTolerance,
+});
+const { db } = await TenantSubscriptionCollection.create(smrtConfig);
+
+export const billing = createBillingHost({
+  provider,
+  db, // needs transaction(): SQLite or PostgreSQL
+  webhookSecret: env.stripe.webhookSecret,
+  metadataSigningSecret: env.metadata.signingSecret,
+  metadataVerificationSecrets: env.metadata.previousSecrets,
+  webhookToleranceSeconds: env.stripe.webhookTolerance,
+  urls: env.urls,
+  prices: env.prices,
+  logger, // optional; receives ids and reason codes only
+});
+
+// src/routes/api/billing/checkout/+server.ts  (authenticate and authorise first)
+export const POST = async ({ request, locals }) => {
+  const membership = await requirePermission(locals, 'billing.manage');
+  return billing.handlers.checkout(request, {
+    tenantId: membership.tenantId,
+    email: membership.userEmail,
+  });
+};
+
+// .../portal/+server.ts  -> billing.handlers.portal(request, { tenantId })
+// .../webhook/+server.ts -> billing.handlers.webhook(request)   (no auth; signature only)
+```
+
+The webhook route must receive the raw body. Point the Stripe endpoint at it
+and subscribe it to `checkout.session.completed` and
+`customer.subscription.created|updated|deleted|paused|resumed`.
+
+### What it guarantees
+
+- **Checkout** takes only a plan key or id from the request. Tenant, price,
+  customer and URLs come from the host's authenticated tenant, server
+  configuration and the tenant's own subscription row. A plan must be visible
+  to the tenant (its own or global), active, fixed-price and priced, and the
+  tenant must not already hold a live Stripe subscription (use the portal to
+  change plans). Only operator-owned (global) plans are sold unless the host
+  sets `tenantPlans: 'allow'`, so a tenant that can write plan rows cannot buy
+  entitlements it defined itself or shadow a plan key; set `allow` only when
+  tenants cannot write `SubscriptionPlan`. `canPurchasePlan` adds host policy.
+  The session metadata is HMAC-signed and bound to the server price, an
+  expiry and, when known, the billing customer, so another integration on the
+  same Stripe account cannot forge metadata for a tenant, and signed metadata
+  cannot be reused for a different price or another customer's subscription.
+- **First purchases are bound to the session the host created (#4814).** The
+  host records each Checkout session id (table
+  `_smrt_billing_checkout_sessions`: session id, tenant, expiry, status
+  `pending`, `completed` or `needs_reconciliation`) before it returns the
+  buyer's URL, and signs an expiry (`smrt_exp`, 25 hours, so a Stripe session's
+  24 hours plus an hour) into the metadata. A paid session links a tenant only
+  when, in order: the signature verifies, a record exists for exactly that
+  session id, it is still `pending`, it names the same tenant as the signed
+  metadata, and the event time (not the delivery time, so late webhook retries
+  of an in-time payment still count) is before the signed and recorded expiry.
+  Metadata copied onto another integration's session is therefore never
+  linked, however it is paid. A completed session is single use: a second
+  completion with the same session id changes nothing.
+- **A paid session that cannot be bound is kept, not dropped.** If the record
+  is missing, expired or names another tenant, the tenant is not linked, the
+  event is claimed (no provider retry loop) and the session is stored as
+  `needs_reconciliation` with a reason code (`session_record_missing`,
+  `session_expired`, `session_record_mismatch`). The webhook answers 200 with
+  `outcome: 'needs_reconciliation'` and logs
+  `billing.checkout.needs_reconciliation` at error level (ids and codes only).
+  A genuine buyer whose record was lost, or a session that was in flight when
+  this binding was deployed (it has no record), lands here. An operator lists
+  them with `host.listCheckoutsNeedingReconciliation()` and links one on
+  purpose with `host.reconcileCheckout({ sessionId, tenantId, operatorId })`:
+  server-side only (authenticate and authorise the operator first; it is not a
+  request handler), it re-reads the subscription from the provider, requires
+  it to be the subscription and customer recorded when the session was
+  flagged, applies the same tenant/customer conflict checks as a normal
+  completion, links once, and logs `billing.checkout.reconciled` with the
+  operator id. Each listed row carries the paying `customerId`, the tenant the
+  host recorded the session for (`targetTenantId`) and
+  `claimedTenantHasOwnSession` (true suggests a copy of that tenant's signed
+  metadata): confirm the customer is the tenant's own before linking. Treat a
+  flagged session you did not expect as another integration's payment and close
+  it with `host.dismissCheckout({ sessionId, operatorId, reason })` (terminal
+  `dismissed`, logged with the operator id and reason), so it leaves the list.
+  The list is paged (`{ limit, offset }`, default 200) and
+  `host.countCheckoutsNeedingReconciliation()` gives the total.
+- **Webhook** verifies the signature on the raw body with a bounded timestamp
+  tolerance, then claims the event id durably in the same transaction as the
+  subscription write (`runOnce`, `_smrt_run_once_claims`). A replay is a 2xx
+  no-op; a failed apply rolls the claim back (non-2xx) so the provider's retry
+  runs. Out-of-order events converge: each applied event records its time on
+  the row and an older one is skipped, and a cancellation wins a same-second
+  tie. A completed checkout reads the subscription back from the provider, so
+  the row reflects current state however events were ordered. A plan change at
+  the provider is applied as an authorised plan-version replacement, so
+  feature keys flip within that one webhook (including a mid-period
+  downgrade the provider billed).
+- **Linking** is by provider ids stored on `TenantSubscription`. A subscription
+  or customer already linked to one tenant is never re-linked to another, and
+  an event for an unknown subscription is acknowledged and ignored.
+- **Portal** opens the portal for the customer on the caller's own
+  subscription row only.
+- **Responses and logs** carry fixed messages, ids and reason codes. Provider
+  error text is never returned, and anything shaped like a key is redacted
+  before logging.
+
+Operational notes: if a second Checkout for a tenant that already holds a live
+subscription is paid (two tabs racing), the webhook cannot track it and logs
+`billing.checkout.orphaned_subscription` at error level with the provider
+subscription id; alert on it and cancel or refund that subscription at the
+provider. Keep server clocks synchronised (NTP): event ordering compares the
+provider's whole-second event time with this host's read-back time. A
+concurrent duplicate of an event being applied answers
+409 and Stripe retries it. Plans and which price backs which plan are the
+owner's input; this module only maps them. No schema change is needed: event
+claims use core's `_smrt_run_once_claims`, retained for its pruning window
+(30 days by default), far longer than Stripe's three-day retry horizon.
+
+## Hosted vault-account restart and supersede (#4841)
+
+The hosted account layer (the service that holds the vault relay's admin
+token) replaces a family's vault account after a restart. That is a takeover
+of the backup line if done by the wrong person, so every action here is gated:
+
+- `supersedeVaultAccount`, `unsupersedeVaultAccount` (relay admin `PUT` and
+  `DELETE .../superseded-by`) and `provisionRestartAccount` (a fresh account
+  linked to the tenant plus the working device's relay signing key, step 1 of
+  the restart in the app-runtime README).
+- Each requires the caller to be the tenant **owner** (`NotOwnerError`, code
+  `not_owner`: a member, a device-only or layered session, no session, or an
+  account of another tenant) **and** a **step-up**: the owner re-authenticated
+  with a fresh password or passkey within `stepUpMaxAgeSeconds` (default 300;
+  `StepUpRequiredError`, code `step_up_required`). A signed-in session or an
+  unlocked device is not enough. See `smrt-users` "Step-up".
+- The relay is called only after both checks pass, exactly once. Every attempt
+  is written to your `audit` sink (`denied` with the reason code, `authorized`
+  before the call, then `succeeded` or `failed`); records hold ids, codes and
+  times, never a password, session id, token or key. If the `authorized`
+  record cannot be written, nothing is done.
+- Collaborators are injected: `session` (from `loadSessionContext`), `relay`
+  (`VaultRelayAdminPort`; `createVaultRelayAdminClient({ baseUrl, adminToken })`
+  speaks the admin HTTP API, and a `VaultRelay` instance fits in-process),
+  `directory` (which tenant owns an account, and linking a new one so
+  `backup.vault` resolves), and `audit`.
+
 ## Svelte entry point
 
 `@happyvertical/smrt-subscriptions/svelte` exports provider-neutral,

package/dist/billing/apply.d.ts

@@ -0,0 +1,52 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { TenantSubscription } from '../models/TenantSubscription.js';
+import { type SubscriptionSnapshot } from './events.js';
+import type { BillingLogger } from './types.js';
+/** JSON-safe result stored with the idempotency claim and replayed. */
+export interface AppliedOutcome {
+    action: 'applied' | 'ignored' | 'needs_reconciliation';
+    reason?: string;
+}
+export interface ApplyContext {
+    db: DatabaseInterface;
+    tenantPlans: 'deny' | 'allow';
+    /** PostgreSQL: serialize concurrent events for one subscription or tenant. */
+    postgres: boolean;
+    prices: Record<string, string> | undefined;
+    logger: BillingLogger | undefined;
+}
+interface EventFacts {
+    eventId: string;
+    eventType: string;
+    /** The provider's own event time (whole seconds). */
+    eventCreated: Date;
+    /** When the snapshot was read, if it was read rather than delivered. */
+    observedAt?: Date;
+}
+/**
+ * Serialize applies that touch the same provider subscription or tenant on
+ * PostgreSQL, where two transactions can otherwise both read the row before
+ * either writes and let an older event overwrite a newer one. Transaction-
+ * scoped, taken in sorted order. Embedded engines already have one writer.
+ */
+export declare function lockBillingKeys(ctx: Pick<ApplyContext, 'db' | 'postgres'>, keys: string[]): Promise<void>;
+/**
+ * A row held for an unmapped price still has a live provider subscription
+ * (`metadata.stripe.held`): checkout must not sell a second one over it.
+ */
+export declare function isHeldSubscription(row: TenantSubscription): boolean;
+/** A `customer.subscription.*` event for an already-linked subscription. */
+export declare function applySubscriptionEvent(ctx: ApplyContext, facts: EventFacts, snapshot: SubscriptionSnapshot): Promise<AppliedOutcome>;
+export interface CheckoutLink {
+    tenantId: string;
+    planId: string;
+    checkoutSessionId: string;
+}
+/**
+ * A completed Checkout whose signed metadata names the tenant and plan. The
+ * snapshot is the subscription read back from the provider after the event,
+ * so the row reflects current state however the events were ordered.
+ */
+export declare function applyCheckoutCompleted(ctx: ApplyContext, facts: EventFacts, link: CheckoutLink, snapshot: SubscriptionSnapshot): Promise<AppliedOutcome>;
+export {};
+//# sourceMappingURL=apply.d.ts.map

package/dist/billing/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/billing/apply.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,sBAAsB,CAAC;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,iBAAiB,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC3C,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;CACnC;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,YAAY,EAAE,IAAI,CAAC;IACnB,wEAAwE;IACxE,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AASD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,UAAU,CAAC,EAC1C,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,IAAI,CAAC,CAQf;AAiDD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CASnE;AA6LD,4EAA4E;AAC5E,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC,CAyEzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,cAAc,CAAC,CA4EzB"}

package/dist/billing/checkout-sessions.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Binding a completed Checkout to the session the host created (#4814).
+ *
+ * The signed metadata alone is copyable: another integration on the same
+ * Stripe account can put it on its own session and pay first. So the host
+ * records each session id when it creates the session, and a paid session
+ * links a tenant only when a pending record for exactly that id names the
+ * same tenant and the signed expiry has not passed at the event time.
+ * Anything else is never linked and never dropped: the paid session is
+ * recorded as `needs_reconciliation` for an operator.
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type BillingCheckoutSession } from '../models/BillingCheckoutSession.js';
+import { type AppliedOutcome, type ApplyContext, applyCheckoutCompleted } from './apply.js';
+import { type SubscriptionSnapshot } from './events.js';
+/** Signed metadata key holding the expiry, in whole epoch seconds. */
+export declare const METADATA_EXPIRY_KEY = "smrt_exp";
+/**
+ * Stripe expires a Checkout session after 24 hours; the host allows an hour
+ * more. The expiry is checked against the event time, not the delivery time,
+ * so a late webhook retry of an in-time payment still completes.
+ */
+export declare const CHECKOUT_SESSION_TTL_MS: number;
+export type CheckoutRefusal = 'session_record_missing' | 'session_record_mismatch' | 'session_expired';
+type Verdict = {
+    kind: 'bound';
+} | {
+    kind: 'replay';
+    reason: string;
+} | {
+    kind: 'reconcile';
+    reason: CheckoutRefusal;
+};
+/** The binding rules, in order. Pure: no I/O. */
+export declare function checkBinding(record: BillingCheckoutSession | null, input: {
+    tenantId: string;
+    exp: string | undefined;
+    eventTime: Date;
+}): Verdict;
+/** Record a session the host just created. Idempotent per session id. */
+export declare function recordCheckoutSession(db: DatabaseInterface, input: {
+    sessionId: string;
+    tenantId: string;
+    expiresAt: Date;
+}): Promise<void>;
+export interface ReconcileContext {
+    eventId: string;
+    eventCreated: string;
+    subscriptionId: string;
+    customerId: string;
+    planId: string;
+    claimedTenantId: string;
+}
+export declare function parseReconcileContext(record: BillingCheckoutSession): ReconcileContext | null;
+export interface BoundCompletion {
+    sessionId: string;
+    /** From the verified signed metadata. */
+    tenantId: string;
+    planId: string;
+    exp: string | undefined;
+    eventId: string;
+    eventTime: Date;
+}
+/**
+ * Inside the idempotency transaction: bind the paid session to its record,
+ * then link the tenant. `ctx.db` is the transaction handle.
+ */
+export declare function completeBoundCheckout(ctx: ApplyContext, input: BoundCompletion, facts: Parameters<typeof applyCheckoutCompleted>[1], snapshot: SubscriptionSnapshot): Promise<AppliedOutcome>;
+/** A flagged session and the ids captured when it was flagged. */
+export declare function loadFlaggedCheckout(db: DatabaseInterface, sessionId: string): Promise<{
+    record: BillingCheckoutSession;
+    flagged: ReconcileContext;
+} | null>;
+/**
+ * Operator action, inside one transaction (`ctx.db`): link a flagged paid
+ * session to `tenantId` on purpose. `snapshot` is the subscription read back
+ * from the provider before the transaction; it must still be the one recorded
+ * when the session was flagged. The row is re-read under the lock, so a
+ * session is reconciled at most once.
+ */
+export declare function reconcileFlaggedCheckout(ctx: ApplyContext, input: {
+    sessionId: string;
+    tenantId: string;
+    planId?: string;
+    operatorId: string;
+    snapshot: SubscriptionSnapshot;
+}): Promise<AppliedOutcome | null>;
+/**
+ * Operator action, inside one transaction (`ctx.db`): close a flagged session
+ * without linking it. The row is re-read under the lock, so a session is
+ * dismissed or reconciled at most once, whichever comes first.
+ */
+export declare function dismissFlaggedCheckout(ctx: ApplyContext, input: {
+    sessionId: string;
+    operatorId: string;
+    reason: string;
+}): Promise<boolean>;
+export {};
+//# sourceMappingURL=checkout-sessions.d.ts.map

package/dist/billing/checkout-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-sessions.d.ts","sourceRoot":"","sources":["../../src/billing/checkout-sessions.ts"],"names":[],"mappings":"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"}

package/dist/billing/config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Host configuration surface for the billing glue (#4786).
+ *
+ * Environment variables, with the secrets held in non-enumerable properties so
+ * a stray `JSON.stringify(config)` or `console.log(config)` cannot print them.
+ * Error messages name the variable and never its value.
+ */
+import type { BillingUrls } from './types.js';
+export declare const BILLING_ENV: {
+    readonly secretKey: "STRIPE_SECRET_KEY";
+    readonly webhookSecret: "STRIPE_WEBHOOK_SECRET";
+    readonly webhookTolerance: "STRIPE_WEBHOOK_TOLERANCE";
+    readonly metadataSecret: "BILLING_METADATA_SECRET";
+    readonly metadataPreviousSecrets: "BILLING_METADATA_PREVIOUS_SECRETS";
+    readonly successUrl: "BILLING_SUCCESS_URL";
+    readonly cancelUrl: "BILLING_CANCEL_URL";
+    readonly portalReturnUrl: "BILLING_PORTAL_RETURN_URL";
+};
+export declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+export declare const MAX_WEBHOOK_TOLERANCE_SECONDS = 900;
+/** The env var holding the provider price id for a plan key. */
+export declare function priceEnvName(planKey: string): string;
+export interface BillingEnvOptions {
+    /** Plan keys whose `STRIPE_PRICE_<KEY>` variables should be read. */
+    planKeys: readonly string[];
+}
+export interface BillingEnvConfig {
+    /**
+     * Provider credentials for `getAccountingProvider({ type: 'stripe', … })`.
+     * `secretKey` and `webhookSecret` are non-enumerable (they do not survive
+     * a spread, `JSON.stringify` or `console.log`), so read them by name.
+     */
+    stripe: {
+        readonly secretKey: string;
+        readonly webhookSecret: string;
+        webhookTolerance: number;
+    };
+    /**
+     * Checkout-metadata signing (#4786). `signingSecret` is unset unless
+     * `BILLING_METADATA_SECRET` is configured (the host then falls back to the
+     * webhook secret). `previousSecrets` (comma-separated
+     * `BILLING_METADATA_PREVIOUS_SECRETS`) are still accepted when a completed
+     * checkout is verified, so rotating a secret does not drop sessions created
+     * before the rotation. Both are non-enumerable.
+     */
+    metadata: {
+        readonly signingSecret: string | undefined;
+        readonly previousSecrets: readonly string[];
+    };
+    urls: BillingUrls;
+    /** Plan key to price id for every plan whose variable is set. */
+    prices: Record<string, string>;
+}
+type Env = Record<string, string | undefined>;
+/**
+ * Validate a redirect destination: absolute, no embedded credentials, and
+ * https (plain http only for loopback development hosts).
+ */
+export declare function assertBillingUrl(name: string, value: string): string;
+export declare function assertWebhookTolerance(seconds: number): number;
+/** Read and validate billing configuration from an environment map. */
+export declare function readBillingEnv(env: Env, options: BillingEnvOptions): BillingEnvConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/billing/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/billing/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,eAAO,MAAM,iCAAiC,MAAM,CAAC;AACrD,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,EAAE;QACN,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF;;;;;;;OAOG;IACH,QAAQ,EAAE;QACR,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7C,CAAC;IACF,IAAI,EAAE,WAAW,CAAC;IAClB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAa9C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBpE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW9D;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,iBAAiB,GACzB,gBAAgB,CAyElB"}