create-ailk 0.21.0 → 0.23.0

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

@@ -60,6 +60,17 @@ jest.mock("@working-theory/stripe-client", () => ({
   },
 }));
 
+// #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 after mock setup
 import { config } from "../../../config/index.js";
 import { checkoutRoutes } from "../index";

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

@@ -82,10 +82,22 @@ 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 after mock setup
 import { config } from "../../../config/index.js";
 import { UnknownCustomerError } from "../../../lib/stripe.js";
 import { prisma } from "../../../lib/prisma.js";
+import { isOfferingsProduct } from "../../../services/offerings/catalog.js";
 import { checkoutRoutes } from "../index";
 
 // #6877 — pin the suite's site origin to the fixtures' own origin, so every
@@ -179,9 +191,23 @@ describe("POST /api/checkout/sessions", () => {
 
     expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
       expect.objectContaining({ allowPromotionCodes: true }),
+      { refuseProduct: isOfferingsProduct },
     );
   });
 
+  it("#8931 A9: an anonymous env checkout passes the Offerings marker as refuseProduct", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(1);
+    const [, options] = mockCreateCheckoutSession.mock.calls[0];
+    expect(Object.keys(options)).toEqual(["refuseProduct"]);
+    expect(options.refuseProduct).toBe(isOfferingsProduct);
+  });
+
   it("omits allowPromotionCodes from the client call when not supplied", async () => {
     await app.inject({
       method: "POST",
@@ -836,6 +862,7 @@ describe("parity with the payload the MCP tool builds (#5971)", () => {
         cancelUrl: "https://example.com/cancelled",
         allowPromotionCodes: true,
       }),
+      { refuseProduct: isOfferingsProduct },
     );
   });
 
@@ -912,6 +939,7 @@ describe("CheckoutSessionRequestSchema preserves Stripe's {CHECKOUT_SESSION_ID}
     expect(res.statusCode).toBe(201);
     expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
       expect.objectContaining({ successUrl: successUrlWithToken }),
+      { refuseProduct: isOfferingsProduct },
     );
   });
 });
@@ -1289,6 +1317,23 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
     });
   });
 
+  it("#8931 A9: the first try and the anonymous retry both refuse an Offerings product with the marker itself", async () => {
+    givenUser({ billingProvider: "stripe", billingCustomerId: "not_a_cus" });
+    mockCreateCheckoutSession.mockRejectedValueOnce(
+      Object.assign(new Error("invalid buyer"), { name: "ZodError" }),
+    );
+
+    const res = await signedIn();
+
+    expect(res.statusCode).toBe(201);
+    expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(2);
+    for (const call of mockCreateCheckoutSession.mock.calls) {
+      expect(call).toHaveLength(2);
+      expect(Object.keys(call[1])).toEqual(["refuseProduct"]);
+      expect(call[1].refuseProduct).toBe(isOfferingsProduct);
+    }
+  });
+
   it("#6866 R12b: an anonymous ZodError is not retried — today's 502 mapping", async () => {
     mockCreateCheckoutSession.mockRejectedValue(
       Object.assign(new Error("invalid"), { name: "ZodError" }),
@@ -1474,6 +1519,7 @@ describe("POST /v1/checkout/sessions — same-origin redirect lock (#6877)", ()
     expect(res.statusCode).toBe(201);
     expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
       expect.objectContaining({ successUrl, cancelUrl }),
+      { refuseProduct: isOfferingsProduct },
     );
   });
 
@@ -1490,6 +1536,7 @@ describe("POST /v1/checkout/sessions — same-origin redirect lock (#6877)", ()
     expect(res.statusCode).toBe(201);
     expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
       expect.objectContaining({ successUrl, cancelUrl }),
+      { refuseProduct: isOfferingsProduct },
     );
   });
 
@@ -1604,6 +1651,7 @@ describe("POST /v1/checkout/sessions — trusted-origin allowlist (#7395)", () =
     expect(res.statusCode).toBe(201);
     expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
       expect.objectContaining({ successUrl, cancelUrl }),
+      { refuseProduct: isOfferingsProduct },
     );
   });
 
@@ -1616,6 +1664,7 @@ describe("POST /v1/checkout/sessions — trusted-origin allowlist (#7395)", () =
     expect(res.statusCode).toBe(201);
     expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
       expect.objectContaining({ successUrl, cancelUrl }),
+      { refuseProduct: isOfferingsProduct },
     );
   });
 

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

@@ -22,6 +22,11 @@
  *     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`).
+ *   - A session the Offerings checkout recorded (#8931 D9, contract A13) is
+ *     read with its record's own connection, in the record's mode, never the
+ *     env key; its line-item names pass the catalog's T1 normalizer. A record
+ *     that cannot be read, or a connection that is gone, unusable or in
+ *     another mode, is 502 — never the env path. No record is today's read.
  *
  * Error mapping mirrors `sessions.ts`'s own vocabulary (D3):
  *   400 validation-error      — `:id` fails the shape check
@@ -29,7 +34,8 @@
  *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty
  *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key the process did not admit
  *   500 config-error          — STRIPE_SECRET_KEY invalid configuration
- *   502 checkout-unavailable  — Stripe SDK threw an unexpected error
+ *   502 checkout-unavailable  — Stripe SDK threw an unexpected error; a recorded
+ *                               Offerings session cannot be read on its connection (#8931)
  */
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
@@ -37,9 +43,11 @@ import { z } from "zod";
 import {
   assertAdmittedStripeKey,
   retrieveCheckoutSession,
+  type RetrieveCheckoutSessionOutput,
   StripeConfigError,
   UnknownSessionError,
 } from "../../lib/stripe.js";
+import { readOfferingsCheckoutSession } from "../../services/offerings/checkout-authorization.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
@@ -63,6 +71,36 @@ function setPrivateResponseHeaders(reply: FastifyReply): void {
   reply.header("Referrer-Policy", "no-referrer");
 }
 
+/** The 200: D3's headers and allow-list, named field-for-field. */
+function sendSessionRead(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  id: string,
+  session: RetrieveCheckoutSessionOutput,
+): FastifyReply {
+  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,
+  });
+}
+
 export async function checkoutSessionReadHandler(
   request: FastifyRequest,
   reply: FastifyReply,
@@ -75,6 +113,23 @@ export async function checkoutSessionReadHandler(
     });
   }
 
+  const { id } = parsed.data;
+
+  // A recorded Offerings session reads on its own connection (#8931 D9). No
+  // record can exist without a database.
+  if (process.env.DATABASE_URL) {
+    const offerings = await readOfferingsCheckoutSession(id);
+    if (offerings.kind === "read") {
+      return sendSessionRead(request, reply, id, offerings.session);
+    }
+    if (offerings.kind === "unknown") {
+      return reply.status(404).send({ error: "unknown-session" });
+    }
+    if (offerings.kind === "unavailable") {
+      return reply.status(502).send({ error: "checkout-unavailable" });
+    }
+  }
+
   const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
   if (!stripeSecretKey) {
     return reply.status(500).send({ error: "stripe-not-configured" });
@@ -85,32 +140,9 @@ export async function checkoutSessionReadHandler(
     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,
-    });
+    return sendSessionRead(request, reply, id, session);
   } catch (err) {
     if (err instanceof UnknownSessionError) {
       // 404 — never echo the id in the response body.

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

@@ -13,9 +13,23 @@
  *   - 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. It READS the database only to resolve
- *     an optional signed-in buyer (below).
+ *   - 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
@@ -48,13 +62,20 @@
  *   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
+ *   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
+ *   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";
 
@@ -78,10 +99,21 @@ 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" }>;
 
@@ -245,14 +277,97 @@ export async function checkoutSessionsHandler(
     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" });
-  }
+  // ── Which path (#8931 D2) — from the server-resolved workspace alone ──────
+  let checkoutPath: OfferingsCheckoutPath;
   try {
-    assertAdmittedStripeKey(stripeSecretKey);
-  } catch {
-    return reply.status(500).send({ error: "live-mode-forbidden" });
+    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);
@@ -306,85 +421,120 @@ export async function checkoutSessionsHandler(
     }
   }
 
-  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(),
-  };
-  // Built only from the session cookie — never from `parsed.data` (#6866 D5).
-  let { buyer, identity } = await resolveBuyer(request);
+  let created: CreateCheckoutSessionOutput;
+  let buyer: Buyer | undefined;
+  let identity: IdentityReason | undefined;
 
-  try {
-    let created: CreateCheckoutSessionOutput;
-    try {
-      created = await createCheckoutSession({
-        ...sessionInput,
-        ...(buyer !== undefined && { buyer }),
-      });
-    } 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);
-    }
-    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 }),
-      },
-      "[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
+  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 (err instanceof StripeConfigError) {
-      // 500 — misconfiguration; log message (no PII) but never echo in response
+    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.name,
-          message: err.message,
+          errName: err instanceof Error ? err.name : "unknown",
         },
-        "[checkout] config error",
+        "[checkout] stripe error; checkout-unavailable",
       );
-      return reply.status(500).send({ error: "config-error" });
+      return reply.status(502).send({ error: "checkout-unavailable" });
     }
-    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 });
 }