create-ailk 0.29.1 → 0.31.0

package/templates/apps/web/CLAUDE.md

@@ -43,7 +43,7 @@ Raw HTML is allowed only when no `@working-theory/ui` component fits. Flag it in
 - Animations: only `transform` and `opacity`. Never `transition-all`.
 - Every interactive element needs hover, focus-visible, and active states.
 
-The four widths above are the responsive contract. Brand reference files (logos, photos, colour and type notes) live in `brand_assets/` at the repo root; the site's own brand colours and fonts are set in `content/_site.mdx` under `brand.colors` and `brand.fonts`. The signed-out header button is set there too, as `header.cta` (`label`, `href`), with `header.signIn: link | hidden` choosing whether Sign in stays beside it as a text link — never by editing `app/[locale]/layout.tsx`. Each page's chrome is set there too (#10049, resolved by `lib/page-chrome.ts`): `header.style` (`full | bare | none`), `footer.style` (`columns | centered | closing | none`), `layout` (`deck | default`, the home's) and one `{ header, footer }` key per route family (`blog`, `docs`, `services`, …), with a page's own `header:` / `footer:` / `layout:` frontmatter winning over all of them.
+The four widths above are the responsive contract. Brand reference files (logos, photos, colour and type notes) live in `brand_assets/` at the repo root; the site's own brand colours and fonts are set in `content/_site.mdx` under `brand.colors` and `brand.fonts`. The signed-out header button is set there too, as `header.cta` (`label`, `href`), with `header.signIn: link | hidden` choosing whether Sign in stays beside it as a text link — never by editing `app/[locale]/layout.tsx`. Each page's chrome is set there too (#10049, resolved by `lib/page-chrome.ts`): `header.style` (`full | bare | none`), `footer.style` (`columns | centered | closing | none`), `layout` (`deck | default`, the home's) and one `{ header, footer }` key per route family (`blog`, `docs`, `services`, …), with a page's own `header:` / `footer:` / `layout:` frontmatter winning over all of them. The closing footer alone also reads three site-level keys (#10550): `footer.locality` (the line above the email, winning over the identity's address), `footer.actions` (one or two `{ label, href }` site paths — the primary, then the secondary — in place of the auth links) and `footer.legalBar` (off by default: `true` moves the legal line into a full-width bottom bar, on the deck's closing slide its bottom edge). The cookie notice's look is set there too (#10555, #10721): `consent.appearance` is `compact` (the floating card, bottom-left) or `hairline` (the full-width band on the page ground); absent, it follows the design's `chromeStyle` — the band under `minimal`, else the card. Only the band waits for the minimal deck home's first slide to leave view (#7782); the card shows on load on every page.
 
 ## Local dev
 
@@ -164,6 +164,16 @@ route's rule, since the API honours consent only with it where
 `OSS_API_INTERNAL_SECRET` is set. A password reset or a sign-out revokes the
 grant, so the next sign-in asks again. `ref` is in both telemetry scrub lists.
 
+## The MCP authorization server
+
+**The site is the OAuth 2.1 authorization server an MCP client signs in through (#10357).** `auth.ts`'s block between `// mcp-oauth:begin` and `// mcp-oauth:end` installs better-auth's `mcp` plugin (dynamic client registration, S256 PKCE, one-hour access tokens, seven-day refresh tokens) and AILK's `lib/mcp-oauth.ts` beside it, only when `BETTER_AUTH_URL` pins the issuer. The plugin is configured, never patched: every AILK behaviour is a hook or an endpoint in that file.
+
+- **Tokens are opaque, validated by lookup** (decision (a)): no JWKS and no `jwt` plugin. `GET /api/auth/mcp/token-info` is the self-check: the bound workspace, the member-clamped `actingRole` and the grants the person's live role still holds — never a token.
+- **Every authorization asks** (decision (b)): a before-hook forces `prompt=consent`, so the plugin always redirects to `/consent` (an `(auth)` page, `AUTH_SEGMENTS`). The page reads only `consent_code` and asks `GET /mcp/consent-details`; Allow posts `POST /mcp/consent`, which binds one `ailk:workspace:<id>` and only role-held `ailk:*` scopes. `/mcp/token` refuses any code that did not pass it or whose approving session has ended, any `code` not shaped like one (so no AILK verification row can be named and consumed), and any non-string body field. The plugin's own `/oauth2/consent`, `/mcp/get-session` and discovery copy are `disabledPaths`; the site serves `/.well-known/oauth-authorization-server` at its root.
+- **Rotation and revocation**: a refresh deletes the used pair and leaves a tombstone, so a replayed refresh token ends the person's line for that client. `POST /mcp/revoke` (RFC 7009) and the person's own `POST /mcp/revoke-client` delete tokens.
+- **A password reset or change deletes every MCP token** of the person: `onPasswordReset`'s guarded blocks, which end the person's sessions first (so none can mint a token in between) and then their tokens (`reason: "session_revocation_failed"` / `"mcp_token_revocation_failed"` on failure, never a rejection) and an after-hook on `/change-password`.
+- Two plugin facts AILK works around: `/mcp/register` answers a raw `Response`, so no after-hook runs on it (the sweep runs before), and the plugin's `/mcp/token` treats any `oauthApplication.type` but `public` as confidential, so `POST /mcp/consent` re-derives it from the stored secret (`public` for a client with no secret, the column defaulting to `web`).
+
 ## Contact page
 
 The contact page (`apps/web/app/[locale]/contact/page.tsx`) renders the
@@ -267,8 +277,8 @@ embedding for it is behind the hero CTA's lightbox gate
 
 The workspace's **Newsletter magnet** (#8847) — seeded live at slug
 `newsletter` in every workspace — is the only source of `/newsletter`,
-`/unsubscribe` and the footer signup; none of their copy is in page code,
-content or the message catalog. All three read it through
+`/unsubscribe`, the footer signup and a bound `newsletter` section; none of
+their copy is in page code, content or the message catalog. All four read it through
 `lib/in-page-magnet.ts`'s `readServedMagnet("newsletter")`, shared for 15
 seconds per instance like /contact's read.
 
@@ -296,6 +306,13 @@ seconds per instance like /contact's read.
 - **The footer** fills `Footer`'s `subscribe` slot with the compact form
   (stacked, `sr-only` label) only when the magnet is served and capture is
   on; the built-in config never fills it.
+- **A bound `newsletter` section** (#10629) — a content `newsletter` section
+  with `magnet: "newsletter"` in place of `action` renders, under its own
+  headline, the full-size signup the locale layout builds from the footer's
+  same read and hands every page through `NewsletterSignupProvider` — with
+  `consentGate: "on-submit"`, so Subscribe stays enabled and an unticked
+  submit shows the consent error beside the box. It renders nothing whenever
+  the footer would show nothing. A section with `action` posts as before.
 
 ## Careers
 
@@ -571,7 +588,7 @@ A visitor's browser never calls the hub. Lead capture, newsletter signup, callba
 - **No cross-site POST.** A `Sec-Fetch-Site` other than `same-origin`, or an `Origin` not on this site's own host, is refused 403 before the hub is called.
 - **Headers are an allow-list.** The visitor's `x-forwarded-for` (else `x-real-ip`) and `user-agent` pass through so per-visitor rate limits still count each visitor; no `authorization`, client-sent `x-ailk-*` or `host` is forwarded, and a `cookie` goes only on `POST /v1/commerce/invoices`, the one session route.
 - **The relay has its own per-visitor budget (#7707).** Each visitor gets 8 calls per 10 minutes across the five visitor routes, and the session route (`POST /v1/commerce/invoices`) gets its own, wider budget of 30 per 10 minutes; the call that exceeds either gets `429 rate_limited` before any hub call. The budget is held in this instance's own process (no shared store, no env variable) and holds only where the site's edge overwrites `x-forwarded-for` and `x-real-ip` — Vercel does; a bare self-hosted Next server does not.
-- **A bot check on the public writes (#9889, #9255).** On Vercel, `lib/bot-check.ts`'s `runBotCheck` asks Vercel BotID for a verdict before the hub is called — in the relay for `POST /v1/leads/{submit,subscribe,callback}` and `POST /v1/schedule/book` (`BOT_CHECKED_ROUTES`: `403 bot_detected`, or `503 bot_check_unavailable` when the check throws, answers no boolean or takes over 5 seconds), and in the contact, careers, newsletter, flow-step, flow-checkout, saved-recommendation and `/dev/purchase` Server Actions immediately before their hub call, which answer their own existing failure variant. The locale layout's `BotIdClient` protects every same-origin POST (`BOT_CLIENT_PROTECT`, `/*`), because a Server Action posts to the page it was submitted from; `next.config.mjs` wraps `withBotId` and `middleware.ts` keeps BotID's proxy prefix out of its matcher. It is on by default and inert off Vercel: `AILK_BOT_CHECK=off` turns every check off, `AILK_BOOKING_BOT_CHECK=off` the booking's alone, and MCP tools never pass through a site, so they are never challenged.
+- **A bot check on the public writes (#9889, #9255).** On Vercel, `lib/bot-check.ts`'s `runBotCheck` asks Vercel BotID for a verdict before the hub is called — in the relay for `POST /v1/leads/{submit,subscribe,callback}` and `POST /v1/schedule/book` (`BOT_CHECKED_ROUTES`: `403 bot_detected`, or `503 bot_check_unavailable` when the check throws, answers no boolean or takes over 5 seconds), and in the contact, careers, newsletter, flow-step, flow-checkout, saved-recommendation and `/dev/purchase` Server Actions immediately before their hub call, which answer their own existing failure variant. The locale layout's `BotIdClient` protects every same-origin POST (`BOT_CLIENT_PROTECT`, `/*`), because a Server Action posts to the page it was submitted from; `next.config.mjs` wraps `withBotId` and `middleware.ts` keeps BotID's proxy prefix out of its matcher. It is on by default and inert off Vercel: `AILK_BOT_CHECK=off` turns every check off, `AILK_BOOKING_BOT_CHECK=off` the booking's alone, and MCP tools never pass through a site, so they are never challenged. A refusal logs `[<source>] bot refused` with BotID's `classificationReason`, `bypassed` and `isVerifiedBot`, the request's `host` and `forwardedHost`, and `proxied` (a `cf-ray` header) — no other header value, no form field (#10715). `AILK_BOT_CHECK=observe` runs the check and logs the same facts plus `isBot` as `observed`, but passes every write — for diagnosis only. **A BotID-protected site must be reached directly — Cloudflare DNS-only, no reverse proxy in front of Vercel (#10715).** Behind a proxy the write reaches Vercel from the proxy's egress rather than the browser that solved the challenge, so BotID refuses every real visitor; the first proxied request per process logs `[<source>] reverse proxy detected` (outcome `proxied`) naming that fix.
 - `/v1` is exempt from next-intl's locale rewrite in `middleware.ts`, as `/api` is.
 
 ## Where the docs live (`docsPath`)
@@ -602,6 +619,15 @@ A list page whose frontmatter sets `navOnly: true` (valid on a registry list typ
 - **Not honoured.** The docs-blog module's Fumadocs `/blog` and `/docs`; `DownloadsList` (`/downloads` already redirects to `/reports`); `LocationsList` (no route). `/sitemap.xml` and `/llms.txt` still list a Nav-only list's URL.
 - **The nav is untouched.** `lib/nav-config.ts` is generated from route surfaces, not from list pages, so the heading and its children stay in the menu.
 
+## The owner's discovery switch
+
+**One switch hides the site from AI and search tools (#10510).** The Admin's MCP tab writes the workspace's `discoverable` setting; this app reads it through `siteDiscoverable()` from `@working-theory/api-client` (`GET /v1/content/discovery`, the workspace the API resolves for this site's key), shared per server instance for 15 seconds, the last answer on a failed read and on when there is none — it never rejects.
+
+- **The seven handlers.** `robots.txt`, `sitemap.xml`, `llms.txt` (both copies — the docs + blog module's `lib/slices/docs-blog/llms-route.ts` too), `.well-known/mcp.json`, `.well-known/ai-plugin.json` and `openapi.json` are `force-dynamic` and read it once per request, after the checks each already makes and before any other work. `createSitemapHandler` and `createLlmsHandler` take a `discoverable` dep (default `siteDiscoverable`); every test caller passes one, so no suite reads a hub.
+- **On** is today, byte for byte. **Off**: robots.txt answers STEALTH's `User-agent: *` / `Disallow: /` with no Sitemap line; the other five answer 404 with no body (mcp.json keeps its CORS headers; its `OPTIONS` is unchanged). Every off answer is `cache-control: no-store`, so a crawler asks again.
+- **Hidden wins.** With `STEALTH` on, or no public page (`PUBLIC_PAGES` false), robots.txt answers as before and makes no read; sitemap.xml and llms.txt 404 before it.
+- **Pages are never hidden.** No page, layout or `middleware.ts` reads the switch, and `<meta robots>` and `X-Robots-Tag` stay `STEALTH`'s alone: off is a preference about discovery, not access control. `STEALTH` remains the hard, deploy-time hide.
+
 ## AEO & performance
 
 - Static rendering is the default. Don't introduce client rendering without a reason.
@@ -618,7 +644,15 @@ A list page whose frontmatter sets `navOnly: true` (valid on a registry list typ
 - Don't reach into `apps/api` or `apps/mcp` from `apps/web`. They're peer apps — talk via HTTP/MCP.
 - Don't commit images to `screenshots/` — only the `.gitkeep` is tracked.
 
-Last updated: 2026-10-28 — § Nav-only lists (`navOnly`): a Nav-only list's route answers 308 to its first child and 404 with none (#10200) — verified against `lib/hub-children.tsx` and the nine list routes it is called from beside the hubs.
+Last updated: 2026-11-02 — § Theme & styling: `consent.appearance` named beside the other `_site.mdx` chrome keys, and the minimal deck home's hold-back is the band's alone, so a minimal site that picks the card sees it on load there too (#10721) — verified against `app/[locale]/layout.tsx`.
+
+Prior: 2026-11-02 — § The same-origin relay: a bot-check refusal names its cause (`classificationReason`, `bypassed`, `isVerifiedBot`, both hosts, `proxied`), `AILK_BOT_CHECK=observe` logs and never refuses, and a BotID-protected site must be reached directly, Cloudflare DNS-only (#10715) — verified against `lib/bot-check.ts`.
+
+Prior: 2026-11-01 — § The owner's discovery switch: the six discovery files read the workspace's `discoverable` setting per request through `siteDiscoverable()`, off answering robots.txt's disallow-all and 404 for the rest, never cached (#10510) — verified against `app/{robots.txt,sitemap.xml,llms.txt,openapi.json}/route.ts`, `app/.well-known/{mcp.json,ai-plugin.json}/route.ts`, `lib/slices/docs-blog/llms-route.ts` and `packages/api-client/src/discovery.ts`.
+
+Prior: 2026-10-30 — § The MCP authorization server: the site's OAuth 2.1 authorization server, its consent step, rotation and revocation (#10357) — verified against `auth.ts`, `lib/mcp-oauth.ts`, `app/[locale]/(auth)/consent/` and `app/.well-known/oauth-authorization-server/route.ts`.
+
+Prior: 2026-10-28 — § Nav-only lists (`navOnly`): a Nav-only list's route answers 308 to its first child and 404 with none (#10200) — verified against `lib/hub-children.tsx` and the nine list routes it is called from beside the hubs.
 
 Prior: 2026-10-27 — § Where the services live (`services.path`): the services base, one category level, the 308 from `/services` and the `update-page` base move (#10043) — verified against `lib/services-path.ts`, `lib/service-listing.ts`, `middleware.ts`, `next.config.mjs` and `app/[locale]/services/`.
 

package/templates/apps/web/app/.well-known/ai-plugin.json/route.ts

@@ -28,9 +28,15 @@
  * See `docs/security/agent-manifest.md` for the full consumer guidance.
  */
 
+import { siteDiscoverable } from "@working-theory/api-client";
+
 import { SITE_DESCRIPTION, SITE_NAME } from "../../../lib/site-brand";
 import { 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";
+
 /** Soft cap to detect runaway `description_for_model` growth. */
 export const DESCRIPTION_FOR_MODEL_SOFT_CAP_CHARS = 8_000;
 
@@ -59,7 +65,9 @@ export function validateDescriptionForModel(description: string): boolean {
 // are flagged before the first request lands.
 validateDescriptionForModel(MANIFEST_DESCRIPTION_FOR_MODEL);
 
-export function GET(): Response {
+export async function GET(): Promise<Response> {
+  // #10510 D4 — hidden by the owner: 404, never cached.
+  if (!(await siteDiscoverable())) return new Response(null, { status: 404, headers: { "cache-control": "no-store" } });
   const baseUrl = resolveBaseUrl();
 
   const manifest = {

package/templates/apps/web/app/.well-known/mcp.json/build-manifest.ts

@@ -24,6 +24,8 @@
  * Issue #8057 — `description` resolves from SITE_DESCRIPTION
  * (`siteIdentity.description` in _site.mdx → neutral default) instead of the
  * template's own blurb on every site.
+ * Issue #10392 — `authorization` names where an OAuth client signs in to the
+ * workspace tools, when the site pins its issuer and advertises its MCP host.
  */
 
 import {
@@ -78,6 +80,16 @@ export interface McpManifest {
   ailk: {
     version: string;
   };
+  /**
+   * Where an OAuth client signs in to the workspace tools (#10392 D8). Present
+   * only when the site pins its issuer and advertises its MCP host.
+   */
+  authorization?: {
+    /** RFC 8414: the site's authorization-server metadata. */
+    authorizationServerMetadata: string;
+    /** RFC 9728: the workspace endpoint's protected-resource metadata. */
+    protectedResourceMetadata: string;
+  };
 }
 
 export interface BuildMcpManifestOptions {
@@ -91,6 +103,13 @@ export interface BuildMcpManifestOptions {
    * Typically sourced from the MCP_PUBLIC_HTTP_URL env var in the web app.
    */
   mcpHttpUrl?: string;
+  /**
+   * Optional: the site's OAuth issuer — the origin apps/web serves its
+   * authorization server from (`BETTER_AUTH_URL`, #10392 D8). With
+   * `mcpHttpUrl`, the manifest names the two OAuth metadata URLs. Injected,
+   * like `mcpHttpUrl`, so the builder stays pure.
+   */
+  authIssuer?: string;
   /**
    * Whether this deployment holds the `commerce` add-on licence claim
    * (#5971). Add-on-gated tools — today only `start_purchase` — are advertised
@@ -125,6 +144,42 @@ export interface BuildMcpManifestOptions {
 /** MCP HTTP transport version this server implements. */
 const MCP_HTTP_VERSION = "2025-03-26";
 
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+
+/** A URL a client may trust for OAuth: `https:`, or `http:` on a loopback host. */
+function trustableUrl(value: string | undefined): URL | null {
+  if (!value) return null;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol === "https:") return url;
+  if (url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname)) return url;
+  return null;
+}
+
+/**
+ * The two OAuth metadata URLs (#10392 D8), or `undefined` unless both the
+ * issuer and the MCP host are trustable — so the manifest never advertises a
+ * sign-in surface the site has not turned on. The protected resource is the
+ * workspace endpoint, RFC 9728's path-inserted location on the MCP origin.
+ */
+function authorizationFor(
+  authIssuer: string | undefined,
+  mcpHttpUrl: string | undefined,
+): McpManifest["authorization"] {
+  const issuer = trustableUrl(authIssuer);
+  const mcp = trustableUrl(mcpHttpUrl);
+  if (!issuer || !mcp) return undefined;
+  const mcpPath = mcp.pathname.replace(/\/+$/, "");
+  return {
+    authorizationServerMetadata: new URL("/.well-known/oauth-authorization-server", issuer).href,
+    protectedResourceMetadata: `${mcp.origin}/.well-known/oauth-protected-resource${mcpPath}/workspace`,
+  };
+}
+
 /**
  * Builds the /.well-known/mcp.json manifest. Pure: same input → same output.
  */
@@ -142,6 +197,8 @@ export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
     });
   }
 
+  const authorization = authorizationFor(opts.authIssuer, opts.mcpHttpUrl);
+
   return {
     schemaVersion: "1",
     name: SITE_NAME,
@@ -160,5 +217,6 @@ export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
     },
     transports,
     ailk: { version: opts.ailkVersion },
+    ...(authorization ? { authorization } : {}),
   };
 }

package/templates/apps/web/app/.well-known/mcp.json/route.ts

@@ -28,6 +28,8 @@
  * is appropriate per the MCP discovery spec.
  */
 
+import { siteDiscoverable } from "@working-theory/api-client";
+
 import { UNSERVED_MCP_TOOLS } from "../../../lib/topology.generated";
 import packageJson from "../../../package.json";
 import {
@@ -37,6 +39,10 @@ import {
 
 import { buildMcpManifest } from "./build-manifest";
 
+// #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";
+
 const CORS_HEADERS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, OPTIONS",
@@ -51,11 +57,20 @@ export function OPTIONS(): Response {
 }
 
 export async function GET(): Promise<Response> {
+  // #10510 D4 — hidden by the owner: 404, never cached, before the licence read.
+  if (!(await siteDiscoverable())) {
+    return new Response(null, {
+      status: 404,
+      headers: { "cache-control": "no-store", ...CORS_HEADERS },
+    });
+  }
   // MCP_PUBLIC_HTTP_URL advertises the standalone HTTP transport endpoint
   // (apps/mcp running in HTTP mode). When set, the manifest names it as
   // `mcpEndpoint` and as an http transport descriptor; when unset, it
   // advertises no MCP URL at all (#7396).
   const mcpHttpUrlEnv = process.env["MCP_PUBLIC_HTTP_URL"];
+  // With it, the site's pinned issuer turns on the OAuth metadata (#10392).
+  const authIssuerEnv = process.env["BETTER_AUTH_URL"];
   const heldFeatures = await resolveLicenceFeatures();
 
   const manifest = buildMcpManifest({
@@ -71,6 +86,7 @@ export async function GET(): Promise<Response> {
     // Spread conditional to satisfy exactOptionalPropertyTypes: omit the key
     // entirely when the env var is not set rather than passing undefined.
     ...(mcpHttpUrlEnv ? { mcpHttpUrl: mcpHttpUrlEnv } : {}),
+    ...(authIssuerEnv ? { authIssuer: authIssuerEnv } : {}),
   });
 
   return Response.json(manifest, {

package/templates/apps/web/app/.well-known/oauth-authorization-server/route.ts

@@ -0,0 +1,53 @@
+/**
+ * GET /.well-known/oauth-authorization-server
+ *
+ * The site's RFC 8414 authorization-server metadata (#10357 D7), at the root
+ * where RFC 8414 and MCP client discovery look for it. It is the `mcp`
+ * plugin's own document — whose HTTP copy under `/api/auth` is disabled, so
+ * there is one — with four AILK edits:
+ *
+ * - `revocation_endpoint` (AILK's RFC 7009 route) and its auth methods;
+ * - `scopes_supported` limited to `offline_access` and the `ailk:*` scopes;
+ * - `jwks_uri` and `userinfo_endpoint` removed — neither route exists; the
+ *   plugin's tokens are opaque and validated by lookup (D1);
+ * - the grant types, PKCE method and RFC 9207 `iss` support stated.
+ *
+ * 404 when the authorization server is not installed (no pinned
+ * BETTER_AUTH_URL — `auth.ts` D4). Public, credential-free, cross-origin by
+ * design, like `.well-known/mcp.json`.
+ */
+import { MCP_SCOPES } from "@working-theory/validation";
+
+import { auth } from "../../../auth";
+
+const HEADERS = {
+  "Cache-Control": "public, max-age=300",
+  "Access-Control-Allow-Origin": "*",
+} as const;
+
+type Metadata = Record<string, unknown> & {
+  token_endpoint?: string;
+  token_endpoint_auth_methods_supported?: unknown;
+};
+
+export async function GET(): Promise<Response> {
+  const read: unknown = Reflect.get(auth.api, "getMcpOAuthConfig");
+  if (typeof read !== "function") return new Response(null, { status: 404 });
+  const metadata = (await read()) as Metadata | null;
+  if (!metadata?.token_endpoint) return new Response(null, { status: 404 });
+
+  const { jwks_uri: _jwks, userinfo_endpoint: _userinfo, ...rest } = metadata;
+  const base = metadata.token_endpoint.replace(/\/mcp\/token$/, "");
+  return Response.json(
+    {
+      ...rest,
+      revocation_endpoint: `${base}/mcp/revoke`,
+      revocation_endpoint_auth_methods_supported: metadata.token_endpoint_auth_methods_supported,
+      scopes_supported: ["offline_access", ...MCP_SCOPES],
+      grant_types_supported: ["authorization_code", "refresh_token"],
+      code_challenge_methods_supported: ["S256"],
+      authorization_response_iss_parameter_supported: true,
+    },
+    { headers: HEADERS },
+  );
+}

package/templates/apps/web/app/[locale]/(auth)/__tests__/password-reset.test.tsx

@@ -62,7 +62,14 @@ jest.mock("better-auth/next-js", () => ({
   nextCookies: () => ({ id: "next-cookies" }),
 }));
 
-jest.mock("better-auth/plugins", () => ({ magicLink: () => ({ id: "magic-link" }) }));
+jest.mock("better-auth/plugins", () => ({
+  magicLink: () => ({ id: "magic-link" }),
+  mcp: () => ({ id: "mcp" }),
+}));
+
+// The MCP authorization server (#10357 D12): its ESM-only module never loads here.
+// eslint-disable-next-line no-restricted-syntax -- #507: lib/mcp-oauth statically imports ESM-only better-auth/api, which CommonJS Jest cannot load.
+jest.mock("../../../../lib/mcp-oauth", () => ({ mcpOAuthPlugin: () => ({ id: "ailk-mcp-oauth" }) }));
 
 /**
  * The signer seam. `buildAuthEmailRequest` has exactly one external

package/templates/apps/web/app/[locale]/(auth)/consent/__tests__/consent-actions.test.ts

@@ -0,0 +1,56 @@
+/**
+ * @jest-environment node
+ *
+ * `decideConsent` — the consent page's Allow and Deny (#10357 D6). `auth` is
+ * mocked; `POST /mcp/consent` runs for real in
+ * `__tests__/auth/mcp-oauth-flow.test.ts`. This suite proves the fallback
+ * redirect is always a path on this site.
+ */
+const mockConsent = jest.fn();
+const mockRedirect = jest.fn();
+
+// eslint-disable-next-line no-restricted-syntax -- #507: auth.ts loads ESM-only better-auth; its consent endpoint runs for real in mcp-oauth-flow.test.ts.
+jest.mock("../../../../../auth", () => ({
+  auth: { api: { mcpConsent: (...args: unknown[]) => mockConsent(...args) } },
+}));
+
+jest.mock("next/headers", () => ({ headers: jest.fn().mockResolvedValue(new Headers()) }));
+
+jest.mock("next/navigation", () => ({ redirect: (...args: unknown[]) => mockRedirect(...args) }));
+
+import { decideConsent } from "../consent.actions";
+
+function form(values: Record<string, string>): FormData {
+  const data = new FormData();
+  for (const [key, value] of Object.entries(values)) data.append(key, value);
+  return data;
+}
+
+beforeEach(() => {
+  mockConsent.mockReset();
+  mockRedirect.mockReset();
+});
+
+it("goes to the client's callback when the consent endpoint answers one", async () => {
+  mockConsent.mockResolvedValue({ redirectURI: "http://127.0.0.1:53682/callback?code=c" });
+  await decideConsent(form({ consent_code: "abc", locale: "en", decision: "deny" }));
+  expect(mockRedirect).toHaveBeenCalledWith("http://127.0.0.1:53682/callback?code=c");
+});
+
+it("returns to this site's consent page on a refusal", async () => {
+  mockConsent.mockRejectedValue(new Error("refused"));
+  await decideConsent(form({ consent_code: "abc", locale: "en", decision: "allow" }));
+  expect(mockRedirect).toHaveBeenCalledWith(expect.stringMatching(/^\/(en\/)?consent\?consent_code=abc$/));
+});
+
+it.each(["/evil.example", "//evil.example", "en/../..", "https://evil.example"])(
+  "never builds the fallback from a posted locale of %s",
+  async (locale) => {
+    mockConsent.mockRejectedValue(new Error("refused"));
+    await decideConsent(form({ consent_code: "abc", locale, decision: "allow" }));
+    const target = String(mockRedirect.mock.calls[0]?.[0]);
+    expect(target.startsWith("//")).toBe(false);
+    expect(target).not.toContain("evil.example");
+    expect(target).toMatch(/^\/(en\/)?consent\?consent_code=abc$/);
+  },
+);

package/templates/apps/web/app/[locale]/(auth)/consent/__tests__/page.test.tsx

@@ -0,0 +1,164 @@
+/**
+ * The MCP consent page (#10357 D6, AC-6). `auth` is mocked — the endpoints it
+ * calls run for real in `__tests__/auth/mcp-oauth-flow.test.ts`; this suite
+ * proves what the page renders from their answer and what it never reads.
+ *
+ * `next-intl/server` is mocked globally (apps/web/__tests__/setup.ts) against
+ * the real en.json.
+ */
+import { fireEvent, render, screen } from "@testing-library/react";
+
+const mockGetSession = jest.fn();
+const mockDetails = jest.fn();
+
+// eslint-disable-next-line no-restricted-syntax -- #507: auth.ts loads ESM-only better-auth; its consent endpoints run for real in mcp-oauth-flow.test.ts.
+jest.mock("../../../../../auth", () => ({
+  auth: {
+    api: {
+      getSession: (...args: unknown[]) => mockGetSession(...args),
+      mcpConsentDetails: (...args: unknown[]) => mockDetails(...args),
+    },
+  },
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- #507: the server action imports auth.ts (ESM-only better-auth).
+jest.mock("../consent.actions", () => ({ decideConsent: jest.fn() }));
+
+jest.mock("next/headers", () => ({
+  headers: jest.fn().mockResolvedValue(new Headers({ cookie: "session=1" })),
+}));
+
+jest.mock("better-auth/react", () => ({
+  __esModule: true,
+  createAuthClient: () => ({ signOut: jest.fn() }),
+}));
+
+// The shared mock neither interpolates nor reads nested keys; this page shows
+// the email, the client name and the scope labels, so this suite's mock does.
+jest.mock("next-intl/server", () => {
+  const catalog = jest.requireActual("../../../../../messages/en.json") as Record<string, unknown>;
+  return {
+    getTranslations: async ({ namespace }: { namespace: string }) =>
+      (key: string, values: Record<string, string> = {}) => {
+        const found = `${namespace}.${key}`
+          .split(".")
+          .reduce<unknown>((node, part) => (node as Record<string, unknown> | undefined)?.[part], catalog);
+        return String(found ?? `${namespace}.${key}`).replace(/\{(\w+)\}/g, (_, name: string) => values[name] ?? "");
+      },
+  };
+});
+
+jest.mock("next/navigation", () => ({
+  useRouter: () => ({ push: jest.fn(), refresh: jest.fn() }),
+  redirect: jest.fn(),
+}));
+
+import en from "../../../../../messages/en.json";
+import ConsentPage, { generateMetadata } from "../page";
+
+const params = Promise.resolve({ locale: "en" });
+const MEMBER_SCOPES = ["ailk:people-read", "ailk:member-pieces-manage", "ailk:people-memory-propose", "ailk:inbox-act"];
+const t = en.mcpConsent;
+
+const twoWorkspaces = {
+  client: { name: "Some App", redirectOrigin: "http://127.0.0.1:53682" },
+  workspaces: [
+    { id: "wksp_a", name: "Alpha", organizationName: "Alpha Co", role: "member", offered: MEMBER_SCOPES },
+    { id: "wksp_b", name: "Beta", organizationName: "Beta Co", role: "member", offered: MEMBER_SCOPES },
+  ],
+};
+
+async function renderPage(query: Record<string, string> = { consent_code: "code-1" }) {
+  render(await ConsentPage({ params, searchParams: Promise.resolve(query) }));
+}
+
+beforeEach(() => {
+  mockGetSession.mockResolvedValue({ user: { email: "person@example.test" } });
+  mockDetails.mockResolvedValue(twoWorkspaces);
+});
+
+describe("the consent page (#10357 AC-6)", () => {
+  it("names the signed-in person, the client's own claim and where the code goes", async () => {
+    await renderPage();
+    expect(screen.getByTestId("mcp-consent-signed-in")).toHaveTextContent("person@example.test");
+    expect(screen.getByTestId("mcp-consent-client")).toHaveTextContent(
+      t.clientClaim.replace("{name}", "Some App"),
+    );
+    expect(screen.getByTestId("mcp-consent-redirect-origin")).toHaveTextContent("http://127.0.0.1:53682");
+    expect(screen.getByTestId("mcp-consent-sign-out")).toBeInTheDocument();
+  });
+
+  it("renders one radio per workspace, none checked when there are two, and Allow disabled", async () => {
+    await renderPage();
+    for (const id of ["wksp_a", "wksp_b"]) {
+      expect(screen.getByTestId(`mcp-consent-workspace-${id}`)).toHaveAttribute("aria-checked", "false");
+    }
+    expect(screen.getByTestId("mcp-consent-allow")).toBeDisabled();
+    expect(screen.queryByTestId("mcp-consent-scope-people-read")).toBeNull();
+  });
+
+  it("on choosing a workspace shows its offered scopes unticked, the member-reads line, and enables Allow", async () => {
+    await renderPage();
+    fireEvent.click(screen.getByTestId("mcp-consent-workspace-wksp_b"));
+    for (const scope of MEMBER_SCOPES) {
+      const permission = scope.slice("ailk:".length);
+      expect(screen.getByTestId(`mcp-consent-scope-${permission}`)).toHaveAttribute("aria-checked", "false");
+    }
+    expect(screen.queryByTestId("mcp-consent-scope-content-edit")).toBeNull();
+    expect(screen.getByText(t.scopes["people-read"])).toBeInTheDocument();
+    expect(screen.getByTestId("mcp-consent-member-reads")).toHaveTextContent(t.memberReads);
+    expect(screen.getByTestId("mcp-consent-allow")).not.toBeDisabled();
+  });
+
+  it("pre-selects the only workspace", async () => {
+    mockDetails.mockResolvedValue({ ...twoWorkspaces, workspaces: [twoWorkspaces.workspaces[0]] });
+    await renderPage();
+    expect(screen.getByTestId("mcp-consent-workspace-wksp_a")).toHaveAttribute("aria-checked", "true");
+    expect(screen.getByTestId("mcp-consent-allow")).not.toBeDisabled();
+  });
+
+  it("reads only consent_code from its query — never a client-controlled scope or client_id", async () => {
+    await renderPage({ consent_code: "code-1", scope: "ailk:content-edit", client_id: "evil" });
+    expect(mockDetails).toHaveBeenCalledWith(
+      expect.objectContaining({ query: { consent_code: "code-1" } }),
+    );
+    fireEvent.click(screen.getByTestId("mcp-consent-workspace-wksp_a"));
+    expect(screen.queryByTestId("mcp-consent-scope-content-edit")).toBeNull();
+    expect(document.body.textContent).not.toContain(t.scopes["content-edit"]);
+    expect(document.body.textContent).not.toContain("evil");
+  });
+
+  it("has Allow and Deny as 44 px buttons in one form", async () => {
+    await renderPage();
+    expect(screen.getByTestId("mcp-consent-form")).toContainElement(screen.getByTestId("mcp-consent-deny"));
+    expect(screen.getByTestId("mcp-consent-deny").className).toContain("control-height-big");
+  });
+
+  it("renders the unavailable line and no form when details are refused", async () => {
+    mockDetails.mockRejectedValue(new Error("invalid_request"));
+    await renderPage();
+    expect(screen.getByTestId("mcp-consent-unavailable")).toHaveTextContent(t.unavailable);
+    expect(screen.queryByTestId("mcp-consent-form")).toBeNull();
+  });
+
+  it("renders the unavailable line with no session, and without a consent_code", async () => {
+    mockGetSession.mockResolvedValue(null);
+    await renderPage();
+    expect(screen.getByTestId("mcp-consent-unavailable")).toBeInTheDocument();
+    mockGetSession.mockResolvedValue({ user: { email: "person@example.test" } });
+  });
+
+  it("offers Deny only when the person has no workspace", async () => {
+    mockDetails.mockResolvedValue({ ...twoWorkspaces, workspaces: [] });
+    await renderPage();
+    expect(screen.getByTestId("mcp-consent-no-workspace")).toHaveTextContent(t.noWorkspace);
+    expect(screen.queryByTestId("mcp-consent-allow")).toBeNull();
+    expect(screen.getByTestId("mcp-consent-deny")).toBeInTheDocument();
+  });
+
+  it("is noindex and sends no cross-site referrer", async () => {
+    const metadata = await generateMetadata({ params, searchParams: Promise.resolve({}) });
+    expect(metadata.robots).toEqual({ index: false, follow: false });
+    expect(metadata.referrer).toBe("same-origin");
+  });
+});