create-ailk 0.24.0 → 0.25.1

package/templates/apps/api/src/routes/checkout/sessions.ts

@@ -1,540 +0,0 @@
-/**
- * POST /api/checkout/sessions
- *
- * Generic Stripe checkout primitive. Resolves a productCode to a Stripe
- * hosted-page checkout session and returns the session ID + URL. The session
- * mode is derived from the resolved price by the stripe-client (a recurring
- * price opens a subscription session), so this route serves both (#4398).
- *
- * Security invariants:
- *   - Admitted key only (#8450): before any Stripe call, a test-mode key or
- *     the restricted live key the process admitted at boot passes
- *     (`assertAdmittedStripeKey`); every other live key is refused.
- *   - No PII in logs: successUrl/cancelUrl and full session IDs are never logged.
- *     Only the first 8 chars of the session ID appear in log lines.
- *   - Error responses never echo user input (productCode, URLs).
- *   - Two paths (#8931 D2, D3): for a server-resolved workspace whose
- *     Organization has a Stripe connection, the Offerings path —
- *     `services/offerings/checkout-authorization.ts` parses the key by the one
- *     grammar, authorizes it against org-enabled ∩ workspace-shown from the
- *     rows, sells the authorized Price id on the connection's own client in an
- *     anonymous session stamped `{ site, ailk_offering }`, and records it
- *     before this route answers. It never reads the env key, the snapshot or
- *     a caller value, charges a per-IP and a per-workspace bucket on every
- *     request, and never resolves a signed-in buyer. A spoke's workspace
- *     whose Organization has no row or no connection is the one 404 before
- *     any budget, env-key read or Stripe call — never the env path (#9126).
- *     Every other request takes the env path below, which now refuses a
- *     Price whose Product carries the Offerings marker (A9). The body schema
- *     is the same on both.
- *   - No DB write on the env path: it creates a Stripe session only. It READS
- *     the database to choose the path and to resolve an optional signed-in
- *     buyer (below).
- *   - Optional cookie identity (#6866): a valid, same-origin Better Auth
- *     session cookie whose user has a verified email makes the Checkout a
- *     signed-in one — the session is pinned to the buyer's Stripe customer and
- *     stamped `metadata.ailk_user_id`, so the #6852 webhook binds it. The id
- *     comes ONLY from the session cookie, never the body; a bearer token never
- *     identifies a buyer. Any lookup failure, and a pinned customer Stripe
- *     does not know, degrades to today's anonymous Checkout — never an error.
- *     The stamped id is never echoed or logged.
- *   - Site stamp (#7868): every session carries `metadata.site` from
- *     `siteStamp()` (lib/site.ts) — on the signed-in try and the anonymous
- *     retry alike — so the Stripe webhook can tell this site's sessions from
- *     a spoke's on a shared account. The body schema has no metadata field,
- *     so no caller can set or override the stamp.
- *   - X-Internal-Auth gate: when OSS_API_INTERNAL_SECRET env var is set,
- *     the X-Internal-Auth header must match; requests without a matching header
- *     are rejected with 401. When the env var is unset, no gate is applied
- *     (backward-compat for OSS standalone deployments). See #935.
- *   - Same-origin redirects (#6877): a request that did not pass an ENABLED
- *     internal-auth gate (the OSS default) must send successUrl and cancelUrl
- *     each on one of the trusted browser origins — `config.TRUSTED_ORIGINS`
- *     (#7395: FRONTEND_URL's origin plus AILK_TRUSTED_ORIGINS), exact scheme +
- *     host + port, checked on the raw string as well as on the parse, because
- *     the raw string is what Stripe receives. Anything else is a 400 before
- *     any Stripe call or database read. A caller authenticated by
- *     X-Internal-Auth keeps its redirects; that exemption holds only while
- *     every internal caller builds its redirects itself — an internal caller
- *     MUST NEVER forward a redirect taken from its own end user.
- *
- * Error mapping:
- *   401 internal-auth-required — X-Internal-Auth missing/mismatch (only when env var set)
- *   400 validation-error      — Zod validation failed (missing/invalid fields), or an
- *                               unauthenticated redirect is off the site origin (#6877)
- *   404 unknown-product-code  — no active Stripe price for the given productCode; on the
- *                               env path, a Price whose Product is Offerings-marked; on the
- *                               Offerings path, every key that is not sellable here (#8931);
- *                               every key, for a spoke whose Organization is unconnected (#9126)
- *   429 rate_limited          — Offerings path: the per-IP or per-workspace bucket (#8931 D4)
- *   503 tenant_unresolved     — a presented spoke key the resolver refused (#8931 A2)
- *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty (no Stripe call)
- *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key the process did not admit
- *   500 config-error          — STRIPE_SECRET_KEY invalid configuration (from the SDK wrapper),
- *                               or no trusted browser origin is configured when the origin
- *                               lock applies (#6877, #7395)
- *   502 checkout-unavailable  — Stripe SDK threw an unexpected error; a database read
- *                               choosing the path failed; Offerings path: Stripe, the rows,
- *                               the connection or the session record failed (#8931)
- */
-import { timingSafeEqual } from "node:crypto";
-
-import type { FastifyReply, FastifyRequest } from "fastify";
-import { z } from "zod";
-
-import { config } from "../../config/index.js";
-import { siteStamp } from "../../lib/site.js";
-import {
-  assertAdmittedStripeKey,
-  createCheckoutSession,
-  StripeConfigError,
-  UnknownCustomerError,
-  UnknownProductCodeError,
-} from "../../lib/stripe.js";
-import type {
-  CreateCheckoutSessionInput,
-  CreateCheckoutSessionOutput,
-} from "../../lib/stripe.js";
-import {
-  type OptionalCookieUser,
-  resolveOptionalCookieUser,
-} from "../../middleware/auth.js";
-import {
-  chargeWriteBudget,
-  DEFAULT_PER_IP_PER_MINUTE_STRICT,
-} from "../../middleware/rate-limit.js";
-import {
-  type CheckoutBuyerResult,
-  resolveCheckoutBuyer,
-} from "../../services/checkout-buyer.js";
-import { isOfferingsProduct } from "../../services/offerings/catalog.js";
-import {
-  OFFERINGS_CHECKOUT_PER_WORKSPACE_PER_MINUTE,
-  type OfferingsCheckoutPath,
-  resolveOfferingsCheckoutPath,
-  startOfferingsCheckout,
-} from "../../services/offerings/checkout-authorization.js";
-
-type OptionalCookieUserNone = Extract<OptionalCookieUser, { kind: "none" }>;
-
-// ── Input validation schema ───────────────────────────────────────────────────
-
-/**
- * Validates a redirect URL: must parse and must use http: or https: scheme.
- * All other schemes (javascript:, ftp:, data:, file:, etc.) are rejected.
- * Accepts http: for dev flexibility; Stripe enforces https: on production
- * hosted-page redirects at their end.
- */
-function isValidRedirectUrl(raw: string): boolean {
-  let parsed: URL;
-  try {
-    parsed = new URL(raw);
-  } catch {
-    return false;
-  }
-  return parsed.protocol === "https:" || parsed.protocol === "http:";
-}
-
-const PRODUCT_CODE_REGEX = /^[A-Za-z0-9._-]{1,200}$/;
-
-const CheckoutSessionRequestSchema = z.object({
-  productCode: z
-    .string()
-    .regex(
-      PRODUCT_CODE_REGEX,
-      "productCode must match /^[A-Za-z0-9._-]{1,200}$/",
-    ),
-  successUrl: z.string().refine(isValidRedirectUrl, {
-    message:
-      "successUrl must be a valid URL with a non-empty host and not use javascript: scheme",
-  }),
-  cancelUrl: z.string().refine(isValidRedirectUrl, {
-    message:
-      "cancelUrl must be a valid URL with a non-empty host and not use javascript: scheme",
-  }),
-  quantity: z.number().int().min(1).max(999).optional(),
-  allowPromotionCodes: z.boolean().optional(),
-});
-
-// ── Internal-auth gate ────────────────────────────────────────────────────────
-
-/**
- * Classify the request against the X-Internal-Auth gate (#935, #6877 D3).
- *
- * Gate is env-var-conditional:
- *   - env var SET, header missing or wrong → "refused" (401)
- *   - env var SET, header matches           → "authenticated" (redirects kept)
- *   - env var UNSET                         → "open" (OSS standalone backward-
- *     compat; the request is anonymous, so the origin lock applies)
- *
- * Uses a constant-time string comparison to prevent timing attacks on the
- * secret value. Node's `crypto.timingSafeEqual` requires equal-length Buffers,
- * so we compare lengths first (short-circuit is safe — length mismatch reveals
- * no information about the secret's content beyond its length, which is
- * acceptable for a shared internal secret).
- */
-function internalAuthVerdict(
-  request: FastifyRequest,
-): "refused" | "open" | "authenticated" {
-  const expectedSecret = process.env["OSS_API_INTERNAL_SECRET"];
-  // Gate is disabled when env var is not set — OSS standalone backward-compat.
-  if (!expectedSecret) return "open";
-
-  const provided = request.headers["x-internal-auth"];
-  if (typeof provided !== "string" || !provided) return "refused";
-
-  // Constant-time comparison.
-  const expectedBuf = Buffer.from(expectedSecret, "utf8");
-  const providedBuf = Buffer.from(provided, "utf8");
-  if (expectedBuf.length !== providedBuf.length) return "refused";
-
-  return timingSafeEqual(expectedBuf, providedBuf)
-    ? "authenticated"
-    : "refused";
-}
-
-// ── Same-origin redirect lock (#6877) ────────────────────────────────────────
-
-/** C0 controls, space, DEL and backslash — anything a parser may normalize. */
-// eslint-disable-next-line no-control-regex -- the control-character range is exactly what D2 check 1 must refuse.
-const NON_CANONICAL_URL_CHAR = /[\u0000-\u0020\u007f\\]/;
-
-/**
- * True only when `raw` is on `siteOrigin` both as written and as parsed
- * (#6877 D2). The raw-string checks matter because the route forwards `raw`
- * itself to Stripe: WHATWG parses `https://example.com\@evil.test/x` to
- * origin `https://example.com`, and another parser may not. Requiring the
- * literal origin followed by `/`, `?`, `#` or the end keeps
- * `https://example.com.evil.test` out, and exact origin equality keeps a
- * scheme downgrade or another port out.
- */
-function isSameOriginRedirect(raw: string, siteOrigin: string): boolean {
-  if (NON_CANONICAL_URL_CHAR.test(raw)) return false;
-  if (!raw.startsWith(siteOrigin)) return false;
-  const boundary = raw.charAt(siteOrigin.length);
-  if (boundary !== "" && !"/?#".includes(boundary)) return false;
-  let resolved: URL;
-  try {
-    resolved = new URL(raw);
-  } catch {
-    return false;
-  }
-  if (resolved.protocol !== "https:" && resolved.protocol !== "http:")
-    return false;
-  return resolved.origin === siteOrigin;
-}
-
-// ── Optional signed-in buyer (#6866) ─────────────────────────────────────────
-
-type Buyer = NonNullable<CreateCheckoutSessionInput["buyer"]>;
-
-/** Why a present cookie produced no buyer — the closed set D6 logs. */
-type IdentityReason =
-  | Exclude<OptionalCookieUserNone["reason"], "no_cookie">
-  | Extract<CheckoutBuyerResult, { ok: false }>["reason"]
-  | "buyer_lookup_failed"
-  | "buyer_invalid"
-  | "stale_customer";
-
-/**
- * Resolve the signed-in buyer from the session cookie alone (#6866 D2/D3).
- * Never throws: a failed lookup is anonymous (F7). `identity` is the reason a
- * present cookie produced no buyer — logged, never the user's id; absent for
- * a call with no cookie (D6).
- */
-async function resolveBuyer(
-  request: FastifyRequest,
-): Promise<{ buyer?: Buyer; identity?: IdentityReason }> {
-  const cookieUser = await resolveOptionalCookieUser(request, {
-    trustedOrigins: config.TRUSTED_ORIGINS,
-  });
-  if (cookieUser.kind === "none") {
-    return cookieUser.reason === "no_cookie"
-      ? {}
-      : { identity: cookieUser.reason };
-  }
-  try {
-    const result = await resolveCheckoutBuyer(cookieUser.userId);
-    if (!result.ok) return { identity: result.reason };
-    const { userId, email, customerId } = result.buyer;
-    return {
-      buyer: { userId, email, ...(customerId !== null && { customerId }) },
-    };
-  } catch {
-    return { identity: "buyer_lookup_failed" };
-  }
-}
-
-// ── Handler ───────────────────────────────────────────────────────────────────
-
-export async function checkoutSessionsHandler(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  // ── X-Internal-Auth gate (env-var-conditional) ────────────────────────────
-  const authVerdict = internalAuthVerdict(request);
-  if (authVerdict === "refused") {
-    return reply.status(401).send({ error: "internal-auth-required" });
-  }
-
-  // ── Which path (#8931 D2) — from the server-resolved workspace alone ──────
-  let checkoutPath: OfferingsCheckoutPath;
-  try {
-    checkoutPath = await resolveOfferingsCheckoutPath(request);
-  } catch (err) {
-    request.log.error(
-      {
-        method: request.method,
-        path: request.url,
-        outcome: "offerings_path_failed",
-        errName: err instanceof Error ? err.name : "unknown",
-      },
-      "[checkout] path read failed; checkout-unavailable",
-    );
-    return reply.status(502).send({ error: "checkout-unavailable" });
-  }
-  if (checkoutPath.kind === "refused") {
-    return reply.status(503).send({ error: "tenant_unresolved" });
-  }
-  if (checkoutPath.kind === "unavailable") {
-    return reply.status(502).send({ error: "checkout-unavailable" });
-  }
-  if (checkoutPath.kind === "unconnected") {
-    // A spoke sells nothing until its Organization connects Stripe (#9126):
-    // the one 404 every miss answers, before any budget, env-key read or
-    // Stripe call, so the hub's env key never sells for a spoke.
-    request.log.warn(
-      { outcome: "unconnected", workspaceId: checkoutPath.workspaceId },
-      "[checkout] spoke has no Stripe connection; unknown-product-code",
-    );
-    return reply.status(404).send({ error: "unknown-product-code" });
-  }
-
-  if (checkoutPath.kind === "env") {
-    const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
-    if (!stripeSecretKey) {
-      return reply.status(500).send({ error: "stripe-not-configured" });
-    }
-    try {
-      assertAdmittedStripeKey(stripeSecretKey);
-    } catch {
-      return reply.status(500).send({ error: "live-mode-forbidden" });
-    }
-  } else {
-    // The Offerings bucket (#8931 D4), before the body is read, whatever the
-    // process's mode: per caller IP, and per workspace — the bound a
-    // caller-set X-Forwarded-For cannot dodge. One charge at a time, the IP
-    // first: a request its IP bucket refuses never spends the workspace's,
-    // so one address cannot shut a seller's checkout for every buyer.
-    const charges = [
-      { key: `ip,${request.ip}`, limit: DEFAULT_PER_IP_PER_MINUTE_STRICT },
-      {
-        key: `ws,${checkoutPath.workspaceId}`,
-        limit: OFFERINGS_CHECKOUT_PER_WORKSPACE_PER_MINUTE,
-      },
-    ];
-    for (const charge of charges) {
-      let budget: Awaited<ReturnType<typeof chargeWriteBudget>>;
-      try {
-        budget = await chargeWriteBudget({
-          scope: "offeringscheckout",
-          charges: [charge],
-          windowMs: 60_000,
-          now: Date.now(),
-          warn: (obj, msg) => request.log.warn(obj, msg),
-        });
-      } catch (err) {
-        // A budget store that throws is a store failure, and the Offerings
-        // path's contract for one is 502 checkout-unavailable (code review on
-        // PR #9032) — never Fastify's 500.
-        request.log.error(
-          {
-            method: request.method,
-            path: request.url,
-            outcome: "offerings_budget_failed",
-            errName: err instanceof Error ? err.name : "unknown",
-          },
-          "[checkout] budget read failed; checkout-unavailable",
-        );
-        return reply.status(502).send({ error: "checkout-unavailable" });
-      }
-      if (!budget.ok) {
-        return reply
-          .header("Retry-After", String(budget.retryAfterSeconds))
-          .status(429)
-          .send({
-            error: "rate_limited",
-            retryAfterSeconds: budget.retryAfterSeconds,
-          });
-      }
-    }
-  }
-
-  const parsed = CheckoutSessionRequestSchema.safeParse(request.body);
-  if (!parsed.success) {
-    return reply.status(400).send({
-      error: "validation-error",
-      details: parsed.error.issues,
-    });
-  }
-
-  const { productCode, successUrl, cancelUrl, quantity, allowPromotionCodes } =
-    parsed.data;
-
-  // ── Same-origin redirect lock (#6877) — before any Stripe or DB call ──────
-  if (authVerdict === "open") {
-    // An empty list is FRONTEND_URL unset in production or unusable, with no
-    // AILK_TRUSTED_ORIGINS (#7395 D4) — refused before any Stripe or DB call.
-    const trustedOrigins = config.TRUSTED_ORIGINS;
-    if (trustedOrigins.length === 0) {
-      request.log.error(
-        { method: request.method, path: request.url },
-        "[checkout] no trusted browser origin is configured",
-      );
-      return reply.status(500).send({ error: "config-error" });
-    }
-    const refused = (["successUrl", "cancelUrl"] as const).filter(
-      (field) =>
-        !trustedOrigins.some((origin) =>
-          isSameOriginRedirect(parsed.data[field], origin),
-        ),
-    );
-    if (refused.length > 0) {
-      // Field names only — the refused URL is never logged or echoed.
-      request.log.warn(
-        {
-          method: request.method,
-          path: request.url,
-          outcome: "redirect_origin_refused",
-          fields: refused,
-        },
-        "[checkout] redirect origin refused",
-      );
-      return reply.status(400).send({
-        error: "validation-error",
-        details: refused.map((field) => ({
-          code: "custom",
-          path: [field],
-          message: `${field} must be on this site's origin`,
-        })),
-      });
-    }
-  }
-
-  let created: CreateCheckoutSessionOutput;
-  let buyer: Buyer | undefined;
-  let identity: IdentityReason | undefined;
-
-  if (checkoutPath.kind === "offerings") {
-    // Anonymous by construction (#8931 C4): no buyer is resolved, and the
-    // session always allows promotion codes (A7, C3).
-    const outcome = await startOfferingsCheckout({
-      workspaceId: checkoutPath.workspaceId,
-      organizationId: checkoutPath.organizationId,
-      productCode,
-      successUrl,
-      cancelUrl,
-      quantity: quantity ?? 1,
-    });
-    if (outcome.kind === "unknown") {
-      // The one 404 every miss answers — never the key (A3, A5).
-      return reply.status(404).send({ error: "unknown-product-code" });
-    }
-    if (outcome.kind === "unavailable") {
-      return reply.status(502).send({ error: "checkout-unavailable" });
-    }
-    created = outcome;
-  } else {
-    const sessionInput: CreateCheckoutSessionInput = {
-      productCode,
-      successUrl,
-      cancelUrl,
-      quantity: quantity ?? 1,
-      // Omitted when the caller says nothing — Stripe's default (no promo-code
-      // field) is unchanged for every existing caller.
-      ...(allowPromotionCodes !== undefined && { allowPromotionCodes }),
-      metadata: siteStamp(),
-    };
-    // The env path never sells an Offerings product (#8931 A9, D8): the one
-    // marker rule decides it, on the first try and the anonymous retry.
-    const envOptions = { refuseProduct: isOfferingsProduct };
-    // Built only from the session cookie — never from `parsed.data` (#6866 D5).
-    ({ buyer, identity } = await resolveBuyer(request));
-
-    try {
-      try {
-        created = await createCheckoutSession(
-          {
-            ...sessionInput,
-            ...(buyer !== undefined && { buyer }),
-          },
-          envOptions,
-        );
-      } catch (err) {
-        // The buyer itself cannot be used — a pinned customer Stripe does not
-        // know (#6866 D8), or a stored email / customer id the library's schema
-        // refuses (F7: no new failure mode). Retry once as anonymous; the
-        // stored binding is never touched here. The request fields already
-        // passed the route's schema, so an anonymous retry that still fails
-        // maps exactly as today.
-        const reason: IdentityReason | undefined =
-          err instanceof UnknownCustomerError
-            ? "stale_customer"
-            : err instanceof Error && err.name === "ZodError"
-              ? "buyer_invalid"
-              : undefined;
-        if (buyer === undefined || reason === undefined) throw err;
-        buyer = undefined;
-        identity = reason;
-        created = await createCheckoutSession(sessionInput, envOptions);
-      }
-    } catch (err) {
-      if (err instanceof UnknownProductCodeError) {
-        // 404 — do NOT echo productCode in the response body
-        return reply.status(404).send({ error: "unknown-product-code" });
-      }
-      if (err instanceof StripeConfigError) {
-        // 500 — misconfiguration; log message (no PII) but never echo in response
-        request.log.error(
-          {
-            method: request.method,
-            path: request.url,
-            errName: err.name,
-            message: err.message,
-          },
-          "[checkout] config error",
-        );
-        return reply.status(500).send({ error: "config-error" });
-      }
-      request.log.error(
-        {
-          method: request.method,
-          path: request.url,
-          errName: err instanceof Error ? err.name : "unknown",
-        },
-        "[checkout] stripe error; checkout-unavailable",
-      );
-      return reply.status(502).send({ error: "checkout-unavailable" });
-    }
-  }
-
-  const { sessionId, url } = created;
-
-  request.log.info(
-    {
-      method: request.method,
-      path: request.url,
-      sessionIdPrefix: sessionId.substring(0, 8),
-      status: 201,
-      buyer: buyer !== undefined ? "signed_in" : "anonymous",
-      ...(identity !== undefined && { identity }),
-      ...(checkoutPath.kind === "offerings" && {
-        checkout: "offerings",
-        workspaceId: checkoutPath.workspaceId,
-      }),
-    },
-    "[checkout] session created",
-  );
-
-  return reply.status(201).send({ sessionId, url });
-}