create-ailk 0.15.0 → 0.16.0

package/templates/apps/web/lib/hub-session/__tests__/hub-session.test.ts

@@ -0,0 +1,262 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The spoke's hub-session module (#7894 D7, D12, D13; spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md AC-5, AC-7, AC-8).
+ *
+ * Covers the sealed cookie (a value sealed under a key derived from the
+ * CLIENT secret never opens — AC-5), the configuration, the session read, the
+ * one request-init re-target `forwardedCookieInit()` makes on a hub-mode spoke
+ * (AC-7), and the buyer read that never trusts the cookie for a customer id
+ * (AC-8). The api-client's `hubSignIn` is the one external boundary mocked.
+ */
+
+import { createCipheriv, hkdfSync, randomBytes } from "node:crypto";
+
+const mockMe = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  hubSignIn: { me: (...args: unknown[]) => mockMe(...args) },
+}));
+
+const mockHeaders = jest.fn();
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  headers: (...args: unknown[]) => mockHeaders(...args),
+  cookies: jest.fn(),
+}));
+
+// 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("../../topology.generated", () => ({
+  __esModule: true,
+  SIGN_IN_PROVIDER: "hub",
+}));
+
+import { forwardedCookieInit } from "../../server-api";
+import { hubSessionConfig } from "../config";
+import { seal, unseal } from "../seal";
+import {
+  type HubSessionPayload,
+  hubNextPath,
+  hubSessionBuyer,
+  hubSessionInit,
+  readHubSession,
+  sessionCookieName,
+} from "../session";
+
+const ENV = process.env;
+const SESSION_SECRET = "s".repeat(43);
+const CLIENT_SECRET = `ailk_hcs_${"c".repeat(43)}`;
+const CREDENTIAL = `ailk_hst_${"t".repeat(43)}`;
+const COOKIE = "ailk-hub-session";
+
+const USER = {
+  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: "https://hub.example.com",
+    AILK_HUB_CLIENT_ID: "spoke_0001",
+    AILK_HUB_CLIENT_SECRET: CLIENT_SECRET,
+    AILK_HUB_SESSION_SECRET: SESSION_SECRET,
+    NEXT_PUBLIC_BASE_URL: "http://127.0.0.1:3100",
+    ...overrides,
+  };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) delete process.env[key];
+  }
+}
+
+function payload(overrides: Partial<HubSessionPayload> = {}): HubSessionPayload {
+  return {
+    v: 1,
+    accessToken: CREDENTIAL,
+    expiresAt: Date.now() + 60_000,
+    user: USER,
+    ...overrides,
+  };
+}
+
+function headersWith(value: string, name = COOKIE): Headers {
+  return new Headers({ cookie: `other=1; ${name}=${value}` });
+}
+
+beforeEach(() => {
+  configure();
+  mockMe.mockReset();
+  mockHeaders.mockReset();
+});
+
+afterAll(() => {
+  process.env = ENV;
+});
+
+describe("seal", () => {
+  it("round-trips a value for the same secret, purpose and cookie name", () => {
+    const sealed = seal({ a: 1 }, SESSION_SECRET, "session", COOKIE);
+    expect(unseal(sealed, SESSION_SECRET, "session", COOKIE)).toEqual({ a: 1 });
+  });
+
+  it("opens nothing under another secret, purpose or cookie name, or altered", () => {
+    const sealed = seal({ a: 1 }, SESSION_SECRET, "session", COOKIE);
+    expect(unseal(sealed, "x".repeat(43), "session", COOKIE)).toBeNull();
+    expect(unseal(sealed, SESSION_SECRET, "flow", COOKIE)).toBeNull();
+    expect(unseal(sealed, SESSION_SECRET, "session", "ailk-hub-flow")).toBeNull();
+    const flipped = Buffer.from(sealed, "base64url");
+    flipped[flipped.length - 1] = (flipped[flipped.length - 1] ?? 0) ^ 1;
+    expect(unseal(flipped.toString("base64url"), SESSION_SECRET, "session", COOKIE)).toBeNull();
+    expect(unseal("", SESSION_SECRET, "session", COOKIE)).toBeNull();
+  });
+
+  it("uses a fresh IV per seal", () => {
+    expect(seal({ a: 1 }, SESSION_SECRET, "session", COOKIE)).not.toBe(
+      seal({ a: 1 }, SESSION_SECRET, "session", COOKIE),
+    );
+  });
+});
+
+describe("hubSessionConfig", () => {
+  it("reads the four variables and the site origin; the redirect URI is the site's, never a header's", () => {
+    expect(hubSessionConfig()).toEqual({
+      hubOrigin: "https://hub.example.com",
+      clientId: "spoke_0001",
+      clientSecret: CLIENT_SECRET,
+      sessionSecret: SESSION_SECRET,
+      siteOrigin: "http://127.0.0.1:3100",
+      redirectUri: "http://127.0.0.1:3100/api/hub-session/callback",
+      secure: false,
+    });
+  });
+
+  it("is secure on an https site", () => {
+    configure({ NEXT_PUBLIC_BASE_URL: "https://spoke.example.com/" });
+    expect(hubSessionConfig()).toMatchObject({
+      siteOrigin: "https://spoke.example.com",
+      secure: true,
+    });
+    expect(sessionCookieName({ secure: true })).toBe("__Host-ailk-hub-session");
+  });
+
+  it.each([
+    ["no hub origin", { AILK_HUB_SIGN_IN_URL: undefined }],
+    ["an http hub off loopback", { AILK_HUB_SIGN_IN_URL: "http://hub.example.com" }],
+    ["a hub URL with a path", { AILK_HUB_SIGN_IN_URL: "https://hub.example.com/x" }],
+    ["no client id", { AILK_HUB_CLIENT_ID: undefined }],
+    ["no client secret", { AILK_HUB_CLIENT_SECRET: undefined }],
+    ["a short session secret", { AILK_HUB_SESSION_SECRET: "short" }],
+    ["an http site off loopback", { NEXT_PUBLIC_BASE_URL: "http://spoke.example.com" }],
+  ])("is null with %s", (_label, overrides) => {
+    configure(overrides);
+    expect(hubSessionConfig()).toBeNull();
+  });
+});
+
+describe("readHubSession", () => {
+  it("reads the person from a sealed, unexpired cookie", async () => {
+    const sealed = seal(payload(), SESSION_SECRET, "session", COOKIE);
+    await expect(readHubSession(headersWith(sealed))).resolves.toEqual({ user: USER });
+  });
+
+  it("reads null with no cookie, an expired one, or with no configuration", async () => {
+    await expect(readHubSession(new Headers())).resolves.toBeNull();
+    const expired = seal(payload({ expiresAt: Date.now() - 1 }), SESSION_SECRET, "session", COOKIE);
+    await expect(readHubSession(headersWith(expired))).resolves.toBeNull();
+    const sealed = seal(payload(), SESSION_SECRET, "session", COOKIE);
+    configure({ AILK_HUB_SESSION_SECRET: undefined });
+    await expect(readHubSession(headersWith(sealed))).resolves.toBeNull();
+  });
+
+  it("AC-5: a cookie sealed with a key derived from AILK_HUB_CLIENT_SECRET reads as null", async () => {
+    // Every way the client secret could have keyed the cookie: the module's own
+    // seal with the client secret as the session secret, and a raw HKDF of it.
+    const viaSeal = seal(payload(), CLIENT_SECRET, "session", COOKIE);
+    await expect(readHubSession(headersWith(viaSeal))).resolves.toBeNull();
+
+    const key = Buffer.from(hkdfSync("sha256", CLIENT_SECRET, Buffer.alloc(0), "ailk-hub-session/v1", 32));
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    cipher.setAAD(Buffer.from(COOKIE));
+    const body = Buffer.concat([cipher.update(JSON.stringify(payload())), cipher.final()]);
+    const forged = Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url");
+    await expect(readHubSession(headersWith(forged))).resolves.toBeNull();
+  });
+
+  it("reads null for a well-sealed value of the wrong shape", async () => {
+    const sealed = seal({ v: 2, accessToken: CREDENTIAL }, SESSION_SECRET, "session", COOKIE);
+    await expect(readHubSession(headersWith(sealed))).resolves.toBeNull();
+  });
+});
+
+describe("AC-7 — forwardedCookieInit on a hub-mode spoke", () => {
+  it("is exactly the Bearer credential signed in", async () => {
+    const sealed = seal(payload(), SESSION_SECRET, "session", COOKIE);
+    mockHeaders.mockResolvedValue(headersWith(sealed));
+    await expect(forwardedCookieInit()).resolves.toEqual({
+      headers: { authorization: `Bearer ${CREDENTIAL}` },
+    });
+    await expect(hubSessionInit()).resolves.toEqual({
+      headers: { authorization: `Bearer ${CREDENTIAL}` },
+    });
+  });
+
+  it("is exactly no header signed out — never the visitor's cookie", async () => {
+    mockHeaders.mockResolvedValue(new Headers({ cookie: "better-auth.session_token=abc" }));
+    await expect(forwardedCookieInit()).resolves.toEqual({ headers: {} });
+  });
+});
+
+describe("AC-8 — hubSessionBuyer reads the customer live, never from the cookie", () => {
+  function request(cookie?: string): Request {
+    return new Request("http://127.0.0.1:3100/api/buy", {
+      headers: cookie === undefined ? {} : { cookie: `${COOKIE}=${cookie}` },
+    });
+  }
+  const signedIn = (): Request => request(seal(payload(), SESSION_SECRET, "session", COOKIE));
+
+  it("returns the customer /me vouches for, sending the credential", async () => {
+    mockMe.mockResolvedValue({ ok: true, body: { user: USER, billingCustomerId: "cus_known" } });
+    await expect(hubSessionBuyer(signedIn())).resolves.toEqual({ customerId: "cus_known" });
+    expect(mockMe).toHaveBeenCalledWith({ headers: { authorization: `Bearer ${CREDENTIAL}` } });
+  });
+
+  it("is null with no session, without calling the hub", async () => {
+    await expect(hubSessionBuyer(request())).resolves.toBeNull();
+    expect(mockMe).not.toHaveBeenCalled();
+  });
+
+  it("is null when /me refuses the credential though the cookie is intact (a revoked credential)", async () => {
+    mockMe.mockResolvedValue({ ok: false, status: 401, body: null });
+    await expect(hubSessionBuyer(signedIn())).resolves.toBeNull();
+  });
+
+  it("is null when /me names no customer, or the read throws", async () => {
+    mockMe.mockResolvedValueOnce({ ok: true, body: { user: USER, billingCustomerId: null } });
+    await expect(hubSessionBuyer(signedIn())).resolves.toBeNull();
+    mockMe.mockRejectedValueOnce(new Error("network"));
+    await expect(hubSessionBuyer(signedIn())).resolves.toBeNull();
+  });
+});
+
+describe("hubNextPath", () => {
+  it.each([
+    ["/account", "/account"],
+    ["/fr/account/inbox?tab=x", "/fr/account/inbox?tab=x"],
+    ["https://evil.example.com/", "/account"],
+    ["//evil.example.com", "/account"],
+    ["/api/hub-session/sign-out", "/account"],
+    ["/api", "/account"],
+    ["/en/../api/hub-session/sign-in?next=/account", "/account"],
+    ["/%2e%2e/api/hub-session/sign-in", "/account"],
+    ["/\u65e5\u672c", "/account"],
+    [null, "/account"],
+  ])("%s → %s", (raw, expected) => {
+    expect(hubNextPath(raw)).toBe(expected);
+  });
+});

package/templates/apps/web/lib/hub-session/config.ts

@@ -0,0 +1,104 @@
+/**
+ * The spoke's hub-session configuration (#7894 D7) — sign-in through the hub.
+ *
+ * A spoke scaffolded with `--hub-sign-in <origin>` signs a visitor in on its
+ * hub and keeps the hub-issued credential in a sealed cookie. Everything that
+ * decides where that exchange goes is read here, from the server env, once
+ * per call:
+ *
+ *   - `AILK_HUB_SIGN_IN_URL`    — the hub's WEB origin (where `/sign-in` and
+ *                                 `/api/auth/hub/authorize` live);
+ *   - `AILK_HUB_CLIENT_ID`      — this spoke's client id (its `Spoke.id`);
+ *   - `AILK_HUB_CLIENT_SECRET`  — the secret `spokes sign-in-client` printed;
+ *   - `AILK_HUB_SESSION_SECRET` — this site's own cookie key material (at
+ *                                 least 32 characters). It never derives from
+ *                                 the client secret (`seal.ts`).
+ *
+ * The site's own origin is `resolveBaseUrl()` — `NEXT_PUBLIC_BASE_URL`, else
+ * the site's `baseUrl` — never a request header, so a forged `Host` cannot move
+ * the redirect URI. Any input missing or malformed reads as "not configured"
+ * (`null`): the routes then send the visitor back to `/account` and the gate
+ * says sign-in is not set up, rather than starting a flow that cannot finish.
+ */
+
+import { resolveBaseUrl } from "../../src/lib/routes";
+
+/** The path the hub redirects back to — the one an operator registers (D3). */
+export const HUB_SESSION_CALLBACK_PATH = "/api/hub-session/callback";
+
+/** Hosts an origin may use over plain `http:` (the api-client's loopback set). */
+const LOOPBACK_HOSTS: readonly string[] = ["localhost", "127.0.0.1"];
+
+/** The shortest `AILK_HUB_SESSION_SECRET` this module accepts. */
+const MIN_SESSION_SECRET_LENGTH = 32;
+
+export interface HubSessionConfig {
+  /** The hub's web origin, normalized (no trailing slash). */
+  hubOrigin: string;
+  clientId: string;
+  clientSecret: string;
+  sessionSecret: string;
+  /** This site's own origin. */
+  siteOrigin: string;
+  /** `<siteOrigin>/api/hub-session/callback`. */
+  redirectUri: string;
+  /** Whether the site origin is https — the cookies are then `__Host-` and `Secure`. */
+  secure: boolean;
+}
+
+/**
+ * `raw` as an https origin (or http on a loopback host), else `null`. With
+ * `originOnly`, a path other than `/`, a query, a fragment or userinfo is
+ * refused rather than dropped.
+ */
+function normalizeOrigin(
+  raw: string | undefined,
+  originOnly: boolean,
+): string | null {
+  if (raw === undefined || raw.trim() === "") return null;
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  const loopback = LOOPBACK_HOSTS.includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    return null;
+  }
+  if (url.username !== "" || url.password !== "") return null;
+  if (
+    originOnly &&
+    (url.pathname !== "/" || url.search !== "" || url.hash !== "")
+  ) {
+    return null;
+  }
+  return url.origin;
+}
+
+/** The hub-session configuration, or `null` when this site is not configured. */
+export function hubSessionConfig(): HubSessionConfig | null {
+  const hubOrigin = normalizeOrigin(process.env.AILK_HUB_SIGN_IN_URL, true);
+  const clientId = process.env.AILK_HUB_CLIENT_ID?.trim() ?? "";
+  const clientSecret = process.env.AILK_HUB_CLIENT_SECRET?.trim() ?? "";
+  const sessionSecret = process.env.AILK_HUB_SESSION_SECRET?.trim() ?? "";
+  const siteOrigin = normalizeOrigin(resolveBaseUrl(), false);
+  if (
+    hubOrigin === null ||
+    siteOrigin === null ||
+    clientId === "" ||
+    clientSecret === "" ||
+    sessionSecret.length < MIN_SESSION_SECRET_LENGTH
+  ) {
+    return null;
+  }
+  return {
+    hubOrigin,
+    clientId,
+    clientSecret,
+    sessionSecret,
+    siteOrigin,
+    redirectUri: `${siteOrigin}${HUB_SESSION_CALLBACK_PATH}`,
+    secure: siteOrigin.startsWith("https:"),
+  };
+}

package/templates/apps/web/lib/hub-session/index.ts

@@ -0,0 +1,23 @@
+/**
+ * The spoke's hub-client module (#7894 D7) — sign-in through the hub, with no
+ * database. It imports no spoke removal seed and no `(auth)` file, so a spoke
+ * keeps it (create-ailk's closure guard proves that, spec 7894 D9).
+ *
+ * The signed-out gate (`sign-in-gate.tsx`) is imported by its own path from
+ * the generated gate seam, so the server-side readers below never pull a
+ * React tree into the modules that call them.
+ */
+
+export {
+  HUB_SESSION_CALLBACK_PATH,
+  type HubSessionConfig,
+  hubSessionConfig,
+} from "./config";
+export {
+  type HubSessionPayload,
+  type HubSessionUser,
+  hubNextPath,
+  hubSessionBuyer,
+  hubSessionInit,
+  readHubSession,
+} from "./session";

package/templates/apps/web/lib/hub-session/seal.ts

@@ -0,0 +1,82 @@
+/**
+ * Sealed cookie values for the spoke's hub session (#7894 D7).
+ *
+ * AES-256-GCM with a fresh 12-byte IV per seal. The key is HKDF-SHA256 of
+ * `AILK_HUB_SESSION_SECRET` with one info string per cookie purpose, so the
+ * session cookie and the flow cookie never share a key, and the cookie's NAME
+ * is the additional authenticated data, so a value sealed for one cookie never
+ * opens as the other. The key never derives from the client secret: a leaked
+ * client secret forges no spoke session.
+ *
+ * Wire form: base64url(iv ‖ tag ‖ ciphertext). Anything that does not open —
+ * a wrong key, a wrong name, a truncated or altered value — reads as `null`,
+ * never a throw. Node `crypto` only; no dependency.
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes,
+} from "node:crypto";
+
+/** The two things this module seals, each under its own derived key. */
+export type SealPurpose = "session" | "flow";
+
+const INFO: Record<SealPurpose, string> = {
+  session: "ailk-hub-session/v1",
+  flow: "ailk-hub-flow/v1",
+};
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+function deriveKey(secret: string, purpose: SealPurpose): Buffer {
+  return Buffer.from(
+    hkdfSync("sha256", secret, Buffer.alloc(0), INFO[purpose], 32),
+  );
+}
+
+/** `value` as JSON, sealed for the cookie `name`. */
+export function seal(
+  value: unknown,
+  secret: string,
+  purpose: SealPurpose,
+  name: string,
+): string {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", deriveKey(secret, purpose), iv);
+  cipher.setAAD(Buffer.from(name, "utf8"));
+  const body = Buffer.concat([
+    cipher.update(JSON.stringify(value), "utf8"),
+    cipher.final(),
+  ]);
+  return Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url");
+}
+
+/** The JSON value `sealed` holds for the cookie `name`, or `null` when it does not open. */
+export function unseal(
+  sealed: string,
+  secret: string,
+  purpose: SealPurpose,
+  name: string,
+): unknown {
+  try {
+    const raw = Buffer.from(sealed, "base64url");
+    if (raw.length <= IV_BYTES + TAG_BYTES) return null;
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      deriveKey(secret, purpose),
+      raw.subarray(0, IV_BYTES),
+    );
+    decipher.setAAD(Buffer.from(name, "utf8"));
+    decipher.setAuthTag(raw.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));
+    const text = Buffer.concat([
+      decipher.update(raw.subarray(IV_BYTES + TAG_BYTES)),
+      decipher.final(),
+    ]).toString("utf8");
+    return JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+}

package/templates/apps/web/lib/hub-session/session.ts

@@ -0,0 +1,180 @@
+/**
+ * The spoke's hub session (#7894 D7, D12, D13) — read, forwarded, never stored.
+ *
+ * A spoke that signs in through its hub has no database: after the callback
+ * route exchanges a code, the hub-issued credential and the person it names
+ * live in ONE sealed, `HttpOnly` cookie. This module is everything that reads
+ * it:
+ *
+ *   - `readHubSession(headers)` — the web seam's `readSession` on a hub-mode
+ *     spoke: unseals the cookie from the `Cookie` header, no network. Expired,
+ *     unreadable or sealed under another key ⇒ `null`.
+ *   - `hubSessionInit()` — what `forwardedCookieInit()` returns on such a
+ *     spoke: the credential as `Authorization: Bearer`, the ONE request-init
+ *     re-target the account area reads the hub through (D12). The api-client
+ *     adds the spoke key itself; the hub admits the credential only beside it.
+ *   - `hubSessionBuyer(request)` — a customer the hub vouches for at buy time
+ *     (D13): read live from `GET /v1/hub-sign-in/me`, never from the cookie.
+ *
+ * Nothing here logs a credential, a cookie value or an email.
+ */
+
+import { hubSignIn } from "@working-theory/api-client";
+import { headers as requestHeaders } from "next/headers";
+
+import { resolveNextPath } from "../next-path";
+
+import { type HubSessionConfig, hubSessionConfig } from "./config";
+import { unseal } from "./seal";
+
+/** The session cookie: `__Host-` on an https site, plain on a loopback one. */
+export function sessionCookieName(config: Pick<HubSessionConfig, "secure">): string {
+  return config.secure ? "__Host-ailk-hub-session" : "ailk-hub-session";
+}
+
+/** The flow cookie that carries state, verifier and `next` across the hub hop. */
+export function flowCookieName(config: Pick<HubSessionConfig, "secure">): string {
+  return config.secure ? "__Host-ailk-hub-flow" : "ailk-hub-flow";
+}
+
+/** The person a hub session names — the fields the account area reads. */
+export interface HubSessionUser {
+  name: string | null;
+  email: string;
+  emailVerified: boolean;
+  createdAt: string;
+}
+
+/** What the session cookie holds (sealed). */
+export interface HubSessionPayload {
+  v: 1;
+  accessToken: string;
+  /** Epoch milliseconds; the cookie's own `Max-Age` ends at the same time. */
+  expiresAt: number;
+  user: HubSessionUser;
+}
+
+/** The value of cookie `name` in a `Cookie` header, or `undefined`. */
+export function readCookie(header: string | null, name: string): string | undefined {
+  if (header === null) return undefined;
+  for (const part of header.split(";")) {
+    const at = part.indexOf("=");
+    if (at === -1) continue;
+    if (part.slice(0, at).trim() === name) return part.slice(at + 1).trim();
+  }
+  return undefined;
+}
+
+/**
+ * A `Set-Cookie` value for one of this module's cookies — always `HttpOnly`,
+ * `SameSite=Lax` (the hub's top-level redirect back must carry the flow
+ * cookie) and `Path=/`; `Secure` on an https site. `maxAge` 0 clears it.
+ */
+export function cookieHeader(
+  name: string,
+  value: string,
+  maxAge: number,
+  config: Pick<HubSessionConfig, "secure">,
+): string {
+  return [
+    `${name}=${value}`,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Lax",
+    `Max-Age=${Math.max(0, Math.floor(maxAge))}`,
+    ...(config.secure ? ["Secure"] : []),
+  ].join("; ");
+}
+
+function isPayload(value: unknown): value is HubSessionPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  const user = v["user"] as Record<string, unknown> | null | undefined;
+  return (
+    v["v"] === 1 &&
+    typeof v["accessToken"] === "string" &&
+    typeof v["expiresAt"] === "number" &&
+    typeof user === "object" &&
+    user !== null &&
+    typeof user["email"] === "string" &&
+    typeof user["emailVerified"] === "boolean" &&
+    (user["name"] === null || typeof user["name"] === "string") &&
+    typeof user["createdAt"] === "string"
+  );
+}
+
+/** The sealed session in `headers`, or `null` — not configured, absent, expired or unreadable. */
+export function readHubSessionPayload(headers: Headers): HubSessionPayload | null {
+  const config = hubSessionConfig();
+  if (config === null) return null;
+  const name = sessionCookieName(config);
+  const sealed = readCookie(headers.get("cookie"), name);
+  if (sealed === undefined || sealed === "") return null;
+  const value = unseal(sealed, config.sessionSecret, "session", name);
+  if (!isPayload(value) || value.expiresAt <= Date.now()) return null;
+  return value;
+}
+
+/** The web seam's `readSession` on a hub-mode spoke: the person, or `null`. */
+export function readHubSession(
+  headers: Headers,
+): Promise<{ user: HubSessionUser } | null> {
+  const payload = readHubSessionPayload(headers);
+  return Promise.resolve(payload === null ? null : { user: payload.user });
+}
+
+/**
+ * `forwardedCookieInit()` on a hub-mode spoke (D12): the credential as a
+ * Bearer header signed in, no header at all signed out. Never the visitor's
+ * cookie — the hub has no session for it.
+ */
+export async function hubSessionInit(): Promise<{ headers: Record<string, string> }> {
+  const payload = readHubSessionPayload(await requestHeaders());
+  return payload === null
+    ? { headers: {} }
+    : { headers: { authorization: `Bearer ${payload.accessToken}` } };
+}
+
+/**
+ * The customer the hub vouches for, for a spoke's buy route (D13): read live
+ * from `GET /v1/hub-sign-in/me` with the person's credential (the api-client
+ * adds the spoke key). `null` with no session, when the hub refuses the
+ * credential (a revoked one reads as signed out here), when it names no
+ * customer, or on any failure — a buyer is never taken from the cookie.
+ */
+export async function hubSessionBuyer(
+  request: Request,
+): Promise<{ customerId: string } | null> {
+  const payload = readHubSessionPayload(request.headers);
+  if (payload === null) return null;
+  try {
+    const res = await hubSignIn.me({
+      headers: { authorization: `Bearer ${payload.accessToken}` },
+    });
+    if (!res.ok) return null;
+    const customerId = res.body.billingCustomerId;
+    return typeof customerId === "string" && customerId !== ""
+      ? { customerId }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where to land after signing in, when `next` is missing or refused. */
+export const HUB_SESSION_FALLBACK_PATH = "/account";
+
+/**
+ * The post-sign-in path for `raw`: `resolveNextPath`'s same-origin rule,
+ * printable ASCII only (it becomes a `Location` header), and never a path
+ * that resolves under `/api` — dot segments included — so a sign-in lands on
+ * a page and never re-enters a route handler.
+ */
+export function hubNextPath(raw: unknown): string {
+  const next = resolveNextPath(raw, HUB_SESSION_FALLBACK_PATH);
+  if (!/^[\x21-\x7e]+$/.test(next)) return HUB_SESSION_FALLBACK_PATH;
+  const path = new URL(next, "http://site.invalid").pathname;
+  return path === "/api" || path.startsWith("/api/")
+    ? HUB_SESSION_FALLBACK_PATH
+    : next;
+}