create-ailk 0.1.0 → 0.2.0

package/templates/.claude/skills/scaffold-commerce/templates/checkout-route.template.ts

@@ -0,0 +1,370 @@
+/**
+ * One-time checkout route — scaffolded by `scaffold-commerce`'s checkout
+ * surface (FEAT-023 U2, Step 10e). Instantiated into the consumer's own
+ * `apps/api/src/routes/checkout/` (Fastify — checkout creation is
+ * server-side only, architecture.yaml `apps/web.may_not_import_from:
+ * packages/stripe-client`). Register the exported handler on a POST route,
+ * scoped behind the shared per-IP rate-limit middleware (mirrors the "leads
+ * routes" anonymous-write registration pattern in `apps/api/src/server.ts`
+ * — this route is exactly that shape: an anonymous write with no auth):
+ *
+ *   await fastify.register(async (checkoutScope) => {
+ *     checkoutScope.register(rateLimitMiddleware); // apps/api/src/middleware/rate-limit.ts
+ *     checkoutScope.post("/api/checkout/one-time", oneTimeCheckoutHandler);
+ *   });
+ *
+ * ── SCAFFOLD-TIME EDITS REQUIRED (both — the route is fail-closed until then) ─
+ *   1. `ALLOWED_LOOKUP_KEYS` below — replace the placeholder with the
+ *      lookup_key(s) this surface may sell (Step 10e-i step 1's selection).
+ *      Until you do, EVERY request 404s. That is deliberate.
+ *   2. `FRONTEND_URL` in the consumer's API env — the site origin every
+ *      checkout redirect is locked to. Unset ⇒ this route 500s `config-error`.
+ *
+ * ── Auth posture — PUBLIC BY DESIGN, not an oversight ──────────────────────
+ * This handler is intentionally UNAUTHENTICATED. It is a storefront "buy"
+ * action, not a management endpoint — it does exactly ONE thing: create a
+ * NEW Stripe Checkout Session for ONE OF THE PRODUCTS THIS SURFACE WAS
+ * SCAFFOLDED TO SELL (`ALLOWED_LOOKUP_KEYS`, enforced server-side before any
+ * Stripe call; the caller can neither name an arbitrary price nor set an
+ * amount — the price is resolved server-side via
+ * `stripe.prices.list({lookup_keys})` inside `createCheckoutSession`).
+ * It has:
+ *   - NO list/read of existing sessions, products, or any other data,
+ *   - NO update/delete/archive of anything,
+ *   - NO local database read or write (stateless — the only side effect is
+ *     a new object created directly in the site owner's own Stripe account),
+ *   - NO cross-tenant surface (single-tenant `packages/stripe-client`
+ *     commerce catalog; the multi-tenant module's org-scoped billing is a
+ *     SEPARATE surface — `apps/workspace` may not import `stripe-client` at
+ *     all, architecture.yaml — so there is no tenant to scope this route to).
+ * A management surface (list/update/archive payment objects) is a DIFFERENT
+ * shape and MUST be authenticated + tenant-scoped — do not use this handler
+ * as a pattern for one.
+ *
+ * NOT a mirror of `apps/api/src/routes/checkout/sessions.ts`'s auth posture.
+ * That route carries an env-conditional `X-Internal-Auth` gate
+ * (`OSS_API_INTERNAL_SECRET`, #935); this one deliberately does not — it is
+ * public on purpose. If you have set `OSS_API_INTERNAL_SECRET` to lock
+ * `/v1/checkout/sessions` to internal callers, be aware that registering THIS
+ * route adds a second, ungated checkout entry point to the same API. Add your
+ * own gate here if that is not what you want.
+ *
+ * ── Abuse hardening ─────────────────────────────────────────────────────
+ * An unauthenticated session-creation endpoint is a known "card testing"
+ * target (repeated session-creation attempts against stolen card numbers).
+ * The registration example above wires the shared per-IP rate-limit
+ * middleware for exactly this reason — do not register this route without
+ * it. AILK's `apps/api/src/server.ts` also registers a GLOBAL rate limit, but
+ * it is IN-MEMORY: on a multi-instance or serverless deployment it does not
+ * bound the aggregate rate, so back it with a shared store (e.g. Redis) before
+ * taking real traffic. Input is otherwise tightly bounded: `lookupKey` must be
+ * in `ALLOWED_LOOKUP_KEYS`, `quantity` is clamped 1-999, and
+ * `successUrl`/`cancelUrl` are origin-locked to the site's own origin.
+ *
+ * Design decision (spec § 3): consumes `stripe-client/checkout.ts` directly
+ * — no new client method. One-time payment is `mode: "payment"` on the
+ * existing Checkout Session call (pinned here, never caller-overridable, so
+ * this endpoint can never be used to open a subscription session).
+ *
+ * Config: loads via the sibling `loadStripeSurfaceConfig()`
+ * (`stripe-config.template.ts`, instantiated alongside this file at Step
+ * 10d) rather than re-deriving env access — the SAME `assertSandboxKey`
+ * test-mode-only guard `getStripeClient()` already applies is enforced again
+ * here, belt-and-suspenders, before any Stripe call. This route deliberately
+ * does NOT hand-roll its own live-key prefix check — it defers ENTIRELY to
+ * the shared `assertSandboxKey` guard (`packages/stripe-client/src/client.ts`)
+ * so it inherits that guard's coverage (and any future fix to it) rather than
+ * risking a second, divergent implementation.
+ *
+ * Security invariants:
+ *   - Allowlisted products only: a `lookupKey` outside `ALLOWED_LOOKUP_KEYS` is
+ *     refused BEFORE any Stripe call, with the same response shape as a
+ *     genuinely-unknown price (so the 404 is not an enumeration oracle).
+ *   - Origin-locked redirects: `successUrl`/`cancelUrl` may only resolve to
+ *     this site's own origin. An attacker cannot mint a real Checkout Session
+ *     for this merchant that lands the paying victim on an attacker page.
+ *   - Sandbox-only: a live Stripe key is rejected before any Stripe call.
+ *   - No PII in logs: successUrl/cancelUrl and full session ids are never
+ *     logged — only the first 8 chars of the session id.
+ *   - Error responses never echo user input (lookupKey, URLs).
+ *
+ * Error mapping:
+ *   400 validation-error      — Zod validation failed (missing/invalid fields)
+ *   400 invalid-redirect-url  — successUrl/cancelUrl does not resolve same-origin
+ *   404 unknown-product-code  — lookupKey is not allowlisted for this surface,
+ *                               OR no active Stripe price exists for it (the
+ *                               404 deliberately does not distinguish the two)
+ *   429 rate_limited          — per-IP rate limit exceeded (see registration example above)
+ *   500 live-mode-forbidden   — the configured Stripe key is a LIVE key
+ *   500 config-error          — the Stripe/site env is missing or misconfigured
+ *   502 checkout-unavailable  — Stripe SDK threw an unexpected error
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import {
+  createCheckoutSession,
+  StripeConfigError,
+  UnknownProductCodeError,
+} from "@working-theory/stripe-client";
+
+// Sibling file instantiated at Step 10d — same directory as this route.
+import { loadStripeSurfaceConfig } from "./stripe-config.js";
+
+// ── Purchasable-product allowlist — SCAFFOLD-TIME EDIT ────────────────────────
+
+/**
+ * The ONLY lookup_keys this surface is allowed to sell.
+ *
+ * Without this allowlist the route resolves a caller-supplied `lookupKey`
+ * against the merchant's ENTIRE Stripe account — so ANY active price in it (a
+ * privately-negotiated discount, an internal comp price, a $0 test price)
+ * becomes publicly purchasable by an anonymous caller who guesses or
+ * enumerates its key. Pin the products, not the account.
+ *
+ * scaffold-commerce Step 10e-i replaces the placeholder below with the
+ * lookup_key(s) the consumer selected at step 1. Until it does, no request
+ * reaches Stripe — fail-closed.
+ */
+const ALLOWED_LOOKUP_KEYS: ReadonlySet<string> = new Set<string>([
+  "REPLACE_WITH_YOUR_STRIPE_LOOKUP_KEY",
+]);
+
+// ── Input validation schema ───────────────────────────────────────────────────
+
+const LOOKUP_KEY_REGEX = /^[A-Za-z0-9._-]{1,200}$/;
+
+/**
+ * Redirects are validated in TWO stages:
+ *   1. here — shape only (non-empty, bounded length), because the site origin
+ *      they must match is env-derived and so only known at request time;
+ *   2. `toSameOriginRedirect()` — the actual origin lock, applied after config
+ *      load. THAT is the security-bearing check; this schema is not.
+ */
+const REDIRECT_MAX_LENGTH = 2048;
+
+const OneTimeCheckoutRequestSchema = z.object({
+  lookupKey: z
+    .string()
+    .regex(LOOKUP_KEY_REGEX, "lookupKey must match /^[A-Za-z0-9._-]{1,200}$/"),
+  successUrl: z
+    .string()
+    .min(1, "successUrl is required")
+    .max(REDIRECT_MAX_LENGTH, "successUrl is too long"),
+  cancelUrl: z
+    .string()
+    .min(1, "cancelUrl is required")
+    .max(REDIRECT_MAX_LENGTH, "cancelUrl is too long"),
+  quantity: z.number().int().min(1).max(999).optional(),
+});
+
+// ── Internal helpers (not exported — this module's only export is the handler) ─
+
+/**
+ * The site's own origin — the ONLY origin a checkout redirect may resolve to.
+ *
+ * `FRONTEND_URL` is the env var the consumer's `apps/api` already uses for its
+ * CORS origin (`apps/api/src/config/index.ts`), reused here rather than
+ * inventing a second site-origin contract. Fail-closed: unset or unparseable ⇒
+ * `config-error`, never a permissive default.
+ */
+function loadSiteOrigin(): URL {
+  const raw = process.env.FRONTEND_URL;
+  if (!raw) {
+    throw new Error(
+      "FRONTEND_URL is missing. It is the site origin checkout redirects are locked to.",
+    );
+  }
+  try {
+    return new URL(raw);
+  } catch {
+    throw new Error("FRONTEND_URL is not a valid absolute URL.");
+  }
+}
+
+/**
+ * Resolve a caller-supplied redirect against the site's own origin. Returns the
+ * absolute same-origin URL, or `null` if the redirect lands ANYWHERE else.
+ *
+ * A relative path ("/checkout/success") is composed server-side onto the site
+ * origin — the recommended shape. An absolute URL is accepted only if it is
+ * exactly same-origin (scheme + host + port). Everything else — another host, a
+ * look-alike host, a non-http(s) scheme (`javascript:`, `data:`, …) — is `null`.
+ *
+ * Why this is security-bearing: without the origin lock, an anonymous caller
+ * can create a REAL Checkout Session for the REAL merchant whose `success_url`
+ * points at a site the attacker controls. The victim sees the merchant's real
+ * branding on Stripe's real domain, pays, and is redirected to the attacker —
+ * an open redirect laundered through a trusted payment page, carrying the
+ * credibility of a completed payment. `cancel_url` is the same vector without
+ * the victim even having to pay.
+ */
+function toSameOriginRedirect(raw: string, siteOrigin: URL): string | null {
+  let resolved: URL;
+  try {
+    resolved = new URL(raw, siteOrigin);
+  } catch {
+    return null;
+  }
+
+  if (resolved.protocol !== "https:" && resolved.protocol !== "http:") {
+    return null;
+  }
+  // Exact origin equality (scheme + host + port). A prefix/suffix comparison
+  // would accept `https://<site-origin>.evil.example`.
+  if (resolved.origin !== siteOrigin.origin) {
+    return null;
+  }
+
+  return resolved.toString();
+}
+
+// ── Handler ───────────────────────────────────────────────────────────────────
+
+/**
+ * POST handler — creates a test-mode ONE-TIME (`mode: "payment"`) Checkout
+ * Session for `lookupKey` and returns `{ sessionId, url }`. The caller (the
+ * scaffolded `CheckoutForm` block's `onCheckout`) redirects the browser to
+ * `url` on success.
+ *
+ * @public-by-design — a storefront "buy" action, intentionally
+ * UNAUTHENTICATED (see the file-header "Auth posture" note). It creates ONE
+ * allowlisted Checkout Session and reads/mutates nothing else; it is NOT a
+ * management surface. The per-handler marker (route-template-auth-gate,
+ * #3751) exempts THIS handler from the identity gate — the exemption is
+ * per-handler and reviewed, never a file-level blanket.
+ */
+export async function oneTimeCheckoutHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  // ── Config: fail-closed, with an EXPLICIT cause classification ────────────
+  //
+  // The two causes are classified DELIBERATELY, never inferred from whichever
+  // Error subclass the sibling config helper happens to throw:
+  //
+  //   (a) missing env     → `config-error`        — checked HERE, first.
+  //   (b) live Stripe key → `live-mode-forbidden` — with (a) ruled out, the
+  //       only thing `loadStripeSurfaceConfig()`'s `assertSandboxKey` can
+  //       reject, so a StripeConfigError at this point unambiguously means a
+  //       live key.
+  //
+  // Getting this backwards is not cosmetic: it makes the live-mode refusal
+  // signal dead code, and makes a mere missing-env fault cry "live mode
+  // forbidden" — training operators to ignore the one alarm that matters.
+  let siteOrigin: URL;
+  try {
+    if (!process.env.STRIPE_SECRET_KEY || !process.env.STRIPE_PUBLISHABLE_KEY) {
+      throw new Error(
+        "STRIPE_SECRET_KEY / STRIPE_PUBLISHABLE_KEY are missing. Run scaffold-commerce (direct payments path) first.",
+      );
+    }
+    siteOrigin = loadSiteOrigin();
+    loadStripeSurfaceConfig();
+  } catch (err) {
+    if (err instanceof StripeConfigError) {
+      // LIVE KEY — the sandbox-only hard floor. Log loudly: this IS the alarm.
+      request.log.error(
+        { method: request.method, path: request.url, message: err.message },
+        "[checkout] one-time: LIVE Stripe key REFUSED — live-mode-forbidden",
+      );
+      return reply.status(500).send({ error: "live-mode-forbidden" });
+    }
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        message: err instanceof Error ? err.message : "unknown",
+      },
+      "[checkout] one-time: config error",
+    );
+    return reply.status(500).send({ error: "config-error" });
+  }
+
+  const parsed = OneTimeCheckoutRequestSchema.safeParse(request.body);
+  if (!parsed.success) {
+    return reply.status(400).send({
+      error: "validation-error",
+      details: parsed.error.issues,
+    });
+  }
+
+  const { lookupKey, successUrl, cancelUrl, quantity } = parsed.data;
+
+  // ── Allowlist gate — BEFORE any Stripe call ───────────────────────────────
+  // Same response shape as a genuinely-unknown price (the 404 below), so this
+  // is not an oracle telling an attacker which lookup_keys exist in the
+  // merchant's Stripe account.
+  if (!ALLOWED_LOOKUP_KEYS.has(lookupKey)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 404 },
+      "[checkout] one-time: lookupKey is not in this surface's allowlist; refused",
+    );
+    return reply.status(404).send({ error: "unknown-product-code" });
+  }
+
+  // ── Redirect origin lock — BEFORE any Stripe call ─────────────────────────
+  const safeSuccessUrl = toSameOriginRedirect(successUrl, siteOrigin);
+  const safeCancelUrl = toSameOriginRedirect(cancelUrl, siteOrigin);
+  if (safeSuccessUrl === null || safeCancelUrl === null) {
+    // Do NOT echo the rejected URL back to the caller.
+    request.log.warn(
+      { method: request.method, path: request.url, status: 400 },
+      "[checkout] one-time: redirect URL is not same-origin; refused",
+    );
+    return reply.status(400).send({ error: "invalid-redirect-url" });
+  }
+
+  try {
+    // Pinned mode: "payment" — this endpoint can never open a subscription
+    // session, regardless of caller input (spec § 3 design decision).
+    const { sessionId, url } = await createCheckoutSession({
+      productCode: lookupKey,
+      successUrl: safeSuccessUrl,
+      cancelUrl: safeCancelUrl,
+      mode: "payment",
+      quantity: quantity ?? 1,
+    });
+
+    request.log.info(
+      {
+        method: request.method,
+        path: request.url,
+        sessionIdPrefix: sessionId.substring(0, 8),
+        status: 201,
+      },
+      "[checkout] one-time: session created",
+    );
+
+    return reply.status(201).send({ sessionId, url });
+  } catch (err) {
+    if (err instanceof UnknownProductCodeError) {
+      // 404 — do NOT echo lookupKey in the response body.
+      return reply.status(404).send({ error: "unknown-product-code" });
+    }
+    if (err instanceof StripeConfigError) {
+      // Config was already validated above, so this is a late/racing config
+      // fault raised inside `getStripeClient()` (which throws StripeConfigError
+      // for BOTH a missing and a live key — hence the generic mapping here; the
+      // authoritative live-key classification is the pre-flight block above).
+      request.log.error(
+        {
+          method: request.method,
+          path: request.url,
+          errName: err.name,
+          message: err.message,
+        },
+        "[checkout] one-time: 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] one-time: stripe error; checkout-unavailable",
+    );
+    return reply.status(502).send({ error: "checkout-unavailable" });
+  }
+}