create-ailk 0.29.1 → 0.30.0

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

package/templates/apps/web/auth.ts

@@ -26,11 +26,14 @@
  */
  
 import type { PrismaClient } from "@working-theory/database";
-import { betterAuth } from "better-auth";
+import { MCP_SCOPES } from "@working-theory/validation";
+import { type BetterAuthPlugin, betterAuth } from "better-auth";
 import { prismaAdapter } from "better-auth/adapters/prisma";
+import type { AuthMiddleware } from "better-auth/api";
 import { nextCookies } from "better-auth/next-js";
-import { magicLink } from "better-auth/plugins";
+import { magicLink, mcp } from "better-auth/plugins";
 
+import { sealMcpCallbacks } from "./app/api/auth/mcp/continuation";
 import {
   authEmailTransport,
   makeMagicLinkOptions,
@@ -44,6 +47,7 @@ import {
   resetSendConfigured,
 } from "./lib/auth-env";
 import { resolveSecret } from "./lib/auth-secret";
+import { type McpMembership, type McpOAuthDeps, mcpOAuthPlugin } from "./lib/mcp-oauth";
 import {
   signUpAgreementHooks,
   signUpAgreementsPlugin,
@@ -67,6 +71,105 @@ const RESET_TOKEN_TTL_SECONDS = 3600;
  */
 const VERIFY_TOKEN_TTL_SECONDS = 86_400;
 
+// mcp-oauth:begin
+/**
+ * The site's MCP authorization server (#10357 D4): better-auth's `mcp` plugin
+ * — dynamic client registration, PKCE, opaque tokens with refresh — and
+ * AILK's plugin beside it (`lib/mcp-oauth.ts`: the workspace + scope consent
+ * step, rotation, revocation, the token self-check). Installed only when
+ * `baseURL` is pinned: the plugin's metadata has no issuer without one, and
+ * an issuer derived from the request's host is the § D13 chain again.
+ *
+ * Every value is set explicitly, even where it equals the library default,
+ * so the numbers are reviewable.
+ */
+/** An authorization code's lifetime: ten minutes to finish consent. */
+const MCP_CODE_TTL_SECONDS = 600;
+/** An access token's lifetime: one hour. */
+const MCP_ACCESS_TOKEN_TTL_SECONDS = 3600;
+/** A refresh token's lifetime: seven days, sliding by rotation. */
+const MCP_REFRESH_TOKEN_TTL_SECONDS = 604_800;
+
+/**
+ * The plugin's HTTP routes AILK turns off: its consent (binds no workspace,
+ * narrows no scope — D2), `/mcp/get-session` (hands any access-token holder
+ * the row, refresh token included), and its own discovery document, which
+ * the site serves once at its root (D7).
+ */
+export const MCP_DISABLED_PATHS = [
+  "/oauth2/consent",
+  "/mcp/get-session",
+  "/.well-known/oauth-authorization-server",
+];
+
+/**
+ * Rate rules for the anonymous MCP endpoints — applied only beside the other
+ * custom rules, where the client IP resolves (see the rate-limit block).
+ */
+export const MCP_RATE_RULES = {
+  "/mcp/register": { window: 3600, max: 10 },
+  "/mcp/token": { window: 60, max: 30 },
+  "/mcp/revoke": { window: 60, max: 30 },
+  // apps/mcp validates every OAuth bearer here from one egress address, so
+  // its lookups get their own bucket, not the global 60/60 s (#10391 D7).
+  "/mcp/token-info": { window: 60, max: 600 },
+};
+
+/**
+ * A sign-in that resumes an MCP authorization carries
+ * `/api/auth/mcp/authorize?<query>` as its callback — the `next` the plugin's
+ * `loginPage` hands `/sign-in` — which the emailed link's verify refuses once
+ * decoded (#10479). Before any sign-in endpoint reads it, this seals it to
+ * `/api/auth/mcp/continue/<ref>` (`app/api/auth/mcp/continuation.ts`).
+ */
+let sealMcpSignIn: AuthMiddleware | undefined;
+
+export const mcpSignInContinuation = {
+  id: "ailk-mcp-sign-in-continuation",
+  hooks: {
+    before: [
+      {
+        matcher: (ctx) => ctx.path?.startsWith("/sign-in/") ?? false,
+        // `better-auth/api` is ESM-only and CommonJS Jest cannot load it (#507),
+        // so it is imported when a hook first runs, never when this module loads.
+        handler: async (ctx) => {
+          const { createAuthMiddleware } = await import("better-auth/api");
+          sealMcpSignIn ??= createAuthMiddleware(async (inner) => {
+            const body = inner.body as Record<string, unknown> | undefined;
+            const sealed = body ? sealMcpCallbacks(body, resolveSecret()) : null;
+            return sealed ? { context: { body: { ...body, ...sealed } } } : undefined;
+          });
+          return sealMcpSignIn(ctx);
+        },
+      },
+    ],
+  },
+} satisfies BetterAuthPlugin;
+
+export function mcpAuthorizationServer(deps: McpOAuthDeps) {
+  return [
+    mcp({
+      loginPage: "/api/auth/mcp/sign-in",
+      oidcConfig: {
+        loginPage: "/api/auth/mcp/sign-in",
+        consentPage: "/consent",
+        // OAuth 2.1: PKCE on every authorization, S256 only.
+        requirePKCE: true,
+        allowPlainCodeChallengeMethod: false,
+        codeExpiresIn: MCP_CODE_TTL_SECONDS,
+        accessTokenExpiresIn: MCP_ACCESS_TOKEN_TTL_SECONDS,
+        refreshTokenExpiresIn: MCP_REFRESH_TOKEN_TTL_SECONDS,
+        scopes: [...MCP_SCOPES],
+        defaultScope: ["offline_access", ...MCP_SCOPES].join(" "),
+        metadata: { scopes_supported: ["offline_access", ...MCP_SCOPES] },
+      },
+    }),
+    mcpOAuthPlugin(deps),
+    mcpSignInContinuation,
+  ];
+}
+// mcp-oauth:end
+
 let prismaForAuthLoad: Promise<PrismaClient> | undefined;
 
 /**
@@ -140,16 +243,20 @@ function deferredPrismaForAuth(): PrismaClient {
 }
 
 /**
- * The two delegate methods `onPasswordReset` reaches for, named so the call
+ * The delegate methods `onPasswordReset` reaches for, named so the call
  * site needs no cast. Method shorthand for the same reason `AuthEmailPrisma`
  * uses it: the generated `PrismaClient` satisfies this structurally, and
- * nothing wider than `verification.deleteMany` and
- * `oAuthAuthorization.updateMany` is reachable through it. The second ends
- * every credential a spoke holds for the person (#7894 D4, SEC-7894-5).
+ * nothing wider than `verification.deleteMany`,
+ * `oAuthAuthorization.updateMany`, `session.deleteMany` and
+ * `oauthAccessToken.deleteMany` is reachable through it. The second ends
+ * every credential a spoke holds for the person (#7894 D4, SEC-7894-5); the
+ * last two every session and MCP token (#10357 D9).
  */
 interface VerificationStore {
   verification: { deleteMany(args: unknown): Promise<unknown> };
   oAuthAuthorization: { updateMany(args: unknown): Promise<unknown> };
+  session: { deleteMany(args: unknown): Promise<unknown> };
+  oauthAccessToken: { deleteMany(args: unknown): Promise<unknown> };
 }
 
 type SocialProviders = {
@@ -471,6 +578,40 @@ export function createAuth(deps: CreateAuthDeps = {}) {
         })}`,
       );
     }
+    /**
+     * And every MCP client token (#10357 D9): an attacker who connected a
+     * client before the owner recovered the account would otherwise keep the
+     * workspace by sliding refresh. Guarded the same way.
+     *
+     * The sessions go first: Better Auth deletes them only after this
+     * callback returns, and until then a live session could approve and
+     * exchange a fresh code (SEC-10357). The library's own delete then finds
+     * none.
+     */
+    try {
+      await verificationStore.session.deleteMany({ where: { userId: user.id } });
+    } catch {
+      console.warn(
+        `[auth-email] ${JSON.stringify({
+          userId: user.id,
+          kind: "password-reset",
+          reason: "session_revocation_failed",
+        })}`,
+      );
+    }
+    try {
+      await verificationStore.oauthAccessToken.deleteMany({
+        where: { userId: user.id },
+      });
+    } catch {
+      console.warn(
+        `[auth-email] ${JSON.stringify({
+          userId: user.id,
+          kind: "password-reset",
+          reason: "mcp_token_revocation_failed",
+        })}`,
+      );
+    }
     /**
      * Guarded like its sibling above, though `lib/auth-email.ts` now also
      * guards its own signing step (#6068). BOTH, deliberately: this callback
@@ -495,6 +636,36 @@ export function createAuth(deps: CreateAuthDeps = {}) {
     }
   };
 
+  /**
+   * The person's workspaces for the MCP consent step and token self-check
+   * (#10357 D4): `listTenancy`'s rule — every workspace of every organization
+   * they belong to, with that membership's role.
+   */
+  const readMemberships = async (userId: string): Promise<McpMembership[]> => {
+    const memberships = await prisma.membership.findMany({
+      where: { userId },
+      select: {
+        role: true,
+        organization: {
+          select: {
+            name: true,
+            workspaces: { select: { id: true, name: true }, orderBy: { createdAt: "asc" } },
+          },
+        },
+      },
+      orderBy: { createdAt: "asc" },
+    });
+    return memberships.flatMap((m) =>
+      m.organization.workspaces.map((w) => ({
+        workspaceId: w.id,
+        workspaceName: w.name,
+        organizationName: m.organization.name,
+        role: m.role,
+      })),
+    );
+  };
+  const mcpServer = baseURL ? mcpAuthorizationServer({ readMemberships }) : [];
+
   const instance = betterAuth({
     /**
      * `transaction: true` (#8765 D4): Better Auth opens one `$transaction` for
@@ -538,6 +709,7 @@ export function createAuth(deps: CreateAuthDeps = {}) {
      * deployment that has not pinned its origin never offers reset at all.
      */
     ...(baseURL ? { trustedOrigins: [baseURL] } : {}),
+    ...(baseURL ? { disabledPaths: MCP_DISABLED_PATHS } : {}),
     emailAndPassword: {
       enabled: passwordMethodActive,
       // Turning the password method on also opens POST /sign-up/email —
@@ -653,6 +825,8 @@ export function createAuth(deps: CreateAuthDeps = {}) {
               ...(magicLinkActive
                 ? { "/sign-in/magic-link": { window: 900, max: 5 } }
                 : {}),
+              // #10357 D4: registration and the token endpoints.
+              ...(baseURL ? MCP_RATE_RULES : {}),
             },
           }
         : {}),
@@ -734,14 +908,17 @@ export function createAuth(deps: CreateAuthDeps = {}) {
      * `signUpAgreementsPlugin` always (#8765 D3): while sign-up is open,
      * `/sign-up/email` without every sign-up agreement is refused before the
      * handler looks the address up.
+     *
+     * The MCP authorization server whenever `baseURL` is pinned (#10357 D4).
      */
     plugins: magicLinkActive
       ? [
           nextCookies(),
           signUpAgreementsPlugin(),
           magicLink(makeMagicLinkOptions({ send: authEmailTransport })),
+          ...mcpServer,
         ]
-      : [nextCookies(), signUpAgreementsPlugin()],
+      : [nextCookies(), signUpAgreementsPlugin(), ...mcpServer],
   });
   return instance;
 }

package/templates/apps/web/lib/__tests__/auth-routes.test.ts

@@ -12,13 +12,14 @@ import { AUTH_SEGMENTS, isAccountPath, isAuthPath, isBookingPath } from "../auth
 const LOCALES = ["en", "fr", "de"];
 
 describe("AUTH_SEGMENTS", () => {
-  it("names exactly the five auth routes", () => {
+  it("names exactly the six auth routes", () => {
     expect([...AUTH_SEGMENTS]).toEqual([
       "sign-in",
       "sign-up",
       "forgot-password",
       "reset-password",
       "verify-email",
+      "consent",
     ]);
   });
 });

package/templates/apps/web/lib/auth-routes.ts

@@ -4,8 +4,8 @@
  * ONE module, so the list `app/[locale]/layout.tsx` branches on to drop the
  * marketing chrome and the list the `(auth)` group's page segments exist at
  * cannot drift. A route group contributes no URL segment, so these are the
- * real paths: `/sign-in`, `/sign-up`, `/forgot-password`, `/reset-password`
- * and `/verify-email`, each under next-intl's `as-needed` prefixing (bare for
+ * real paths: `/sign-in`, `/sign-up`, `/forgot-password`, `/reset-password`,
+ * `/verify-email` and the MCP consent step `/consent` (#10357), each under next-intl's `as-needed` prefixing (bare for
  * the default locale, `/<locale>/…` otherwise).
  *
  * `isAccountPath()` (#7430, spec 7423 D4) is the same predicate for the
@@ -21,13 +21,15 @@
  * No Next.js import — pure functions, asserted directly by their own suite.
  */
 
-/** The five segments the `(auth)` route group serves. */
+/** The six segments the `(auth)` route group serves. */
 export const AUTH_SEGMENTS = [
   "sign-in",
   "sign-up",
   "forgot-password",
   "reset-password",
   "verify-email",
+  // The MCP consent step (#10357 D6).
+  "consent",
 ] as const;
 
 export type AuthSegment = (typeof AUTH_SEGMENTS)[number];