create-ailk 0.15.0 → 0.17.0

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,
+    ),
+  ]);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Start a sign-in through the hub (#7894 D2, D7) — `GET /api/hub-session/sign-in?next=<path>`.
+ *
+ * Mints a `state` and a PKCE verifier (32 random bytes each, base64url), seals
+ * them with the sanitized `next` into the flow cookie for ten minutes, and
+ * sends the visitor to the hub's `/api/auth/hub/authorize` with the S256
+ * challenge. The redirect URI is this site's configured origin plus
+ * `/api/hub-session/callback` — never derived from the request's `Host`.
+ *
+ *   - not a hub-mode spoke (`SIGN_IN_PROVIDER` is not `"hub"`): 404;
+ *   - hub mode but not configured: 303 to `/account`, whose gate says so.
+ *
+ * Nothing here logs the state, the verifier or the challenge.
+ */
+import { createHash, randomBytes } from "node:crypto";
+
+import { hubSessionConfig } from "../../../../lib/hub-session/config";
+import { seal } from "../../../../lib/hub-session/seal";
+import {
+  HUB_SESSION_FALLBACK_PATH,
+  cookieHeader,
+  flowCookieName,
+  hubNextPath,
+} from "../../../../lib/hub-session/session";
+import { SIGN_IN_PROVIDER } from "../../../../lib/topology.generated";
+
+/** How long a sign-in may take on the hub before the flow cookie expires. */
+const FLOW_TTL_SECONDS = 600;
+
+/** The hub's browser step (spec 7894 D4). */
+const AUTHORIZE_PATH = "/api/auth/hub/authorize";
+
+function see(location: string, setCookie?: string): Response {
+  const headers = new Headers({
+    Location: location,
+    "Cache-Control": "no-store",
+    "Referrer-Policy": "no-referrer",
+  });
+  if (setCookie !== undefined) headers.append("Set-Cookie", setCookie);
+  return new Response(null, { status: 303, headers });
+}
+
+// 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 state = randomBytes(32).toString("base64url");
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+
+  const name = flowCookieName(config);
+  const flow = seal(
+    { v: 1, state, verifier, next, expiresAt: Date.now() + FLOW_TTL_SECONDS * 1000 },
+    config.sessionSecret,
+    "flow",
+    name,
+  );
+
+  const authorize = new URL(AUTHORIZE_PATH, config.hubOrigin);
+  authorize.search = new URLSearchParams({
+    response_type: "code",
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    state,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+  }).toString();
+
+  return see(
+    authorize.toString(),
+    cookieHeader(name, flow, FLOW_TTL_SECONDS, config),
+  );
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Sign out of a spoke that signs in through its hub (#7894 D7) — `POST /api/hub-session/sign-out`.
+ *
+ * The signed-in Nav's "Sign out" posts here (`SIGN_OUT_ENDPOINT`). It revokes
+ * the credential at the hub (best-effort: a hub that cannot be reached still
+ * leaves the visitor signed out here), clears the session cookie and answers
+ * 204.
+ *
+ * Same-origin only: a `Sec-Fetch-Site` other than `same-origin`, an `Origin`
+ * that is not this site's configured origin, or a request carrying neither is
+ * refused 403 before anything is revoked, so another site cannot sign a
+ * visitor out. POST only — Next answers 405 to any other method.
+ */
+import { hubSignIn } from "@working-theory/api-client";
+
+import { hubSessionConfig } from "../../../../lib/hub-session/config";
+import {
+  cookieHeader,
+  readHubSessionPayload,
+  sessionCookieName,
+} from "../../../../lib/hub-session/session";
+import { SIGN_IN_PROVIDER } from "../../../../lib/topology.generated";
+
+/** Whether `request` comes from a page on `siteOrigin`. */
+function isSameOrigin(request: Request, siteOrigin: string | null): boolean {
+  const fetchSite = request.headers.get("sec-fetch-site");
+  const origin = request.headers.get("origin");
+  if (fetchSite === null && origin === null) return false;
+  if (fetchSite !== null && fetchSite !== "same-origin") return false;
+  if (origin !== null && origin !== siteOrigin) return false;
+  return true;
+}
+
+// platform-decisions-waiver: api-versioning — sign-in redirect endpoint, not a versioned API contract (spec 7894 §7)
+export async function POST(request: Request): Promise<Response> {
+  if (SIGN_IN_PROVIDER !== "hub") return new Response(null, { status: 404 });
+  const config = hubSessionConfig();
+  if (!isSameOrigin(request, config?.siteOrigin ?? null)) {
+    return new Response(null, { status: 403 });
+  }
+  if (config === null) return new Response(null, { status: 204 });
+
+  const payload = readHubSessionPayload(request.headers);
+  if (payload !== null) {
+    try {
+      await hubSignIn.revoke(
+        { clientId: config.clientId, clientSecret: config.clientSecret },
+        { accessToken: payload.accessToken },
+      );
+    } catch (err) {
+      console.error(
+        `[hub-session] revoke failed errName=${err instanceof Error ? err.name : "unknown"}`,
+      );
+    }
+  }
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "Cache-Control": "no-store",
+      "Set-Cookie": cookieHeader(sessionCookieName(config), "", 0, config),
+    },
+  });
+}