create-ailk 0.20.0 → 0.22.0

package/templates/apps/web/app/api/auth/hub/authorize/__tests__/route.test.ts

@@ -10,6 +10,10 @@
  * are the two external boundaries; both are mocked. The route's own decisions
  * are what is under test: which query it accepts, who it sends to sign in,
  * where a minted code goes, and what it refuses to redirect to.
+ *
+ * #8757 D9 (AC-6): an optional `login_hint` reaches the sign-in page as
+ * `email` on the no-session branch only; it never enters the continuation ref
+ * or the code redirect, and a repeated one is a 400 like any repeated key.
  */
 
 // --- Mocks set up BEFORE imports ---
@@ -345,3 +349,113 @@ describe("a signed-in person", () => {
     },
   );
 });
+
+describe("the login_hint (#8757 D9)", () => {
+  const HINT = "a@b.example";
+
+  /** The `next` value of the 303, and the ref inside it. */
+  function continuationOf(res: Response): { next: string; ref: string } {
+    const location = res.headers.get("location") ?? "";
+    const next = new URL(location, HUB).searchParams.get("next") ?? "";
+    return { next, ref: next.slice(`${CONTINUE}/`.length) };
+  }
+
+  it("no session + a valid login_hint: 303 to /sign-in?next=<continue path>&email=a%40b.example; the ref opens to the six-key canonical query alone", async () => {
+    mockGetSession.mockResolvedValue(null);
+    const canonical = query();
+
+    const res = await GET(
+      request(`${canonical}&login_hint=${encodeURIComponent(HINT)}`),
+    );
+
+    expect(res.status).toBe(303);
+    const { next, ref } = continuationOf(res);
+    expect(res.headers.get("location")).toBe(
+      `/sign-in?next=${encodeURIComponent(`${CONTINUE}/${ref}`)}&email=a%40b.example`,
+    );
+    expect(next).toBe(`${CONTINUE}/${ref}`);
+    const opened = openContinuation(ref, mockSecret);
+    expect(opened).toBe(canonical);
+    expect(opened).not.toContain("login_hint");
+    expect(opened).not.toContain("email");
+    expect(mockCreateCode).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["an invalid login_hint", "nope"],
+    ["a login_hint carrying a separator", "a@b.example&next=/x"],
+    ["an over-long login_hint", `${"a".repeat(250)}@b.example`],
+  ])(
+    "no session + %s: dropped — the 303 carries no email",
+    async (_name, hint) => {
+      mockGetSession.mockResolvedValue(null);
+      const canonical = query();
+
+      const res = await GET(
+        request(`${canonical}&login_hint=${encodeURIComponent(hint)}`),
+      );
+
+      expect(res.status).toBe(303);
+      const { ref } = continuationOf(res);
+      expect(res.headers.get("location")).toBe(
+        `/sign-in?next=${encodeURIComponent(`${CONTINUE}/${ref}`)}`,
+      );
+      expect(openContinuation(ref, mockSecret)).toBe(canonical);
+    },
+  );
+
+  it.each([
+    ["no session", null],
+    ["a session", { user: { id: "u1" } }],
+  ])(
+    "a repeated login_hint is a 400 invalid_request (%s)",
+    async (_name, session) => {
+      mockGetSession.mockResolvedValue(session);
+
+      const res = await GET(
+        request(`${query()}&login_hint=a%40b.example&login_hint=c%40d.example`),
+      );
+
+      expect(res.status).toBe(400);
+      expect(res.headers.get("location")).toBeNull();
+      expect(await res.json()).toEqual({ error: "invalid_request" });
+      expect(mockCreateCode).not.toHaveBeenCalled();
+      expect(mockGetSession).not.toHaveBeenCalled();
+    },
+  );
+
+  it("with a session: the code redirect is unchanged and carries no hint", async () => {
+    mockGetSession.mockResolvedValue({ user: { id: "u1" } });
+    mockCreateCode.mockResolvedValue({
+      ok: true,
+      body: { code: CODE, redirectUri: SPOKE_CALLBACK },
+    });
+
+    const withHint = await GET(
+      request(`${query()}&login_hint=${encodeURIComponent(HINT)}`, {
+        cookie: "better-auth.session_token=tok",
+      }),
+    );
+    const without = await GET(
+      request(query(), { cookie: "better-auth.session_token=tok" }),
+    );
+
+    expect(withHint.status).toBe(303);
+    const location = withHint.headers.get("location") ?? "";
+    expect(location).toBe(without.headers.get("location"));
+    expect(location).toBe(`${SPOKE_CALLBACK}?code=${CODE}&state=${STATE}`);
+    expect(location).not.toContain("login_hint");
+    expect(location).not.toContain("email");
+    expect(location).not.toContain("b.example");
+    // The hint is never handed to the API either.
+    expect(mockCreateCode).toHaveBeenNthCalledWith(
+      1,
+      {
+        clientId: "spoke_abc",
+        redirectUri: SPOKE_CALLBACK,
+        codeChallenge: CHALLENGE,
+      },
+      { headers: { cookie: "better-auth.session_token=tok", origin: HUB } },
+    );
+  });
+});

package/templates/apps/web/app/api/auth/hub/authorize/route.ts

@@ -11,6 +11,7 @@
  *   GET /api/auth/hub/authorize
  *       ?response_type=code&client_id=…&redirect_uri=…&state=…
  *       &code_challenge=…&code_challenge_method=S256
+ *       [&login_hint=<email>]   (optional, #8757 D9 — see below)
  *
  *   - a malformed query is a 400 and NEVER a redirect;
  *   - no Better Auth session: the six validated keys are sealed into a short
@@ -32,6 +33,14 @@
  *   - any other refusal is a 400 with `{ "error": "invalid_request" }` and no
  *     visitor copy: only a misconfigured client reaches it.
  *
+ * `login_hint` (#8757 D9) is optional and read beside the six keys with
+ * `accountEmailHintSchema` (`hubAuthorizeQuerySchema` is unchanged): repeated
+ * → 400 like any repeated key; refused → dropped. It acts only on the
+ * no-session branch, as the sign-in page's `email`, so the form opens with the
+ * address typed. It never enters the ref, a code or a cookie — the continue
+ * route rebuilds the query from the ref, so the hint is gone after sign-in —
+ * and with a session it is ignored.
+ *
  * `BETTER_AUTH_URL` pins the `Origin` sent with the cookie-authenticated write
  * (Node's `fetch` sets none). Unset, the step answers 503: it needs a pinned
  * origin, exactly as the emailed link does.
@@ -42,7 +51,10 @@
  * state, a challenge or a cookie.
  */
 import { hubSignIn } from "@working-theory/api-client";
-import { hubAuthorizeQuerySchema } from "@working-theory/validation";
+import {
+  accountEmailHintSchema,
+  hubAuthorizeQuerySchema,
+} from "@working-theory/validation";
 
 import { auth, resolveSecret } from "../../../../../auth";
 import {
@@ -109,9 +121,13 @@ export async function GET(request: Request): Promise<Response> {
     if (values.length > 1) return json(400, "invalid_request");
     raw[key] = values[0];
   }
+  // #8757 D9 — the optional hint: the same once-only rule; refused → dropped.
+  const hints = url.searchParams.getAll("login_hint");
+  if (hints.length > 1) return json(400, "invalid_request");
   const parsed = hubAuthorizeQuerySchema.safeParse(raw);
   if (!parsed.success) return json(400, "invalid_request");
   const query = parsed.data;
+  const hint = accountEmailHintSchema.safeParse(hints[0]);
 
   const session = await auth.api.getSession({ headers: request.headers });
   if (!session) {
@@ -121,8 +137,9 @@ export async function GET(request: Request): Promise<Response> {
     for (const key of QUERY_KEYS) canonical.set(key, query[key]);
     const ref = mintContinuation(canonical.toString(), resolveSecret());
     if (ref.length > CONTINUATION_REF_MAX) return json(400, "invalid_request");
-    const next = `${CONTINUE_PATH}/${ref}`;
-    return see(`/sign-in?next=${encodeURIComponent(next)}`);
+    const signIn = new URLSearchParams({ next: `${CONTINUE_PATH}/${ref}` });
+    if (hint.success) signIn.set("email", hint.data);
+    return see(`/sign-in?${signIn.toString()}`);
   }
 
   const origin = pinnedOrigin();

package/templates/apps/web/app/api/checkout/[offering]/route.ts

@@ -0,0 +1,48 @@
+// The buy route — the standard spoke checkout (#8748), kept current by
+// `create-ailk update`: do not edit it. Every guarantee lives in the
+// spoke-checkout package and arrives by a package bump. This site's offerings
+// are data in lib/checkout-config.ts, the one file to edit. It answers 404 on
+// any build that is not a spoke.
+//
+// A buyer who is signed in when checkout starts returns to /account; everyone
+// else returns to the thank-you page with Stripe's session id (#8757 D12). The
+// session is read through the site's generated seam: Better Auth on a site,
+// the sealed hub session on a hub-sign-in spoke, none without sign-in.
+import { createSpokeCheckout } from "@working-theory/spoke-checkout";
+
+import {
+  checkoutNotServed,
+  checkoutServed,
+  spokeCheckoutConfig,
+} from "../../../../lib/checkout";
+import { readSession } from "../../../../lib/topology.generated";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type BuyRoute = ReturnType<typeof createSpokeCheckout>["buy"];
+type BuyContext = Parameters<BuyRoute["GET"]>[1];
+
+let buy: BuyRoute | undefined;
+
+/** `/account` for a request with a session, else `null` (the thank-you page). */
+async function successPath(request: Request): Promise<string | null> {
+  return (await readSession(request.headers)) ? "/account" : null;
+}
+
+/** Built on the first served request and kept, so the package's rate limiters persist. */
+function buyRoute(): BuyRoute {
+  buy ??= createSpokeCheckout(spokeCheckoutConfig, { successPath }).buy;
+  return buy;
+}
+
+// platform-decisions-waiver: api-versioning — a browser buy link that redirects to Stripe Checkout, not a versioned API contract (spec 8748 §7)
+export async function GET(request: Request, ctx: BuyContext): Promise<Response> {
+  if (!checkoutServed()) return checkoutNotServed();
+  return buyRoute().GET(request, ctx);
+}
+
+export async function POST(request: Request, ctx: BuyContext): Promise<Response> {
+  if (!checkoutServed()) return checkoutNotServed();
+  return buyRoute().POST(request, ctx);
+}

package/templates/apps/web/app/api/checkout/__tests__/route.test.ts

@@ -0,0 +1,120 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The standard buy route (#8748 D1, D11; spec
+ * docs/specs/8748-a-standard-spoke-checkout-route-spec.md AC-2, AC-4).
+ *
+ * The checkout package is mocked: every guarantee is its own, proven by its
+ * own suites. These cases prove the route is wiring only — built once from
+ * `spokeCheckoutConfig`, serving the package's `buy` handlers on a spoke and
+ * a 404 anywhere else — and that it declares no offering and no Stripe
+ * client of its own.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const mockBuyGet = jest.fn();
+const mockBuyPost = jest.fn();
+const mockCreateSpokeCheckout = jest.fn((_config: unknown) => ({
+  buy: { GET: mockBuyGet, POST: mockBuyPost },
+}));
+// `virtual`: CI runs this suite before the package's dist is built, so it
+// may not resolve at all — the factory stands in either way.
+jest.mock(
+  "@working-theory/spoke-checkout",
+  () => ({
+    __esModule: true,
+    createSpokeCheckout: (config: unknown) => mockCreateSpokeCheckout(config),
+  }),
+  { virtual: true },
+);
+
+const mockTopology: { value: "hub" | "spoke" } = { value: "spoke" };
+// eslint-disable-next-line no-restricted-syntax -- #507: the topology is a generated constant (#7426), not a runtime input; the seam IS the boundary between a hub and a spoke build, and no env or HTTP surface selects it.
+jest.mock("../../../../lib/topology.generated", () => ({
+  __esModule: true,
+  get TOPOLOGY() {
+    return mockTopology.value;
+  },
+}));
+
+import { checkoutConfig } from "../../../../lib/checkout-config";
+import { spokeCheckoutConfig } from "../../../../lib/checkout";
+import { GET, POST } from "../[offering]/route";
+
+const ROUTE_SOURCE = readFileSync(
+  join(__dirname, "..", "[offering]", "route.ts"),
+  "utf8",
+);
+
+function ctxFor(offering: string) {
+  return { params: Promise.resolve({ offering }) };
+}
+
+function request(method: "GET" | "POST"): Request {
+  return new Request("https://acme.example.com/api/checkout/example", {
+    method,
+  });
+}
+
+describe("the standard buy route (#8748 AC-2)", () => {
+  beforeEach(() => {
+    mockBuyGet.mockReset();
+    mockBuyPost.mockReset();
+  });
+
+  it("answers 404 with no-store on a hub, and never builds the package's handlers (D11)", async () => {
+    mockTopology.value = "hub";
+    for (const res of [
+      await GET(request("GET"), ctxFor("example")),
+      await POST(request("POST"), ctxFor("example")),
+    ]) {
+      expect(res.status).toBe(404);
+      expect(res.headers.get("cache-control")).toBe("no-store");
+    }
+    expect(mockCreateSpokeCheckout).not.toHaveBeenCalled();
+    expect(mockBuyGet).not.toHaveBeenCalled();
+    expect(mockBuyPost).not.toHaveBeenCalled();
+  });
+
+  it("serves the package's buy handlers on a spoke, built once from spokeCheckoutConfig", async () => {
+    mockTopology.value = "spoke";
+    const fromGet = new Response(null, { status: 303 });
+    const fromPost = new Response(null, { status: 303 });
+    mockBuyGet.mockResolvedValue(fromGet);
+    mockBuyPost.mockResolvedValue(fromPost);
+
+    const getRequest = request("GET");
+    const getCtx = ctxFor("example");
+    expect(await GET(getRequest, getCtx)).toBe(fromGet);
+    expect(mockBuyGet).toHaveBeenCalledWith(getRequest, getCtx);
+
+    const postRequest = request("POST");
+    const postCtx = ctxFor("example");
+    expect(await POST(postRequest, postCtx)).toBe(fromPost);
+    expect(mockBuyPost).toHaveBeenCalledWith(postRequest, postCtx);
+
+    expect(mockCreateSpokeCheckout).toHaveBeenCalledTimes(1);
+    const [config] = mockCreateSpokeCheckout.mock.calls[0] as [
+      typeof spokeCheckoutConfig,
+    ];
+    expect(config).toBe(spokeCheckoutConfig);
+    expect(config.offerings).toBe(checkoutConfig.offerings);
+  });
+
+  it("names no offering of the site's own", () => {
+    for (const slug of Object.keys(checkoutConfig.offerings)) {
+      const quoted = new RegExp(`["'\`]${slug}["'\`]`);
+      const property = new RegExp(`\\b${slug}\\s*:`);
+      expect(ROUTE_SOURCE).not.toMatch(quoted);
+      expect(ROUTE_SOURCE).not.toMatch(property);
+    }
+  });
+
+  it("reads no Stripe setting and imports no Stripe client (AC-4)", () => {
+    expect(ROUTE_SOURCE).not.toContain("STRIPE_");
+    expect(ROUTE_SOURCE).not.toContain("stripe-client");
+  });
+});

package/templates/apps/web/app/api/checkout/__tests__/success-path.test.ts

@@ -0,0 +1,86 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The buy route's success path (#8757 D12, AC-10): a buyer signed in when
+ * checkout starts returns to `/account`, everyone else to the thank-you page.
+ *
+ * The route hands the checkout package a `successPath` hook built on the
+ * site's generated session seam (`readSession` in lib/topology.generated —
+ * Better Auth on a site, the sealed hub session on a hub-sign-in spoke, none
+ * on a spoke without sign-in). The package is mocked: what it does with the
+ * answer is its own suite's (`buy-route.test.ts`). These cases prove the hook
+ * answers `"/account"` for a request with a session and `null` without one.
+ */
+const mockCreateSpokeCheckout = jest.fn((_config: unknown, _options?: unknown) => ({
+  buy: { GET: jest.fn(async () => new Response(null, { status: 303 })), POST: jest.fn() },
+}));
+// `virtual`: CI runs this suite before the package's dist is built.
+jest.mock(
+  "@working-theory/spoke-checkout",
+  () => ({
+    __esModule: true,
+    createSpokeCheckout: (config: unknown, options?: unknown) =>
+      mockCreateSpokeCheckout(config, options),
+  }),
+  { virtual: true },
+);
+
+const mockReadSession = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- #507: the topology is a generated constant (#7426), not a runtime input; the seam IS the boundary between a hub and a spoke build, and no env or HTTP surface selects it.
+jest.mock("../../../../lib/topology.generated", () => ({
+  __esModule: true,
+  TOPOLOGY: "spoke",
+  readSession: (headers: Headers) => mockReadSession(headers),
+}));
+
+import { GET } from "../[offering]/route";
+
+type SuccessPath = (request: Request) => Promise<string | null>;
+
+/** The `successPath` the route built its handlers with. */
+async function successPathHook(): Promise<SuccessPath> {
+  await GET(new Request("https://acme.example.com/api/checkout/example"), {
+    params: Promise.resolve({ offering: "example" }),
+  });
+  expect(mockCreateSpokeCheckout).toHaveBeenCalledTimes(1);
+  const [, options] = mockCreateSpokeCheckout.mock.calls[0] as [
+    unknown,
+    { successPath?: SuccessPath } | undefined,
+  ];
+  expect(typeof options?.successPath).toBe("function");
+  return options!.successPath!;
+}
+
+describe("the buy route's success path (#8757 AC-10)", () => {
+  let successPath: SuccessPath;
+
+  beforeAll(async () => {
+    successPath = await successPathHook();
+  });
+
+  beforeEach(() => {
+    mockReadSession.mockReset();
+  });
+
+  it("a request with a session answers /account", async () => {
+    mockReadSession.mockResolvedValue({
+      user: { email: "cleo@x.io", emailVerified: true },
+    });
+    const request = new Request("https://acme.example.com/api/checkout/example", {
+      headers: { cookie: "session=abc" },
+    });
+    await expect(successPath(request)).resolves.toBe("/account");
+    expect(mockReadSession).toHaveBeenCalledTimes(1);
+    const [headers] = mockReadSession.mock.calls[0] as [Headers];
+    expect(headers.get("cookie")).toBe("session=abc");
+  });
+
+  it("a request without one answers null", async () => {
+    mockReadSession.mockResolvedValue(null);
+    await expect(
+      successPath(new Request("https://acme.example.com/api/checkout/example")),
+    ).resolves.toBeNull();
+  });
+});

package/templates/apps/web/app/api/hub-session/__tests__/routes.test.ts

@@ -13,6 +13,9 @@
  * a callback that BURNS a code it cannot complete (AC-5), and a sign-out that
  * refuses a cross-site request and revokes nothing (AC-5). Each route is a 404
  * unless the web seam's `SIGN_IN_PROVIDER` is `"hub"` (AC-9).
+ *
+ * #8757 D9 (AC-6): a valid single `?email=` on the sign-in route becomes the
+ * authorize URL's `login_hint`; the sealed flow cookie never carries it.
  */
 
 import { createHash } from "node:crypto";
@@ -36,7 +39,7 @@ jest.mock("../../../../lib/topology.generated", () => ({
   },
 }));
 
-import { seal } from "../../../../lib/hub-session/seal";
+import { seal, unseal } from "../../../../lib/hub-session/seal";
 import { GET as callback } from "../callback/route";
 import { GET as signIn } from "../sign-in/route";
 import { POST as signOut } from "../sign-out/route";
@@ -161,6 +164,46 @@ describe("GET /api/hub-session/sign-in", () => {
   });
 });
 
+describe("GET /api/hub-session/sign-in — the hinted email (#8757 D9)", () => {
+  function startWith(query: string): { authorize: URL; payload: Record<string, unknown> } {
+    const res = signIn(new Request(`${SITE}/api/hub-session/sign-in?${query}`));
+    expect(res.status).toBe(303);
+    const flow = cookieValue(res, "ailk-hub-flow");
+    if (flow === undefined) throw new Error("no flow cookie");
+    const payload = unseal(flow, SESSION_SECRET, "flow", "ailk-hub-flow");
+    if (payload === null || typeof payload !== "object") throw new Error("flow did not open");
+    return {
+      authorize: new URL(res.headers.get("location") ?? ""),
+      payload: payload as Record<string, unknown>,
+    };
+  }
+
+  it("?next=/account&email=a%40b.example → the authorize URL carries login_hint; the flow cookie does not", () => {
+    const { authorize, payload } = startWith("next=/account&email=a%40b.example");
+    expect(authorize.searchParams.get("login_hint")).toBe("a@b.example");
+    expect(authorize.search).toContain("login_hint=a%40b.example");
+    // The six keys are untouched beside it.
+    expect(authorize.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(authorize.searchParams.getAll("login_hint")).toHaveLength(1);
+    expect(payload.next).toBe("/account");
+    expect(payload).not.toHaveProperty("email");
+    expect(payload).not.toHaveProperty("login_hint");
+    expect(JSON.stringify(payload)).not.toContain("a@b.example");
+  });
+
+  it.each([
+    ["an invalid value", "next=/account&email=bad"],
+    ["a repeated value", "next=/account&email=a%40b.example&email=c%40d.example"],
+    ["a value carrying a separator", "next=/account&email=a%40b.example%26x%3D1"],
+    ["no value", "next=/account"],
+  ])("%s → no login_hint", (_label, query) => {
+    const { authorize, payload } = startWith(query);
+    expect(authorize.searchParams.has("login_hint")).toBe(false);
+    expect(payload).not.toHaveProperty("email");
+    expect(payload).not.toHaveProperty("login_hint");
+  });
+});
+
 describe("GET /api/hub-session/callback", () => {
   function exchangeOk(): void {
     mockExchange.mockResolvedValue({

package/templates/apps/web/app/api/hub-session/sign-in/route.ts

@@ -10,10 +10,17 @@
  *   - not a hub-mode spoke (`SIGN_IN_PROVIDER` is not `"hub"`): 404;
  *   - hub mode but not configured: 303 to `/account`, whose gate says so.
  *
+ * Hinted email (#8757 D9): a single `?email=` that `accountEmailHintSchema`
+ * accepts rides to the hub as `login_hint`, so its sign-in form opens with
+ * the address typed. A refused or repeated value is dropped. The hint goes on
+ * the authorize URL only — never into the sealed flow cookie.
+ *
  * Nothing here logs the state, the verifier or the challenge.
  */
 import { createHash, randomBytes } from "node:crypto";
 
+import { accountEmailHintSchema } from "@working-theory/validation";
+
 import { hubSessionConfig } from "../../../../lib/hub-session/config";
 import { seal } from "../../../../lib/hub-session/seal";
 import {
@@ -40,13 +47,22 @@ function see(location: string, setCookie?: string): Response {
   return new Response(null, { status: 303, headers });
 }
 
+/** #8757 D9 — the one `email` the hint schema accepts; repeated or refused → none. */
+function emailHint(params: URLSearchParams): string | undefined {
+  const values = params.getAll("email");
+  if (values.length !== 1) return undefined;
+  const parsed = accountEmailHintSchema.safeParse(values[0]);
+  return parsed.success ? parsed.data : undefined;
+}
+
 // platform-decisions-waiver: api-versioning — sign-in redirect endpoint, not a versioned API contract (spec 7894 §7)
 export function GET(request: Request): Response {
   if (SIGN_IN_PROVIDER !== "hub") return new Response(null, { status: 404 });
   const config = hubSessionConfig();
   if (config === null) return see(HUB_SESSION_FALLBACK_PATH);
 
-  const next = hubNextPath(new URL(request.url).searchParams.get("next"));
+  const params = new URL(request.url).searchParams;
+  const next = hubNextPath(params.get("next"));
   const state = randomBytes(32).toString("base64url");
   const verifier = randomBytes(32).toString("base64url");
   const challenge = createHash("sha256").update(verifier).digest("base64url");
@@ -60,14 +76,17 @@ export function GET(request: Request): Response {
   );
 
   const authorize = new URL(AUTHORIZE_PATH, config.hubOrigin);
-  authorize.search = new URLSearchParams({
+  const query = new URLSearchParams({
     response_type: "code",
     client_id: config.clientId,
     redirect_uri: config.redirectUri,
     state,
     code_challenge: challenge,
     code_challenge_method: "S256",
-  }).toString();
+  });
+  const loginHint = emailHint(params);
+  if (loginHint !== undefined) query.set("login_hint", loginHint);
+  authorize.search = query.toString();
 
   return see(
     authorize.toString(),

package/templates/apps/web/app/api/webhooks/stripe/__tests__/route.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The standard Stripe webhook route (#8748 D1, D11; spec
+ * docs/specs/8748-a-standard-spoke-checkout-route-spec.md AC-2, AC-4).
+ *
+ * The checkout package is mocked: its verification, filters, retries and
+ * duplicate guard are proven by its own suites. These cases prove the route
+ * is wiring only — built once from `spokeCheckoutConfig`, serving the
+ * package's `webhook` handler on a spoke and a 404 anywhere else.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const mockWebhookPost = jest.fn();
+const mockCreateSpokeCheckout = jest.fn((_config: unknown) => ({
+  webhook: { POST: mockWebhookPost },
+}));
+// `virtual`: CI runs this suite before the package's dist is built, so it
+// may not resolve at all — the factory stands in either way.
+jest.mock(
+  "@working-theory/spoke-checkout",
+  () => ({
+    __esModule: true,
+    createSpokeCheckout: (config: unknown) => mockCreateSpokeCheckout(config),
+  }),
+  { virtual: true },
+);
+
+const mockTopology: { value: "hub" | "spoke" } = { value: "spoke" };
+// eslint-disable-next-line no-restricted-syntax -- #507: the topology is a generated constant (#7426), not a runtime input; the seam IS the boundary between a hub and a spoke build, and no env or HTTP surface selects it.
+jest.mock("../../../../../lib/topology.generated", () => ({
+  __esModule: true,
+  get TOPOLOGY() {
+    return mockTopology.value;
+  },
+}));
+
+import { checkoutConfig } from "../../../../../lib/checkout-config";
+import { spokeCheckoutConfig } from "../../../../../lib/checkout";
+import { POST } from "../route";
+
+const ROUTE_SOURCE = readFileSync(join(__dirname, "..", "route.ts"), "utf8");
+
+function delivery(): Request {
+  return new Request("https://acme.example.com/api/webhooks/stripe", {
+    method: "POST",
+    body: "{}",
+  });
+}
+
+describe("the standard Stripe webhook route (#8748 AC-2)", () => {
+  beforeEach(() => {
+    mockWebhookPost.mockReset();
+  });
+
+  it("answers 404 with no-store on a hub, and never builds the package's handlers (D11)", async () => {
+    mockTopology.value = "hub";
+    const res = await POST(delivery());
+    expect(res.status).toBe(404);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    expect(mockCreateSpokeCheckout).not.toHaveBeenCalled();
+    expect(mockWebhookPost).not.toHaveBeenCalled();
+  });
+
+  it("serves the package's webhook handler on a spoke, built once from spokeCheckoutConfig", async () => {
+    mockTopology.value = "spoke";
+    const answered = new Response(null, { status: 200 });
+    mockWebhookPost.mockResolvedValue(answered);
+
+    const first = delivery();
+    expect(await POST(first)).toBe(answered);
+    expect(mockWebhookPost).toHaveBeenCalledWith(first);
+    const second = delivery();
+    expect(await POST(second)).toBe(answered);
+    expect(mockWebhookPost).toHaveBeenLastCalledWith(second);
+
+    expect(mockCreateSpokeCheckout).toHaveBeenCalledTimes(1);
+    const [config] = mockCreateSpokeCheckout.mock.calls[0] as [
+      typeof spokeCheckoutConfig,
+    ];
+    expect(config).toBe(spokeCheckoutConfig);
+    expect(config.offerings).toBe(checkoutConfig.offerings);
+  });
+
+  it("reads no Stripe setting and imports no Stripe client (AC-4)", () => {
+    expect(ROUTE_SOURCE).not.toContain("STRIPE_");
+    expect(ROUTE_SOURCE).not.toContain("stripe-client");
+  });
+});