@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/mcp-oauth.ts

@@ -9,7 +9,11 @@ import {
   McpOAuthClientRegistrationRequest,
   McpOAuthClientRegistrationResponse,
   McpOAuthProtectedResourceMetadata,
+  McpConnectionDecision,
   McpOAuthTokenResponse,
+  OrganizationAccessPolicy,
+  organizationAccessPresetPermissions,
+  type AccessContext,
   type AccessGrant,
   type ToolGatewayCatalog,
   type ToolGatewayIdentity,
@@ -19,18 +23,32 @@ import {
   createMcpOAuthAuthorizationRequest,
   deleteMcpOAuthAuthorizationRequest,
   exchangeMcpOAuthAuthorizationCode,
+  getManagedAccount,
   getMcpOAuthAuthorizationRequest,
   getMcpOAuthClient,
+  getWorkspace,
+  listSharedWorkspacesForAccount,
+  listWorkspacesForSubject,
   McpOAuthClientRegistrationRateLimitError,
+  rebindMcpOAuthAuthorizationRequest,
   registerMcpOAuthClient,
   resolveLiveMcpOAuthGrant,
   resolveMcpOAuthAccessToken,
   rotateMcpOAuthRefreshToken,
+  setMcpOAuthRequestOrganizationAccess,
+  type McpOAuthAccess,
 } from "@opengeni/db";
-import { requireAccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
+import {
+  hasPermission,
+  requireAccessContext,
+  requireAccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
 import { Hono, type Context } from "hono";
 import { HTTPException } from "hono/http-exception";
-import { trustedRequestSourceAddress } from "./http/request-source";
+import { trustedRequestSourceRateLimitKey, type RequestSourceTrust } from "./http/request-source";
+import { isAgentActingAsPerson, requireFullAccessIfAgent } from "./http/acting-person";
+import { requireSameOriginBrowserMutation } from "./routes/codex";
 import {
   prepareWorkspaceToolGateway,
   requireWorkspaceToolGatewayAuthorization,
@@ -45,10 +63,14 @@ const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/u;
 const PKCE_CHALLENGE = /^[A-Za-z0-9_-]{43}$/u;
 const WORKSPACE_MCP_PATH = /^\/v1\/workspaces\/([0-9a-f-]{36})\/mcp(?:\/(docs|files))?$/u;
 
+/** One organization MCP server for everyone; the sign-in chooses the organization. */
+export const ORGANIZATION_MCP_PATH = "/v1/mcp";
+
 export type McpOAuthResource = {
   resource: string;
-  workspaceId: string;
-  kind: "all" | "docs" | "files";
+  /** Null for the organization server. */
+  workspaceId: string | null;
+  kind: "all" | "docs" | "files" | "organization";
 };
 
 export type McpOAuthRouteAccess = {
@@ -57,7 +79,10 @@ export type McpOAuthRouteAccess = {
 };
 
 export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
-  app.get("/.well-known/oauth-authorization-server", (c) => {
+  // RFC 8414 path-aware discovery: MCP clients (Claude among them) ask for the
+  // metadata at /.well-known/oauth-authorization-server/<resource path> first
+  // and give up on anything but JSON. Serve the same document at both.
+  const authorizationServerMetadata = (c: Context) => {
     requireMcpOAuthEnabled(deps);
     const issuer = mcpOAuthIssuer(deps);
     c.header("cache-control", "public, max-age=300");
@@ -75,7 +100,9 @@ export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
         authorization_response_iss_parameter_supported: true,
       }),
     );
-  });
+  };
+  app.get("/.well-known/oauth-authorization-server", authorizationServerMetadata);
+  app.get("/.well-known/oauth-authorization-server/*", authorizationServerMetadata);
 
   app.get("/.well-known/oauth-protected-resource/*", (c) => {
     requireMcpOAuthEnabled(deps);
@@ -115,9 +142,7 @@ export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
         clientName: parsed.data.client_name ?? null,
         grantTypes: parsed.data.grant_types,
         responseTypes: ["code"],
-        registrationScopeHash: tokenHash(
-          mcpOAuthRegistrationClientKey(c, deps.settings.mcpOauthTrustedProxyHops),
-        ),
+        registrationScopeHash: tokenHash(mcpOAuthRegistrationClientKey(c, deps.settings)),
       });
     } catch (error) {
       if (error instanceof McpOAuthClientRegistrationRateLimitError) {
@@ -148,10 +173,62 @@ export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
     const query = new URL(c.req.url).searchParams;
     const client = await requireAuthorizationClient(deps, query);
     const resource = requireAuthorizationResource(deps, query);
+    if (resource.kind === "organization") {
+      // The person picks the organization, what the agent can do and where on
+      // the web app's sign-in page, which reads and answers this request.
+      const web = new URL(deps.settings.webBaseUrl ?? mcpOAuthIssuer(deps));
+      let person: { context: AccessContext };
+      try {
+        person = await requireBrowserPerson(c, deps);
+      } catch (error) {
+        if (!(error instanceof HTTPException) || error.status !== 401) throw error;
+        // Not signed in here yet: sign in on the web app, which returns to
+        // this exact authorization request (a same-origin path only).
+        const url = new URL(c.req.url);
+        c.header("cache-control", "no-store");
+        return c.redirect(
+          `${web.origin}/connect-agent?authorize=${encodeURIComponent(`${url.pathname}${url.search}`)}`,
+          302,
+        );
+      }
+      const accountId =
+        person.context.defaultAccountId ?? person.context.accountGrants[0]?.accountId;
+      if (!accountId) {
+        throw new HTTPException(403, { message: "no organization is available for MCP OAuth" });
+      }
+      const requestToken = opaque(REQUEST_PREFIX);
+      await createMcpOAuthAuthorizationRequest(deps.db, {
+        requestHash: tokenHash(requestToken),
+        clientId: client.clientId,
+        accountId,
+        workspaceId: null,
+        subjectId: person.context.subjectId,
+        resource: resource.resource,
+        redirectUri: requireRedirectUri(client.redirectUris, query.get("redirect_uri")),
+        codeChallenge: requireCodeChallenge(query),
+        state: boundedState(query.get("state")),
+        permissions: [],
+        toolIdentities: [],
+        organizationAccess: DEFAULT_ORGANIZATION_ACCESS(),
+        expiresAt: expiresIn(MCP_OAUTH_CONSENT_TTL_SECONDS),
+      });
+      c.header("cache-control", "no-store");
+      return c.redirect(
+        `${web.origin}/connect-agent?request=${encodeURIComponent(requestToken)}`,
+        302,
+      );
+    }
+    const context = await requireAccessContext(c, deps);
+    const workspaces = await listConsentWorkspaces(deps, context);
+    if (workspaces.length === 0) {
+      throw new HTTPException(403, { message: "no workspace is available for MCP OAuth" });
+    }
+    const selectedWorkspace =
+      workspaces.find((workspace) => workspace.id === resource.workspaceId) ?? workspaces[0]!;
     const authorization = await requireAccessGrantAuthorization(
       c,
       deps,
-      resource.workspaceId,
+      selectedWorkspace.id,
       "workspace:read",
     );
     const grant = requireWorkspaceToolGatewayAuthorization(authorization);
@@ -170,47 +247,112 @@ export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
         state: boundedState(query.get("state")),
         permissions: grant.permissions,
         toolIdentities: mcpOAuthConsentToolIdentities(prepared.toolGatewayCatalog),
+        organizationAccess: null,
         expiresAt: expiresIn(MCP_OAUTH_CONSENT_TTL_SECONDS),
       });
     } finally {
       await prepared.close();
     }
+    const accounts = await consentAccountsForWorkspaces(deps, workspaces);
     c.header(
       "content-security-policy",
-      "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'",
+      "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'",
     );
     c.header("cache-control", "no-store");
-    return c.html(consentHtml(client.clientName ?? client.clientId, resource, requestToken));
+    return c.html(
+      renderMcpOAuthConsentPage({
+        clientName: client.clientName ?? "MCP client",
+        requestToken,
+        accounts,
+        workspaces: workspaces.map((workspace) => ({
+          id: workspace.id,
+          accountId: workspace.accountId,
+          name: workspace.name,
+          kind: workspace.kind,
+        })),
+        selectedWorkspaceId: grant.workspaceId,
+      }),
+    );
   });
 
   app.post("/oauth/authorize", async (c) => {
     requireMcpOAuthEnabled(deps);
     const form = new URLSearchParams(await c.req.text());
     const requestToken = form.get("request") ?? "";
-    if (!requestToken.startsWith(REQUEST_PREFIX)) return oauthError(c, "invalid_request", 400);
+    if (!requestToken.startsWith(REQUEST_PREFIX)) {
+      return oauthAuthorizeBrowserError(
+        c,
+        "This authorization request is missing or already used.",
+      );
+    }
     const request = await getMcpOAuthAuthorizationRequest(deps.db, tokenHash(requestToken));
-    if (!request) return oauthError(c, "invalid_request", 400);
+    if (!request) {
+      return oauthAuthorizeBrowserError(
+        c,
+        "This authorization request expired or was already approved.",
+      );
+    }
+    // Organization sign-ins are answered on the Opengeni page they opened.
+    if (request.workspaceId === null) {
+      return oauthAuthorizeBrowserError(c, "Answer this sign-in on the Opengeni page it opened.");
+    }
+    const requestWorkspaceId = request.workspaceId;
+    if (form.get("decision") !== "approve") {
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        requestWorkspaceId,
+        "workspace:read",
+      );
+      if (requireWorkspaceToolGatewayAuthorization(authorization).subjectId !== request.subjectId) {
+        throw new HTTPException(403, { message: "OAuth consent authority changed" });
+      }
+      await deleteMcpOAuthAuthorizationRequest(deps.db, request.requestHash);
+      return completeAuthorizationRedirect(
+        c,
+        authorizationRedirect(request.redirectUri, {
+          error: "access_denied",
+          iss: mcpOAuthIssuer(deps),
+          ...(request.state ? { state: request.state } : {}),
+        }),
+      );
+    }
+    const selectedWorkspaceId = form.get("workspace_id") || requestWorkspaceId;
+    if (!isWorkspaceId(selectedWorkspaceId)) {
+      return oauthAuthorizeBrowserError(c, "Choose a workspace before authorizing this client.");
+    }
     const authorization = await requireAccessGrantAuthorization(
       c,
       deps,
-      request.workspaceId,
+      selectedWorkspaceId,
       "workspace:read",
     );
     const grant = requireWorkspaceToolGatewayAuthorization(authorization);
-    if (grant.subjectId !== request.subjectId || grant.accountId !== request.accountId) {
+    if (grant.subjectId !== request.subjectId) {
       throw new HTTPException(403, {
         message: "OAuth consent authority changed",
       });
     }
-    if (form.get("decision") !== "approve") {
-      await deleteMcpOAuthAuthorizationRequest(deps.db, request.requestHash);
-      return c.redirect(
-        authorizationRedirect(request.redirectUri, {
-          error: "access_denied",
-          iss: mcpOAuthIssuer(deps),
-          ...(request.state ? { state: request.state } : {}),
-        }),
-      );
+    if (grant.workspaceId !== request.workspaceId || grant.accountId !== request.accountId) {
+      const prepared = await prepareWorkspaceToolGateway(deps, authorization);
+      try {
+        const rebound = await rebindMcpOAuthAuthorizationRequest(deps.db, {
+          requestHash: request.requestHash,
+          subjectId: grant.subjectId,
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          permissions: grant.permissions,
+          toolIdentities: mcpOAuthConsentToolIdentities(prepared.toolGatewayCatalog),
+        });
+        if (!rebound) {
+          return oauthAuthorizeBrowserError(
+            c,
+            "This authorization request expired or was already approved.",
+          );
+        }
+      } finally {
+        await prepared.close();
+      }
     }
     const code = opaque(CODE_PREFIX);
     const consumed = await consumeMcpOAuthAuthorizationRequest(deps.db, {
@@ -219,8 +361,14 @@ export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
       codeHash: tokenHash(code),
       codeExpiresAt: expiresIn(MCP_OAUTH_AUTHORIZATION_CODE_TTL_SECONDS),
     });
-    if (!consumed) return oauthError(c, "invalid_request", 400);
-    return c.redirect(
+    if (!consumed) {
+      return oauthAuthorizeBrowserError(
+        c,
+        "This authorization request expired or was already approved.",
+      );
+    }
+    return completeAuthorizationRedirect(
+      c,
       authorizationRedirect(consumed.redirectUri, {
         code,
         iss: mcpOAuthIssuer(deps),
@@ -229,6 +377,83 @@ export function registerMcpOAuthRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  // The web sign-in page for the organization server reads the pending request…
+  app.get("/v1/mcp-connections/requests/:request", async (c) => {
+    requireMcpOAuthEnabled(deps);
+    const person = await requireBrowserPerson(c, deps);
+    const request = await requirePendingOrganizationRequest(deps, c.req.param("request"), person);
+    const client = await getMcpOAuthClient(deps.db, request.clientId);
+    const organizations = await consentOrganizations(deps, person.context);
+    c.header("cache-control", "no-store");
+    return c.json({
+      client: {
+        name: client?.clientName ?? "MCP client",
+        host: redirectHost(request.redirectUri),
+      },
+      person: { name: person.context.subjectLabel ?? null },
+      organizations,
+      defaultOrganizationId: organizations.some((each) => each.id === request.accountId)
+        ? request.accountId
+        : (organizations[0]?.id ?? null),
+    });
+  });
+
+  // …and answers it. Approving returns the agent's redirect with a code.
+  app.post("/v1/mcp-connections/requests/:request", async (c) => {
+    requireMcpOAuthEnabled(deps);
+    requireSameOriginBrowserMutation(c, deps);
+    const person = await requireBrowserPerson(c, deps);
+    const request = await requirePendingOrganizationRequest(deps, c.req.param("request"), person);
+    const parsed = McpConnectionDecision.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid sign-in decision" });
+    const decision = parsed.data;
+    if (decision.decision === "deny") {
+      await deleteMcpOAuthAuthorizationRequest(deps.db, request.requestHash);
+      return c.json({
+        redirectTo: authorizationRedirect(request.redirectUri, {
+          error: "access_denied",
+          iss: mcpOAuthIssuer(deps),
+          ...(request.state ? { state: request.state } : {}),
+        }),
+      });
+    }
+    const organizations = await consentOrganizations(deps, person.context);
+    const organization = organizations.find((each) => each.id === decision.organizationId);
+    if (!organization) throw new HTTPException(403, { message: "organization is not available" });
+    const access = decision.access;
+    if (access.workspaceScope.kind === "selected") {
+      const reachable = new Set(organization.workspaces.map((workspace) => workspace.id));
+      if (access.workspaceScope.workspaceIds.some((id) => !reachable.has(id))) {
+        throw new HTTPException(403, { message: "a selected workspace is not available" });
+      }
+    }
+    const bound = await setMcpOAuthRequestOrganizationAccess(deps.db, {
+      requestHash: request.requestHash,
+      subjectId: person.context.subjectId,
+      accountId: organization.id,
+      organizationAccess: access,
+    });
+    const code = opaque(CODE_PREFIX);
+    const consumed = bound
+      ? await consumeMcpOAuthAuthorizationRequest(deps.db, {
+          requestHash: request.requestHash,
+          subjectId: person.context.subjectId,
+          codeHash: tokenHash(code),
+          codeExpiresAt: expiresIn(MCP_OAUTH_AUTHORIZATION_CODE_TTL_SECONDS),
+        })
+      : null;
+    if (!consumed) {
+      throw new HTTPException(410, { message: "This sign-in expired or was already answered." });
+    }
+    return c.json({
+      redirectTo: authorizationRedirect(consumed.redirectUri, {
+        code,
+        iss: mcpOAuthIssuer(deps),
+        ...(consumed.state ? { state: consumed.state } : {}),
+      }),
+    });
+  });
+
   app.post("/oauth/token", async (c) => {
     requireMcpOAuthEnabled(deps);
     const form = new URLSearchParams(await c.req.text());
@@ -305,9 +530,11 @@ export async function resolveMcpOAuthRouteAccess(
     deps,
     `${mcpOAuthIssuer(deps)}${new URL(request.url).pathname}`,
   );
+  // The client URL is the resource indicator. Consent may bind a different
+  // workspace than the path UUID; the token grant is the authorized workspace.
   if (
     !access ||
-    access.workspaceId !== workspaceId ||
+    requestResource.workspaceId !== workspaceId ||
     access.resource !== requestResource.resource
   ) {
     throw new HTTPException(401, { message: "invalid MCP OAuth access token" });
@@ -331,7 +558,7 @@ export function mcpOAuthBearerToken(request: Request): string | null {
 }
 
 export function isMcpOAuthResourcePath(pathname: string): boolean {
-  return WORKSPACE_MCP_PATH.test(pathname);
+  return WORKSPACE_MCP_PATH.test(pathname) || pathname === ORGANIZATION_MCP_PATH;
 }
 
 export function mcpOAuthConsentToolIdentities(catalog: ToolGatewayCatalog): ToolGatewayIdentity[] {
@@ -341,6 +568,7 @@ export function mcpOAuthConsentToolIdentities(catalog: ToolGatewayCatalog): Tool
 export function isMcpOAuthPublicProtocolPath(pathname: string): boolean {
   return (
     pathname === "/.well-known/oauth-authorization-server" ||
+    pathname.startsWith("/.well-known/oauth-authorization-server/") ||
     pathname.startsWith("/.well-known/oauth-protected-resource/") ||
     pathname === "/oauth/register" ||
     pathname === "/oauth/authorize" ||
@@ -369,6 +597,20 @@ function parseMcpOAuthResource(deps: ApiRouteDeps, value: string): McpOAuthResou
     throw new HTTPException(400, { message: "invalid OAuth resource" });
   }
   const issuer = mcpOAuthIssuer(deps);
+  if (
+    url.pathname === ORGANIZATION_MCP_PATH &&
+    url.origin === issuer &&
+    !url.username &&
+    !url.password &&
+    !url.search &&
+    !url.hash
+  ) {
+    return {
+      resource: `${issuer}${ORGANIZATION_MCP_PATH}`,
+      workspaceId: null,
+      kind: "organization",
+    };
+  }
   const match = url.pathname.match(WORKSPACE_MCP_PATH);
   if (url.origin !== issuer || url.username || url.password || url.search || url.hash || !match) {
     throw new HTTPException(400, { message: "invalid OAuth resource" });
@@ -441,17 +683,26 @@ async function exchangeAuthorizationCode(
   if (!code.startsWith(CODE_PREFIX) || !PKCE_VERIFIER.test(verifier)) return null;
   const redirectUri = form.get("redirect_uri");
   if (!redirectUri || !redirectUris.includes(redirectUri)) return null;
-  return await exchangeMcpOAuthAuthorizationCode(deps.db, {
-    codeHash: tokenHash(code),
-    clientId: input.clientId,
-    redirectUri,
-    resource: input.resource,
-    codeChallenge: pkceChallenge(verifier),
-    accessTokenHash: input.accessTokenHash,
-    refreshTokenHash: input.refreshTokenHash,
-    accessExpiresAt: input.accessExpiresAt,
-    refreshExpiresAt: input.refreshExpiresAt,
-  });
+  for (const candidate of mcpOAuthRedirectUriCandidates(redirectUris, redirectUri)) {
+    const access = await exchangeMcpOAuthAuthorizationCode(deps.db, {
+      codeHash: tokenHash(code),
+      clientId: input.clientId,
+      redirectUri: candidate,
+      resource: input.resource,
+      codeChallenge: pkceChallenge(verifier),
+      accessTokenHash: input.accessTokenHash,
+      refreshTokenHash: input.refreshTokenHash,
+      accessExpiresAt: input.accessExpiresAt,
+      refreshExpiresAt: input.refreshExpiresAt,
+    });
+    if (access) return access;
+  }
+  return null;
+}
+
+export function mcpOAuthRedirectUriCandidates(registered: string[], requested: string): string[] {
+  if (!registered.includes(requested)) return [];
+  return [requested, ...registered.filter((uri) => uri !== requested)];
 }
 
 async function rotateRefreshToken(
@@ -474,11 +725,37 @@ async function rotateRefreshToken(
   });
 }
 
+const BLOCKED_REDIRECT_PROTOCOLS = new Set([
+  "javascript:",
+  "data:",
+  "file:",
+  "about:",
+  "blob:",
+  "vbscript:",
+]);
+
+function isNativeAppRedirect(url: URL): boolean {
+  return (
+    /^[a-z][a-z0-9+.-]*:$/u.test(url.protocol) &&
+    !BLOCKED_REDIRECT_PROTOCOLS.has(url.protocol) &&
+    url.protocol !== "http:" &&
+    url.protocol !== "https:" &&
+    Boolean(url.hostname) &&
+    url.pathname.startsWith("/") &&
+    url.pathname !== "/"
+  );
+}
+
 function validateRedirectUri(value: string): string {
   const url = new URL(value);
   const loopback =
     url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
-  if (url.username || url.password || url.hash || (url.protocol !== "https:" && !loopback)) {
+  if (
+    url.username ||
+    url.password ||
+    url.hash ||
+    (url.protocol !== "https:" && !loopback && !isNativeAppRedirect(url))
+  ) {
     throw new HTTPException(400, {
       message: "invalid public OAuth redirect URI",
     });
@@ -506,8 +783,8 @@ function tokenHash(value: string): string {
   return createHash("sha256").update(value, "utf8").digest("hex");
 }
 
-function mcpOAuthRegistrationClientKey(c: Context, trustedProxyHops: number): string {
-  return `mcp-oauth-registration:${trustedRequestSourceAddress(c, trustedProxyHops)}`;
+function mcpOAuthRegistrationClientKey(c: Context, trust: RequestSourceTrust): string {
+  return `mcp-oauth-registration:${trustedRequestSourceRateLimitKey(c, trust)}`;
 }
 
 function expiresIn(seconds: number): Date {
@@ -520,8 +797,190 @@ function authorizationRedirect(redirectUri: string, params: Record<string, strin
   return url.toString();
 }
 
-function consentHtml(clientName: string, resource: McpOAuthResource, requestToken: string): string {
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Authorize OpenGeni tools</title><style>body{font:16px/1.5 system-ui,sans-serif;max-width:42rem;margin:4rem auto;padding:0 1.5rem;color:#18181b}main{border:1px solid #e4e4e7;border-radius:16px;padding:2rem}code{word-break:break-all;background:#f4f4f5;padding:.15rem .35rem;border-radius:4px}.actions{display:flex;gap:.75rem;margin-top:1.5rem}button{border:0;border-radius:8px;padding:.7rem 1rem;font:inherit;cursor:pointer}.approve{background:#18181b;color:white}.deny{background:#e4e4e7}</style></head><body><main><h1>Authorize workspace tools</h1><p><strong>${escapeHtml(clientName)}</strong> is requesting MCP access to this workspace.</p><p>Resource: <code>${escapeHtml(resource.resource)}</code></p><p>The grant is limited to the tools and permissions available now. OpenGeni rechecks live workspace authority on every request.</p><form method="post" action="/oauth/authorize"><input type="hidden" name="request" value="${escapeHtml(requestToken)}"><div class="actions"><button class="approve" name="decision" value="approve">Authorize</button><button class="deny" name="decision" value="deny">Deny</button></div></form></main></body></html>`;
+export function completeAuthorizationRedirect(c: Context, redirectTo: string) {
+  // Consent posts under CSP form-action 'self'. A 302 to the client's
+  // registered redirect_uri (loopback HTTP or a custom scheme) is blocked,
+  // so the waiter never receives the code. Return 200 HTML that navigates
+  // to the exact requested URI from script and Refresh.
+  c.header("cache-control", "no-store");
+  c.header(
+    "content-security-policy",
+    "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; frame-ancestors 'none'",
+  );
+  c.header("refresh", `0;url=${redirectTo}`);
+  return c.html(renderMcpOAuthContinuePage(redirectTo));
+}
+
+function oauthAuthorizeBrowserError(c: Context, message: string) {
+  c.header("cache-control", "no-store");
+  c.header("pragma", "no-cache");
+  c.header(
+    "content-security-policy",
+    "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'",
+  );
+  return c.html(renderMcpOAuthExpiredPage(message), 400);
+}
+
+export type McpOAuthConsentAccount = {
+  id: string;
+  name: string;
+};
+
+export type McpOAuthConsentWorkspace = {
+  id: string;
+  accountId: string;
+  name: string;
+  kind: "personal" | "shared";
+};
+
+export function renderMcpOAuthConsentPage(input: {
+  clientName: string;
+  requestToken: string;
+  accounts: McpOAuthConsentAccount[];
+  workspaces: McpOAuthConsentWorkspace[];
+  selectedWorkspaceId: string;
+}): string {
+  const selectedWorkspace =
+    input.workspaces.find((workspace) => workspace.id === input.selectedWorkspaceId) ??
+    input.workspaces[0];
+  if (!selectedWorkspace) {
+    throw new Error("MCP OAuth consent requires at least one workspace");
+  }
+  const selectedAccountId = selectedWorkspace.accountId;
+  const accountOptions = input.accounts
+    .map(
+      (account) =>
+        `<option value="${escapeHtml(account.id)}"${account.id === selectedAccountId ? " selected" : ""}>${escapeHtml(account.name)}</option>`,
+    )
+    .join("");
+  const workspaceOptions = input.workspaces
+    .filter((workspace) => workspace.accountId === selectedAccountId)
+    .map(
+      (workspace) =>
+        `<option value="${escapeHtml(workspace.id)}"${workspace.id === selectedWorkspace.id ? " selected" : ""}>${escapeHtml(consentWorkspaceLabel(workspace))}</option>`,
+    )
+    .join("");
+  const workspacePayload = input.workspaces.map((workspace) => ({
+    id: workspace.id,
+    accountId: workspace.accountId,
+    label: consentWorkspaceLabel(workspace),
+  }));
+  const body = `<p class="lede"><strong>${escapeHtml(input.clientName)}</strong> wants MCP access to the organization and workspace you choose.</p>
+<form method="post" action="/oauth/authorize" onsubmit="var submitter=event.submitter;if(submitter&&submitter.name){var input=document.createElement('input');input.type='hidden';input.name=submitter.name;input.value=submitter.value;this.appendChild(input)}this.querySelectorAll('button').forEach(function(button){button.disabled=true})">
+<input type="hidden" name="request" value="${escapeHtml(input.requestToken)}">
+<label class="field"><span>Organization</span><select id="organization" name="organization" autocomplete="off">${accountOptions}</select></label>
+<label class="field"><span>Workspace</span><select id="workspace_id" name="workspace_id" autocomplete="off">${workspaceOptions}</select></label>
+<p class="note">The grant is limited to tools available in the workspace you authorize. Opengeni rechecks live authority on every request.</p>
+<div class="actions"><button class="approve" name="decision" value="approve">Authorize</button><button class="deny" name="decision" value="deny">Deny</button></div>
+</form>
+<script type="application/json" id="mcp-oauth-workspaces">${jsonForScript(workspacePayload)}</script>
+<script>
+(function () {
+  var data = JSON.parse(document.getElementById("mcp-oauth-workspaces").textContent);
+  var account = document.getElementById("organization");
+  var workspace = document.getElementById("workspace_id");
+  function sync() {
+    var selected = workspace.value;
+    var items = data.filter(function (item) { return item.accountId === account.value; });
+    workspace.replaceChildren();
+    items.forEach(function (item) {
+      var option = document.createElement("option");
+      option.value = item.id;
+      option.textContent = item.label;
+      workspace.appendChild(option);
+    });
+    if (items.some(function (item) { return item.id === selected; })) workspace.value = selected;
+  }
+  account.addEventListener("change", sync);
+})();
+</script>`;
+  return oauthDocument({
+    title: "Authorize MCP access",
+    heading: "Authorize this client",
+    body,
+  });
+}
+
+export function renderMcpOAuthContinuePage(redirectTo: string): string {
+  return oauthDocument({
+    title: "Returning to the app",
+    heading: "Returning to the app",
+    head: `<meta http-equiv="refresh" content="0;url=${escapeHtml(redirectTo)}">`,
+    body: `<p class="lede">Authorization succeeded. You can close this window.</p><script>(function (url) { try { location.replace(url); } catch (error) {} try { location.href = url; } catch (error) {} var frame = document.createElement("iframe"); frame.src = url; frame.style.display = "none"; document.body.appendChild(frame); })(${JSON.stringify(redirectTo)});</script>`,
+  });
+}
+
+export function renderMcpOAuthExpiredPage(message: string): string {
+  return oauthDocument({
+    title: "Authorization expired",
+    heading: "Authorization expired",
+    body: `<p class="lede">${escapeHtml(message)}</p><p class="note">Close this window and start authorization again from the client.</p>`,
+  });
+}
+
+async function listConsentWorkspaces(deps: ApiRouteDeps, context: AccessContext) {
+  const readableWorkspaceIds = [
+    ...new Set(
+      context.workspaceGrants
+        .filter((grant) => hasPermission(grant.permissions, "workspace:read"))
+        .map((grant) => grant.workspaceId),
+    ),
+  ];
+  const readableAccountIds = context.accountGrants
+    .filter((grant) => hasPermission(grant.permissions, "workspace:read"))
+    .map((grant) => grant.accountId);
+  const [fromGrants, memberships, shared] = await Promise.all([
+    Promise.all(readableWorkspaceIds.map((workspaceId) => getWorkspace(deps.db, workspaceId))),
+    listWorkspacesForSubject(deps.db, context.subjectId),
+    Promise.all(
+      readableAccountIds.map((accountId) => listSharedWorkspacesForAccount(deps.db, accountId)),
+    ),
+  ]);
+  const byId = new Map<string, NonNullable<(typeof fromGrants)[number]>>();
+  for (const workspace of [...fromGrants, ...memberships, ...shared.flat()]) {
+    if (workspace) byId.set(workspace.id, workspace);
+  }
+  return [...byId.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+async function consentAccountsForWorkspaces(
+  deps: ApiRouteDeps,
+  workspaces: Array<{ accountId: string }>,
+): Promise<McpOAuthConsentAccount[]> {
+  const accountIds = [...new Set(workspaces.map((workspace) => workspace.accountId))];
+  return (
+    await Promise.all(
+      accountIds.map(async (accountId) => {
+        const account = await getManagedAccount(deps.db, accountId);
+        return { id: accountId, name: account?.name.trim() || "Organization" };
+      }),
+    )
+  ).sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function consentWorkspaceLabel(workspace: McpOAuthConsentWorkspace): string {
+  const name = workspace.name.trim() || "Workspace";
+  return workspace.kind === "personal" ? `${name} (Personal)` : name;
+}
+
+function isWorkspaceId(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value);
+}
+
+function oauthDocument(input: {
+  title: string;
+  heading: string;
+  body: string;
+  head?: string;
+}): string {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(input.title)}</title>${input.head ?? ""}<style>${OAUTH_PAGE_CSS}</style></head><body><main><p class="mark">Opengeni</p><h1>${escapeHtml(input.heading)}</h1>${input.body}</main></body></html>`;
+}
+
+const OAUTH_PAGE_CSS =
+  'html,body{margin:0}body{min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px;background:#f4f4f5;color:#18181b;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;font-size:15px;line-height:1.5;-webkit-font-smoothing:antialiased}main{width:min(100%,28rem);background:#fff;border:1px solid #e4e4e7;border-radius:20px;padding:24px}h1{margin:8px 0 0;font-size:22px;line-height:1.3;font-weight:650}p{margin:12px 0 0}strong{font-weight:600}.mark{margin:0;font-size:12px;font-weight:600;color:#71717a}.lede,.note{color:#52525b}.field{display:flex;flex-direction:column;gap:6px;margin-top:16px;font-size:13px;color:#71717a}select{width:100%;border:1px solid #e4e4e7;border-radius:10px;background:#f4f4f5;color:#18181b;padding:10px 12px;font:inherit}.actions{display:flex;gap:12px;margin-top:20px}button{flex:1;min-height:40px;border:0;border-radius:10px;padding:10px 16px;font:inherit;font-weight:600;cursor:pointer}.approve{background:#18181b;color:#fff}.deny{background:#fff;color:#18181b;border:1px solid #e4e4e7}button:disabled{opacity:0.6;cursor:wait}@media(prefers-color-scheme:dark){body{background:#09090b;color:#fafafa}main{background:#18181b;border-color:#3f3f46}h1{color:#fafafa}.mark{color:#a1a1aa}.lede,.note{color:#a1a1aa}select{background:#27272a;border-color:#3f3f46;color:#fafafa}.approve{background:#fafafa;color:#18181b}.deny{background:#27272a;color:#fafafa;border-color:#3f3f46}}';
+
+function jsonForScript(value: unknown): string {
+  return JSON.stringify(value).replace(/</gu, "\\u003c");
 }
 
 function escapeHtml(value: string): string {
@@ -537,3 +996,134 @@ function oauthError(c: Context, error: string, status: 400 | 401 | 429) {
   c.header("pragma", "no-cache");
   return c.json({ error }, status);
 }
+
+/* ----------------------------------------------------------------------------
+   Organization server sign-in: a person picks the organization, what the agent
+   can do and where. The agent then acts as that person, never beyond their
+   live access, on every request.
+   -------------------------------------------------------------------------- */
+
+/** Read only, every workspace: the least surprising default until the person chooses. */
+function DEFAULT_ORGANIZATION_ACCESS(): OrganizationAccessPolicy {
+  return {
+    preset: "read_only",
+    permissions: organizationAccessPresetPermissions("read_only"),
+    workspaceScope: { kind: "all" },
+  };
+}
+
+/**
+ * A person signed in to Opengeni in this browser, or an agent with their full
+ * access answering a sign-in that person started: never a key, bearer or
+ * service. A limited agent can't approve sign-ins, so it can't widen access.
+ */
+async function requireBrowserPerson(
+  c: Context,
+  deps: ApiRouteDeps,
+): Promise<{ context: AccessContext }> {
+  if (isAgentActingAsPerson(c)) {
+    requireFullAccessIfAgent(c, "Approving an agent sign-in");
+    const context = await requireAccessContext(c, deps);
+    if (context.mode !== "managed" || !context.subjectId.startsWith("user:")) {
+      throw new HTTPException(403, { message: "Approving an agent sign-in needs a person" });
+    }
+    return { context };
+  }
+  if (
+    deps.settings.productAccessMode !== "managed" ||
+    !c.req.header("cookie") ||
+    c.req.header("authorization")
+  ) {
+    throw new HTTPException(401, { message: "sign in to Opengeni in this browser first" });
+  }
+  const context = await requireAccessContext(c, deps);
+  if (context.mode !== "managed" || !context.subjectId.startsWith("user:")) {
+    throw new HTTPException(401, { message: "sign in to Opengeni in this browser first" });
+  }
+  return { context };
+}
+
+async function requirePendingOrganizationRequest(
+  deps: ApiRouteDeps,
+  requestToken: string,
+  person: { context: AccessContext },
+) {
+  const request = requestToken.startsWith(REQUEST_PREFIX)
+    ? await getMcpOAuthAuthorizationRequest(deps.db, tokenHash(requestToken))
+    : null;
+  if (!request || request.workspaceId !== null) {
+    throw new HTTPException(410, { message: "This sign-in expired or was already answered." });
+  }
+  if (request.subjectId !== person.context.subjectId) {
+    throw new HTTPException(403, { message: "This sign-in belongs to someone else." });
+  }
+  return request;
+}
+
+/** Organizations the person belongs to, with what they could hand an agent there. */
+async function consentOrganizations(deps: ApiRouteDeps, context: AccessContext) {
+  const memberOf = new Set(context.accountGrants.map((grant) => grant.accountId));
+  const workspaces = (await listConsentWorkspaces(deps, context)).filter((workspace) =>
+    memberOf.has(workspace.accountId),
+  );
+  const accounts = await consentAccountsForWorkspaces(
+    deps,
+    [...memberOf].map((accountId) => ({ accountId })),
+  );
+  const canonical = organizationAccessPresetPermissions("full");
+  return accounts.map((account) => {
+    const accountGrant = context.accountGrants.find((grant) => grant.accountId === account.id);
+    const workspaceGrants = context.workspaceGrants.filter(
+      (grant) => grant.accountId === account.id,
+    );
+    return {
+      id: account.id,
+      name: account.name,
+      workspaces: workspaces
+        .filter((workspace) => workspace.accountId === account.id)
+        .map((workspace) => ({
+          id: workspace.id,
+          name: workspace.name,
+          personal: workspace.kind === "personal",
+        })),
+      grantable: canonical.filter(
+        (permission) =>
+          (accountGrant !== undefined && hasPermission(accountGrant.permissions, permission)) ||
+          workspaceGrants.some((grant) => hasPermission(grant.permissions, permission)),
+      ),
+    };
+  });
+}
+
+function redirectHost(redirectUri: string): string | null {
+  try {
+    const url = new URL(redirectUri);
+    return url.host || url.protocol.replace(/:$/u, "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The organization connection behind an organization-server bearer, or null
+ * when the request carries no MCP OAuth token. Invalid, revoked, expired or
+ * workspace-bound tokens are refused.
+ */
+export async function resolveOrganizationMcpOAuthAccess(
+  deps: ApiRouteDeps,
+  request: Request,
+): Promise<(McpOAuthAccess & { organizationAccess: OrganizationAccessPolicy }) | null> {
+  const token = mcpOAuthBearerToken(request);
+  if (!token) return null;
+  requireMcpOAuthEnabled(deps);
+  const access = await resolveMcpOAuthAccessToken(deps.db, tokenHash(token));
+  if (
+    !access ||
+    access.workspaceId !== null ||
+    access.organizationAccess === null ||
+    access.resource !== `${mcpOAuthIssuer(deps)}${ORGANIZATION_MCP_PATH}`
+  ) {
+    throw new HTTPException(401, { message: "invalid MCP OAuth access token" });
+  }
+  return { ...access, organizationAccess: access.organizationAccess };
+}