create-ailk 0.18.0 → 0.19.1

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

@@ -0,0 +1,143 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The hub's sign-in continuation module (#8146 D3; spec AC-3(b), AC-4).
+ * Pure functions over `seal.ts`; no mocks.
+ */
+import { seal } from "../../../../../lib/hub-session/seal";
+import {
+  CONTINUATION_REF_MAX,
+  CONTINUATION_TTL_SECONDS,
+  CONTINUE_PATH,
+  mintContinuation,
+  openContinuation,
+} from "../continuation";
+
+const SECRET = "k".repeat(43);
+const T = 1_790_000_000_000;
+
+const Q = new URLSearchParams({
+  response_type: "code",
+  client_id: "spoke_abc",
+  redirect_uri: "https://spoke.example.com/api/hub-session/callback",
+  state: "s".repeat(43),
+  code_challenge: "c".repeat(43),
+  code_challenge_method: "S256",
+}).toString();
+
+describe("constants", () => {
+  it("pins the path, the ref cap and the 600 s life", () => {
+    expect(CONTINUE_PATH).toBe("/api/auth/hub/continue");
+    expect(CONTINUATION_REF_MAX).toBe(4096);
+    expect(CONTINUATION_TTL_SECONDS).toBe(600);
+  });
+});
+
+describe("AC-4 — the continuation lives 600 s and round-trips", () => {
+  it("opens to the query it was minted from, up to the last millisecond", () => {
+    const ref = mintContinuation(Q, SECRET, T);
+    expect(openContinuation(ref, SECRET, T + 599_000)).toBe(Q);
+    expect(openContinuation(ref, SECRET, T + 599_999)).toBe(Q);
+  });
+
+  it("is gone at exactly 600 s (exp <= now)", () => {
+    const ref = mintContinuation(Q, SECRET, T);
+    expect(openContinuation(ref, SECRET, T + 600_000)).toBeNull();
+    expect(openContinuation(ref, SECRET, T + 600_001)).toBeNull();
+  });
+
+  it("is base64url only, so no decode can change it", () => {
+    const ref = mintContinuation(Q, SECRET, T);
+    expect(ref).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(decodeURIComponent(decodeURIComponent(ref))).toBe(ref);
+    expect(ref.length).toBeLessThan(CONTINUATION_REF_MAX);
+  });
+});
+
+describe("AC-3(b) — a ref that is not ours opens to null", () => {
+  const good = mintContinuation(Q, SECRET, T);
+
+  it("flips the first character", () => {
+    const flipped = (good[0] === "A" ? "B" : "A") + good.slice(1);
+    expect(openContinuation(flipped, SECRET, T)).toBeNull();
+  });
+
+  it("sealed under another secret", () => {
+    const other = mintContinuation(Q, "x".repeat(43), T);
+    expect(openContinuation(other, SECRET, T)).toBeNull();
+  });
+
+  it('a valid payload sealed with purpose "flow" and the SAME AAD (only the key differs)', () => {
+    const forged = seal(
+      { v: 1, q: Q, exp: T + 600_000 },
+      SECRET,
+      "flow",
+      "hub-continue",
+    );
+    expect(openContinuation(forged, SECRET, T)).toBeNull();
+  });
+
+  it("a value sealed under another name never opens as a continuation", () => {
+    const forged = seal(
+      { v: 1, q: Q, exp: T + 600_000 },
+      SECRET,
+      "continue",
+      "ailk-hub-flow",
+    );
+    expect(openContinuation(forged, SECRET, T)).toBeNull();
+  });
+
+  it("exp in the past", () => {
+    const expired = seal(
+      { v: 1, q: Q, exp: T - 1 },
+      SECRET,
+      "continue",
+      "hub-continue",
+    );
+    expect(openContinuation(expired, SECRET, T)).toBeNull();
+  });
+
+  it("4097 characters", () => {
+    expect(openContinuation("A".repeat(4097), SECRET, T)).toBeNull();
+  });
+
+  it("a character outside base64url", () => {
+    expect(openContinuation(`${good}%`, SECRET, T)).toBeNull();
+    expect(openContinuation(`${good}?x=1`, SECRET, T)).toBeNull();
+    expect(openContinuation("", SECRET, T)).toBeNull();
+  });
+
+  it("the base64url of plain JSON, unsealed", () => {
+    const plain = Buffer.from(
+      JSON.stringify({ v: 1, q: Q, exp: T + 600_000 }),
+    ).toString("base64url");
+    expect(openContinuation(plain, SECRET, T)).toBeNull();
+  });
+
+  it.each([
+    ["a wrong version", { v: 2, q: Q, exp: T + 1000 }],
+    ["an empty q", { v: 1, q: "", exp: T + 1000 }],
+    ["a non-string q", { v: 1, q: 5, exp: T + 1000 }],
+    ["a non-number exp", { v: 1, q: Q, exp: "later" }],
+    ["a bare string", "hello"],
+    ["null", null],
+  ])("a sealed value with %s", (_name, value) => {
+    const ref = seal(value, SECRET, "continue", "hub-continue");
+    expect(openContinuation(ref, SECRET, T)).toBeNull();
+  });
+
+  it("re-serializes a forged q so a CR/LF is percent-encoded and never throws", () => {
+    const ref = seal(
+      { v: 1, q: "a=1\r\nX-Injected: 1", exp: T + 600_000 },
+      SECRET,
+      "continue",
+      "hub-continue",
+    );
+    const opened = openContinuation(ref, SECRET, T);
+    expect(opened).not.toBeNull();
+    expect(opened).not.toMatch(/[\r\n]/);
+    expect(() => new Headers({ Location: `/x?${opened}` })).not.toThrow();
+  });
+});

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

@@ -15,12 +15,14 @@
 // --- Mocks set up BEFORE imports ---
 
 const mockGetSession = jest.fn();
+const mockSecret = "k".repeat(43);
 // 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) },
   },
+  resolveSecret: () => mockSecret,
 }));
 
 const mockCreateCode = jest.fn();
@@ -30,9 +32,11 @@ jest.mock("@working-theory/api-client", () => ({
 }));
 
 import { resolveNextPath } from "../../../../../[locale]/(auth)/sign-in/next-path";
+import { openContinuation } from "../../continuation";
 import { GET } from "../route";
 
 const HUB = "https://hub.example.com";
+const CONTINUE = "/api/auth/hub/continue";
 const SPOKE_CALLBACK = "https://spoke.example.com/api/hub-session/callback";
 const CHALLENGE = "c".repeat(43);
 const STATE = "s".repeat(43);
@@ -102,34 +106,82 @@ describe("a malformed query is a 400 and never a redirect", () => {
 });
 
 describe("no Better Auth session", () => {
-  it("AC-4: 303 to /sign-in?next= followed by the encoded authorize path and query", async () => {
+  /** The `next` value of the 303, and the ref inside it. */
+  function continuationOf(res: Response): { next: string; ref: string } {
+    const location = res.headers.get("location") ?? "";
+    const next = new URL(location, HUB).searchParams.get("next") ?? "";
+    return { next, ref: next.slice(`${CONTINUE}/`.length) };
+  }
+
+  it("#8146 AC-1(b): 303 to /sign-in?next= followed by the encoded continue path and a sealed ref", 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}`)}`,
+    const { next, ref } = continuationOf(res);
+    expect(res.headers.get("location")).toBe(
+      `/sign-in?next=${encodeURIComponent(`${CONTINUE}/${ref}`)}`,
     );
+    expect(next).toBe(`${CONTINUE}/${ref}`);
+    expect(openContinuation(ref, mockSecret)).toBe(search);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    expect(res.headers.get("referrer-policy")).toBe("no-referrer");
     expect(mockCreateCode).not.toHaveBeenCalled();
   });
 
-  it("AC-6: the next value is a same-origin path the sign-in card keeps (resolveNextPath)", async () => {
+  it("#8146 AC-1(b): the next value is a same-origin path the sign-in card keeps (resolveNextPath) and a second decode cannot change", 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);
+    const { next } = continuationOf(res);
+    expect(next.startsWith(`${CONTINUE}/`)).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?:/);
+    // Better Auth decodes the callback a second time: nothing may change.
+    expect(next).toMatch(/^[A-Za-z0-9_/-]+$/);
+    expect(decodeURIComponent(decodeURIComponent(next))).toBe(next);
+  });
+
+  it("#8146 AC-1(b): the ref holds the canonical six-key query — a reversed query with an extra key opens to the same string, without it", async () => {
+    mockGetSession.mockResolvedValue(null);
+    const canonical = query();
+    const reversed = [...new URLSearchParams(canonical).entries()]
+      .reverse()
+      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+      .join("&");
+
+    const res = await GET(request(`${reversed}&extra=1`));
+
+    expect(res.status).toBe(303);
+    const opened = openContinuation(continuationOf(res).ref, mockSecret);
+    expect(opened).toBe(canonical);
+    expect(opened).not.toContain("extra");
+  });
+
+  it("#8146 AC-3(b): a redirect_uri whose ref would pass 4096 characters is a 400 with NO Location", async () => {
+    mockGetSession.mockResolvedValue(null);
+    const redirectUri = "https://spoke.example.com/".padEnd(2048, "/");
+
+    const res = await GET(request(query({ redirect_uri: redirectUri })));
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("location")).toBeNull();
+    expect(await res.json()).toEqual({ error: "invalid_request" });
+  });
+
+  it("#8146 AC-3(b): a 2048-character redirect_uri whose ref stays under the cap is a normal 303", async () => {
+    mockGetSession.mockResolvedValue(null);
+    const redirectUri = "https://spoke.example.com/".padEnd(2048, "a");
+
+    const res = await GET(request(query({ redirect_uri: redirectUri })));
+
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toMatch(/^\/sign-in\?next=/);
   });
 });
 

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

@@ -13,11 +13,15 @@
  *       &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);
+ *   - no Better Auth session: the six validated keys are sealed into a short
+ *     ref and the answer is a 303 to `/sign-in?next=<the same-origin path
+ *     /api/auth/hub/continue/<ref>>` (#8146). `resolveNextPath` keeps that
+ *     path and the existing sign-in card hands it to Better Auth as the
+ *     callback for Google and for the emailed link alike; the continue route
+ *     then returns the visitor here. This route's own URL is NOT the callback:
+ *     Better Auth's magic-link verify decodes a callback twice, which turns the
+ *     encoded `redirect_uri` inside it into a URL its origin check refuses. A
+ *     ref longer than `CONTINUATION_REF_MAX` is a 400, never a redirect;
  *   - 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
@@ -40,7 +44,12 @@
 import { hubSignIn } from "@working-theory/api-client";
 import { hubAuthorizeQuerySchema } from "@working-theory/validation";
 
-import { auth } from "../../../../../auth";
+import { auth, resolveSecret } from "../../../../../auth";
+import {
+  CONTINUATION_REF_MAX,
+  CONTINUE_PATH,
+  mintContinuation,
+} from "../continuation";
 
 /** The six query keys, each read exactly once. */
 const QUERY_KEYS = [
@@ -106,7 +115,13 @@ export async function GET(request: Request): Promise<Response> {
 
   const session = await auth.api.getSession({ headers: request.headers });
   if (!session) {
-    const next = `${url.pathname}${url.search}`;
+    // Only the six validated keys, in QUERY_KEYS order: a ref carries nothing
+    // that did not pass the schema, and extra or reordered keys are dropped.
+    const canonical = new URLSearchParams();
+    for (const key of QUERY_KEYS) canonical.set(key, query[key]);
+    const ref = mintContinuation(canonical.toString(), resolveSecret());
+    if (ref.length > CONTINUATION_REF_MAX) return json(400, "invalid_request");
+    const next = `${CONTINUE_PATH}/${ref}`;
     return see(`/sign-in?next=${encodeURIComponent(next)}`);
   }
 

package/templates/apps/web/app/api/auth/hub/continuation.ts

@@ -0,0 +1,73 @@
+/**
+ * The hub's sign-in continuation (#8146, spec
+ * docs/specs/8146-email-link-sign-in-from-spec.md D2, D3).
+ *
+ * Better Auth's magic-link verify decodes `callbackURL` a second time, so a
+ * callback that holds an encoded `redirect_uri` is refused as
+ * INVALID_CALLBACK_URL. The authorize step therefore does not hand the sign-in
+ * page its own URL. It seals the validated authorize query into a short,
+ * opaque ref and hands over the same-origin path `/api/auth/hub/continue/<ref>`
+ * instead. A base64url string has no `%`, `?`, `&`, `=` or `:`, so no number of
+ * decodes changes it.
+ *
+ * Sealed (AES-256-GCM, key derived from the caller's secret under its own
+ * purpose), with its expiry inside. The ref is opaque but is NOT a secret: it
+ * carries what the cleartext `next` carried before (spec § 9 SEC-8146-1).
+ * Nothing here logs a ref.
+ */
+import { seal, unseal } from "../../../../lib/hub-session/seal";
+
+/** The same-origin path a ref is appended to. */
+export const CONTINUE_PATH = "/api/auth/hub/continue";
+
+/** The longest ref the authorize step will mint, and the continue route open. */
+export const CONTINUATION_REF_MAX = 4096;
+
+/**
+ * 600 s, matching the spoke's flow cookie: a longer life is useless (the spoke
+ * refuses the callback once its flow expires) and it covers the 300 s emailed
+ * link plus time on the sign-in page.
+ */
+export const CONTINUATION_TTL_SECONDS = 600;
+
+/** A fixed name: a value sealed for a cookie never opens here, nor the reverse. */
+const AAD = "hub-continue";
+
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+
+/** `search` (the canonical authorize query, no leading `?`) as a sealed ref. */
+export function mintContinuation(
+  search: string,
+  secret: string,
+  now: number = Date.now(),
+): string {
+  return seal(
+    { v: 1, q: search, exp: now + CONTINUATION_TTL_SECONDS * 1000 },
+    secret,
+    "continue",
+    AAD,
+  );
+}
+
+/**
+ * The authorize query a ref holds, or `null` when the ref is too long, is not
+ * base64url, does not open, is not the expected shape, or has expired.
+ *
+ * The query is re-serialized through `URLSearchParams`: for what
+ * `mintContinuation` wrote that is the same string, and for a `q` forged under
+ * a known secret it percent-encodes CR/LF so a `Location` can never be split
+ * and never throws (spec § 9 SEC-8146-7).
+ */
+export function openContinuation(
+  ref: string,
+  secret: string,
+  now: number = Date.now(),
+): string | null {
+  if (ref.length > CONTINUATION_REF_MAX || !BASE64URL.test(ref)) return null;
+  const value = unseal(ref, secret, "continue", AAD);
+  if (typeof value !== "object" || value === null) return null;
+  const { v, q, exp } = value as Record<string, unknown>;
+  if (v !== 1 || typeof q !== "string" || q === "") return null;
+  if (typeof exp !== "number" || exp <= now) return null;
+  return new URLSearchParams(q).toString();
+}

package/templates/apps/web/app/api/auth/hub/continue/[ref]/__tests__/route.test.ts

@@ -0,0 +1,188 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * Tests for the hub's continue step (#8146, spec
+ * docs/specs/8146-email-link-sign-in-from-spec.md D4; AC-1(c), AC-3(b)).
+ *
+ * `auth.ts` (the Better Auth singleton: `resolveSecret`, the session read) and
+ * `@working-theory/api-client`'s `hubSignIn` are the external boundaries; both
+ * are mocked, exactly as the authorize suite does. The route's own decisions
+ * are under test: where a ref sends the visitor, and what it never does.
+ */
+
+// --- Mocks set up BEFORE imports ---
+
+const mockGetSession = jest.fn();
+const mockSecret = "k".repeat(43);
+// 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 secret and the session read is the repo-standard double for that boundary (see the authorize suite beside this one).
+jest.mock("../../../../../../../auth", () => ({
+  __esModule: true,
+  auth: {
+    api: { getSession: (...args: unknown[]) => mockGetSession(...args) },
+  },
+  resolveSecret: () => mockSecret,
+}));
+
+const mockCreateCode = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  hubSignIn: { createCode: (...args: unknown[]) => mockCreateCode(...args) },
+}));
+
+import { seal } from "../../../../../../../lib/hub-session/seal";
+import { GET as authorize } from "../../../authorize/route";
+import { mintContinuation } from "../../../continuation";
+import { GET } from "../route";
+
+const HUB = "https://hub.example.com";
+const SPOKE_CALLBACK = "https://spoke.example.com/api/hub-session/callback";
+const STATE = "s".repeat(43);
+const CODE = "k".repeat(43);
+
+const ORIGINAL_ENV = process.env;
+
+const QUERY = new URLSearchParams({
+  response_type: "code",
+  client_id: "spoke_abc",
+  redirect_uri: SPOKE_CALLBACK,
+  state: STATE,
+  code_challenge: "c".repeat(43),
+  code_challenge_method: "S256",
+}).toString();
+
+function continueTo(ref: string): Promise<Response> {
+  return GET(new Request(`${HUB}/api/auth/hub/continue/${ref}`), {
+    params: Promise.resolve({ ref }),
+  });
+}
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  process.env = { ...ORIGINAL_ENV, BETTER_AUTH_URL: HUB };
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe("AC-1(c) — a valid ref returns the visitor to the authorize step", () => {
+  it("answers 303 to /api/auth/hub/authorize with the same six-key query", async () => {
+    const res = await continueTo(mintContinuation(QUERY, mockSecret));
+
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe(
+      `/api/auth/hub/authorize?${QUERY}`,
+    );
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    expect(res.headers.get("referrer-policy")).toBe("no-referrer");
+  });
+
+  it("chained into the authorize step with a session: 303 to the registered spoke URI with the code and the original state", async () => {
+    mockGetSession.mockResolvedValue({ user: { id: "u1" } });
+    mockCreateCode.mockResolvedValue({
+      ok: true,
+      body: { code: CODE, redirectUri: SPOKE_CALLBACK },
+    });
+
+    const step = await continueTo(mintContinuation(QUERY, mockSecret));
+    const res = await authorize(
+      new Request(`${HUB}${step.headers.get("location")}`, {
+        headers: { 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);
+  });
+
+  it("reads no session itself: the authorize step decides every code", async () => {
+    await continueTo(mintContinuation(QUERY, mockSecret));
+    expect(mockGetSession).not.toHaveBeenCalled();
+    expect(mockCreateCode).not.toHaveBeenCalled();
+  });
+});
+
+describe("AC-3(b) — any other ref answers 303 /account", () => {
+  const good = mintContinuation(QUERY, mockSecret);
+  const T = Date.now();
+
+  it.each([
+    [
+      "the first character flipped",
+      (good[0] === "A" ? "B" : "A") + good.slice(1),
+    ],
+    [
+      "sealed under another secret",
+      mintContinuation(QUERY, "x".repeat(43)),
+    ],
+    [
+      'a valid payload sealed with purpose "flow" and the SAME name',
+      seal(
+        { v: 1, q: QUERY, exp: T + 600_000 },
+        mockSecret,
+        "flow",
+        "hub-continue",
+      ),
+    ],
+    ["exp in the past", mintContinuation(QUERY, mockSecret, T - 601_000)],
+    ["4097 characters", "A".repeat(4097)],
+    ["a character outside base64url", `${good}%2Fevil`],
+    [
+      "plain base64url JSON, unsealed",
+      Buffer.from(
+        JSON.stringify({ v: 1, q: QUERY, exp: T + 600_000 }),
+      ).toString("base64url"),
+    ],
+    ["an empty-looking ref", "-"],
+  ])("%s", async (_name, ref) => {
+    const res = await continueTo(ref);
+
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/account");
+    expect(res.headers.get("cache-control")).toBe("no-store");
+  });
+
+  it("a ref sealed under the test secret whose q holds CR/LF answers 303 without throwing, with no CR or LF in Location", async () => {
+    const ref = seal(
+      { v: 1, q: "a=1\r\nX-Injected: 1", exp: T + 600_000 },
+      mockSecret,
+      "continue",
+      "hub-continue",
+    );
+
+    const res = await continueTo(ref);
+
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).not.toMatch(/[\r\n]/);
+    expect(res.headers.get("x-injected")).toBeNull();
+  });
+
+  it("every Location is /account or starts with /api/auth/hub/authorize? — never `//` or a scheme", async () => {
+    const refs = [
+      good,
+      "garbage",
+      mintContinuation("redirect_uri=https://evil.example/x", mockSecret),
+      mintContinuation("//evil.example/x", mockSecret),
+      seal(
+        { v: 1, q: "https://evil.example/x", exp: T + 600_000 },
+        mockSecret,
+        "continue",
+        "hub-continue",
+      ),
+    ];
+    for (const ref of refs) {
+      const location = (await continueTo(ref)).headers.get("location") ?? "";
+      expect(
+        location === "/account" ||
+          location.startsWith("/api/auth/hub/authorize?"),
+      ).toBe(true);
+      expect(location.startsWith("//")).toBe(false);
+      expect(location).not.toMatch(/^[a-z][a-z0-9+.-]*:/i);
+    }
+  });
+});

package/templates/apps/web/app/api/auth/hub/continue/[ref]/route.ts

@@ -0,0 +1,53 @@
+/**
+ * The hub's sign-in continuation (#8146, spec
+ * docs/specs/8146-email-link-sign-in-from-spec.md D4).
+ *
+ *   GET /api/auth/hub/continue/<ref>
+ *
+ * The authorize step, for a signed-out visitor, seals the validated authorize
+ * query into `<ref>` and sends the visitor to sign in with THIS path as the
+ * destination (Better Auth decodes a callback twice, so the path must hold
+ * nothing a decode can change). After sign-in — by the emailed link or by
+ * Google — the visitor lands here, and this route sends them back to the
+ * authorize step with the original query.
+ *
+ *   - a valid, unexpired ref: 303 to `/api/auth/hub/authorize?<the query>`;
+ *   - any other ref (forged, expired, replayed past its life, unreadable): 303
+ *     to the hub's own `/account`. By then the spoke's flow cookie (600 s) has
+ *     expired too, so returning to the spoke could not finish.
+ *
+ * Both targets are fixed relative paths: this route redirects nowhere else,
+ * and never to a URL carried in the ref. It reads no session — the authorize
+ * step does that and mints the code, so every decision about a code stays in
+ * one place. It logs nothing.
+ */
+import { resolveSecret } from "../../../../../../auth";
+import { openContinuation } from "../../continuation";
+
+/** Where an unreadable ref goes: the destination the hub's own sign-in uses. */
+const FALLBACK_PATH = "/account";
+
+const AUTHORIZE_PATH = "/api/auth/hub/authorize";
+
+/** A 303 to a fixed same-origin path. */
+function see(location: string): Response {
+  return new Response(null, {
+    status: 303,
+    headers: {
+      Location: location,
+      "Cache-Control": "no-store",
+      // The authorize query rides this URL; no page may leak it through a Referer.
+      "Referrer-Policy": "no-referrer",
+    },
+  });
+}
+
+// platform-decisions-waiver: api-versioning — sign-in redirect step, not a versioned API contract (spec 8146 §7)
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ ref: string }> },
+): Promise<Response> {
+  const { ref } = await params;
+  const query = openContinuation(ref, resolveSecret());
+  return see(query === null ? FALLBACK_PATH : `${AUTHORIZE_PATH}?${query}`);
+}

package/templates/apps/web/app/robots.txt/route.ts

@@ -6,6 +6,9 @@
  *   - Sitemap location declared
  *   - Optional path disallow via AILK_ROBOTS_DISALLOW env var
  *     (comma-separated paths, e.g. "/admin/,/private/")
+ *   - STEALTH=true disallows every path for every crawler — layer 1 of the
+ *     three-layer stealth posture (#884, #7374); it subsumes any
+ *     AILK_ROBOTS_DISALLOW paths
  */
 
 import { resolveBaseUrl } from "../../src/lib/routes";
@@ -14,10 +17,13 @@ export function GET(): Response {
   const baseUrl = resolveBaseUrl();
   const disallowEnv = process.env["AILK_ROBOTS_DISALLOW"] ?? "";
 
-  const disallowPaths = disallowEnv
-    .split(",")
-    .map((p) => p.trim())
-    .filter((p) => p.length > 0);
+  const disallowPaths =
+    process.env["STEALTH"] === "true"
+      ? ["/"]
+      : disallowEnv
+          .split(",")
+          .map((p) => p.trim())
+          .filter((p) => p.length > 0);
 
   const lines = [
     "User-agent: *",