create-ailk 0.24.0 → 0.26.0

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

@@ -1,332 +0,0 @@
-// 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
- *      (only an Offerings `plan` Product sells — `refuseProduct`, #9338 DD4;
- *      a refused or unexpanded Product is `plan_price_missing`)
- *   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";
-import { isOfferingsPlanProduct } from "../../services/offerings/catalog.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 — only a Price whose Product is an Offerings `plan` (#9338
-  // DD4), checked by stripe-client on the same expanded Price it sells.
-  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,
-      },
-      { refuseProduct: (product) => !isOfferingsPlanProduct(product) },
-    );
-  } 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

@@ -1,178 +0,0 @@
-/**
- * @file live-key.test.ts
- *
- * The hub checkout with a live key (#8450 AC 1, AC 2): `POST
- * /v1/checkout/sessions` and the return page's `GET
- * /v1/checkout/sessions/:id`. Unlike `sessions.test.ts` and
- * `session.test.ts`, BOTH guards here are real: `lib/stripe.ts` runs as
- * itself (only the two Stripe calls are mocked, so nothing leaves the
- * process), and `@working-theory/stripe-client` runs as itself with
- * `assertSandboxKey` wrapped in a spy, so the test can see whether a route
- * still calls the sandbox-only guard.
- *
- * The process admits a restricted live key once, in `beforeAll`, exactly as
- * `build()` does at boot. Every live-shaped key is composed at runtime from
- * fragments — never a literal (architecture.yaml's live-key pattern).
- */
-import type { FastifyInstance } from "fastify";
-
-const mockCreateCheckoutSession = jest.fn();
-const mockRetrieveCheckoutSession = jest.fn();
-
-jest.mock("@working-theory/stripe-client", () => {
-  const actual = jest.requireActual("@working-theory/stripe-client");
-  return { ...actual, assertSandboxKey: jest.fn(actual.assertSandboxKey) };
-});
-
-// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
-jest.mock("../../../lib/stripe.js", () => ({
-  ...jest.requireActual("../../../lib/stripe.js"),
-  createCheckoutSession: (...args: unknown[]) => mockCreateCheckoutSession(...args),
-  retrieveCheckoutSession: (...args: unknown[]) => mockRetrieveCheckoutSession(...args),
-}));
-
-// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted; the DB boundary, mirrors sessions.test.ts
-jest.mock("../../../lib/prisma.js", () => ({
-  prisma: {
-    session: { findUnique: jest.fn() },
-    user: { findUnique: jest.fn() },
-    apiToken: { findUnique: jest.fn(), update: jest.fn() },
-  },
-}));
-
-// #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";
-import { admitApiStripeKey, stripeKeyMode } from "../../../lib/stripe.js";
-import { __resetBuckets } from "../../../middleware/rate-limit.js";
-import { checkoutRoutes } from "../index";
-
-config.FRONTEND_URL = "https://example.com";
-config.TRUSTED_ORIGINS = ["https://example.com"];
-
-const TAIL = "FixtureOnlyCheckout";
-const restrictedLiveKey = ["rk", "live", ""].join("_") + TAIL;
-const secretLiveKey = ["sk", "live", ""].join("_") + TAIL;
-const publishableLiveKey = ["pk", "live", ""].join("_") + TAIL;
-
-const sandboxSpy = assertSandboxKey as jest.MockedFunction<typeof assertSandboxKey>;
-
-const ENV_KEYS = ["STRIPE_SECRET_KEY", "STRIPE_MODE", "VERCEL_ENV", "OSS_API_INTERNAL_SECRET"] as const;
-const savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
-
-const VALID_BODY = {
-  productCode: "ailk-pro",
-  successUrl: "https://example.com/success",
-  cancelUrl: "https://example.com/cancel",
-};
-
-const SESSION_ID = "cs_live_fixture12345";
-
-function buildApp(): FastifyInstance {
-  const fastify = require("fastify")({ logger: false });
-  fastify.register(checkoutRoutes);
-  return fastify;
-}
-
-describe("the hub checkout — an admitted live key (#8450)", () => {
-  let app: FastifyInstance;
-
-  beforeAll(() => {
-    delete process.env["OSS_API_INTERNAL_SECRET"];
-    process.env["STRIPE_SECRET_KEY"] = restrictedLiveKey;
-    process.env["STRIPE_MODE"] = "live";
-    process.env["VERCEL_ENV"] = "production";
-    expect(admitApiStripeKey()).toBe("live");
-    expect(stripeKeyMode()).toBe("live");
-  });
-
-  afterAll(() => {
-    for (const k of ENV_KEYS) {
-      if (savedEnv[k] === undefined) delete process.env[k];
-      else process.env[k] = savedEnv[k];
-    }
-  });
-
-  beforeEach(async () => {
-    jest.clearAllMocks();
-    __resetBuckets();
-    process.env["STRIPE_SECRET_KEY"] = restrictedLiveKey;
-    mockCreateCheckoutSession.mockResolvedValue({
-      sessionId: "cs_live_fixture12345",
-      url: "https://checkout.stripe.com/c/pay/fixture",
-    });
-    mockRetrieveCheckoutSession.mockResolvedValue({
-      id: SESSION_ID,
-      status: "complete",
-      paymentStatus: "paid",
-      currency: "usd",
-      amountTotal: 4800,
-      lineItems: [],
-    });
-    app = buildApp();
-    await app.ready();
-  });
-
-  afterEach(async () => {
-    await app.close();
-  });
-
-  describe("POST /v1/checkout/sessions", () => {
-    it("gets past the key check on the restricted live key, without the sandbox-only guard", async () => {
-      const res = await app.inject({ method: "POST", url: "/v1/checkout/sessions", payload: VALID_BODY });
-
-      expect(res.statusCode).toBe(201);
-      expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(1);
-      expect(sandboxSpy).not.toHaveBeenCalled();
-    });
-
-    it.each([
-      ["an unrestricted live key", secretLiveKey],
-      ["a publishable live key", publishableLiveKey],
-    ])("still refuses %s with 500 live-mode-forbidden and no Stripe call", async (_label, key) => {
-      process.env["STRIPE_SECRET_KEY"] = key;
-
-      const res = await app.inject({ method: "POST", url: "/v1/checkout/sessions", payload: VALID_BODY });
-
-      expect(res.statusCode).toBe(500);
-      expect(res.json()).toEqual({ error: "live-mode-forbidden" });
-      expect(res.body).not.toContain(TAIL);
-      expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("GET /v1/checkout/sessions/:id", () => {
-    it("gets past the key check on the restricted live key, without the sandbox-only guard", async () => {
-      const res = await app.inject({ method: "GET", url: `/v1/checkout/sessions/${SESSION_ID}` });
-
-      expect(res.statusCode).toBe(200);
-      expect(mockRetrieveCheckoutSession).toHaveBeenCalledTimes(1);
-      expect(sandboxSpy).not.toHaveBeenCalled();
-    });
-
-    it.each([
-      ["an unrestricted live key", secretLiveKey],
-      ["a publishable live key", publishableLiveKey],
-    ])("still refuses %s with 500 live-mode-forbidden and no Stripe call", async (_label, key) => {
-      process.env["STRIPE_SECRET_KEY"] = key;
-
-      const res = await app.inject({ method: "GET", url: `/v1/checkout/sessions/${SESSION_ID}` });
-
-      expect(res.statusCode).toBe(500);
-      expect(res.json()).toEqual({ error: "live-mode-forbidden" });
-      expect(res.body).not.toContain(TAIL);
-      expect(mockRetrieveCheckoutSession).not.toHaveBeenCalled();
-    });
-  });
-});