create-ailk 0.5.0 → 0.6.0

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

@@ -0,0 +1,34 @@
+/**
+ * Checkout route group.
+ *
+ * Routes:
+ *   POST /v1/checkout/sessions     — create a Stripe hosted-page checkout session
+ *   GET  /v1/checkout/sessions/:id — read a session's payment status + line items (#6084)
+ *
+ * The GET registers inside a NESTED scope carrying its own rate limiter
+ * (D16) — the same composition idiom the sibling `requests` scope uses
+ * (`server.ts`'s `requestsScope`). Nesting keeps the POST above
+ * byte-identical: the limiter applies only to routes registered on
+ * `readScope`. Both routes inherit `requireCommerceClaim` from the OUTER
+ * `checkoutScope` in `server.ts` — no gate code is written in either file.
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import {
+  DEFAULT_PER_IP_PER_MINUTE_STRICT,
+  rateLimitMiddleware,
+} from "../../middleware/rate-limit.js";
+
+import { checkoutSessionReadHandler } from "./session.js";
+import { checkoutSessionsHandler } from "./sessions.js";
+
+export const checkoutRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/checkout/sessions", checkoutSessionsHandler);
+
+  await fastify.register(async (readScope) => {
+    await readScope.register(rateLimitMiddleware, {
+      perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
+    });
+    readScope.get("/v1/checkout/sessions/:id", checkoutSessionReadHandler);
+  });
+};

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

@@ -0,0 +1,139 @@
+/**
+ * GET /v1/checkout/sessions/:id
+ *
+ * Reads a Checkout Session's payment status + paid line items — a READ,
+ * never a write (the webhook already granted; #6084 spec §1.2). Registered
+ * inside `checkoutRoutes` (`index.ts`), which inherits the SAME
+ * `requireCommerceClaim` scope preHandler `sessions.ts`'s POST does — no
+ * gate code is written here (spec §1.4, D8 layer 3).
+ *
+ * Security invariants (spec D8):
+ *   - `:id` shape-gated BEFORE any Stripe call — a non-matching id answers
+ *     400 with zero SDK invocations, so this route is not a free Stripe-API
+ *     proxy.
+ *   - PII-free response: an explicit six-key allow-list (D3) — never a
+ *     spread of the retrieve's projection.
+ *   - The id is never echoed in an error body, and only the first 8
+ *     characters ever reach a log line — mirroring `sessions.ts`'s own
+ *     stated invariant.
+ *   - `Cache-Control: no-store`, `X-Robots-Tag: noindex, nofollow`,
+ *     `Referrer-Policy: no-referrer` on the 200 — the same three headers
+ *     `routes/requests/confirm.ts` sets on its own unauthenticated,
+ *     token-bearing response (D3, AC-9).
+ *   - Deliberately NOT gated by `X-Internal-Auth` (D8 layer 4 — withdrawn;
+ *     no `apps/web` file holds `OSS_API_INTERNAL_SECRET`).
+ *
+ * Error mapping mirrors `sessions.ts`'s own vocabulary (D3):
+ *   400 validation-error      — `:id` fails the shape check
+ *   404 unknown-session       — Stripe raised `resource_missing`
+ *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty
+ *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key
+ *   500 config-error          — STRIPE_SECRET_KEY invalid configuration
+ *   502 checkout-unavailable  — Stripe SDK threw an unexpected error
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  assertSandboxKey,
+  retrieveCheckoutSession,
+  StripeConfigError,
+  UnknownSessionError,
+} from "../../lib/stripe.js";
+
+// A Stripe Checkout Session id is an unguessable bearer capability, not an
+// authorization-checked resource (D8). The shape gate is layer 2 of D8's
+// defense: it runs BEFORE any Stripe call, so a non-matching id can never
+// spend a Stripe API call. Exported so the test suite can assert the upper
+// bound directly — an id over Fastify's OWN `maxParamLength` (default 100,
+// unconfigured here) never reaches this schema at all, and the test suite
+// covers that layer separately.
+export const SESSION_ID_PATTERN = /^cs_[A-Za-z0-9_]{1,250}$/;
+
+const CheckoutSessionParamsSchema = z.object({
+  id: z
+    .string()
+    .regex(SESSION_ID_PATTERN, "id must match /^cs_[A-Za-z0-9_]{1,250}$/"),
+});
+
+/** D3's response headers — the unauthenticated-bearer-credential precedent (`confirm.ts:41-43`). */
+function setPrivateResponseHeaders(reply: FastifyReply): void {
+  reply.header("Cache-Control", "no-store");
+  reply.header("X-Robots-Tag", "noindex, nofollow");
+  reply.header("Referrer-Policy", "no-referrer");
+}
+
+export async function checkoutSessionReadHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const parsed = CheckoutSessionParamsSchema.safeParse(request.params);
+  if (!parsed.success) {
+    return reply.status(400).send({
+      error: "validation-error",
+      details: parsed.error.issues,
+    });
+  }
+
+  const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
+  if (!stripeSecretKey) {
+    return reply.status(500).send({ error: "stripe-not-configured" });
+  }
+  try {
+    assertSandboxKey(stripeSecretKey);
+  } catch {
+    return reply.status(500).send({ error: "live-mode-forbidden" });
+  }
+
+  const { id } = parsed.data;
+
+  try {
+    const session = await retrieveCheckoutSession({ sessionId: id });
+
+    request.log.info(
+      {
+        method: request.method,
+        sessionIdPrefix: id.substring(0, 8),
+        status: 200,
+      },
+      "[checkout] session read",
+    );
+
+    setPrivateResponseHeaders(reply);
+    // The D3 allow-list, named field-for-field — never a spread. Nothing
+    // else may join this object (AC-3's set-equality test pins exactly
+    // these six keys).
+    return reply.status(200).send({
+      id: session.id,
+      status: session.status,
+      paymentStatus: session.paymentStatus,
+      currency: session.currency,
+      amountTotal: session.amountTotal,
+      lineItems: session.lineItems,
+    });
+  } catch (err) {
+    if (err instanceof UnknownSessionError) {
+      // 404 — never echo the id in the response body.
+      return reply.status(404).send({ error: "unknown-session" });
+    }
+    if (err instanceof StripeConfigError) {
+      request.log.error(
+        {
+          method: request.method,
+          errName: err.name,
+          message: err.message,
+        },
+        "[checkout] config error",
+      );
+      return reply.status(500).send({ error: "config-error" });
+    }
+    request.log.error(
+      {
+        method: request.method,
+        errName: err instanceof Error ? err.name : "unknown",
+      },
+      "[checkout] stripe error; checkout-unavailable",
+    );
+    return reply.status(502).send({ error: "checkout-unavailable" });
+  }
+}

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

@@ -0,0 +1,197 @@
+/**
+ * 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:
+ *   - Sandbox-only: live Stripe keys are rejected at runtime 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 appear in log lines.
+ *   - Error responses never echo user input (productCode, URLs).
+ *   - No DB write: this unit creates a Stripe session only; webhook-driven
+ *     persistence is a follow-up issue.
+ *   - 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.
+ *
+ * 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)
+ *   404 unknown-product-code  — no active Stripe price for the given productCode
+ *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty (no Stripe call)
+ *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key
+ *   500 config-error          — STRIPE_SECRET_KEY invalid configuration (from the SDK wrapper)
+ *   502 checkout-unavailable  — Stripe SDK threw an unexpected error
+ */
+import { timingSafeEqual } from "node:crypto";
+
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  assertSandboxKey,
+  createCheckoutSession,
+  StripeConfigError,
+  UnknownProductCodeError,
+} from "../../lib/stripe.js";
+
+// ── 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 ────────────────────────────────────────────────────────
+
+/**
+ * Enforce the X-Internal-Auth gate when OSS_API_INTERNAL_SECRET is configured.
+ *
+ * Gate is env-var-conditional:
+ *   - env var SET → header must be present and must match exactly
+ *   - env var UNSET → no gate applied (OSS standalone backward-compat)
+ *
+ * Returns true if the request should be allowed through; false if it must be
+ * rejected with 401.
+ *
+ * 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 passesInternalAuthGate(request: FastifyRequest): boolean {
+  const expectedSecret = process.env["OSS_API_INTERNAL_SECRET"];
+  // Gate is disabled when env var is not set — OSS standalone backward-compat.
+  if (!expectedSecret) return true;
+
+  const provided = request.headers["x-internal-auth"];
+  if (typeof provided !== "string" || !provided) return false;
+
+  // Constant-time comparison.
+  const expectedBuf = Buffer.from(expectedSecret, "utf8");
+  const providedBuf = Buffer.from(provided, "utf8");
+  if (expectedBuf.length !== providedBuf.length) return false;
+
+  return timingSafeEqual(expectedBuf, providedBuf);
+}
+
+// ── Handler ───────────────────────────────────────────────────────────────────
+
+export async function checkoutSessionsHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  // ── X-Internal-Auth gate (env-var-conditional) ────────────────────────────
+  if (!passesInternalAuthGate(request)) {
+    return reply.status(401).send({ error: "internal-auth-required" });
+  }
+
+  const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
+  if (!stripeSecretKey) {
+    return reply.status(500).send({ error: "stripe-not-configured" });
+  }
+  try {
+    assertSandboxKey(stripeSecretKey);
+  } catch {
+    return reply.status(500).send({ error: "live-mode-forbidden" });
+  }
+
+  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;
+
+  try {
+    const { sessionId, url } = await createCheckoutSession({
+      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 }),
+    });
+
+    request.log.info(
+      {
+        method: request.method,
+        path: request.url,
+        sessionIdPrefix: sessionId.substring(0, 8),
+        status: 201,
+      },
+      "[checkout] session created",
+    );
+
+    return reply.status(201).send({ sessionId, url });
+  } 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" });
+  }
+}