create-ailk 0.24.0 → 0.26.0

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

@@ -1,403 +0,0 @@
-/**
- * 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), refuses the hub's own plan keys at any period
- * (#9338 DD5), 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 fallback (A5), and this path never
- * sells on the environment key: an Organization that owns it checks out on the
- * env path until it has a stored connection (#9296, #8936).
- *
- * THE READ. `readOfferingsCheckoutSession` reads a recorded session with its
- * record's own connection, never a caller value (A13). Only a stored connection
- * records a session (#9296), so this read never runs on the environment key.
- *
- * 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,
-  isPlanPurchaseKey,
-  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 {
-  getOfferingsConnectionState,
-  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 getOfferingsConnectionState(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" };
-  // An Organization on the environment key never takes the Offerings path
-  // (#9296): that path stamps `ailk_offering`, which the legacy webhook acks
-  // `offerings_path` without recording and the per-Organization receiver takes
-  // only for a stored connection's token, so a sale on the environment key
-  // would be charged and never fulfilled. Its checkout stays on the env path
-  // until environment-key fulfilment exists (#8936 stores the connection).
-  if (summary === "environment") return noConnection;
-  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();
-
-  // 1b. Never a hub plan (#9338 DD5): AILK's own Pro / Pro Plus, at any
-  // period, for every Organization. A sale here would stamp `ailk_offering`,
-  // which no billing path mints a licence for — the buyer would be charged
-  // with no key. Same 404, same log reason, before any read.
-  if (isPlanPurchaseKey(productCode)) 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

@@ -1,192 +0,0 @@
-/**
- * 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");
-}