create-ailk 0.14.0 → 0.16.0

package/templates/apps/web/lib/account-config.ts

@@ -32,22 +32,41 @@
 // failure rejects — a 401/403 for a verified email included — so the area
 // shows an error row with Retry instead of an empty Inbox (D12). Scheduled
 // (the old Upcoming) stays empty in the base area; a module fills it.
+//
+// The member area's spoke leg (#7920) — the client's own records on the hub,
+// read by a spoke that signs its clients in through the hub (#7877, #7894):
+//
+//   - Inbox kinds `piece` (`GET /v1/member/pieces`) and `message`
+//     (`GET /v1/member/messages`). A message with a file has a file action to
+//     this site's own member file read, `account/inbox/message/[id]/file`,
+//     which re-serves the hub's bytes — the browser holds no hub credential.
+//   - For-you source `piece-needs-client` — each piece waiting on the client,
+//     with an Open action to its Inbox row. It shares the pieces read.
+//
+// The hub admits these reads only with the client's hub credential, which
+// `ctx.init` carries as `Authorization` on such a spoke and nowhere else. On a
+// cookie-session site (a hub, or a site with its own sign-in) there is none,
+// so the three make no call and load `[]` — inert, never an error row.
 
 import {
   flowCheckouts,
+  member,
   subscription,
   waitlistSignups,
   type FlowCheckoutMeItem,
   type WaitlistSignupMeResponse,
 } from "@working-theory/api-client";
 import type {
+  AccountContext,
   AccountForYouSource,
   AccountInboxKind,
   AccountSettingsSection,
   AccountUser,
 } from "@working-theory/templates/account";
 import { localeHref } from "@working-theory/ui";
+import type { MemberMessage, MemberPiece } from "@working-theory/validation";
 import { formatMoney, formatNumber } from "@working-theory/web-i18n";
+import { cache } from "react";
 
 import { unwrapApiResult } from "./server-api";
 
@@ -168,6 +187,92 @@ const purchase: AccountInboxKind<FlowCheckoutMeItem> = {
   },
 };
 
+// ── Member Inbox kinds (#7920) ───────────────────────────────────────────────
+
+/** Whether `init` carries the client's hub credential (see the header). */
+function hasHubCredential({ init }: AccountContext): boolean {
+  return Object.keys(init.headers).some((name) => name.toLowerCase() === "authorization");
+}
+
+/** One pieces read per request — the `piece` kind and the For-you source share it. */
+const memberPieces = cache((init: AccountContext["init"]) => member.pieces(init));
+
+async function loadPieces(ctx: AccountContext): Promise<MemberPiece[]> {
+  if (!hasHubCredential(ctx)) return [];
+  return (await read(memberPieces(ctx.init), ctx.user))?.items ?? [];
+}
+
+const piece: AccountInboxKind<MemberPiece> = {
+  kind: "piece",
+  label: "pieces.heading",
+  section: "updates",
+  async load(ctx) {
+    return (await loadPieces(ctx)).map((p) => ({
+      id: p.id,
+      title: p.title,
+      at: p.updatedAt,
+      data: p,
+    }));
+  },
+  renderDetail({ data }, { locale, t }) {
+    return {
+      status: data.stage,
+      ...(data.needsClient ? { lead: t("pieces.needsClient") } : {}),
+      fields: {
+        heading: t("pieces.heading"),
+        items: [
+          { label: t("pieces.stage"), value: data.stage },
+          { label: t("pieces.createdAt"), value: formatWhen(data.createdAt, locale) },
+          { label: t("pieces.updatedAt"), value: formatWhen(data.updatedAt, locale) },
+        ],
+      },
+    };
+  },
+};
+
+const message: AccountInboxKind<MemberMessage> = {
+  kind: "message",
+  label: "messages.heading",
+  section: "updates",
+  async load(ctx) {
+    if (!hasHubCredential(ctx)) return [];
+    const messages = (await read(member.messages(ctx.init), ctx.user))?.items ?? [];
+    return messages.map((m) => ({
+      id: m.id,
+      title: m.subject,
+      at: m.createdAt,
+      data: m,
+    }));
+  },
+  renderDetail({ data }, { locale, t }) {
+    return {
+      lead: data.body,
+      ...(data.file
+        ? {
+            actions: [
+              {
+                key: "file",
+                label: t("messages.download", { filename: data.file.filename }),
+                variant: "default" as const,
+                href: localeHref(
+                  locale,
+                  `/account/inbox/message/${encodeURIComponent(data.id)}/file`,
+                ),
+              },
+            ],
+          }
+        : {}),
+      fields: {
+        heading: t("messages.heading"),
+        items: [
+          { label: t("messages.sentAt"), value: formatWhen(data.createdAt, locale) },
+          ...(data.file ? [{ label: t("messages.file"), value: data.file.filename }] : []),
+        ],
+      },
+    };
+  },
+};
+
 // ── Base For-you sources (D9 as amended, D8a) ────────────────────────────────
 
 const emailUnverified: AccountForYouSource = {
@@ -206,10 +311,33 @@ const paymentDue: AccountForYouSource = {
   },
 };
 
+// ── Member For-you source (#7920) ────────────────────────────────────────────
+
+const pieceNeedsClient: AccountForYouSource = {
+  id: "piece-needs-client",
+  async load(ctx) {
+    const { locale, t } = ctx;
+    return (await loadPieces(ctx))
+      .filter((p) => p.needsClient)
+      .map((p) => ({
+        id: `piece:${p.id}`,
+        type: { id: "piece", label: t("pieces.type"), tone: "needs-you" },
+        title: p.title,
+        // The read carries no time the piece began waiting — its last update.
+        time: { kind: "at", at: p.updatedAt },
+        action: {
+          kind: "open",
+          href: localeHref(locale, `/account/inbox/piece/${encodeURIComponent(p.id)}`),
+        },
+        dismissible: true,
+      }));
+  },
+};
+
 // ── Contributions ─────────────────────────────────────────────────────────────
 
 /** Inbox item kinds, in load order. A module appends its own. */
-export const accountInboxKinds: AccountInboxKind[] = [result, purchase];
+export const accountInboxKinds: AccountInboxKind[] = [result, purchase, piece, message];
 
 /** User-settings sections a module adds after the base ones. None in the base area. */
 export const accountSettingsSections: AccountSettingsSection[] = [];
@@ -218,4 +346,5 @@ export const accountSettingsSections: AccountSettingsSection[] = [];
 export const accountForYouSources: AccountForYouSource[] = [
   emailUnverified,
   paymentDue,
+  pieceNeedsClient,
 ];

package/templates/apps/web/lib/api-origin.generated.ts

@@ -0,0 +1,11 @@
+// api-origin.generated.ts — the browser-facing API origin this site's server reads.
+//
+// GENERATED by create-ailk for this site's topology (#7874). Do not edit:
+// every scaffold rewrites it. A hub reads NEXT_PUBLIC_AILK_API_URL as a
+// fallback API origin; a spoke (`--topology spoke`) has no browser-facing
+// API origin — its hub origin is server-only (AILK_API_URL) — so its render
+// reads no environment variable.
+
+export function browserApiOrigin(): string | undefined {
+  return process.env.NEXT_PUBLIC_AILK_API_URL;
+}

package/templates/apps/web/lib/closing-footer-path.ts

@@ -0,0 +1,50 @@
+/**
+ * Whether a page ends on the closing footer (#7797).
+ *
+ * The `closingFooterPaths` chrome knob lists route paths as the site writes
+ * them ("/about"). The visitor's pathname arrives as the middleware forwards it, so
+ * it may carry a locale prefix ("/es/about") or a trailing slash ("/about/").
+ * Both sides are reduced to the same form before they are compared, so the
+ * list names a page once however a request spells it.
+ *
+ * No Next.js import — pure functions, asserted directly by their own suite,
+ * in the `profile-back-link.ts` idiom.
+ */
+
+/** `path` without its query or fragment, any enabled-locale prefix, or trailing slashes; "/" for the root. */
+export function normalizeRoutePath(
+  path: string,
+  locales: readonly string[],
+): string {
+  const bare = path.split(/[?#]/)[0] ?? "";
+  // Compare the first segment to the locale list rather than building a
+  // pattern from it, so a locale code is never read as regex syntax.
+  const segments = bare.split("/");
+  const first = segments[1];
+  const unprefixed =
+    first !== undefined && locales.includes(first)
+      ? ["", ...segments.slice(2)].join("/")
+      : bare;
+  const trimmed = unprefixed.replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed;
+}
+
+/**
+ * True when `pathname` is one of `paths` and is not the home.
+ *
+ * Fail-safe direction: an absent or empty list, or an absent pathname, answers
+ * `false`, so a site that sets no list renders exactly as before. The home is
+ * never an inner page, so listing "/" has no effect — the home's footer is its
+ * own knobs' (`home`, `chromeStyle`).
+ */
+export function isClosingFooterPath(input: {
+  pathname: string | null | undefined;
+  paths: readonly string[] | undefined;
+  locales: readonly string[];
+}): boolean {
+  const { pathname, paths, locales } = input;
+  if (!pathname || !paths || paths.length === 0) return false;
+  const current = normalizeRoutePath(pathname, locales);
+  if (current === "/") return false;
+  return paths.some((path) => normalizeRoutePath(path, locales) === current);
+}

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";