create-ailk 0.15.0 → 0.17.0

package/templates/apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx

@@ -0,0 +1,90 @@
+// signed-out-gate.generated.tsx — what the (authed) group shows a signed-out visitor.
+//
+// GENERATED by create-ailk for this site's topology and sign-in mode (#7894).
+// Do not edit: every scaffold rewrites it. A hub renders its own sign-in —
+// the operator gate, or the account area's member gate; a spoke that signs in
+// through its hub (`--hub-sign-in`) renders the hub-session gate.
+import { localeHref } from "@working-theory/ui";
+import { Button, Heading, Link, Text } from "@working-theory/ui/primitives";
+import type { AuthPanelProvider } from "@working-theory/ui/sections";
+import { readLocales } from "@working-theory/web-i18n";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { resolveSignInCardText } from "../(auth)/sign-in/sign-in-text";
+import { getActiveProviderIds } from "../../../lib/auth-env";
+import { isAccountPath } from "../../../lib/auth-routes";
+
+import { SignInGate } from "./sign-in-gate";
+
+const SUPPORTED_PROVIDERS: readonly AuthPanelProvider[] = ["google", "github"];
+
+export interface SignedOutGateProps {
+  locale: string;
+  /** The incoming request's headers (`x-pathname` names the requested page). */
+  requestHeaders: Headers;
+}
+
+export async function SignedOutGate({
+  locale,
+  requestHeaders,
+}: SignedOutGateProps): Promise<ReactElement> {
+  // No `x-pathname`, no locale read: a render outside the middleware keeps
+  // the operator gate without touching the locale config.
+  const pathname = requestHeaders.get("x-pathname");
+  const isAccount =
+    pathname !== null && isAccountPath(pathname, readLocales());
+  const t = await getTranslations({
+    locale,
+    namespace: isAccount ? "account.gate" : "waitlistDashboard.gate",
+  });
+  const active = getActiveProviderIds();
+  const emailLink = active.includes("magic-link")
+    ? { text: await resolveSignInCardText(locale) }
+    : undefined;
+  const providers = active.filter((id): id is AuthPanelProvider =>
+    (SUPPORTED_PROVIDERS as readonly string[]).includes(id),
+  );
+  const signInPath = localeHref(locale, "/sign-in");
+
+  if (isAccount && providers.length === 0 && !emailLink) {
+    return (
+      <div
+        className="flex min-h-screen flex-col items-center justify-center gap-4 py-section text-center"
+        data-testid="account-sign-in-gate"
+      >
+        <Heading level={1} visual={4}>
+          {t("emptyHeadline")}
+        </Heading>
+        <Text variant="body-sm" tone="muted" className="max-w-xs">
+          {t("emptyDescription")}
+        </Text>
+        {/* With no sign-in method on, /sign-in has nothing for a member
+            either, so the one action goes back to the site. Outline
+            action, 44px on a phone and 36px from md up. */}
+        <Button asChild variant="secondary" className="max-md:min-h-11">
+          <Link
+            href={localeHref(locale, "/")}
+            variant="bare"
+            data-testid="account-sign-in-gate-home"
+          >
+            {t("homeLink")}
+          </Link>
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <SignInGate
+      labels={{
+        emptyHeadline: t("emptyHeadline"),
+        emptyDescription: t("emptyDescription"),
+        signInLinkLabel: t("signInLink"),
+      }}
+      signInPath={signInPath}
+      providers={providers}
+      {...(emailLink ? { emailLink } : {})}
+    />
+  );
+}

package/templates/apps/web/app/[locale]/layout.tsx

@@ -69,7 +69,12 @@ import "../../lib/site-identity";
 // (#7521). Inert without AILK_LISTING_PUBLIC_KEY or the paid package.
 import "../../lib/listings";
 import { siteThemeHead } from "../../lib/site-theme-head";
-import { SIGN_IN_ENABLED, readSession } from "../../lib/topology.generated";
+import {
+  SIGN_IN_PATH,
+  SIGN_OUT_ENDPOINT,
+  SIGN_UP_PATH,
+  readSession,
+} from "../../lib/topology.generated";
 import { resolveBaseUrl } from "../../src/lib/routes";
 
 import { readSiteContactLines } from "./contact/site-contact-lines";
@@ -361,16 +366,22 @@ export default async function LocaleLayout({
   // above).
   // The signed-out auth pair, shared by the header (every page but the deck
   // home) and the deck home's closing footer slide (#7718 D4).
-  // A spoke (#7426 D11) has no sign-in, so it offers no auth pair anywhere:
-  // not in the header, the deck's closing footer or a bare page's footer.
-  const authActions: readonly Extract<NavAction, { path: string }>[] =
-    SIGN_IN_ENABLED
+  // The pair comes from the generated seam (#7894 D10): a hub's /sign-in and
+  // /sign-up; a spoke that signs in through its hub has Sign in → /account
+  // (its gate starts the hub sign-in) and no Sign up; a spoke without sign-in
+  // (#7426 D11) has neither, so it offers no auth pair anywhere — not in the
+  // header, the deck's closing footer or a bare page's footer.
+  const authActions: readonly Extract<NavAction, { path: string }>[] = [
+    ...(SIGN_IN_PATH !== null
       ? [
           // NO_HAND_IMPLEMENT_OK: operator-directed live Free-template pass.
-          { labelKey: "signIn", path: "/sign-in", variant: "outline-strong" },
-          { labelKey: "signUp", path: "/sign-up", variant: "primary" },
+          { labelKey: "signIn", path: SIGN_IN_PATH, variant: "outline-strong" as const },
         ]
-      : [];
+      : []),
+    ...(SIGN_UP_PATH !== null
+      ? [{ labelKey: "signUp", path: SIGN_UP_PATH, variant: "primary" as const }]
+      : []),
+  ];
   const navActions: NavAction[] = session
     ? [
         { labelKey: "account", kind: "flow", flow: NAV_CLIENT_ACTION_FLOW },
@@ -416,12 +427,14 @@ export default async function LocaleLayout({
     ? []
     : session
       ? [{ label: tNav("account"), href: localeHref(locale, "/account") }]
-      : SIGN_IN_ENABLED
-        ? [
-            { label: tNav("signIn"), href: localeHref(locale, "/sign-in") },
-            { label: tNav("signUp"), href: localeHref(locale, "/sign-up") },
-          ]
-        : [];
+      : [
+          ...(SIGN_IN_PATH !== null
+            ? [{ label: tNav("signIn"), href: localeHref(locale, SIGN_IN_PATH) }]
+            : []),
+          ...(SIGN_UP_PATH !== null
+            ? [{ label: tNav("signUp"), href: localeHref(locale, SIGN_UP_PATH) }]
+            : []),
+        ];
 
   // A flow action needs `renderFlowTrigger`, a function — and this layout is a
   // Server Component. Nav forwards that function into NavMobileMenu ("use
@@ -749,7 +762,7 @@ export default async function LocaleLayout({
                     }}
                   />
                 ) : hasFlowAction ? (
-                  <SignedInNav {...navProps} />
+                  <SignedInNav {...navProps} signOutEndpoint={SIGN_OUT_ENDPOINT} />
                 ) : (
                   <Nav
                     {...navProps}

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

@@ -0,0 +1,295 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * Tests for the hub's authorize step (#7894, spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md D4; AC-4, AC-6).
+ *
+ * The Better Auth session read and `@working-theory/api-client`'s `hubSignIn`
+ * are the two external boundaries; both are mocked. The route's own decisions
+ * are what is under test: which query it accepts, who it sends to sign in,
+ * where a minted code goes, and what it refuses to redirect to.
+ */
+
+// --- Mocks set up BEFORE imports ---
+
+const mockGetSession = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- auth.ts is the Better Auth singleton (its adapter needs a live database); this stand-in for the session read is the repo-standard double for that boundary (see the sibling suites under app/[locale]/(authed)/account/__tests__).
+jest.mock("../../../../../../auth", () => ({
+  __esModule: true,
+  auth: {
+    api: { getSession: (...args: unknown[]) => mockGetSession(...args) },
+  },
+}));
+
+const mockCreateCode = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  hubSignIn: { createCode: (...args: unknown[]) => mockCreateCode(...args) },
+}));
+
+import { resolveNextPath } from "../../../../../[locale]/(auth)/sign-in/next-path";
+import { GET } from "../route";
+
+const HUB = "https://hub.example.com";
+const SPOKE_CALLBACK = "https://spoke.example.com/api/hub-session/callback";
+const CHALLENGE = "c".repeat(43);
+const STATE = "s".repeat(43);
+const CODE = "k".repeat(43);
+
+const ORIGINAL_ENV = process.env;
+
+function query(overrides: Record<string, string | undefined> = {}): string {
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: "spoke_abc",
+    redirect_uri: SPOKE_CALLBACK,
+    state: STATE,
+    code_challenge: CHALLENGE,
+    code_challenge_method: "S256",
+  });
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) params.delete(key);
+    else params.set(key, value);
+  }
+  return params.toString();
+}
+
+function request(
+  search: string,
+  headers: Record<string, string> = {},
+): Request {
+  return new Request(`${HUB}/api/auth/hub/authorize?${search}`, { headers });
+}
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  process.env = { ...ORIGINAL_ENV, BETTER_AUTH_URL: `${HUB}/some/base` };
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe("a malformed query is a 400 and never a redirect", () => {
+  it.each([
+    ["no client_id", { client_id: undefined }],
+    ["response_type token", { response_type: "token" }],
+    ["method plain", { code_challenge_method: "plain" }],
+    ["a short code_challenge", { code_challenge: "short" }],
+    ["no state", { state: undefined }],
+    ["a state with a delimiter", { state: "a&b=c;d e" }],
+    ["no redirect_uri", { redirect_uri: undefined }],
+  ])("%s", async (_name, overrides) => {
+    mockGetSession.mockResolvedValue({ user: { id: "u1" } });
+
+    const res = await GET(request(query(overrides)));
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("location")).toBeNull();
+    expect(res.headers.get("content-type")).toBe("application/json");
+    expect(await res.json()).toEqual({ error: "invalid_request" });
+    expect(mockCreateCode).not.toHaveBeenCalled();
+    expect(mockGetSession).not.toHaveBeenCalled();
+  });
+
+  it("a repeated key is ambiguous, so 400", async () => {
+    const res = await GET(request(`${query()}&client_id=spoke_other`));
+    expect(res.status).toBe(400);
+    expect(res.headers.get("location")).toBeNull();
+  });
+});
+
+describe("no Better Auth session", () => {
+  it("AC-4: 303 to /sign-in?next= followed by the encoded authorize path and query", async () => {
+    mockGetSession.mockResolvedValue(null);
+    const search = query();
+
+    const res = await GET(request(search));
+
+    expect(res.status).toBe(303);
+    const location = res.headers.get("location") ?? "";
+    expect(location).toBe(
+      `/sign-in?next=${encodeURIComponent(`/api/auth/hub/authorize?${search}`)}`,
+    );
+    expect(mockCreateCode).not.toHaveBeenCalled();
+  });
+
+  it("AC-6: the next value is a same-origin path the sign-in card keeps (resolveNextPath)", async () => {
+    mockGetSession.mockResolvedValue(null);
+
+    const res = await GET(request(query()));
+
+    const next =
+      new URL(res.headers.get("location") ?? "", HUB).searchParams.get(
+        "next",
+      ) ?? "";
+    expect(next.startsWith("/api/auth/hub/authorize?")).toBe(true);
+    // Unchanged — not the fallback — so Better Auth is handed it as the callback
+    // for Google and for the emailed link alike.
+    expect(resolveNextPath(next, "/account")).toBe(next);
+    expect(next).not.toMatch(/^https?:/);
+  });
+});
+
+describe("a signed-in person", () => {
+  beforeEach(() => {
+    mockGetSession.mockResolvedValue({ user: { id: "u1" } });
+  });
+
+  it("AC-4: 303 to the REGISTERED redirect URI with the code and the same state", async () => {
+    mockCreateCode.mockResolvedValue({
+      ok: true,
+      body: { code: CODE, redirectUri: SPOKE_CALLBACK },
+    });
+
+    const res = await GET(
+      request(query(), { cookie: "better-auth.session_token=tok" }),
+    );
+
+    expect(res.status).toBe(303);
+    const target = new URL(res.headers.get("location") ?? "");
+    expect(`${target.origin}${target.pathname}`).toBe(SPOKE_CALLBACK);
+    expect(target.searchParams.get("code")).toBe(CODE);
+    expect(target.searchParams.get("state")).toBe(STATE);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    expect(res.headers.get("referrer-policy")).toBe("no-referrer");
+  });
+
+  it("forwards the visitor's cookie and the hub's pinned origin to the API — nothing else", async () => {
+    mockCreateCode.mockResolvedValue({
+      ok: true,
+      body: { code: CODE, redirectUri: SPOKE_CALLBACK },
+    });
+
+    await GET(
+      request(query(), {
+        cookie: "better-auth.session_token=tok",
+        origin: "https://evil.example",
+      }),
+    );
+
+    expect(mockCreateCode).toHaveBeenCalledWith(
+      {
+        clientId: "spoke_abc",
+        redirectUri: SPOKE_CALLBACK,
+        codeChallenge: CHALLENGE,
+      },
+      { headers: { cookie: "better-auth.session_token=tok", origin: HUB } },
+    );
+  });
+
+  it("AC-4: a redirect_uri the API does not register is a 400 with NO Location header", async () => {
+    mockCreateCode.mockResolvedValue({
+      ok: false,
+      status: 400,
+      body: {
+        ok: false,
+        error: { code: "invalid_redirect_uri", message: "x" },
+      },
+    });
+
+    const res = await GET(
+      request(
+        query({
+          redirect_uri: "https://attacker.example.com/api/hub-session/callback",
+        }),
+      ),
+    );
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("location")).toBeNull();
+    expect(await res.json()).toEqual({ error: "invalid_request" });
+  });
+
+  it("redirects to the URI the API echoed, never to the query's own", async () => {
+    // A (hypothetical) API answer for a different URI than the query named.
+    mockCreateCode.mockResolvedValue({
+      ok: true,
+      body: { code: CODE, redirectUri: SPOKE_CALLBACK },
+    });
+
+    const res = await GET(
+      request(
+        query({
+          redirect_uri: "https://attacker.example.com/api/hub-session/callback",
+        }),
+      ),
+    );
+
+    expect(new URL(res.headers.get("location") ?? "").origin).toBe(
+      "https://spoke.example.com",
+    );
+  });
+
+  it("answers 503, not a redirect, when the API echoes a URI that does not parse", async () => {
+    mockCreateCode.mockResolvedValue({
+      ok: true,
+      body: { code: CODE, redirectUri: "not a url" },
+    });
+
+    const res = await GET(request(query()));
+
+    expect(res.status).toBe(503);
+    expect(res.headers.get("location")).toBeNull();
+  });
+
+  it("AC-6: an unverified email goes to the hub's own /account/settings, never the spoke", async () => {
+    mockCreateCode.mockResolvedValue({
+      ok: false,
+      status: 403,
+      body: { ok: false, error: { code: "email_unverified", message: "x" } },
+    });
+
+    const res = await GET(request(query()));
+
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/account/settings");
+    expect(res.headers.get("location")).not.toContain("spoke.example.com");
+  });
+
+  it.each([
+    ["an unknown client", 400, "invalid_client"],
+    ["a rate limit", 429, "rate_limited"],
+    ["a forbidden caller", 403, "forbidden"],
+    ["an expired session", 401, "unauthorized"],
+  ])("%s is a 400, never a redirect", async (_name, status, code) => {
+    mockCreateCode.mockResolvedValue({
+      ok: false,
+      status,
+      body: { ok: false, error: { code, message: "x" } },
+    });
+
+    const res = await GET(request(query()));
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("location")).toBeNull();
+  });
+
+  it("answers 503 — not a redirect — when the API cannot be reached", async () => {
+    mockCreateCode.mockRejectedValue(new Error("network"));
+
+    const res = await GET(request(query()));
+
+    expect(res.status).toBe(503);
+    expect(res.headers.get("location")).toBeNull();
+    expect(await res.json()).toEqual({ error: "temporarily_unavailable" });
+  });
+
+  it.each([
+    ["unset", undefined],
+    ["not a URL", "not a url"],
+  ])(
+    "answers 503 when BETTER_AUTH_URL is %s (no pinned origin to send)",
+    async (_name, value) => {
+      if (value === undefined) delete process.env.BETTER_AUTH_URL;
+      else process.env.BETTER_AUTH_URL = value;
+
+      const res = await GET(request(query()));
+
+      expect(res.status).toBe(503);
+      expect(mockCreateCode).not.toHaveBeenCalled();
+    },
+  );
+});

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