create-ailk 0.29.0 → 0.30.0

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

@@ -0,0 +1,92 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The MCP sign-in leg's continuation (#10479): the hub's sealed ref, under a
+ * name of its own. Pure functions over `seal.ts`; no mocks.
+ */
+import { mintContinuation } from "../../hub/continuation";
+import {
+  MCP_CONTINUE_PATH,
+  mintMcpContinuation,
+  openMcpContinuation,
+  sealMcpCallbacks,
+} from "../continuation";
+
+const SECRET = "k".repeat(43);
+const T = 1_790_000_000_000;
+
+const Q = new URLSearchParams({
+  response_type: "code",
+  client_id: "mcp-client",
+  redirect_uri: "http://127.0.0.1:53682/callback",
+  state: "s".repeat(43),
+  code_challenge: "c".repeat(43),
+  code_challenge_method: "S256",
+}).toString();
+
+it("pins the continue path", () => {
+  expect(MCP_CONTINUE_PATH).toBe("/api/auth/mcp/continue");
+});
+
+it("round-trips the authorize query, scheme-bearing redirect_uri included", () => {
+  expect(openMcpContinuation(mintMcpContinuation(Q, SECRET, T), SECRET, T + 1_000)).toBe(Q);
+});
+
+it("mints a ref no decode can change: base64url only, so no ':', '%', '?', '&' or '='", () => {
+  expect(mintMcpContinuation(Q, SECRET, T)).toMatch(/^[A-Za-z0-9_-]+$/);
+});
+
+it("expires at 600 s", () => {
+  expect(openMcpContinuation(mintMcpContinuation(Q, SECRET, T), SECRET, T + 600_000)).toBeNull();
+});
+
+it("never opens a hub ref, nor under another secret", () => {
+  expect(openMcpContinuation(mintContinuation(Q, SECRET, T), SECRET, T)).toBeNull();
+  expect(openMcpContinuation(mintMcpContinuation(Q, SECRET, T), "x".repeat(43), T)).toBeNull();
+});
+
+describe("sealMcpCallbacks — the sign-in body's MCP resume, sealed", () => {
+  const next = `/api/auth/mcp/authorize?${Q}`;
+  const refOf = (path: string | undefined) =>
+    /^\/api\/auth\/mcp\/continue\/([A-Za-z0-9_-]+)$/.exec(path ?? "")?.[1] ?? "";
+
+  it("seals callbackURL and the next inside the sign-in page's errorCallbackURL; both open to the query", () => {
+    const sealed = sealMcpCallbacks(
+      { callbackURL: next, errorCallbackURL: `/de/sign-in?next=${encodeURIComponent(next)}` },
+      SECRET,
+    );
+    expect(openMcpContinuation(refOf(sealed?.callbackURL), SECRET)).toBe(Q);
+    const error = new URL(sealed?.errorCallbackURL ?? "", "http://x.invalid");
+    expect(error.pathname).toBe("/de/sign-in");
+    expect(openMcpContinuation(refOf(error.searchParams.get("next") ?? ""), SECRET)).toBe(Q);
+    // No decode of either value can produce a ':'.
+    expect(decodeURIComponent(decodeURIComponent(sealed?.errorCallbackURL ?? ""))).not.toContain(":");
+  });
+
+  it.each([
+    ["no callbacks", {}],
+    ["an ordinary next", { callbackURL: "/account", errorCallbackURL: "/sign-in?next=%2Faccount" }],
+    ["the hub's own authorize path", { callbackURL: `/api/auth/hub/authorize?${Q}` }],
+    ["a foreign errorCallbackURL", { errorCallbackURL: `https://evil.example/?next=${encodeURIComponent(next)}` }],
+    ["a non-string callbackURL", { callbackURL: [next] }],
+    // Security review: URL's dot-segment collapse would emit //evil.example.
+    ["a dot-segment errorCallbackURL", { errorCallbackURL: `/.//evil.example?next=${encodeURIComponent(next)}` }],
+    ["an errorCallbackURL on another page", { errorCallbackURL: `/account?next=${encodeURIComponent(next)}` }],
+    ["an errorCallbackURL with a second key", { errorCallbackURL: `/sign-in?next=${encodeURIComponent(next)}&x=1` }],
+    ["a next holding CR/LF", { callbackURL: `${next}%0D%0A`.replace("%0D%0A", "\r\n") }],
+    ["an undecodable next", { errorCallbackURL: "/sign-in?next=%E0%A4%A" }],
+  ])("leaves %s alone (null)", (_name, body) => {
+    expect(sealMcpCallbacks(body, SECRET)).toBeNull();
+  });
+
+  it("seals the sign-up page's errorCallbackURL the same way", () => {
+    const sealed = sealMcpCallbacks({ errorCallbackURL: `/sign-up?next=${encodeURIComponent(next)}` }, SECRET);
+    expect(sealed?.errorCallbackURL).toMatch(/^\/sign-up\?next=%2Fapi%2Fauth%2Fmcp%2Fcontinue%2F[A-Za-z0-9_-]+$/);
+  });
+
+  it("leaves a query too long to seal under the continue route's cap as it was", () => {
+    expect(sealMcpCallbacks({ callbackURL: `${next}&state=${"s".repeat(4096)}` }, SECRET)).toBeNull();
+  });
+});

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

@@ -0,0 +1,89 @@
+/**
+ * The MCP sign-in leg's continuation (#10479).
+ *
+ * The plugin's `loginPage` (`lib/mcp-oauth.ts`, `/mcp/sign-in`) hands
+ * `/sign-in` a `next` of `/api/auth/mcp/authorize?<query>`, and the page sends
+ * it on as the sign-in's `callbackURL`. An MCP client's query carries a
+ * scheme-bearing `redirect_uri` (`http://127.0.0.1:PORT/callback`, any
+ * `https://` callback), and Better Auth's magic-link verify decodes
+ * `callbackURL` and checks it as a relative path whose query admits no `:` —
+ * so the emailed link answered 403 INVALID_CALLBACK_URL and the person never
+ * reached `/consent`.
+ *
+ * `auth.ts` therefore rewrites such a callback, as a sign-in request arrives,
+ * to the same-origin path `/api/auth/mcp/continue/<ref>` — the hub's sealed
+ * ref (`../hub/continuation.ts`), under a name of its own so a ref minted for
+ * one leg never opens at the other — and the continue route returns the
+ * person to `/mcp/authorize`, which forces consent again.
+ */
+import { CONTINUATION_REF_MAX, mintContinuation, openContinuation } from "../hub/continuation";
+
+/** The same-origin path a ref is appended to. */
+export const MCP_CONTINUE_PATH = "/api/auth/mcp/continue";
+
+/** The resume target the plugin's `loginPage` puts in `next`. */
+const AUTHORIZE_PREFIX = "/api/auth/mcp/authorize?";
+
+const NAME = "mcp-continue";
+
+const PRINTABLE = /^[\x21-\x7e]+$/;
+
+/**
+ * The exact `errorCallbackURL` the sign-in and sign-up pages send:
+ * `[/<locale>]/sign-in?next=<encoded>` (or `/sign-up`). Matched on the raw
+ * string and rebuilt from its own path bytes — never through `URL`, whose
+ * dot-segment collapse would turn an accepted `/.//host` into a
+ * protocol-relative `//host` after Better Auth's origin check has run.
+ */
+const SIGN_IN_ERROR_CALLBACK = /^(\/(?:[a-z]{2}(?:-[A-Za-z]{2,4})?\/)?sign-(?:in|up))\?next=([^&#]*)$/;
+
+/** `search` (the authorize query, no leading `?`) as a sealed ref. */
+export function mintMcpContinuation(search: string, secret: string, now: number = Date.now()): string {
+  return mintContinuation(search, secret, now, NAME);
+}
+
+/** The authorize query a ref holds, or `null` (see `openContinuation`). */
+export function openMcpContinuation(ref: string, secret: string, now: number = Date.now()): string | null {
+  return openContinuation(ref, secret, now, NAME);
+}
+
+/** `path` as a continue path when it resumes an MCP authorization, else unchanged. */
+function sealed(path: string, secret: string): string {
+  // Printable ASCII only, as the origin check admits: nothing sealed may hold
+  // a control or non-Latin-1 character the continue route's Location refuses.
+  if (!path.startsWith(AUTHORIZE_PREFIX) || !PRINTABLE.test(path)) return path;
+  const ref = mintMcpContinuation(path.slice(AUTHORIZE_PREFIX.length), secret);
+  // Past the cap the continue route would not open it: leave the path as it was.
+  return ref.length > CONTINUATION_REF_MAX ? path : `${MCP_CONTINUE_PATH}/${ref}`;
+}
+
+/**
+ * The sign-in body's callbacks with every MCP resume sealed, or `null` when
+ * none is: `callbackURL` itself, and the `next` the sign-in page puts inside
+ * `errorCallbackURL` (`SIGN_IN_ERROR_CALLBACK`), whose decoded form holds the
+ * same query. Every other value — any other shape included — passes through
+ * unchanged, so this hook can only ever write a same-origin continue path.
+ */
+export function sealMcpCallbacks(
+  body: { callbackURL?: unknown; errorCallbackURL?: unknown },
+  secret: string,
+): { callbackURL?: string; errorCallbackURL?: string } | null {
+  const out: { callbackURL?: string; errorCallbackURL?: string } = {};
+  if (typeof body.callbackURL === "string") {
+    const callbackURL = sealed(body.callbackURL, secret);
+    if (callbackURL !== body.callbackURL) out.callbackURL = callbackURL;
+  }
+  const match = typeof body.errorCallbackURL === "string" ? SIGN_IN_ERROR_CALLBACK.exec(body.errorCallbackURL) : null;
+  if (match) {
+    const [, page, encoded = ""] = match;
+    let next: string;
+    try {
+      next = decodeURIComponent(encoded);
+    } catch {
+      next = "";
+    }
+    const continued = sealed(next, secret);
+    if (continued !== next) out.errorCallbackURL = `${page}?next=${encodeURIComponent(continued)}`;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The MCP sign-in leg's continue step (#10479): a ref returns the person to
+ * `/api/auth/mcp/authorize` with the original query, and nowhere else.
+ */
+import { mintContinuation } from "../../../../hub/continuation";
+import { mintMcpContinuation } from "../../../continuation";
+import { GET } from "../route";
+
+const SITE = "https://site.example.com";
+const SECRET = "flow-secret-0123456789abcdef0123456789abcdef";
+const ORIGINAL_ENV = process.env;
+
+const QUERY = new URLSearchParams({
+  response_type: "code",
+  client_id: "mcp-client",
+  redirect_uri: "http://127.0.0.1:53682/callback",
+  state: "s".repeat(43),
+  code_challenge: "c".repeat(43),
+  code_challenge_method: "S256",
+}).toString();
+
+function continueTo(ref: string): Promise<Response> {
+  return GET(new Request(`${SITE}/api/auth/mcp/continue/${ref}`), {
+    params: Promise.resolve({ ref }),
+  });
+}
+
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV, BETTER_AUTH_SECRET: SECRET };
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+it("answers a valid ref with 303 to /api/auth/mcp/authorize and the same query", async () => {
+  const res = await continueTo(mintMcpContinuation(QUERY, SECRET));
+
+  expect(res.status).toBe(303);
+  expect(res.headers.get("location")).toBe(`/api/auth/mcp/authorize?${QUERY}`);
+  expect(res.headers.get("cache-control")).toBe("no-store");
+  expect(res.headers.get("referrer-policy")).toBe("no-referrer");
+});
+
+it.each([
+  ["a forged ref", "not-a-ref"],
+  ["a hub ref", mintContinuation(QUERY, SECRET)],
+  ["an expired ref", mintMcpContinuation(QUERY, SECRET, Date.now() - 601_000)],
+  ["a ref sealed under another secret", mintMcpContinuation(QUERY, "x".repeat(43))],
+])("sends %s to /account, never to a URL it carries", async (_name, ref) => {
+  const res = await continueTo(ref);
+
+  expect(res.status).toBe(303);
+  expect(res.headers.get("location")).toBe("/account");
+});

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

@@ -0,0 +1,41 @@
+/**
+ * The MCP sign-in leg's continue step (#10479).
+ *
+ *   GET /api/auth/mcp/continue/<ref>
+ *
+ * After sign-in — by the emailed link, the password or a social provider —
+ * the person lands here, and this route returns them to the authorize step:
+ *
+ *   - a valid, unexpired ref: 303 to `/api/auth/mcp/authorize?<the query>`;
+ *   - any other ref (forged, a hub ref, expired, unreadable): 303 to
+ *     `/account`.
+ *
+ * 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, and forces consent. It logs nothing.
+ */
+import { resolveSecret } from "../../../../../../lib/auth-secret";
+import { openMcpContinuation } from "../../continuation";
+
+const AUTHORIZE_PATH = "/api/auth/mcp/authorize";
+
+/** Where an unreadable ref goes: the site's own signed-in destination. */
+const FALLBACK_PATH = "/account";
+
+// platform-decisions-waiver: api-versioning — sign-in redirect step, not a versioned API contract (#10479)
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ ref: string }> },
+): Promise<Response> {
+  const { ref } = await params;
+  const query = openMcpContinuation(ref, resolveSecret());
+  return new Response(null, {
+    status: 303,
+    headers: {
+      Location: query === null ? FALLBACK_PATH : `${AUTHORIZE_PATH}?${query}`,
+      "Cache-Control": "no-store",
+      // The authorize query rides this URL; no page may leak it through a Referer.
+      "Referrer-Policy": "no-referrer",
+    },
+  });
+}

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

@@ -27,6 +27,7 @@
  * `listDocsPages`).
  */
 
+import { siteDiscoverable } from "@working-theory/api-client";
 import {
   SCHEMA_ORG_TYPES,
   resolvedAdapterKind,
@@ -44,6 +45,10 @@ import { PUBLIC_PAGES } from "../../lib/modules.generated";
 import { SITE_NAME } from "../../lib/site-brand";
 import { pagePathFor, resolveBaseUrl } from "../../src/lib/routes";
 
+// #10510 D4 — read per request: the owner's discovery switch is a runtime
+// setting a prerendered file could never follow.
+export const dynamic = "force-dynamic";
+
 export interface LlmsHandlerDeps {
   /**
    * Content adapter factory. Defaults to the real implementation.
@@ -58,6 +63,8 @@ export interface LlmsHandlerDeps {
   getBlogPages?: () => Array<{ url: string; data: { title: string; description?: string } }>;
   /** The docs pages (#10041). Defaults to `listDocsPages` over this app's docs directory. */
   getDocsPages?: () => DocsIndexPage[];
+  /** The owner's discovery switch (#10510 D4). Defaults to `siteDiscoverable`. */
+  discoverable?: () => Promise<boolean>;
 }
 
 /**
@@ -68,10 +75,13 @@ export function createLlmsHandler(deps: LlmsHandlerDeps = {}) {
   const resolveAdapter = deps.getContentAdapter ?? defaultGetContentAdapter;
   const resolveBlogPages = deps.getBlogPages ?? (() => []);
   const resolveDocsPages = deps.getDocsPages ?? listDocsPages;
+  const isDiscoverable = deps.discoverable ?? siteDiscoverable;
 
   return async function llmsGET(): Promise<Response> {
     // #10040 decision 7 — no public page, no content index: 404 before the adapter.
     if (!PUBLIC_PAGES) return new Response(null, { status: 404 });
+    // #10510 D4 — hidden by the owner: 404, never cached, before the adapter.
+    if (!(await isDiscoverable())) return new Response(null, { status: 404, headers: { "cache-control": "no-store" } });
     const adapter = resolveAdapter();
     const baseUrl = resolveBaseUrl();
     const lines: string[] = [`# ${SITE_NAME} — content index`, ""];

package/templates/apps/web/app/openapi.json/__tests__/route.test.ts

@@ -15,6 +15,21 @@
 
 import { GET } from "../route";
 
+// #10510 D4 — the owner's discovery switch, mocked so no case reads a hub. On
+// (`true`) by default: the state every case above the #10510 describe assumes.
+const mockSiteDiscoverable = jest.fn<Promise<boolean>, []>();
+jest.mock("@working-theory/api-client", () => ({
+  ...jest.requireActual<typeof import("@working-theory/api-client")>(
+    "@working-theory/api-client",
+  ),
+  siteDiscoverable: () => mockSiteDiscoverable(),
+}));
+
+beforeEach(() => {
+  mockSiteDiscoverable.mockReset();
+  mockSiteDiscoverable.mockResolvedValue(true);
+});
+
 // The REAL committed seam, for the #8060 hub-only guards: the mock below
 // shadows `TOPOLOGY` per case, but whether a hub-only case runs depends on the
 // render this scaffold carries, not on the topology a case picks.
@@ -295,3 +310,28 @@ describe("GET /openapi.json on a spoke (#7426 D12)", () => {
     expect(JSON.stringify(body)).toContain("hub.example.com");
   });
 });
+
+// #10510 D4, AC-1–AC-2 — the owner's discovery switch: read once per request,
+// before the API is fetched.
+describe("GET /openapi.json and the owner's discovery switch (#10510)", () => {
+  it("on: today's cache-control, the switch read once per request", async () => {
+    apiAnswers(200, JSON.stringify(SPEC));
+    const response = await GET();
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("public, max-age=3600");
+    expect(mockSiteDiscoverable).toHaveBeenCalledTimes(1);
+    apiAnswers(200, JSON.stringify(SPEC));
+    await GET();
+    expect(mockSiteDiscoverable).toHaveBeenCalledTimes(2);
+  });
+
+  it("off: 404 with no body, never cached, and the API never fetched", async () => {
+    mockSiteDiscoverable.mockResolvedValue(false);
+    apiAnswers(200, JSON.stringify(SPEC));
+    const response = await GET();
+    expect(response.status).toBe(404);
+    expect(await response.text()).toBe("");
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/web/app/openapi.json/route.ts

@@ -23,6 +23,8 @@
  * host, and never calls a path this site would answer 404.
  */
 
+import { siteDiscoverable } from "@working-theory/api-client";
+
 import { browserApiOrigin } from "../../lib/api-origin.generated";
 import { RELAY_ROUTES } from "../../lib/relay";
 import { TOPOLOGY } from "../../lib/topology.generated";
@@ -157,6 +159,8 @@ function badGateway(message: string): Response {
 }
 
 export async function GET(): Promise<Response> {
+  // #10510 D4 — hidden by the owner: 404, never cached, the API never read.
+  if (!(await siteDiscoverable())) return new Response(null, { status: 404, headers: { "cache-control": "no-store" } });
   let upstream: Response;
   try {
     upstream = await fetch(`${apiBase()}${UPSTREAM_PATH}`, {

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

@@ -13,12 +13,17 @@
  *     parse (#8511), so 1, yes and on count too, and an unknown value throws.
  */
 
+import { siteDiscoverable } from "@working-theory/api-client";
 import { parseStealth } from "@working-theory/web-i18n/stealth";
 
 import { PUBLIC_PAGES } from "../../lib/modules.generated";
 import { resolveBaseUrl } from "../../src/lib/routes";
 
-export function GET(): Response {
+// #10510 D4 — read per request: the owner's discovery switch is a runtime
+// setting a prerendered file could never follow.
+export const dynamic = "force-dynamic";
+
+export async function GET(): Promise<Response> {
   const baseUrl = resolveBaseUrl();
   const disallowEnv = process.env["AILK_ROBOTS_DISALLOW"] ?? "";
   // #10040 decision 7 — a site with neither marketing nor docs-blog (a hub)
@@ -26,6 +31,18 @@ export function GET(): Response {
   // STEALTH, read from the module list, never from a setting.
   const stealth = parseStealth(process.env["STEALTH"]) || !PUBLIC_PAGES;
 
+  // #10510 D4 — the owner's switch, read only when neither already hides the
+  // site: off is STEALTH's body, never cached, so a crawler asks again.
+  if (!stealth && !(await siteDiscoverable())) {
+    return new Response("User-agent: *\nDisallow: /", {
+      status: 200,
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        "cache-control": "no-store",
+      },
+    });
+  }
+
   const disallowPaths = stealth
     ? ["/"]
     : disallowEnv

package/templates/apps/web/app/sitemap.xml/route.ts

@@ -37,6 +37,7 @@
  * directory is listed instead (`getDocsPages`, default `listDocsPages`).
  */
 
+import { siteDiscoverable } from "@working-theory/api-client";
 import {
   SCHEMA_ORG_TYPES,
   resolvedAdapterKind,
@@ -53,6 +54,10 @@ import {
 import { PUBLIC_PAGES } from "../../lib/modules.generated";
 import { pagePathFor, resolveBaseUrl } from "../../src/lib/routes";
 
+// #10510 D4 — read per request: the owner's discovery switch is a runtime
+// setting a prerendered file could never follow.
+export const dynamic = "force-dynamic";
+
 export interface SitemapHandlerDeps {
   /**
    * Content adapter factory. Defaults to the real implementation.
@@ -61,6 +66,8 @@ export interface SitemapHandlerDeps {
   getContentAdapter?: () => ContentAdapter;
   /** The docs pages (#10041). Defaults to `listDocsPages` over this app's docs directory. */
   getDocsPages?: () => DocsIndexPage[];
+  /** The owner's discovery switch (#10510 D4). Defaults to `siteDiscoverable`. */
+  discoverable?: () => Promise<boolean>;
 }
 
 function escapeXml(value: string): string {
@@ -96,9 +103,12 @@ function buildLocaleUrl(
 export function createSitemapHandler(deps: SitemapHandlerDeps = {}) {
   const resolveAdapter = deps.getContentAdapter ?? defaultGetContentAdapter;
   const resolveDocsPages = deps.getDocsPages ?? listDocsPages;
+  const isDiscoverable = deps.discoverable ?? siteDiscoverable;
   return async function sitemapGET(): Promise<Response> {
     // #10040 decision 7 — no public page, no sitemap: 404 before the adapter.
     if (!PUBLIC_PAGES) return new Response(null, { status: 404 });
+    // #10510 D4 — hidden by the owner: 404, never cached, before the adapter.
+    if (!(await isDiscoverable())) return new Response(null, { status: 404, headers: { "cache-control": "no-store" } });
     const adapter = resolveAdapter();
     const baseUrl = resolveBaseUrl();
     const today = new Date().toISOString().slice(0, 10);