create-ailk 0.14.0 → 0.16.0

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

@@ -0,0 +1,156 @@
+/**
+ * The hub's browser step of "sign in through the hub" (#7894, spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md D2, D4).
+ *
+ * A spoke redirects a visitor here; this route is the one place the person
+ * must be signed in on the HUB'S OWN origin, because that is where the Better
+ * Auth session cookie lives. It owns no stored artifact: codes and credentials
+ * live behind `apps/api` (`POST /v1/hub-sign-in/codes`), reached through
+ * `@working-theory/api-client` with the visitor's own cookie.
+ *
+ *   GET /api/auth/hub/authorize
+ *       ?response_type=code&client_id=…&redirect_uri=…&state=…
+ *       &code_challenge=…&code_challenge_method=S256
+ *
+ *   - a malformed query is a 400 and NEVER a redirect;
+ *   - no Better Auth session: 303 to `/sign-in?next=<this path and query>` —
+ *     a same-origin path, so `resolveNextPath` keeps it and the existing
+ *     sign-in card hands it to Better Auth as the callback for Google and for
+ *     the emailed link alike (the hub's own `magicLink` sends the link, and it
+ *     returns through this step);
+ *   - a session: the API mints a single-use code, and this route redirects to
+ *     the REGISTERED redirect URI the API echoes back, with `code` and the
+ *     same `state` — never to the query's own `redirect_uri` until the API has
+ *     confirmed it is the client's;
+ *   - a person whose email is not verified (403 `email_unverified`) goes to the
+ *     hub's own `/account/settings`, whose For-you item says how to verify —
+ *     never to the spoke;
+ *   - any other refusal is a 400 with `{ "error": "invalid_request" }` and no
+ *     visitor copy: only a misconfigured client reaches it.
+ *
+ * `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.
+ *
+ * This is the second api-shaped route under `apps/web/app/api/auth/`, beside
+ * Better Auth's catch-all; it sits under `app/api/auth`, a spoke removal seed
+ * (spec 7426 D4), so no spoke ever carries it. Nothing here logs a code, a
+ * state, a challenge or a cookie.
+ */
+import { hubSignIn } from "@working-theory/api-client";
+import { hubAuthorizeQuerySchema } from "@working-theory/validation";
+
+import { auth } from "../../../../../auth";
+
+/** The six query keys, each read exactly once. */
+const QUERY_KEYS = [
+  "response_type",
+  "client_id",
+  "redirect_uri",
+  "state",
+  "code_challenge",
+  "code_challenge_method",
+] as const;
+
+/** Where an unverified person is sent to verify: the hub's own account page. */
+const VERIFY_EMAIL_PATH = "/account/settings";
+
+function json(status: number, error: string): Response {
+  return new Response(JSON.stringify({ error }), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+/** A 303 whose target may be a same-origin path or an absolute spoke URL. */
+function see(location: string): Response {
+  return new Response(null, {
+    status: 303,
+    headers: {
+      Location: location,
+      "Cache-Control": "no-store",
+      // The code rides this URL; no page may leak it through a Referer.
+      "Referrer-Policy": "no-referrer",
+    },
+  });
+}
+
+/** The pinned origin of the hub's own web app, or `null` when unset/invalid. */
+function pinnedOrigin(): string | null {
+  const raw = process.env.BETTER_AUTH_URL;
+  if (!raw) return null;
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return null;
+  }
+}
+
+// platform-decisions-waiver: api-versioning — sign-in redirect endpoint, not a versioned API contract (spec 7894 §7)
+export async function GET(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+
+  // Each declared key exactly once: a repeated key is ambiguous, so 400.
+  const raw: Record<string, string | undefined> = {};
+  for (const key of QUERY_KEYS) {
+    const values = url.searchParams.getAll(key);
+    if (values.length > 1) return json(400, "invalid_request");
+    raw[key] = values[0];
+  }
+  const parsed = hubAuthorizeQuerySchema.safeParse(raw);
+  if (!parsed.success) return json(400, "invalid_request");
+  const query = parsed.data;
+
+  const session = await auth.api.getSession({ headers: request.headers });
+  if (!session) {
+    const next = `${url.pathname}${url.search}`;
+    return see(`/sign-in?next=${encodeURIComponent(next)}`);
+  }
+
+  const origin = pinnedOrigin();
+  if (origin === null) return json(503, "temporarily_unavailable");
+
+  let result: Awaited<ReturnType<typeof hubSignIn.createCode>>;
+  try {
+    result = await hubSignIn.createCode(
+      {
+        clientId: query.client_id,
+        redirectUri: query.redirect_uri,
+        codeChallenge: query.code_challenge,
+      },
+      {
+        headers: {
+          cookie: request.headers.get("cookie") ?? "",
+          origin,
+        },
+      },
+    );
+  } catch {
+    return json(503, "temporarily_unavailable");
+  }
+
+  if (result.ok) {
+    // Redirect to the URI the API confirmed is registered for this client.
+    let target: URL;
+    try {
+      target = new URL(result.body.redirectUri);
+    } catch {
+      // A registered URI is validated at registration; an unparseable echo is
+      // a server fault, never something to redirect to.
+      return json(503, "temporarily_unavailable");
+    }
+    target.searchParams.set("code", result.body.code);
+    target.searchParams.set("state", query.state);
+    return see(target.toString());
+  }
+
+  const code = (result.body as { error?: { code?: unknown } } | null)?.error
+    ?.code;
+  if (result.status === 403 && code === "email_unverified") {
+    return see(VERIFY_EMAIL_PATH);
+  }
+  return json(400, "invalid_request");
+}

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

@@ -0,0 +1,341 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The spoke's three hub-session routes (#7894 D2, D7; spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md AC-3, AC-5).
+ *
+ * The api-client's `hubSignIn` (the hub API) is the one external boundary
+ * mocked; the seal, the cookies and the routes' decisions are real. Covers:
+ * the authorize redirect (PKCE S256, a state, the configured redirect URI —
+ * never one built from `Host`), the callback's state check and its exchange,
+ * 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).
+ */
+
+import { createHash } from "node:crypto";
+
+const mockExchange = jest.fn();
+const mockRevoke = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  hubSignIn: {
+    exchange: (...args: unknown[]) => mockExchange(...args),
+    revoke: (...args: unknown[]) => mockRevoke(...args),
+  },
+}));
+
+const mockProvider: { value: "site" | "hub" | "none" } = { value: "hub" };
+// eslint-disable-next-line no-restricted-syntax -- #507: the sign-in provider is a generated constant (#7894 D8), not a runtime input; the seam IS the boundary between a hub and a hub-mode spoke build, and no env or HTTP surface selects it.
+jest.mock("../../../../lib/topology.generated", () => ({
+  __esModule: true,
+  get SIGN_IN_PROVIDER() {
+    return mockProvider.value;
+  },
+}));
+
+import { seal } 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";
+
+const ENV = process.env;
+const SITE = "http://127.0.0.1:3100";
+const HUB = "http://127.0.0.1:4100";
+const SESSION_SECRET = "s".repeat(43);
+const CLIENT = { clientId: "spoke_0001", clientSecret: `ailk_hcs_${"c".repeat(43)}` };
+const CREDENTIAL = `ailk_hst_${"t".repeat(43)}`;
+const CODE = "k".repeat(43);
+const USER = {
+  id: "user_1",
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+  emailVerified: true,
+  createdAt: "2026-09-01T00:00:00.000Z",
+};
+
+function configure(overrides: Record<string, string | undefined> = {}): void {
+  process.env = {
+    ...ENV,
+    AILK_HUB_SIGN_IN_URL: HUB,
+    AILK_HUB_CLIENT_ID: CLIENT.clientId,
+    AILK_HUB_CLIENT_SECRET: CLIENT.clientSecret,
+    AILK_HUB_SESSION_SECRET: SESSION_SECRET,
+    NEXT_PUBLIC_BASE_URL: SITE,
+  };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+}
+
+/** Each `Set-Cookie` the response carries. */
+function setCookies(res: Response): string[] {
+  return res.headers.getSetCookie();
+}
+
+/** `name=value` of the cookie `name` in `res`'s `Set-Cookie` headers. */
+function cookieValue(res: Response, name: string): string | undefined {
+  const line = setCookies(res).find((c) => c.startsWith(`${name}=`));
+  return line?.slice(name.length + 1).split(";")[0];
+}
+
+/** Start a sign-in and return the flow cookie and the authorize URL. */
+function start(next = "/account"): { flow: string; authorize: URL; res: Response } {
+  const res = signIn(
+    new Request(`${SITE}/api/hub-session/sign-in?next=${encodeURIComponent(next)}`, {
+      // A Host unlike the site's: the redirect URI must not follow it.
+      headers: { host: "attacker.example.com" },
+    }),
+  );
+  const flow = cookieValue(res, "ailk-hub-flow");
+  if (flow === undefined) throw new Error("no flow cookie");
+  return { flow, authorize: new URL(res.headers.get("location") ?? ""), res };
+}
+
+function callbackRequest(query: string, cookie?: string): Request {
+  return new Request(`${SITE}/api/hub-session/callback?${query}`, {
+    headers: cookie === undefined ? {} : { cookie },
+  });
+}
+
+beforeEach(() => {
+  configure();
+  mockProvider.value = "hub";
+  mockExchange.mockReset();
+  mockRevoke.mockReset().mockResolvedValue({ ok: true, body: { revoked: true } });
+  jest.spyOn(console, "warn").mockImplementation(() => undefined);
+  jest.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+afterAll(() => {
+  process.env = ENV;
+});
+
+describe("GET /api/hub-session/sign-in", () => {
+  it("303s to the hub's authorize step with PKCE S256, a state and the configured callback, and sets the flow cookie", () => {
+    const { authorize, res } = start();
+    expect(res.status).toBe(303);
+    expect(`${authorize.origin}${authorize.pathname}`).toBe(`${HUB}/api/auth/hub/authorize`);
+    const q = authorize.searchParams;
+    expect(q.get("response_type")).toBe("code");
+    expect(q.get("client_id")).toBe(CLIENT.clientId);
+    expect(q.get("redirect_uri")).toBe(`${SITE}/api/hub-session/callback`);
+    expect(q.get("code_challenge")).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(q.get("code_challenge_method")).toBe("S256");
+    expect(q.get("state")).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    const flow = setCookies(res).find((c) => c.startsWith("ailk-hub-flow="));
+    expect(flow).toMatch(/; HttpOnly/);
+    expect(flow).toMatch(/; SameSite=Lax/);
+    expect(flow).toMatch(/; Max-Age=600/);
+    expect(flow).not.toMatch(/Secure/);
+  });
+
+  it("names the __Host- cookie, Secure, on an https site", () => {
+    configure({ NEXT_PUBLIC_BASE_URL: "https://spoke.example.com" });
+    const res = signIn(new Request("https://spoke.example.com/api/hub-session/sign-in"));
+    const flow = setCookies(res).find((c) => c.startsWith("__Host-ailk-hub-flow="));
+    expect(flow).toMatch(/; Secure$/);
+    expect(new URL(res.headers.get("location") ?? "").searchParams.get("redirect_uri")).toBe(
+      "https://spoke.example.com/api/hub-session/callback",
+    );
+  });
+
+  it("with no configuration 303s to /account and sets no cookie", () => {
+    configure({ AILK_HUB_CLIENT_SECRET: undefined });
+    const res = signIn(new Request(`${SITE}/api/hub-session/sign-in?next=/account`));
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/account");
+    expect(setCookies(res)).toEqual([]);
+  });
+
+  it.each(["site", "none"] as const)("is 404 when the provider is %s", (provider) => {
+    mockProvider.value = provider;
+    expect(signIn(new Request(`${SITE}/api/hub-session/sign-in`)).status).toBe(404);
+  });
+});
+
+describe("GET /api/hub-session/callback", () => {
+  function exchangeOk(): void {
+    mockExchange.mockResolvedValue({
+      ok: true,
+      body: { accessToken: CREDENTIAL, tokenType: "Bearer", expiresIn: 86400, user: USER },
+    });
+  }
+
+  it("exchanges the code with the verifier whose S256 is the challenge, seals the session and lands on next", async () => {
+    exchangeOk();
+    const { flow, authorize } = start("/fr/account/inbox");
+    const state = authorize.searchParams.get("state") ?? "";
+    const res = await callback(
+      callbackRequest(`code=${CODE}&state=${state}`, `ailk-hub-flow=${flow}`),
+    );
+
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/fr/account/inbox");
+    expect(mockExchange).toHaveBeenCalledTimes(1);
+    const [auth, body] = mockExchange.mock.calls[0] as [
+      typeof CLIENT,
+      { code: string; redirectUri: string; codeVerifier: string },
+    ];
+    expect(auth).toEqual(CLIENT);
+    expect(body.code).toBe(CODE);
+    expect(body.redirectUri).toBe(`${SITE}/api/hub-session/callback`);
+    expect(createHash("sha256").update(body.codeVerifier).digest("base64url")).toBe(
+      authorize.searchParams.get("code_challenge"),
+    );
+    const session = setCookies(res).find((c) => c.startsWith("ailk-hub-session="));
+    expect(session).toMatch(/; HttpOnly/);
+    expect(session).toMatch(/; Max-Age=86400/);
+    // The flow cookie is cleared, and the credential never appears in clear.
+    expect(setCookies(res).find((c) => c.startsWith("ailk-hub-flow="))).toMatch(/Max-Age=0/);
+    expect(setCookies(res).join("\n")).not.toContain(CREDENTIAL);
+    expect(mockRevoke).not.toHaveBeenCalled();
+  });
+
+  it("lands on the flow cookie's next, never a next in the callback's query", async () => {
+    exchangeOk();
+    const { flow, authorize } = start("/account");
+    const state = authorize.searchParams.get("state") ?? "";
+    const res = await callback(
+      callbackRequest(`code=${CODE}&state=${state}&next=%2F%2Fevil.example.com`, `ailk-hub-flow=${flow}`),
+    );
+    expect(res.headers.get("location")).toBe("/account");
+  });
+
+  it("AC-5: without its flow cookie, burns the code at the hub and exchanges nothing", async () => {
+    const res = await callback(callbackRequest(`code=${CODE}&state=${"s".repeat(43)}`));
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/account");
+    expect(mockExchange).not.toHaveBeenCalled();
+    expect(mockRevoke).toHaveBeenCalledTimes(1);
+    expect(mockRevoke).toHaveBeenCalledWith(CLIENT, { code: CODE });
+    expect(setCookies(res).some((c) => c.startsWith("ailk-hub-session="))).toBe(false);
+  });
+
+  it("burns the code on a state mismatch, a hub error, an expired flow and a failed exchange", async () => {
+    const { flow, authorize } = start();
+    const state = authorize.searchParams.get("state") ?? "";
+    const cookie = `ailk-hub-flow=${flow}`;
+
+    await callback(callbackRequest(`code=${CODE}&state=${"x".repeat(43)}`, cookie));
+    await callback(callbackRequest(`code=${CODE}&state=${state}&error=access_denied`, cookie));
+    const expired = seal(
+      { v: 1, state, verifier: "v".repeat(43), next: "/account", expiresAt: Date.now() - 1 },
+      SESSION_SECRET,
+      "flow",
+      "ailk-hub-flow",
+    );
+    await callback(callbackRequest(`code=${CODE}&state=${state}`, `ailk-hub-flow=${expired}`));
+    expect(mockExchange).not.toHaveBeenCalled();
+
+    mockExchange.mockResolvedValue({ ok: false, status: 400, body: { error: "invalid_grant" } });
+    const failed = await callback(callbackRequest(`code=${CODE}&state=${state}`, cookie));
+    expect(failed.headers.get("location")).toBe("/account");
+    expect(mockRevoke).toHaveBeenCalledTimes(4);
+    for (const call of mockRevoke.mock.calls) expect(call).toEqual([CLIENT, { code: CODE }]);
+  });
+
+  it.each([[0], [86_401], [Number.NaN], [undefined]])(
+    "refuses a token answer whose expiresIn is %s, setting no session",
+    async (expiresIn) => {
+      mockExchange.mockResolvedValue({
+        ok: true,
+        body: { accessToken: CREDENTIAL, tokenType: "Bearer", expiresIn, user: USER },
+      });
+      const { flow, authorize } = start();
+      const state = authorize.searchParams.get("state") ?? "";
+      const res = await callback(callbackRequest(`code=${CODE}&state=${state}`, `ailk-hub-flow=${flow}`));
+      expect(res.headers.get("location")).toBe("/account");
+      expect(setCookies(res).some((c) => c.startsWith("ailk-hub-session="))).toBe(false);
+    },
+  );
+
+  it("never logs the query string, the code or the state", async () => {
+    const warn = jest.spyOn(console, "warn");
+    await callback(callbackRequest(`code=${CODE}&state=${"s".repeat(43)}`));
+    const logged = warn.mock.calls.flat().join(" ");
+    expect(logged).toContain("reason=no_flow");
+    expect(logged).not.toContain(CODE);
+    expect(logged).not.toContain("s".repeat(43));
+  });
+
+  it("does not try to burn a malformed code", async () => {
+    await callback(callbackRequest("code=not-a-code&state=x"));
+    expect(mockRevoke).not.toHaveBeenCalled();
+  });
+
+  it("is 404 unless the provider is hub", async () => {
+    mockProvider.value = "none";
+    const res = await callback(callbackRequest(`code=${CODE}&state=x`));
+    expect(res.status).toBe(404);
+    expect(mockRevoke).not.toHaveBeenCalled();
+  });
+});
+
+describe("POST /api/hub-session/sign-out", () => {
+  function sessionCookie(): string {
+    const sealed = seal(
+      { v: 1, accessToken: CREDENTIAL, expiresAt: Date.now() + 60_000, user: USER },
+      SESSION_SECRET,
+      "session",
+      "ailk-hub-session",
+    );
+    return `ailk-hub-session=${sealed}`;
+  }
+
+  function post(headers: Record<string, string>): Promise<Response> {
+    return signOut(
+      new Request(`${SITE}/api/hub-session/sign-out`, {
+        method: "POST",
+        headers: { cookie: sessionCookie(), ...headers },
+      }),
+    );
+  }
+
+  it("same-origin: revokes the credential at the hub, clears the cookie and answers 204", async () => {
+    const res = await post({ "sec-fetch-site": "same-origin", origin: SITE });
+    expect(res.status).toBe(204);
+    expect(mockRevoke).toHaveBeenCalledTimes(1);
+    expect(mockRevoke).toHaveBeenCalledWith(CLIENT, { accessToken: CREDENTIAL });
+    expect(setCookies(res)).toEqual([
+      "ailk-hub-session=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0",
+    ]);
+  });
+
+  it("AC-5: refuses Sec-Fetch-Site cross-site with 403, revoking nothing", async () => {
+    const res = await post({ "sec-fetch-site": "cross-site" });
+    expect(res.status).toBe(403);
+    expect(mockRevoke).not.toHaveBeenCalled();
+    expect(setCookies(res)).toEqual([]);
+  });
+
+  it("AC-5: refuses a foreign Origin with 403, revoking nothing", async () => {
+    const res = await post({ origin: "https://evil.example.com" });
+    expect(res.status).toBe(403);
+    expect(mockRevoke).not.toHaveBeenCalled();
+  });
+
+  it("refuses a request carrying neither header", async () => {
+    expect((await post({})).status).toBe(403);
+    expect(mockRevoke).not.toHaveBeenCalled();
+  });
+
+  it("still signs out when the hub cannot be reached", async () => {
+    mockRevoke.mockRejectedValue(new Error("network"));
+    const res = await post({ "sec-fetch-site": "same-origin" });
+    expect(res.status).toBe(204);
+    expect(setCookies(res)[0]).toMatch(/Max-Age=0/);
+  });
+
+  it("is 404 unless the provider is hub", async () => {
+    mockProvider.value = "site";
+    expect((await post({ "sec-fetch-site": "same-origin" })).status).toBe(404);
+  });
+});

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

@@ -0,0 +1,168 @@
+/**
+ * Finish a sign-in through the hub (#7894 D2, D7) — `GET /api/hub-session/callback?code=…&state=…`.
+ *
+ * The URI an operator registers on the hub (`spokes sign-in-client
+ * --redirect-uri <site>/api/hub-session/callback`). It reads and clears the
+ * flow cookie, checks the returned `state` against it in constant time, and
+ * exchanges the code, the PKCE verifier and the client secret at the hub API
+ * (the api-client adds this site's spoke key; the hub requires both). On
+ * success the credential and its person are sealed into the session cookie,
+ * whose `Max-Age` is the credential's own lifetime, and the visitor lands on
+ * the flow cookie's `next` — never on a value from this request's query.
+ *
+ * Every other outcome — no flow cookie, an expired one, a state mismatch, an
+ * `error` from the hub, a failed exchange — lands on `/account` (its gate
+ * offers to try again) after BURNING any code it received
+ * (`hubSignIn.revoke({ code })`, best-effort): a code this route cannot
+ * complete must not stay live for someone else to complete (SEC-7894-4).
+ * The log line names the reason only — never the query string, a code, a
+ * state or a credential.
+ */
+import { timingSafeEqual } from "node:crypto";
+
+import { hubSignIn } from "@working-theory/api-client";
+import { hubAuthorizationCodeSchema } from "@working-theory/validation";
+
+import {
+  type HubSessionConfig,
+  hubSessionConfig,
+} from "../../../../lib/hub-session/config";
+import { seal, unseal } from "../../../../lib/hub-session/seal";
+import {
+  HUB_SESSION_FALLBACK_PATH,
+  type HubSessionPayload,
+  cookieHeader,
+  flowCookieName,
+  hubNextPath,
+  readCookie,
+  sessionCookieName,
+} from "../../../../lib/hub-session/session";
+import { SIGN_IN_PROVIDER } from "../../../../lib/topology.generated";
+
+/** The longest session the spoke keeps — the hub's own credential lifetime (spec 7894 D5). */
+const MAX_SESSION_SECONDS = 86_400;
+
+/** What the sign-in route sealed into the flow cookie. */
+interface FlowPayload {
+  v: 1;
+  state: string;
+  verifier: string;
+  next: string;
+  expiresAt: number;
+}
+
+function isFlow(value: unknown): value is FlowPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v["v"] === 1 &&
+    typeof v["state"] === "string" &&
+    typeof v["verifier"] === "string" &&
+    typeof v["next"] === "string" &&
+    typeof v["expiresAt"] === "number"
+  );
+}
+
+function see(location: string, setCookies: readonly string[]): Response {
+  const headers = new Headers({
+    Location: location,
+    "Cache-Control": "no-store",
+    "Referrer-Policy": "no-referrer",
+  });
+  for (const value of setCookies) headers.append("Set-Cookie", value);
+  return new Response(null, { status: 303, headers });
+}
+
+function sameState(a: string, b: string): boolean {
+  const x = Buffer.from(a, "utf8");
+  const y = Buffer.from(b, "utf8");
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/** Burn a code this route cannot complete. Best-effort: a failure is logged, never thrown. */
+async function burn(config: HubSessionConfig, code: string | null): Promise<void> {
+  if (code === null || !hubAuthorizationCodeSchema.safeParse(code).success) {
+    return;
+  }
+  try {
+    await hubSignIn.revoke(
+      { clientId: config.clientId, clientSecret: config.clientSecret },
+      { code },
+    );
+  } catch (err) {
+    console.error(
+      `[hub-session] code burn failed errName=${err instanceof Error ? err.name : "unknown"}`,
+    );
+  }
+}
+
+// platform-decisions-waiver: api-versioning — sign-in redirect endpoint, not a versioned API contract (spec 7894 §7)
+export async function GET(request: Request): Promise<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 params = new URL(request.url).searchParams;
+  const code = params.get("code");
+  const flowName = flowCookieName(config);
+  const clearFlow = cookieHeader(flowName, "", 0, config);
+
+  const refuse = async (reason: string): Promise<Response> => {
+    await burn(config, code);
+    console.warn(`[hub-session] sign-in not completed reason=${reason}`);
+    return see(HUB_SESSION_FALLBACK_PATH, [clearFlow]);
+  };
+
+  const sealed = readCookie(request.headers.get("cookie"), flowName);
+  const flow =
+    sealed === undefined
+      ? null
+      : unseal(sealed, config.sessionSecret, "flow", flowName);
+  if (!isFlow(flow)) return refuse("no_flow");
+  if (flow.expiresAt <= Date.now()) return refuse("flow_expired");
+  const state = params.get("state");
+  if (state === null || !sameState(state, flow.state)) {
+    return refuse("state_mismatch");
+  }
+  if (params.has("error")) return refuse("hub_error");
+  if (code === null) return refuse("no_code");
+
+  let exchanged: Awaited<ReturnType<typeof hubSignIn.exchange>>;
+  try {
+    exchanged = await hubSignIn.exchange(
+      { clientId: config.clientId, clientSecret: config.clientSecret },
+      { code, redirectUri: config.redirectUri, codeVerifier: flow.verifier },
+    );
+  } catch {
+    return refuse("exchange_failed");
+  }
+  if (!exchanged.ok) return refuse(`exchange_status_${exchanged.status}`);
+
+  const { accessToken, expiresIn, user } = exchanged.body;
+  // The cookie's lifetime is the credential's: a malformed answer from the
+  // hub must never yield a session that does not expire.
+  if (!Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > MAX_SESSION_SECONDS) {
+    return refuse("token_response_invalid");
+  }
+  const payload: HubSessionPayload = {
+    v: 1,
+    accessToken,
+    expiresAt: Date.now() + expiresIn * 1000,
+    user: {
+      name: user.name,
+      email: user.email,
+      emailVerified: user.emailVerified,
+      createdAt: user.createdAt,
+    },
+  };
+  const sessionName = sessionCookieName(config);
+  return see(hubNextPath(flow.next), [
+    clearFlow,
+    cookieHeader(
+      sessionName,
+      seal(payload, config.sessionSecret, "session", sessionName),
+      expiresIn,
+      config,
+    ),
+  ]);
+}