create-ailk 0.22.0 → 0.23.0

package/templates/apps/api/src/routes/billing/plan-checkout.ts

@@ -0,0 +1,325 @@
+// oss: false
+/**
+ * POST /v1/billing/plan-checkout
+ *
+ * The Billing tab's Purchase plan (#9067 D3, D13; spec
+ * `docs/specs/9067-the-billing-tab-s-plan-spec.md`): starts a subscription
+ * Stripe Checkout for the caller's OWN Organization's plan, on the
+ * deployment's Stripe account, sandbox-only like the Organization portal.
+ * The Organization is ALWAYS `request.tenant.organizationId`. The session
+ * creates its own customer (no `buyer`, no `customerId`, so no
+ * `ailk_user_id`), and the webhook binds that customer to the Organization
+ * only because this route recorded the session's id (D13).
+ *
+ * Check order — each step refuses `{ ok: false, error: { code, message } }`
+ * or passes to the next, so a refusal answers before the work it guards:
+ *
+ *   1. tenant                     401 unauthorized
+ *   2. `billing-manage`           403 forbidden — before any lookup or budget
+ *   3. write budget               429 rate_limited (10/h per Organization and per person)
+ *   4. commerce claim             409 purchase_unavailable · 503 license_undetermined
+ *   5. body                       400 validation_failed
+ *   6. return URL                 400 return_url_refused · 500 config-error
+ *   7. no customer; a plan tier   409 billing_customer_exists · 409 plan_not_purchasable
+ *   8. Stripe key                 500 stripe-not-configured · 500 live-mode-forbidden
+ *   7b. one payable session       409 purchase_pending · 502 checkout-unavailable
+ *   9. create                     500 plan_price_missing · 500 config-error · 502 checkout-unavailable
+ *   10. a Checkout URL            502 checkout-unavailable (the session expired)
+ *   9b. record (compare-and-set)  409 purchase_pending · 502 (the new session expired)
+ *
+ * PII/secret-min: no response body or log line carries the return URL, an
+ * Organization or Stripe id, or a Stripe error message — errors are logged
+ * by `name` only.
+ *
+ * MCP parity: owner-only purchase, and `billing-manage` is never
+ * agent-grantable, so no twin could succeed. Recorded in
+ * `tests/parity/README.md` § Routes with no tool, by decision.
+ */
+import {
+  can,
+  planCheckoutRequestSchema,
+  planCheckoutResponseSchema,
+  planPurchaseLookupKey,
+} from "@working-theory/validation";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+
+import { config } from "../../config/index.js";
+import {
+  LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS,
+  resolveCommerceClaim,
+} from "../../lib/require-commerce-claim.js";
+import { siteStamp } from "../../lib/site.js";
+import {
+  assertSandboxKey,
+  CheckoutModeMismatchError,
+  createCheckoutSession,
+  expireCheckoutSession,
+  PLATFORM_TERMS_OF_SERVICE,
+  retrieveCheckoutSession,
+  StripeConfigError,
+  UnknownProductCodeError,
+  UnknownSessionError,
+} from "../../lib/stripe.js";
+import { chargeWriteBudget } from "../../middleware/rate-limit.js";
+import {
+  bindOrgPlanCheckout,
+  getOrgBillingIdentity,
+  readOrgPlanCheckoutSession,
+  resolveEntitlements,
+  setOrgPlanCheckoutSession,
+} from "../../services/entitlements.js";
+
+/** Route-level body bound (D3 step 5). */
+const BODY_LIMIT = 4096;
+const WRITE_BUDGET_SCOPE = "plancheckout";
+const WRITE_BUDGET_WINDOW_MS = 60 * 60 * 1000;
+const PLAN_CHECKOUTS_PER_HOUR = 10;
+/** The quantity range the buyer picks on Checkout (sites). */
+const SITES_MIN = 1;
+const SITES_MAX = 50;
+const NO_STORE = "private, no-store";
+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1"]);
+
+function refuse(reply: FastifyReply, status: number, code: string, message: string) {
+  return reply.status(status).send({ ok: false, error: { code, message } });
+}
+
+function checkoutUnavailable(reply: FastifyReply) {
+  return refuse(reply, 502, "checkout-unavailable", "The purchase is temporarily unavailable");
+}
+
+/**
+ * D3 step 6 — a return URL the Admin may hand Stripe: canonical (its own
+ * parse's `href`, which refuses CR, LF, tab, backslash and every other
+ * re-spelling), no userinfo, query or fragment (the Admin sends none, and a
+ * `{CHECKOUT_SESSION_ID}` template would leak the session id), no `//` path,
+ * `https:` (or `http:` on a local host), on a trusted origin.
+ */
+function isAcceptableReturnUrl(value: string, trusted: readonly string[]): boolean {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.href !== value) return false;
+  if (url.username !== "" || url.password !== "" || url.hash !== "" || value.includes("#")) {
+    return false;
+  }
+  if (url.search !== "" || value.includes("?") || url.pathname.startsWith("//")) return false;
+  const secure =
+    url.protocol === "https:" || (url.protocol === "http:" && LOCAL_HOSTNAMES.has(url.hostname));
+  return secure && trusted.includes(url.origin);
+}
+
+/** Expire a session this route opened and will not hand out; a failure is logged by name. */
+async function expireQuietly(request: FastifyRequest, sessionId: string): Promise<void> {
+  try {
+    await expireCheckoutSession(sessionId);
+  } catch (err) {
+    request.log.error(
+      { errName: err instanceof Error ? err.name : "unknown" },
+      "[billing] plan checkout expire failed",
+    );
+  }
+}
+
+export async function planCheckoutHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  // 1. Tenant — the preHandler denies an unresolvable tenant first.
+  const tenant = request.tenant;
+  if (!tenant) return refuse(reply, 401, "unauthorized", "Authentication required");
+
+  // 2. Permission — before any lookup, budget or body read.
+  if (!can(tenant.role, "billing-manage")) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[billing] plan checkout denied; insufficient role",
+    );
+    return refuse(reply, 403, "forbidden", "Forbidden");
+  }
+
+  // 3. Write budget — every request that got this far is counted.
+  const budget = await chargeWriteBudget({
+    scope: WRITE_BUDGET_SCOPE,
+    windowMs: WRITE_BUDGET_WINDOW_MS,
+    now: Date.now(),
+    charges: [
+      { key: `org,${tenant.organizationId}`, limit: PLAN_CHECKOUTS_PER_HOUR },
+      { key: `user,${tenant.userId}`, limit: PLAN_CHECKOUTS_PER_HOUR },
+    ],
+    warn: (obj, msg) => request.log.warn(obj, msg),
+  });
+  if (!budget.ok) {
+    reply.header("Retry-After", String(budget.retryAfterSeconds));
+    return refuse(reply, 429, "rate_limited", "Too many purchase attempts; try again later");
+  }
+
+  // 4. Commerce claim — the webhook that binds the customer serves only with it.
+  const claim = await resolveCommerceClaim();
+  if (claim === "undetermined") {
+    reply.header("Retry-After", String(LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS));
+    return refuse(reply, 503, "license_undetermined", "The licence could not be read; try again later");
+  }
+  if (claim !== "claimed") {
+    return refuse(reply, 409, "purchase_unavailable", "Purchasing a plan is not available on this site");
+  }
+
+  // 5. Body.
+  const body = planCheckoutRequestSchema.safeParse(request.body);
+  if (!body.success) return refuse(reply, 400, "validation_failed", "Invalid request body");
+  const { returnUrl } = body.data;
+
+  // 6. Return URL — never logged.
+  if (config.TRUSTED_ORIGINS.length === 0) {
+    request.log.error({ outcome: "no_trusted_origins" }, "[billing] plan checkout misconfigured");
+    return refuse(reply, 500, "config-error", "The purchase is misconfigured");
+  }
+  if (!isAcceptableReturnUrl(returnUrl, config.TRUSTED_ORIGINS)) {
+    return refuse(reply, 400, "return_url_refused", "The return address is not allowed");
+  }
+
+  // 7. Not already a customer; a purchasable tier.
+  const [identity, entitlements] = await Promise.all([
+    getOrgBillingIdentity(tenant.organizationId),
+    resolveEntitlements(tenant.organizationId),
+  ]);
+  if (identity.billingCustomerId != null) {
+    return refuse(reply, 409, "billing_customer_exists", "This organization already has a plan");
+  }
+  const productCode = planPurchaseLookupKey(entitlements.limits.static.tier);
+  if (productCode === null) {
+    return refuse(reply, 409, "plan_not_purchasable", "This plan cannot be purchased here");
+  }
+
+  // 8. Stripe key — sandbox-only, as the Organization portal.
+  const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
+  if (!stripeSecretKey) {
+    return refuse(reply, 500, "stripe-not-configured", "Stripe is not configured");
+  }
+  try {
+    assertSandboxKey(stripeSecretKey);
+  } catch {
+    return refuse(reply, 500, "live-mode-forbidden", "Live Stripe keys are not permitted");
+  }
+
+  // 7b. One payable session at a time (D13).
+  const earlier = await readOrgPlanCheckoutSession(tenant.organizationId);
+  if (earlier !== null) {
+    let status: Awaited<ReturnType<typeof retrieveCheckoutSession>>["status"] | null;
+    let customer: string | null = null;
+    try {
+      const retrieved = await retrieveCheckoutSession({ sessionId: earlier });
+      status = retrieved.status;
+      customer = retrieved.customer;
+    } catch (err) {
+      if (!(err instanceof UnknownSessionError)) {
+        request.log.error(
+          { errName: err instanceof Error ? err.name : "unknown" },
+          "[billing] plan checkout read failed",
+        );
+        return checkoutUnavailable(reply);
+      }
+      status = null;
+    }
+    if (status === "complete") {
+      // The webhook's bind never landed (a lost event, a swallowed database
+      // error). A completed session carries its customer, so bind from it
+      // here, under the same guard the webhook uses; a bound Organization
+      // then reads exactly as step 7 reads one. Only a session with no
+      // customer yet stays pending.
+      if (customer !== null) {
+        let bound: boolean;
+        try {
+          bound = await bindOrgPlanCheckout(tenant.organizationId, earlier, customer);
+        } catch (err) {
+          request.log.error(
+            { errName: err instanceof Error ? err.name : "unknown" },
+            "[billing] plan checkout bind failed",
+          );
+          return checkoutUnavailable(reply);
+        }
+        if (bound) {
+          request.log.info({ outcome: "org_bound_from_completed_session" }, "[billing] plan checkout bound");
+          return refuse(reply, 409, "billing_customer_exists", "This organization already has a plan");
+        }
+      }
+      return refuse(reply, 409, "purchase_pending", "A purchase is already being confirmed");
+    }
+    if (status === "open") {
+      try {
+        await expireCheckoutSession(earlier);
+      } catch (err) {
+        request.log.error(
+          { errName: err instanceof Error ? err.name : "unknown" },
+          "[billing] plan checkout expire failed",
+        );
+        return checkoutUnavailable(reply);
+      }
+    }
+  }
+
+  // 9. Start.
+  const stamp = { organizationId: tenant.organizationId, ...siteStamp() };
+  let created: { sessionId: string; url: string };
+  try {
+    created = await createCheckoutSession({
+      productCode,
+      successUrl: returnUrl,
+      cancelUrl: returnUrl,
+      mode: "subscription",
+      adjustableQuantity: { enabled: true, minimum: SITES_MIN, maximum: SITES_MAX },
+      metadata: stamp,
+      subscriptionMetadata: { ...stamp },
+      termsOfService: PLATFORM_TERMS_OF_SERVICE,
+    });
+  } catch (err) {
+    const errName = err instanceof Error ? err.name : "unknown";
+    request.log.error({ errName }, "[billing] plan checkout create failed");
+    if (err instanceof UnknownProductCodeError || err instanceof CheckoutModeMismatchError) {
+      return refuse(reply, 500, "plan_price_missing", "The plan's price is not set up");
+    }
+    if (err instanceof StripeConfigError) {
+      return refuse(reply, 500, "config-error", "The purchase is misconfigured");
+    }
+    return checkoutUnavailable(reply);
+  }
+
+  // 10. A Checkout URL only — anything else is never handed out.
+  const answer = planCheckoutResponseSchema.safeParse({ url: created.url });
+  if (!answer.success) {
+    request.log.error({ outcome: "not_checkout_url" }, "[billing] plan checkout answer refused");
+    await expireQuietly(request, created.sessionId);
+    return checkoutUnavailable(reply);
+  }
+
+  // 9b. Record it — no payable session is left unrecorded.
+  let recorded: boolean;
+  try {
+    recorded = await setOrgPlanCheckoutSession(tenant.organizationId, earlier, created.sessionId);
+  } catch (err) {
+    request.log.error(
+      { errName: err instanceof Error ? err.name : "unknown" },
+      "[billing] plan checkout record failed",
+    );
+    await expireQuietly(request, created.sessionId);
+    return checkoutUnavailable(reply);
+  }
+  if (!recorded) {
+    await expireQuietly(request, created.sessionId);
+    return refuse(reply, 409, "purchase_pending", "A purchase is already being confirmed");
+  }
+
+  request.log.info(
+    { method: request.method, path: request.url, status: 200 },
+    "[billing] plan checkout created",
+  );
+  return reply.status(200).header("Cache-Control", NO_STORE).send({ ok: true, data: answer.data });
+}
+
+/** Registers the route beside the billing routes, in the same tenant scope (D3). */
+export function registerPlanCheckoutRoute(fastify: FastifyInstance): void {
+  fastify.post("/v1/billing/plan-checkout", { bodyLimit: BODY_LIMIT }, planCheckoutHandler);
+}

package/templates/apps/api/src/routes/checkout/__tests__/live-key.test.ts

@@ -40,6 +40,17 @@ jest.mock("../../../lib/prisma.js", () => ({
   },
 }));
 
+// #8931 — the route now asks the Offerings service which path a request
+// takes before the env checks; every case in this suite is an env-path case,
+// so the service answers `env` for both the POST and the GET.
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../services/offerings/checkout-authorization.js", () => ({
+  resolveOfferingsCheckoutPath: jest.fn(async () => ({ kind: "env" })),
+  readOfferingsCheckoutSession: jest.fn(async () => ({ kind: "env" })),
+  startOfferingsCheckout: jest.fn(),
+  OFFERINGS_CHECKOUT_PER_WORKSPACE_PER_MINUTE: 60,
+}));
+
 import { assertSandboxKey } from "@working-theory/stripe-client";
 
 import { config } from "../../../config/index.js";