@pithy-sh/payments 0.1.0

package/src/http/scopes.ts

@@ -0,0 +1,260 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+
+/**
+ * Payments' control-plane scopes, and the admin surface a manifest advertises.
+ *
+ * **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
+ * client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
+ * writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
+ * program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
+ * one compiled `PithyHonoEnv`, which reached core's `capability.ts`, which named Worker globals that
+ * program has none of. **This module imports types and nothing else, and a gate holds it there**:
+ * `tooling/browser-scopes` compiles a DOM-only program against every scope the kit declares.
+ *
+ * ## Two scopes, not one admin flag
+ *
+ * The interim gate checked a single `payments:admin` scope on the `AuthContext`. That string is a valid
+ * {@link ControlPlaneScope} — it matches the seam's pattern, so nothing forced this change — but it names a
+ * *credential holder*, and the seam's scopes name *operations*. Under that model one flag is wrong on the
+ * merits: granting and revoking an entitlement are two operations with different blast radii and different
+ * holders. **Grant** mints paid product out of nothing, so a compromised comp tool costs revenue and can
+ * escalate itself into anything the catalog sells. **Revoke** takes paid access away from a live customer, so
+ * a compromised refund tool is an outage for people who paid. A refund tool needs revoke and never grant; a
+ * support-comp tool needs grant and never revoke. One flag makes each of them the other, and an adopter who
+ * wanted to hand out only the safer half had no way to say so.
+ *
+ * The split is real rather than cosmetic because `scopeCovers` matches exactly, with no prefix or wildcard
+ * rule: `payments:entitlements` confers neither of these, and holding one confers nothing about the other.
+ *
+ * The names are constants rather than config, for the reason the old comment gave and which has not changed: a
+ * configurable scope name is a way to misconfigure a default-denied gate into a differently-named one, and
+ * support tooling that read the docs would then quietly hold a scope nothing checks. They are also the join
+ * key with what `pithy dashboard connect` offers an adopter to grant, so they must be the same strings in both
+ * places.
+ */
+
+/**
+ * Minting a discount — an administrative act with a cost attached, and its own scope for that reason.
+ *
+ * Deliberately not covered by, and not covering, the entitlement grants. Comping somebody an entitlement and
+ * creating a code that reduces what everybody who holds it pays are different powers with different blast
+ * radii, and a tool that needs one must not acquire the other. `scopeCovers` matches exactly.
+ */
+export const PAYMENTS_DISCOUNT_CREATE_SCOPE: ControlPlaneScope = "payments:discounts:create";
+
+/**
+ * Reading the codes this project has issued.
+ *
+ * Separate from creating one, and strictly narrower: a pane that lists what was minted does not need the
+ * power to mint. The read exists because the write does — a management client that can create a code and
+ * never see it leaves a pane computing *absent* rather than blocked, which no grant repairs (#247).
+ */
+export const PAYMENTS_DISCOUNT_READ_SCOPE: ControlPlaneScope = "payments:discounts:read";
+
+/**
+ * Write an entitlement nobody paid for — a comp, or the repair of a purchase that verified and never
+ * projected. The more dangerous of the two: a connection holding this can give any account anything the
+ * catalog sells.
+ */
+export const PAYMENTS_ENTITLEMENT_GRANT_SCOPE: ControlPlaneScope = "payments:entitlements:grant";
+
+/**
+ * Take an entitlement back — a chargeback, an abuse decision, a comp withdrawn. Effective on the account's
+ * next request, which is exactly why it is granted separately from the ability to hand one out.
+ */
+export const PAYMENTS_ENTITLEMENT_REVOKE_SCOPE: ControlPlaneScope = "payments:entitlements:revoke";
+
+/**
+ * Read the purchase log — every verified provider transaction, across every account.
+ *
+ * Strictly more disclosure than {@link PAYMENTS_SUBSCRIPTIONS_READ_SCOPE}, which is why the two are
+ * separate: a renewal monitor needs to know who is still paying and when their period ends, and has no
+ * business reading what everybody ever bought. Neither read reaches a stored provider payload.
+ */
+export const PAYMENTS_PURCHASES_READ_SCOPE: ControlPlaneScope = "payments:purchases:read";
+
+/**
+ * Read the purchases that renew — the same rows as the purchase log, narrowed to `type: subscription`.
+ *
+ * The narrower of the two grants, and the one a renewal or churn tool should hold on its own. Holding it
+ * confers nothing about the rest of the log: `scopeCovers` matches exactly, with no prefix rule.
+ */
+export const PAYMENTS_SUBSCRIPTIONS_READ_SCOPE: ControlPlaneScope = "payments:subscriptions:read";
+
+/**
+ * Read the entitlement model — what accounts hold, whether it grants right now, and where it came from.
+ *
+ * **The read that had to exist for grant and revoke to be honest.** Payments shipped both writes with no
+ * read beside them, so a management client could comp an entitlement and take one back while never being
+ * able to list one; a console that cannot see what it changed is asking an operator to act blind. It is
+ * still granted separately, because seeing what every account is entitled to and deciding what they are
+ * entitled to are different operations with different blast radii.
+ */
+export const PAYMENTS_ENTITLEMENTS_READ_SCOPE: ControlPlaneScope = "payments:entitlements:read";
+
+/**
+ * Read what this project **sells** — each product's id, type, display name, and the entitlement keys it
+ * grants. Not what anybody bought.
+ *
+ * **Its own scope, and the reason is that the two disclosures are unrelated.** Every other read here is a
+ * page of the adopter's customers: who paid, what they hold, when it lapses. This one names no account and
+ * no transaction, and would read identically against a database with no rows in it. A tool that populates a
+ * "comp this person an entitlement" list needs exactly this and nothing else, and it should be able to hold
+ * exactly this and nothing else — a dropdown is not a reason to hand a client the purchase log.
+ *
+ * The converse matters as much and is why it is not folded into {@link PAYMENTS_ENTITLEMENTS_READ_SCOPE}: a
+ * catalog is a commercial fact — every tier a company sells and every feature it gates — and a connection
+ * granted the entitlement model should not acquire it by implication. `scopeCovers` matches exactly, so
+ * neither scope confers the other.
+ */
+export const PAYMENTS_CATALOG_READ_SCOPE: ControlPlaneScope = "payments:catalog:read";
+
+/**
+ * Read what **reconciliation** did — the log of passes, their tallies, and when they last ran.
+ *
+ * Its own scope because it is operational state rather than anybody's commerce. A run record names no
+ * account, no transaction and no amount; it says whether the compensating control for a delivery mechanism
+ * that is known to fail has been firing, and how much it had to repair. An adopter should be able to give a
+ * health monitor exactly that and nothing else — a "has the cron stopped" alarm has no business holding the
+ * purchase log, and `scopeCovers` matches exactly, so neither confers the other.
+ */
+export const PAYMENTS_RECONCILE_READ_SCOPE: ControlPlaneScope = "payments:reconcile:read";
+
+/**
+ * Start a reconciliation pass now.
+ *
+ * **Separate from the read, and it is the sharpest split in this list.** Reading the run log says whether the
+ * nightly repair has been firing; starting one calls the store, walks the catalog, and *writes entitlements* —
+ * granting what a dropped webhook never granted and revoking what a missed cancellation left standing. The
+ * health monitor that holds `:read` to alarm on a stopped cron must not be able to move somebody's access, and
+ * `scopeCovers` matches exactly, so it cannot.
+ *
+ * **A trigger exists because the cron is not enough.** `pithy payments reconcile` runs the same pass, and it
+ * needs a laptop, a checkout, and a Cloudflare API token for the project — so the answer to "my subscription
+ * isn't showing up" at 4pm on a Saturday is either this route or nothing until 04:00 UTC. Adopted from
+ * `pithy-sh/dashboard#96`, where the operator with the run log open had no way to act on it.
+ *
+ * Idempotent by construction, so the scope carries no warning about pressing twice: `reconcilePayments` finds
+ * a reconciled catalog already matching and writes nothing.
+ */
+export const PAYMENTS_RECONCILE_RUN_SCOPE: ControlPlaneScope = "payments:reconcile:run";
+
+/**
+ * Every control-plane scope payments defines — what `pithy dashboard connect` offers for this capability, and
+ * the list a manifest or a doc quotes rather than re-typing. Core's `SEAM_SCOPES` is the same idea for the
+ * seam's own routes.
+ *
+ * Reads first, writes after, because that is the order an adopter should read them in: the reads are the
+ * grant most connections want and the smallest one that makes a dashboard useful.
+ */
+export const PAYMENTS_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
+  PAYMENTS_CATALOG_READ_SCOPE,
+  PAYMENTS_PURCHASES_READ_SCOPE,
+  PAYMENTS_SUBSCRIPTIONS_READ_SCOPE,
+  PAYMENTS_ENTITLEMENTS_READ_SCOPE,
+  PAYMENTS_DISCOUNT_READ_SCOPE,
+  PAYMENTS_RECONCILE_READ_SCOPE,
+  PAYMENTS_ENTITLEMENT_GRANT_SCOPE,
+  PAYMENTS_ENTITLEMENT_REVOKE_SCOPE,
+  PAYMENTS_DISCOUNT_CREATE_SCOPE,
+  PAYMENTS_RECONCILE_RUN_SCOPE,
+];
+
+/**
+ * Payments' management surface, as `GET /control-plane/manifest` reports it.
+ *
+ * Declared beside the scopes rather than in `routes.ts` so the scope a route demands and the scope a
+ * manifest advertises are the same constant, read from one place. `basePath` is a parameter and never a
+ * default: an adopter who mounted payments at `/billing` must get a manifest naming
+ * `/billing/entitlements/grant`, or a management client composing its calls from it would 404 against
+ * exactly the adopters who customized anything.
+ *
+ * The summaries say what the operation *is for*, not what it does mechanically. A client renders these
+ * next to a button somebody is about to press on a paying customer's account.
+ *
+ * **Everything sits under an `admin/` segment.** The player surface already owns `${basePath}/purchases`
+ * and `${basePath}/entitlements`, and the second of those is a `GET` — so a management read mounted at
+ * the bare path would either collide outright or sit behind whichever of the two Hono matched first, with
+ * a route's gate decided by registration order. The extra segment makes the two sets disjoint by
+ * construction rather than by luck. It also keeps the reads at the shape a management client looks for: a
+ * `GET`, with a declared scope, no `:` segment, ending in the resource's own noun.
+ */
+export function paymentsAdminRoutes(basePath: string): AdminRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${basePath}/admin/catalog`,
+      scope: PAYMENTS_CATALOG_READ_SCOPE,
+      summary:
+        "What this project sells — each product's id, kind, display name, and the entitlement keys it grants. The list a comp control fills its dropdown from.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/purchases`,
+      scope: PAYMENTS_PURCHASES_READ_SCOPE,
+      summary:
+        "Page the purchase log — every verified transaction, newest first, filtered by holder (both halves of the subject), store, status or store environment.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/subscriptions`,
+      scope: PAYMENTS_SUBSCRIPTIONS_READ_SCOPE,
+      summary: "Page the purchases that renew — who is still paying, and when the period they paid for ends.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/entitlements`,
+      scope: PAYMENTS_ENTITLEMENTS_READ_SCOPE,
+      summary: "Page what accounts hold — whether each entitlement grants right now, and which purchase is the reason.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/entitlements/:subjectType/:subjectId`,
+      scope: PAYMENTS_ENTITLEMENTS_READ_SCOPE,
+      summary:
+        "Everything one subject is entitled to, resolved now — addressed by both halves, `user`/`organization` and the id. The answer to “why can this person not use what they paid for”.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/discounts`,
+      scope: PAYMENTS_DISCOUNT_READ_SCOPE,
+      summary: "The discount codes this project has issued, read from the store that holds them.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/admin/discounts`,
+      scope: PAYMENTS_DISCOUNT_CREATE_SCOPE,
+      summary: "Mint a discount code at one store, from terms stated in the units a customer experiences.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/reconcile-runs`,
+      scope: PAYMENTS_RECONCILE_READ_SCOPE,
+      summary:
+        "The reconciliation passes this deployment has run — when each ran, what it compared, and what it had to repair. The answer to whether the nightly repair is still firing.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/admin/reconcile-runs`,
+      scope: PAYMENTS_RECONCILE_RUN_SCOPE,
+      summary:
+        "Start a reconciliation pass now, rather than waiting for the nightly one. The repair path for a purchase a dropped webhook never projected.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/entitlements/grant`,
+      scope: PAYMENTS_ENTITLEMENT_GRANT_SCOPE,
+      summary: "Comp an entitlement, or repair a purchase that verified but never projected.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/entitlements/revoke`,
+      scope: PAYMENTS_ENTITLEMENT_REVOKE_SCOPE,
+      summary: "Take an entitlement back, effective immediately.",
+    },
+  ];
+}

package/src/http/view.ts

@@ -0,0 +1,188 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaymentsPurchaseRecord } from "../admin/read";
+import type { PaymentsConfig } from "../config/config";
+import type { PaymentsEntitlement } from "../data/entitlement";
+import type { PaymentsReconcileRun } from "../data/reconcileRun";
+import type { PurchaseProjection } from "../projection/writer";
+import type {
+  PaymentsAdminCatalogResponse,
+  PaymentsAdminEntitlementView,
+  PaymentsAdminPurchaseView,
+  PaymentsAdminReconcileRunView,
+  PaymentsEntitlementView,
+  PaymentsPurchaseView,
+} from "./responses";
+
+/**
+ * What a client is shown. Nothing in this package ever returns a raw row.
+ *
+ * ## What payments holds, and therefore what this can leak
+ *
+ * There is exactly one column across all four tables that is personal data in the ordinary sense, and it
+ * is `pithy_payments_purchases.payload` — the verified provider response, retained as received. On Apple
+ * and Google it is a bearer artifact. On Stripe it is a document carrying the buyer's email address,
+ * their name, and their billing details. So the question `@pithy-sh/email` answers by masking a
+ * recipient has a different answer here, and a stronger one: **the payload is not masked, it is not
+ * projected, and the management queries do not select it** (`admin/read.ts`). A field that never reaches
+ * the Worker's memory cannot reach a response.
+ *
+ * Everything else payments stores is an identifier or a fact about a transaction. The only identity is the
+ * **subject pair**, `(subjectType, subjectId)` — opaque ids the adopter's auth capability and its own
+ * membership model issued, and already the address a management client must name to ask about a holder.
+ * Turning either into a name or an address needs `auth:users:read`, which is a separate grant against a
+ * separate capability.
+ *
+ * The two halves are projected together or not at all. A view carrying `subjectId` alone would read as a
+ * person whenever an adopter's organization ids and user ids met on a value, so the management
+ * projections below copy the pair off one row and never assemble one from config and a column.
+ *
+ * ## The two audiences, and why their projections differ
+ *
+ * {@link purchaseView} and {@link entitlementView} answer the adopter's own app, over `requireAuth()`,
+ * always about the caller's own rows. {@link adminPurchaseView} and {@link adminEntitlementView} answer a
+ * management client, over the control-plane seam, about everybody's. The management views are wider by
+ * the facts an operator cannot work without — who owns it, what was charged, whether a human granted it,
+ * and which purchase is the reason — and narrower by `outcome`, which describes a write and has no
+ * meaning on a read. The client views name no subject at all: the caller is the holder, and a body
+ * echoing that back would be the protocol offering a field a client could one day fill in.
+ *
+ * ## The field lists live in `responses.ts`
+ *
+ * Every return type below is `z.output` of the Zod object there, so there is one declaration of what a
+ * client receives rather than an interface here and a hand-written mirror of it in every management
+ * client. A field added to one and not the other does not compile.
+ *
+ * Dates render as ISO-8601 strings. They are ms-epoch integers in SQLite and `Date`s in TypeScript, and
+ * a JSON number would leave every client guessing which unit it was in.
+ */
+
+/**
+ * A purchase as its own buyer may see it — the projection a write hands back.
+ *
+ * Deliberately not the row: the stored `payload` is the whole provider response, and a client has no use
+ * for its own receipt read back to it.
+ */
+export function purchaseView(projection: PurchaseProjection): PaymentsPurchaseView {
+  const { purchase } = projection;
+  return {
+    id: purchase.id,
+    rail: purchase.rail,
+    productId: purchase.productId,
+    type: purchase.type,
+    status: purchase.status,
+    environment: purchase.environment,
+    purchasedAt: purchase.purchasedAt.toISOString(),
+    expiresAt: purchase.expiresAt?.toISOString() ?? null,
+    resumesAt: purchase.resumesAt?.toISOString() ?? null,
+    outcome: projection.outcome,
+  };
+}
+
+/** An entitlement as its holder reads it: the key, whether it grants right now, and when it lapses. */
+export function entitlementView(entitlement: {
+  key: string;
+  active: boolean;
+  expiresAt: Date | null;
+}): PaymentsEntitlementView {
+  return { key: entitlement.key, granted: entitlement.active, expiresAt: entitlement.expiresAt?.toISOString() ?? null };
+}
+
+/**
+ * Project the catalog for a management client — what this project sells, and nothing about who bought it.
+ *
+ * The one projection in this file built from **config** rather than from a row, and that is the whole
+ * reason it is safe: the value it reads is `pithy.config.ts`, so a credential, a stored payload, and a
+ * customer's identity are not merely withheld here, they are not in the input. What *is* in the input and
+ * must not cross is the commercial half of the catalog — every rail's SKU, the Stripe price id, and the
+ * `grants` block's currency and amount — and the four fields below are the whole of what does.
+ *
+ * `{ enabled: false }` when the project defines nothing, matching `clientProjection`'s answer for the same
+ * state and for the same reason: a client branches on `enabled`, so "composed with nothing to sell" must
+ * read as its own state rather than as an empty list that looks like a failed load.
+ */
+export function adminCatalogView(config: PaymentsConfig): PaymentsAdminCatalogResponse {
+  const products = Object.entries(config.products).map(([id, product]) => ({
+    id,
+    type: product.type,
+    name: product.name,
+    entitlements: [...product.entitlements],
+  }));
+  const manualEntitlements = [...config.manualEntitlements];
+  if (products.length === 0 && manualEntitlements.length === 0) return { enabled: false };
+  // Catalog order, not sorted: the order an adopter wrote their products in is the order a list should
+  // show them, exactly as the client projection argues.
+  return { enabled: true, products, manualEntitlements };
+}
+
+/** Project one purchase for a management client. The record's columns, verbatim, with dates as strings. */
+export function adminPurchaseView(purchase: PaymentsPurchaseRecord): PaymentsAdminPurchaseView {
+  return {
+    id: purchase.id,
+    subjectType: purchase.subjectType,
+    subjectId: purchase.subjectId,
+    rail: purchase.rail,
+    providerTransactionId: purchase.providerTransactionId,
+    originalTransactionId: purchase.originalTransactionId,
+    productId: purchase.productId,
+    type: purchase.type,
+    status: purchase.status,
+    environment: purchase.environment,
+    amountMinor: purchase.amountMinor,
+    currency: purchase.currency,
+    purchasedAt: purchase.purchasedAt.toISOString(),
+    expiresAt: purchase.expiresAt?.toISOString() ?? null,
+    revokedAt: purchase.revokedAt?.toISOString() ?? null,
+    resumesAt: purchase.resumesAt?.toISOString() ?? null,
+    updatedAt: purchase.updatedAt.toISOString(),
+  };
+}
+
+/**
+ * Project one entitlement row for a management client, resolving `granted` against `now`.
+ *
+ * The stored `active` flag is what the projection last wrote; `expiresAt` is the truth. A subscription
+ * can lapse with no notification arriving at all, so a row can say `active` with an expiry in the past —
+ * and the gate the adopter's own app calls applies the timestamp on every request. A dashboard that
+ * rendered the flag would disagree with that gate, and the customer would believe the dashboard.
+ */
+export function adminEntitlementView(row: PaymentsEntitlement, now: Date): PaymentsAdminEntitlementView {
+  const lapsed = row.expiresAt !== null && row.expiresAt.getTime() <= now.getTime();
+  return {
+    subjectType: row.subjectType,
+    subjectId: row.subjectId,
+    key: row.entitlement,
+    granted: row.active && !lapsed,
+    expiresAt: row.expiresAt?.toISOString() ?? null,
+    manual: row.manual,
+    source: row.sourcePurchaseId,
+  };
+}
+
+/**
+ * Project one reconciliation run for a management client.
+ *
+ * The row's columns verbatim, with the dates as ISO strings and `createdAt` left behind — when the row was
+ * *written* is bookkeeping, and `finishedAt` already answers the only version of that question an operator
+ * asks. Nothing is withheld beyond it, because there is nothing to withhold: the table has no column a
+ * store's response could reach.
+ */
+export function adminReconcileRunView(run: PaymentsReconcileRun): PaymentsAdminReconcileRunView {
+  return {
+    id: run.id,
+    startedAt: run.startedAt.toISOString(),
+    finishedAt: run.finishedAt.toISOString(),
+    environment: run.environment,
+    rail: run.rail,
+    pages: run.pages,
+    scanned: run.scanned,
+    unchanged: run.unchanged,
+    drifted: run.drifted,
+    superseded: run.superseded,
+    skipped: run.skipped,
+    failed: run.failed,
+    truncated: run.truncated,
+    dryRun: run.dryRun,
+  };
+}