create-ailk 0.29.1 → 0.30.0

package/templates/apps/mcp/CLAUDE.md

@@ -57,6 +57,13 @@ now mean `packages/mcp-server/src/<file>`.
   instance answers), `false`/`0` stateful (sessions in one process's memory). Unset, the
   Vercel entry is stateless and `src/index.ts` is stateful. Any other value fails the boot.
   The Vercel entry needs stateless: a session kept in one instance is lost on the next.
+- **The owner's discovery switch (#10510 D5).** `httpTransportConfigFromEnv()` sets
+  `discoverable: siteDiscoverable` (`@working-theory/api-client`), so while the owner has hidden
+  the site, GET, POST and DELETE on the anonymous path answer Fastify's own 404 — an off server
+  looks like none — before the abuse guard or any tool runs. It is read per request through the
+  reader's 15-second shared answer; a failed read keeps the last answer, then on.
+  `/mcp/workspace`, its protected-resource metadata and stdio are untouched. A hub's own tool
+  server needs the hub site's `AILK_SPOKE_KEY`, or its hub refuses the read and the server stays on.
 - **Content root.** Every content tool and `audit` take their root from `mcpContentRoot()`
   (`lib/content-adapter.ts`): `AILK_CONTENT_ROOT`, else `<cwd>/content`, else
   `<cwd>/../../content`. Never build a content path from `process.cwd()` in a tool — the one
@@ -130,9 +137,11 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 
 - **22 in the `TOOLS` array / parity test**: the `TOOLS` array in
   `packages/metadata/src/mcp-tool-catalog.ts` defines 22 anonymous tools; the
-  parity test counts that full array. It also holds the thirty-three signed-in
+  parity test counts that full array. It also holds the thirty-seven signed-in
   workspace tools (#3591; the content-suggestion pair `draft_page_suggestions`
-  and `decide_page_suggestion` since #10218), which no anonymous view returns — see § The
+  and `decide_page_suggestion` since #10218; the draft pair `save_draft` and
+  `read_report` since #10336; the knowledge-base pair `read_knowledge` and
+  `read_knowledge_doc` since #10345), which no anonymous view returns — see § The
   signed-in workspace surface below.
 - **20 registered on a KEYLESS deployment, 21 on a commerce-claimed one,
   while the Free level is held or over HTTP — 21 and 22 over stdio once it is
@@ -178,12 +187,14 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
 - **apps/mcp checks only the key's shape.** The key is attached as the SDK's `req.auth` for that
   request alone and reaches a tool as `extra.authInfo.token`. apps/api is the one place it is
   checked, and its tenant guard and the caller's clamped role decide every answer.
-- **Thirty-one tools, each a `twin`.** The catalog rows carry `surface: "workspace"`, `tier: "pro"`
+- **Thirty-eight tools, each a `twin`.** The catalog rows carry `surface: "workspace"`, `tier: "pro"`
   and `modulesAnyOf` (the modules any one of which registers the tool — its twin route's gate):
   `get_agent_context`, (#9683) `get_workspace_knowledge` — twin of `GET
   /v1/workspaces/:workspaceId/knowledge`: the business's shown offerings, live magnets, listed
   meeting types, sites served and strategy documents, read with the `people-read` or
-  `people-memory-propose` grant — the five message tools (#9686 added `list_inbox_threads`, twin of
+  `people-memory-propose` grant — (#10393) `list_connected_clients` — twin of `GET
+  /v1/workspaces/:workspaceId/clients`: the AI clients and agent keys connected to the workspace,
+  only the caller's own person's for an agent; revoking has no tool — the five message tools (#9686 added `list_inbox_threads`, twin of
   `GET …/messages/threads`: the inbox's threads, 25 to a page with a count per view; Done now
   archives the message's thread and accept no longer marks it done, and an agent reaches any
   inbox tool only with the `inbox-act` grant), the three submission tools, the three
@@ -198,18 +209,35 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
   tools, `list_proposals` and `create_proposal`, twinning `GET`/`POST
   /v1/workspaces/:workspaceId/people/:personId/proposals` with the same grant: a proposal is
   private to one client, `payments` says whether approval leads to a Stripe page, and an agent's
-  price is refused `proposal_needs_person` (a person prices) — and (#9681) the four person-thread tools, `get_person_thread`, `set_person_thread_state`, `list_external_threads` and `add_external_thread`, twinning `GET`/`PATCH …/people/:personId/thread` and `GET`/`POST …/people/:personId/external-threads`: a client's whole thread page by page with its read/archived/resolved state, and pointers to email and Slack threads (never message text); reading needs the `people-read` grant, writing also `inbox-act`, and the client erasure route has no tool, by decision — and (#9682) the three person-memory tools, `list_person_memories`, `get_person_memory` and `propose_person_memory`, twinning `GET …/people/:personId/memories`, `GET …/memories/:path` and `POST …/memories`: an agent reads only live, unexpired memories (confirmed by a person, read within 180 days) and its proposal is never live — a new path is a draft, a confirmed one gets a pending version — needing the `people-read` or `people-memory-propose` grant to read and `people-memory-propose` to propose; the six person-only memory routes (edit, delete, confirm, redact, the versions list, restore) have no tool, by decision — and (#9749) `get_slack_connection_status`, twin of `GET /v1/workspaces/:workspaceId/slack-connection` (registered with `workspace`/`multi-tenant`, its route's `TENANCY` row: whether the Organization's Slack is connected, its team name and the date, never a credential; connect and disconnect are a person's act and have no tool, by decision), and `get_prospect_channel_settings` / `set_prospect_channel_settings`, twins of `GET`/`PUT …/prospect-channel` (registered with `scheduling`, their routes' module): the update replaces every field, needs the `meeting-types-manage` grant, is refused `slack_not_connected` while the Organization has no Slack connection, and an agent may change only `enabled`, `channelPrefix` and `archiveDays` — a change to `memberIds` or `welcomeTemplate` is refused `prospect_channel_needs_person`. Each takes its route's params, query and body and returns the route's
+  price is refused `proposal_needs_person` (a person prices) — and (#9681) the four person-thread tools, `get_person_thread`, `set_person_thread_state`, `list_external_threads` and `add_external_thread`, twinning `GET`/`PATCH …/people/:personId/thread` and `GET`/`POST …/people/:personId/external-threads`: a client's whole thread page by page with its read/archived/resolved state, and pointers to email and Slack threads (never message text); reading needs the `people-read` grant, writing also `inbox-act`, and the client erasure route has no tool, by decision — and (#9682) the three person-memory tools, `list_person_memories`, `get_person_memory` and `propose_person_memory`, twinning `GET …/people/:personId/memories`, `GET …/memories/:path` and `POST …/memories`: an agent reads only live, unexpired memories (confirmed by a person, read within 180 days) and its proposal is never live — a new path is a draft, a confirmed one gets a pending version — needing the `people-read` or `people-memory-propose` grant to read and `people-memory-propose` to propose; the six person-only memory routes (edit, delete, confirm, redact, the versions list, restore) have no tool, by decision — and (#9749) `get_slack_connection_status`, twin of `GET /v1/workspaces/:workspaceId/slack-connection` (registered with `workspace`/`multi-tenant`, its route's `TENANCY` row: whether the Organization's Slack is connected, its team name and the date, never a credential; connect and disconnect are a person's act and have no tool, by decision), and `get_prospect_channel_settings` / `set_prospect_channel_settings`, twins of `GET`/`PUT …/prospect-channel` (registered with `scheduling`, their routes' module): the update replaces every field, needs the `meeting-types-manage` grant, is refused `slack_not_connected` while the Organization has no Slack connection, and an agent may change only `enabled`, `channelPrefix` and `archiveDays` — a change to `memberIds` or `welcomeTemplate` is refused `prospect_channel_needs_person` — and (#10218) the content-suggestion pair, `draft_page_suggestions` and `decide_page_suggestion` — and (#10336) the draft pair, `save_draft` and `read_report`, twinning `PATCH`/`GET …/content/:type/:slug` with the `content-edit` grant: `save_draft` takes the page's `content` whole as the PATCH body and its `version` as `X-Draft-Version`, writes a draft version that never goes live (no tool publishes; a person does), and answers 409 `conflict` with `currentVersion` when the draft moved; `read_report` returns the draft tip, the version a save must send, its open suggestions and the route's check report (`ready`, `needs repair` or `needs your words`), computed by the route and never by the tool — and (#10345) the knowledge-base pair, `read_knowledge` and `read_knowledge_doc`, twinning `GET …/knowledge-base` and `GET …/knowledge-base/:type/:slug` with no grant (`docs-read` is every role's): the docs a named member may read (`userId`, by default the agent's own person), at the lower of the agent's person's role and that member's, so naming someone only narrows; Live does not gate them and a disabled doc never appears; `filter: "workspace-memory"` answers the always-loaded set with its `totalTokens` and an 8000-token `warning`. No workspace tool sets Live, widens Audience or re-enables a doc — those routes answer an agent 403 `agent_refused`, which reaches a tool as the code and status. Each takes its route's params, query and body and returns the route's
   `data`. They are in the parity guard like every other tool, and never in
   `/.well-known/mcp.json`.
+- **The OAuth bearer branch (#10391).** When `BETTER_AUTH_URL` (the site's origin, its OAuth
+  2.1 authorization server, #10357) and `MCP_PUBLIC_HTTP_URL` are both `https:` (or `http:` on a
+  loopback host), `/mcp/workspace` also accepts the site's access token — only the plugin's
+  shape, `Bearer` + 32 ASCII letters, so an arbitrary string is 401 with no lookup. Each request
+  is validated by one `GET <BETTER_AUTH_URL>/api/auth/mcp/token-info` (`oauth-bearer.ts`: 5 s
+  timeout, no redirect followed, nothing cached — a revoked token fails its next call). A valid
+  token reaches tools as `AuthInfo` (`clientId`, the `ailk:*` scopes the live grants still name,
+  `expiresAt`, `resource`, and `extra: { kind: "oauth", userId, workspaceId, actingRole }`), its
+  `token` forwarded to apps/api like a key; a `tools/call` whose `arguments.workspaceId` is not
+  the token's workspace is 401 before any tool runs. While the branch is on, every 401 carries
+  `WWW-Authenticate: Bearer [error="invalid_token", ]resource_metadata="…"`, the RFC 9728
+  document is served at `/.well-known/oauth-protected-resource${path}/workspace` (no root
+  document), and an authorization server that cannot answer is `503 authorization_unavailable`
+  with `Retry-After: 5` — never a pass and never a 401. Issuer and resource come from env only,
+  never a request's `Host`. Either name unset, the route takes agent keys only, exactly as before;
+  a spoke has no authorization server, so it leaves `BETTER_AUTH_URL` unset. `/mcp` is untouched.
 - **Handlers forward, nothing else.** `workspace-server.ts` resolves each tool from
   `@working-theory/mcp-workspace`'s `workspaceTools` (`agent_context.ts`, `knowledge.ts`, `inbox_messages.ts`,
-  `inbox_submissions.ts`, `inbox_applications.ts`, `people_list.ts`, `person_notes.ts`, `person_thread.ts`, `person_memory.ts`, `proposals.ts`, `slack_connection.ts`, all
+  `inbox_submissions.ts`, `inbox_applications.ts`, `people_list.ts`, `person_notes.ts`, `person_thread.ts`, `person_memory.ts`, `proposals.ts`, `slack_connection.ts`, `page_suggestions.ts`, `content_draft.ts`, `knowledge_base.ts`, all
   `// oss: false`) and, for the two prospect-channel settings tools, `@working-theory/mcp-scheduling`'s
   `workspaceTools` (`prospect_channel_settings.ts`, #9749 — the pack the scheduling module carries, so a
   scheduling-only build serves what it lists), loaded through the site's generated registry, as `server.ts` resolves the
   module-gated tools from their packs (#9460). Each calls `@working-theory/api-client`'s `inbox` surface
   (the people-list, notes, person-thread, person-memory and proposals tools, its `people` surface; the
-  Slack status and prospect-channel tools, its `slack` surface) with the key. A refusal from the
+  Slack status and prospect-channel tools, its `slack` surface; the suggestion and draft tools, its
+  `pageSuggestions` and `contentDrafts` surfaces) with the key. A refusal from the
   route is an MCP tool error naming the route's `error.code` and HTTP status only.
 - **Never log or return the key.** Don't log or serialise `extra`, `extra.authInfo` or
   `extra.requestInfo` — the SDK puts the raw `authorization` header there.
@@ -285,7 +313,13 @@ Example (lead routing):
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-10-29 — #10202 (D8): `get_redirect` (`mcp-workspace`'s `redirect.ts`, the pack's first anonymous handler) twins `GET /v1/redirects` under `module: "content-write"` and `feature: "workspace"` — 22 in `TOOLS`, 20 registered keyless and 21 commerce-claimed while Free is held, seven `tier: "pro"` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
+Last updated: 2026-10-31 — #10391 (D2–D6): `/mcp/workspace` gains the OAuth bearer branch beside the agent key — one `token-info` lookup per request, the `WWW-Authenticate` challenge and the RFC 9728 protected-resource document, on only with `BETTER_AUTH_URL` and `MCP_PUBLIC_HTTP_URL` — verified against `packages/mcp-server/src/{http-transport,oauth-bearer}.ts`.
+
+Prior: 2026-10-31 — #10345 (D9, D12): `read_knowledge` and `read_knowledge_doc` (`mcp-workspace`'s `knowledge_base.ts`) twin the per-user knowledge-base read — the signed-in workspace surface is thirty-seven tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-31 — #10336 (D1, D2, D10): `save_draft` and `read_report` (`mcp-workspace`'s `content_draft.ts`) twin the content-write draft save and read — the signed-in workspace surface is thirty-five tools, and the guard's `wire` row option binds the save's body and header — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-29 — #10202 (D8): `get_redirect` (`mcp-workspace`'s `redirect.ts`, the pack's first anonymous handler) twins `GET /v1/redirects` under `module: "content-write"` and `feature: "workspace"` — 22 in `TOOLS`, 20 registered keyless and 21 commerce-claimed while Free is held, seven `tier: "pro"` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
 
 Prior: 2026-10-26 — #9965 (D12, D13): `create_project` is served over stdio only — the HTTP transport, the default, never registers it, and the web manifest always drops it — and `trustOneHop` trusts its hop only on Vercel — verified against `packages/mcp-server/src/{server,run,serverless-app}.ts` and `apps/web/app/.well-known/mcp.json/route.ts`.
 

package/templates/apps/web/CLAUDE.md

@@ -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
@@ -602,6 +612,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 +637,11 @@ 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-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");
+  });
+});