create-ailk 0.22.0 → 0.23.0

package/templates/apps/api/src/services/offerings/checkout-authorization.ts

@@ -0,0 +1,385 @@
+/**
+ * The Offerings checkout (#8931, spec
+ * docs/specs/8931-offerings-checkout-authorization-server-side-spec.md D1,
+ * D2, D5, D7, D9, D11; contract
+ * docs/specs/8879-the-offerings-security-contract-key-spec.md A1–A9, A11,
+ * A13, G1, G3, G6, K6).
+ *
+ * THE PATH. `resolveOfferingsCheckoutPath` decides, from the server-resolved
+ * workspace and its Organization's connection alone, whether a checkout
+ * request takes the Offerings path, the deployment's env-key path, or
+ * neither. No request body field names a workspace or an Organization (A1).
+ * A spoke's workspace with no connection is `unconnected`, never the env
+ * key: that key sells the deployment's own products, not a spoke's (#9126).
+ *
+ * THE SALE. `startOfferingsCheckout` parses the lookup key by the one grammar
+ * before any read (A3), authorizes it at click time against org-enabled ∩
+ * workspace-shown from the rows — never the snapshot (A4), and for a
+ * workspace saved per Price only a shown Price (#9070 D5) — resolves it live
+ * with the connection's own client, sells the authorized Price id in an
+ * anonymous hosted session stamped `{ site, ailk_offering }` by the server
+ * (A6, A7), and records the session before it answers; a failed record
+ * expires the session (A11). Every miss is one `unknown`; every failure one
+ * `unavailable`; there is never a snapshot or env-key fallback (A5).
+ *
+ * THE READ. `readOfferingsCheckoutSession` reads a recorded session with its
+ * record's own connection, never the env key or a caller value (A13).
+ *
+ * LOGGING (D11, T6). Only `workspaceId` or `organizationId`, an 8-character
+ * session-id prefix, a fixed `reason`, and an error's class name. Never a
+ * lookup key, a Price or Product id, Stripe text, a URL, a full session id
+ * or an error message.
+ */
+import { logger } from "@working-theory/observability";
+import {
+  OFFERINGS_NAME_MAX,
+  lookupKeyPeriodSchema,
+  parseLookupKey,
+} from "@working-theory/validation";
+import type { FastifyRequest } from "fastify";
+
+import {
+  createCheckoutSessionForPrice,
+  expireCheckoutSessionWith,
+  findActivePriceByLookupKey,
+  retrieveCheckoutSession,
+  type RetrieveCheckoutSessionOutput,
+  UnknownSessionError,
+} from "../../lib/stripe.js";
+import { resolvePublicWorkspace } from "../public-site-resolver.js";
+
+import { normalizeCatalog, normalizeText } from "./catalog.js";
+import {
+  CheckoutSessionRecordError,
+  readCheckoutSessionRecord,
+  recordCheckoutSession,
+} from "./checkout-session-record.js";
+import {
+  getStripeConnectionSummary,
+  stripeClientForOrganization,
+} from "./connection.js";
+import { organizationIdOfWorkspace } from "./store.js";
+
+import { getSellableProductIds } from "./index.js";
+
+/** One seller's Offerings checkouts a minute, across every caller (D4). */
+export const OFFERINGS_CHECKOUT_PER_WORKSPACE_PER_MINUTE = 60;
+
+/** The resolver's own header; its presence is what makes a refusal a refused key (D2). */
+const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
+
+export type OfferingsCheckoutPath =
+  | { kind: "env" }
+  | { kind: "refused" }
+  | { kind: "unavailable" }
+  | { kind: "unconnected"; workspaceId: string }
+  | { kind: "offerings"; workspaceId: string; organizationId: string };
+
+/**
+ * Which path a checkout request takes (D2). Rejects when a read rejects —
+ * the resolver's, the Organization's or the connection summary's — so a
+ * workspace it could not read never falls through to the env key.
+ */
+export async function resolveOfferingsCheckoutPath(
+  request: FastifyRequest,
+): Promise<OfferingsCheckoutPath> {
+  const site = await resolvePublicWorkspace(request);
+  if (site.kind === "not-required") return { kind: "env" };
+  if (site.kind === "unresolved") {
+    // A keyless call on a hub that requires a key is also `spoke-refused`;
+    // only a presented key that was refused is `refused` (A2, C6).
+    return site.reason === "spoke-refused" &&
+      request.headers[SPOKE_KEY_HEADER] !== undefined
+      ? { kind: "refused" }
+      : { kind: "env" };
+  }
+
+  const { workspaceId } = site;
+  // A keyless call resolves only where no spoke key is required (a deployment
+  // that is not a hub, or a hub's AILK_HUB_REQUIRE_SPOKE_KEY=off opt-out),
+  // whose env key sells its own products; a presented key resolved only to
+  // its spoke's workspace, which sells on its own connection or not at all
+  // (#9126).
+  const noConnection: OfferingsCheckoutPath =
+    request.headers[SPOKE_KEY_HEADER] !== undefined
+      ? { kind: "unconnected", workspaceId }
+      : { kind: "env" };
+  const organizationId = await organizationIdOfWorkspace(workspaceId);
+  if (organizationId === null) return noConnection;
+  const summary = await getStripeConnectionSummary(organizationId);
+  if (summary === null) return noConnection;
+  // Never the rows, which read a corrupt connection as an empty set (404).
+  if (summary === "unreadable") return { kind: "unavailable" };
+  return { kind: "offerings", workspaceId, organizationId };
+}
+
+export interface OfferingsCheckoutInput {
+  workspaceId: string;
+  organizationId: string;
+  productCode: string;
+  successUrl: string;
+  cancelUrl: string;
+  quantity: number;
+}
+
+export type OfferingsCheckoutOutcome =
+  | { kind: "created"; sessionId: string; url: string }
+  | { kind: "unknown" }
+  | { kind: "unavailable" };
+
+const UNKNOWN = { kind: "unknown" } as const;
+const UNAVAILABLE = { kind: "unavailable" } as const;
+
+function errName(err: unknown): string {
+  return err instanceof Error ? err.name : "unknown";
+}
+
+/**
+ * Authorize the key, sell its Price and record the session (D5–D7). Stops at
+ * the first step that fails; never rejects.
+ */
+export async function startOfferingsCheckout(
+  input: OfferingsCheckoutInput,
+): Promise<OfferingsCheckoutOutcome> {
+  const { workspaceId, organizationId, productCode } = input;
+  const unknown = (): OfferingsCheckoutOutcome => {
+    logger.info(
+      { workspaceId, reason: "offerings_unknown_product" },
+      "[offerings] checkout key not sellable",
+    );
+    return UNKNOWN;
+  };
+  const unavailable = (
+    reason: string,
+    err?: unknown,
+  ): OfferingsCheckoutOutcome => {
+    logger.error(
+      {
+        workspaceId,
+        reason,
+        ...(err !== undefined && { errName: errName(err) }),
+      },
+      "[offerings] checkout unavailable",
+    );
+    return UNAVAILABLE;
+  };
+
+  // 1. Grammar first (A3): no read and no Stripe call for a key G1 refuses.
+  const parsed = parseLookupKey(productCode);
+  if (parsed === null) return unknown();
+
+  // 2. The connection's own client (K6) — before the rows, so a key that
+  // cannot be used answers 502 whatever the rows hold.
+  let connection: Awaited<ReturnType<typeof stripeClientForOrganization>>;
+  try {
+    connection = await stripeClientForOrganization(organizationId);
+  } catch (err) {
+    return unavailable("offerings_connection_unusable", err);
+  }
+  if (connection.kind !== "ok")
+    return unavailable("offerings_connection_unusable");
+  const { client, mode } = connection;
+
+  // 3. The rows (A4): org-enabled ∩ workspace-shown, never the snapshot.
+  let sellable: Awaited<ReturnType<typeof getSellableProductIds>>;
+  try {
+    sellable = await getSellableProductIds(workspaceId);
+  } catch (err) {
+    return unavailable("offerings_rows_failed", err);
+  }
+  if (sellable === null || sellable.productIds.length === 0) return unknown();
+  if (sellable.organizationId !== organizationId) {
+    return unavailable("offerings_rows_failed");
+  }
+
+  // 4. The live lookup (A4), on the connection's client.
+  let price: Awaited<ReturnType<typeof findActivePriceByLookupKey>>;
+  try {
+    price = await findActivePriceByLookupKey(client, productCode);
+  } catch (err) {
+    return unavailable("offerings_price_lookup_failed", err);
+  }
+  if (price === null) return unknown();
+
+  // 5. The intersection and the period (A4, G3): the Price's own Product
+  // must be sellable here — and, for a workspace saved per Price, the Price
+  // itself shown (#9070 D5) — and the one normalizer must keep this exact
+  // Price under this key and period.
+  const product: unknown = price.product;
+  if (typeof product !== "object" || product === null) return unknown();
+  const productId = (product as { id?: unknown }).id;
+  if (
+    typeof productId !== "string" ||
+    !sellable.productIds.includes(productId) ||
+    (sellable.priceIds !== null && !sellable.priceIds.includes(price.id))
+  ) {
+    return unknown();
+  }
+  const offering = normalizeCatalog({
+    products: [product],
+    prices: [price],
+  }).offerings.find((o) => o.productId === productId);
+  const authorized = offering?.prices.some(
+    (p) =>
+      p.priceId === price.id &&
+      p.lookupKey === productCode &&
+      p.period === parsed.period,
+  );
+  if (!authorized) return unknown();
+
+  // 6. The sale (A6, A7): the authorized Price id, anonymous, stamped by the
+  // server, its mode from the period step 5 checked against the Price.
+  const metadata = { site: workspaceId, ailk_offering: productCode };
+  let created: { sessionId: string; url: string };
+  try {
+    created = await createCheckoutSessionForPrice(client, {
+      priceId: price.id,
+      mode:
+        parsed.period === lookupKeyPeriodSchema.enum.once
+          ? "payment"
+          : "subscription",
+      successUrl: input.successUrl,
+      cancelUrl: input.cancelUrl,
+      quantity: input.quantity,
+      allowPromotionCodes: true,
+      customerCreation: "always",
+      metadata,
+    });
+  } catch (err) {
+    return unavailable("offerings_session_create_failed", err);
+  }
+
+  // 7. The record (A11), before the URL leaves the server. A failed record
+  // expires the session on the same client: an unrecorded session is one the
+  // webhook never fulfils, so no buyer may reach it.
+  const sessionIdPrefix = created.sessionId.substring(0, 8);
+  try {
+    await recordCheckoutSession({
+      sessionId: created.sessionId,
+      workspaceId,
+      organizationId,
+      priceId: price.id,
+      lookupKey: productCode,
+      mode,
+    });
+  } catch (err) {
+    logger.error(
+      {
+        workspaceId,
+        sessionIdPrefix,
+        reason: "offerings_record_failed",
+        errName: errName(err),
+        ...(err instanceof CheckoutSessionRecordError && {
+          recordReason: err.reason,
+        }),
+      },
+      "[offerings] checkout session record failed; expiring the session",
+    );
+    try {
+      await expireCheckoutSessionWith(client, created.sessionId);
+    } catch (expireErr) {
+      logger.error(
+        {
+          workspaceId,
+          sessionIdPrefix,
+          reason: "offerings_expire_failed",
+          errName: errName(expireErr),
+        },
+        "[offerings] unrecorded checkout session could not be expired",
+      );
+    }
+    return UNAVAILABLE;
+  }
+
+  return { kind: "created", sessionId: created.sessionId, url: created.url };
+}
+
+export type OfferingsSessionRead =
+  | { kind: "env" }
+  | { kind: "read"; session: RetrieveCheckoutSessionOutput }
+  | { kind: "unknown" }
+  | { kind: "unavailable" };
+
+/**
+ * Read a session the Offerings checkout recorded, with its record's own
+ * connection (D9, A13). No record is `env`; a record that cannot be read, or
+ * a connection that is gone, unusable or in another mode, is `unavailable` —
+ * never the env path. Never rejects.
+ */
+export async function readOfferingsCheckoutSession(
+  sessionId: string,
+): Promise<OfferingsSessionRead> {
+  const sessionIdPrefix = sessionId.substring(0, 8);
+
+  let record: Awaited<ReturnType<typeof readCheckoutSessionRecord>>;
+  try {
+    record = await readCheckoutSessionRecord(sessionId);
+  } catch (err) {
+    logger.error(
+      {
+        sessionIdPrefix,
+        reason: "offerings_record_failed",
+        errName: errName(err),
+      },
+      "[offerings] checkout session record read failed",
+    );
+    return UNAVAILABLE;
+  }
+  if (record === null) return { kind: "env" };
+  if (record === "unreadable") return UNAVAILABLE;
+
+  const { organizationId } = record;
+  let connection: Awaited<ReturnType<typeof stripeClientForOrganization>>;
+  try {
+    connection = await stripeClientForOrganization(organizationId);
+  } catch (err) {
+    logger.error(
+      {
+        organizationId,
+        reason: "offerings_connection_unusable",
+        errName: errName(err),
+      },
+      "[offerings] checkout session read unavailable",
+    );
+    return UNAVAILABLE;
+  }
+  // C7: only the connection the session was made on, in that mode.
+  if (connection.kind !== "ok" || connection.mode !== record.mode) {
+    logger.error(
+      { organizationId, reason: "offerings_connection_unusable" },
+      "[offerings] checkout session read unavailable",
+    );
+    return UNAVAILABLE;
+  }
+
+  let session: RetrieveCheckoutSessionOutput;
+  try {
+    session = await retrieveCheckoutSession(
+      { sessionId },
+      { client: connection.client },
+    );
+  } catch (err) {
+    if (err instanceof UnknownSessionError) return UNKNOWN;
+    logger.error(
+      {
+        organizationId,
+        reason: "offerings_session_read_failed",
+        errName: errName(err),
+      },
+      "[offerings] checkout session read unavailable",
+    );
+    return UNAVAILABLE;
+  }
+
+  // The seller's Product names are Stripe text: served only as T1 bounds them.
+  return {
+    kind: "read",
+    session: {
+      ...session,
+      lineItems: session.lineItems.map((line) => ({
+        ...line,
+        description: normalizeText(line.description, OFFERINGS_NAME_MAX) ?? "",
+      })),
+    },
+  };
+}

package/templates/apps/api/src/services/offerings/checkout-session-record.ts

@@ -0,0 +1,192 @@
+/**
+ * The Offerings Checkout session record (#8930, spec
+ * docs/specs/8930-the-offerings-checkout-session-record-spec.md D4, D5, D7;
+ * contract docs/specs/8879-the-offerings-security-contract-key-spec.md A11,
+ * W5, A13) — the ONE file naming the OfferingsCheckoutSession delegate.
+ *
+ * WRITE ONCE. The checkout route records `{ sessionId, workspaceId,
+ * organizationId, priceId, lookupKey, mode }` before it answers, and the
+ * per-Organization webhook and the session read act only on a session
+ * recorded here — never on metadata alone. One `create` and one `findUnique`
+ * by Checkout Session id; nothing here updates, upserts, deletes or lists, so
+ * no record is rebound to another workspace and none is enumerated.
+ *
+ * `null` means one thing: the database holds no row for that id (or the id
+ * has a shape no row can hold). A database error rejects `read_failed`, and a
+ * row that fails the parse answers `"unreadable"` — neither is ever `null`,
+ * because a caller that read `null` would treat a paid session as foreign.
+ *
+ * ERRORS AND LOGGING (D7, contract T6). A `CheckoutSessionRecordError` carries
+ * a fixed message per reason and no `cause`, so no Prisma or Postgres text — a
+ * CHECK violation prints the failing row — reaches a log line or an HTTP
+ * error. Logs carry only a fixed `reason` (and the workspace on a failed
+ * write); never a session id, Price id, lookup key or mode.
+ */
+import { idRegex } from "@working-theory/ids";
+import { logger } from "@working-theory/observability";
+import {
+  offeringsStripeIdSchema,
+  parseLookupKey,
+} from "@working-theory/validation";
+import { z } from "zod";
+
+import { prisma } from "../../lib/prisma.js";
+import { isUniqueViolation } from "../default-tenant.js";
+
+import { organizationIdOfWorkspace } from "./store.js";
+
+export type CheckoutSessionMode = "test" | "live";
+
+export interface CheckoutSessionRecordInput {
+  sessionId: string;
+  workspaceId: string;
+  organizationId: string;
+  priceId: string;
+  lookupKey: string;
+  mode: CheckoutSessionMode;
+}
+
+export interface CheckoutSessionRecord extends CheckoutSessionRecordInput {
+  createdAt: Date;
+}
+
+export type CheckoutSessionRecordFailure =
+  | "invalid"
+  | "workspace_mismatch"
+  | "conflict"
+  | "write_failed"
+  | "read_failed";
+
+const FAILURE_MESSAGES: Record<CheckoutSessionRecordFailure, string> = {
+  invalid: "The Checkout session record is malformed",
+  workspace_mismatch:
+    "The Checkout session record names a workspace outside its Organization",
+  conflict: "The Checkout session is already recorded",
+  write_failed: "The Checkout session record could not be written",
+  read_failed: "The Checkout session record could not be read",
+};
+
+export class CheckoutSessionRecordError extends Error {
+  readonly reason: CheckoutSessionRecordFailure;
+
+  constructor(reason: CheckoutSessionRecordFailure) {
+    super(FAILURE_MESSAGES[reason]);
+    this.name = "CheckoutSessionRecordError";
+    this.reason = reason;
+  }
+}
+
+/** A Checkout Session id: the migration's `_session_id_format` CHECK body. */
+const SESSION_ID_PATTERN = /^cs_(test|live)_[A-Za-z0-9]{1,250}$/;
+
+/** Every column the migration CHECKs, mirrored so a refused write never reaches Postgres. */
+const recordShape = {
+  sessionId: z.string().regex(SESSION_ID_PATTERN),
+  workspaceId: z.string().regex(idRegex("workspace")),
+  organizationId: z.string().regex(idRegex("organization")),
+  priceId: offeringsStripeIdSchema,
+  lookupKey: z.string().refine((key) => parseLookupKey(key) !== null),
+  mode: z.enum(["test", "live"]),
+};
+
+/** The `_session_mode_agree` CHECK: a live key makes a `cs_live_` session. */
+const modeAgrees = (record: {
+  sessionId: string;
+  mode: CheckoutSessionMode;
+}): boolean =>
+  (record.mode === "live") === record.sessionId.startsWith("cs_live_");
+
+const recordInputSchema = z.object(recordShape).strict().refine(modeAgrees);
+const recordRowSchema = z
+  .object({ ...recordShape, createdAt: z.date() })
+  .strict()
+  .refine(modeAgrees);
+
+/** The record's columns, never its `id`. */
+const RECORD_SELECT = {
+  sessionId: true,
+  workspaceId: true,
+  organizationId: true,
+  priceId: true,
+  lookupKey: true,
+  mode: true,
+  createdAt: true,
+} as const;
+
+/**
+ * Record one Checkout Session, once, for a workspace of the named
+ * Organization. Rejects `invalid` (a malformed input), `workspace_mismatch`
+ * (no such workspace, or another Organization's), `conflict` (the session is
+ * already recorded; the first record stands) or `write_failed`.
+ */
+export async function recordCheckoutSession(
+  input: CheckoutSessionRecordInput,
+): Promise<void> {
+  const parsed = recordInputSchema.safeParse(input);
+  if (!parsed.success) throw new CheckoutSessionRecordError("invalid");
+  const data = parsed.data;
+
+  let organizationId: string | null;
+  try {
+    organizationId = await organizationIdOfWorkspace(data.workspaceId);
+  } catch {
+    throw writeFailed(data.workspaceId);
+  }
+  if (organizationId !== data.organizationId) {
+    throw new CheckoutSessionRecordError("workspace_mismatch");
+  }
+
+  try {
+    await prisma.offeringsCheckoutSession.create({
+      data,
+      select: { sessionId: true },
+    });
+  } catch (err) {
+    if (isUniqueViolation(err))
+      throw new CheckoutSessionRecordError("conflict");
+    throw writeFailed(data.workspaceId);
+  }
+}
+
+/**
+ * The record of one Checkout Session: the record, `"unreadable"` for a row
+ * that fails the parse, or `null` when no row holds that id. Rejects
+ * `read_failed` when the database read fails.
+ */
+export async function readCheckoutSessionRecord(
+  sessionId: unknown,
+): Promise<CheckoutSessionRecord | "unreadable" | null> {
+  if (typeof sessionId !== "string" || !SESSION_ID_PATTERN.test(sessionId))
+    return null;
+
+  let row: unknown;
+  try {
+    row = await prisma.offeringsCheckoutSession.findUnique({
+      where: { sessionId },
+      select: RECORD_SELECT,
+    });
+  } catch {
+    logger.error(
+      { reason: "checkout_record_read_failed" },
+      "[offerings] checkout session record read failed",
+    );
+    throw new CheckoutSessionRecordError("read_failed");
+  }
+  if (row === null) return null;
+
+  const record = recordRowSchema.safeParse(row);
+  if (record.success) return record.data;
+  logger.error(
+    { reason: "checkout_record_unreadable" },
+    "[offerings] checkout session record is unreadable",
+  );
+  return "unreadable";
+}
+
+function writeFailed(workspaceId: string): CheckoutSessionRecordError {
+  logger.error(
+    { workspaceId, reason: "checkout_record_write_failed" },
+    "[offerings] checkout session record write failed",
+  );
+  return new CheckoutSessionRecordError("write_failed");
+}