@peoplethread/saas-mcp 0.0.0-stage → 0.3.0

package/dist/hono/routes.js

@@ -0,0 +1,739 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { authorizationServerMetadataUrlForIssuer, buildMcpAuthorizationServerMetadata, buildMcpBearerChallenge, buildMcpProtectedResourceMetadata, trimTrailingSlash, validateMcpHttpEnvelope } from "../core/index.js";
+import { addSeconds, hashMcpToken, parseBearerToken, randomMcpToken, verifyPkceS256 } from "../node/index.js";
+import { formatMcpScopeString, hasRequiredMcpScopes, includesUnsupportedMcpScope, normalizeMcpScopes, requestedMcpScopes } from "../core/scopes.js";
+/**
+ * Thrown by `createMcpContext` to refuse a session for a token that authenticated but
+ * cannot act on this resource — a principal whose access to the addressed tenant has
+ * gone away, say.
+ *
+ * The router answers `401` with `error="invalid_token"` rather than letting it surface
+ * as a server fault. The token is intact, so the description is arguable, but the
+ * outcome it produces is the correct one: the condition is durable, and a client that
+ * retries the same credential will fail identically until it re-authorizes.
+ */
+export class McpContextUnauthorizedError extends Error {
+    constructor(message = "Bearer token cannot be used with this resource") {
+        super(message);
+        this.name = "McpContextUnauthorizedError";
+    }
+}
+/**
+ * Thrown by `resolveConsentIdentity` when no human is signed in to the product.
+ *
+ * The authorization endpoint answers this by sending the browser to the product's sign-in
+ * page and returning it to the same authorization request, because the condition is one the
+ * user can fix in place. It is deliberately distinct from every other failure that resolver
+ * can raise: those are reported to the OAuth client, and this one is not, since telling a
+ * client "invalid request" for a missing cookie leaves the user with nothing to act on.
+ */
+export class McpConsentSignInRequiredError extends Error {
+    constructor(message = "Sign-in is required to authorize this MCP client") {
+        super(message);
+        this.name = "McpConsentSignInRequiredError";
+    }
+}
+/**
+ * Thrown by `resolveConsentIdentity` when a human *is* signed in but may not authorize the
+ * requested resource — no membership in the addressed workspace, say.
+ *
+ * Terminal, unlike `McpConsentSignInRequiredError`: signing in again cannot change the
+ * answer, so the router refuses to the client with `access_denied` rather than looping the
+ * browser through sign-in. The message reaches the client as `error_description`, so it must
+ * not name a resource the caller has not been shown to be entitled to know exists.
+ */
+export class McpConsentForbiddenError extends Error {
+    constructor(message = "This account cannot authorize the requested resource") {
+        super(message);
+        this.name = "McpConsentForbiddenError";
+    }
+}
+function json(data, status = 200, headers = {}) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: {
+            "content-type": "application/json",
+            ...headers
+        }
+    });
+}
+function configuredResponse(data, status = 200) {
+    return json(data, status, { "cache-control": "no-store", "Access-Control-Allow-Origin": "*" });
+}
+function tokenResponse(data) {
+    return json(data, 200, { "cache-control": "no-store", pragma: "no-cache" });
+}
+function oauthError(error, description, status = 400) {
+    return json({ error, error_description: description }, status, { "cache-control": "no-store", pragma: "no-cache" });
+}
+function jsonRpcErrorResponse(status, code, message, id = null, headers = {}) {
+    return json({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id
+    }, status, headers);
+}
+function bearerUnauthorized(config, message = "Missing or invalid bearer token", challengeError) {
+    return jsonRpcErrorResponse(401, ErrorCode.InvalidRequest, message, null, {
+        "WWW-Authenticate": buildMcpBearerChallenge({
+            appBaseUrl: config.appBaseUrl,
+            protectedResourceMetadataPath: config.routes.protectedResourceMetadataPath,
+            scopes: config.supportedScopes,
+            error: challengeError
+        })
+    });
+}
+function formValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+async function readBody(c) {
+    const contentType = c.req.header("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return ((await c.req.json().catch(() => ({}))) ?? {});
+    }
+    const form = await c.req.parseBody().catch(() => ({}));
+    return Object.fromEntries(Object.entries(form).map(([key, value]) => [key, formValue(value)]));
+}
+function queryOrBody(c, body, key) {
+    const fromQuery = c.req.query(key);
+    if (fromQuery !== undefined)
+        return fromQuery;
+    const fromBody = body[key];
+    return typeof fromBody === "string" ? fromBody : undefined;
+}
+function clientIdFromRequest(c, body) {
+    const clientId = queryOrBody(c, body, "client_id");
+    if (!clientId)
+        throw new Error("client_id is required");
+    return clientId;
+}
+function validateRedirectUri(clientRedirectUris, redirectUri) {
+    if (!redirectUri || !clientRedirectUris.includes(redirectUri))
+        throw new Error("redirect_uri is invalid for this OAuth client");
+    return redirectUri;
+}
+function validateResource(resource, config) {
+    const resolved = resource ?? config.resourceUri;
+    if (resolved !== config.resourceUri)
+        throw new Error("resource is invalid for this MCP server");
+    return resolved;
+}
+function requestedResource(c, body, config) {
+    return validateResource(queryOrBody(c, body, "resource"), config);
+}
+function redirectWithError(redirectUri, failure) {
+    const url = new URL(redirectUri);
+    url.searchParams.set("error", failure.error);
+    if (failure.description)
+        url.searchParams.set("error_description", failure.description);
+    if (failure.state)
+        url.searchParams.set("state", failure.state);
+    return Response.redirect(url, 302);
+}
+/**
+ * Named fields rather than positions: `state` and `description` are both optional strings
+ * with opposite meanings — one is the client's opaque CSRF value, the other is prose — so a
+ * positional pair of them is a swap that type-checks and corrupts the value a client verifies.
+ */
+function authorizationRequestError(redirectUri, failure) {
+    return redirectUri
+        ? redirectWithError(redirectUri, failure)
+        : oauthError(failure.error, failure.description, failure.status ?? 400);
+}
+/** Report a fault the router swallowed, through the product's logger when it supplied one. */
+function reportServerFault(adapters, message, error) {
+    if (adapters.logError)
+        adapters.logError(message, error);
+    else
+        console.error(message, error);
+}
+/**
+ * Marks an authorization request that has already been sent through sign-in once.
+ *
+ * Bounds the bounce to a single round trip: if the request comes back still reporting no
+ * signed-in human, the router refuses instead of redirecting again. Without it, a session
+ * cookie that never reaches the host serving the authorize route — a split-host deployment,
+ * say — spins the browser forever instead of producing a diagnosable OAuth error.
+ */
+const SIGN_IN_RETURN_PARAM = "mcp_signed_in";
+/** Consent decision parameters, read by the POST authorize handler. */
+const CONSENT_DECISION_PARAMS = ["consent_action", "decision", "action"];
+/**
+ * What an OAuth client is told when the product's identity resolver fails unexpectedly.
+ *
+ * Fixed text, deliberately: the only descriptions that leave this endpoint are ones written
+ * for a stranger's eyes, and an arbitrary exception message is not one of them.
+ */
+const CONSENT_IDENTITY_FAILED = "The authorization server could not determine who is signing in";
+function signInReturnTarget(c, body) {
+    const target = new URL(c.req.url);
+    // A consent POST carries the authorization request in its body, and the browser's request
+    // after sign-in is a GET, so fold the body into the query to re-present the same request.
+    // Everything is carried, not a list of the parameters this server happens to understand:
+    // a GET's query survives the round trip whole, and a client that sends an extension
+    // parameter should not lose it purely for having sent it by POST.
+    for (const [name, value] of Object.entries(body)) {
+        if (target.searchParams.has(name))
+            continue;
+        if (name === SIGN_IN_RETURN_PARAM)
+            continue;
+        if (typeof value === "string" && value.length > 0)
+            target.searchParams.set(name, value);
+    }
+    // The decision is deliberately left behind, from the query as well as the body: an approval
+    // given before sign-in must not be replayed as though whoever signed in afterwards had
+    // granted it. Only the POST handler reads these, so today the returning GET would ignore
+    // them anyway — dropping them here means that stays true if the GET path ever changes.
+    for (const name of CONSENT_DECISION_PARAMS)
+        target.searchParams.delete(name);
+    return target;
+}
+/**
+ * Resolve a configured product page address against the app's base URL.
+ *
+ * Resolution alone, with no pathname assignment after it: overwriting the pathname turns two
+ * reasonable configurations into nonsense with no error. An absolute URL — what a product whose
+ * identity lives on a separate host supplies — would be re-rooted under `appBaseUrl` as a path,
+ * and a path carrying a query would have its `?` percent-encoded into the pathname. Both work
+ * as written when `URL` is left to do the resolving.
+ */
+function productPageUrl(appBaseUrl, path) {
+    return new URL(path, `${trimTrailingSlash(appBaseUrl)}/`);
+}
+function signInRedirect(config, signInPath, target) {
+    target.searchParams.set(SIGN_IN_RETURN_PARAM, "1");
+    const url = productPageUrl(config.appBaseUrl, signInPath);
+    url.searchParams.set("callbackURL", `${target.pathname}${target.search}`);
+    return Response.redirect(url, 302);
+}
+function consentRedirect(config, request) {
+    const consentPath = config.routes.consentPagePath ?? "/oauth/consent";
+    const url = productPageUrl(config.appBaseUrl, consentPath);
+    url.searchParams.set("client_id", request.client.id);
+    url.searchParams.set("redirect_uri", request.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("code_challenge", request.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("scope", formatMcpScopeString(request.scopes));
+    url.searchParams.set("resource", request.resource);
+    url.searchParams.set("workspace_id", request.workspaceId);
+    url.searchParams.set("user_id", request.userId);
+    if (request.state)
+        url.searchParams.set("state", request.state);
+    return Response.redirect(url, 302);
+}
+function forwardedProto(c) {
+    const forwardedProtoHeader = c.req.header("x-forwarded-proto")?.split(",")[0]?.trim().toLowerCase();
+    if (forwardedProtoHeader)
+        return forwardedProtoHeader;
+    const forwardedHeader = c.req.header("forwarded")?.split(",")[0];
+    const protoPair = forwardedHeader
+        ?.split(";")
+        .map((part) => part.trim())
+        .find((part) => part.toLowerCase().startsWith("proto="));
+    return protoPair?.slice("proto=".length).replace(/^"|"$/g, "").toLowerCase() ?? null;
+}
+async function parseMcpBody(request) {
+    if (request.method !== "POST")
+        return null;
+    const body = await request.clone().json().catch(() => null);
+    const messages = Array.isArray(body) ? body : body ? [body] : [];
+    const isInitialize = messages.some((message) => typeof message === "object" && message && message.method === "initialize");
+    const requestMessage = messages.find((message) => typeof message === "object" && message && "id" in message);
+    return { body, isInitialize, id: requestMessage?.id ?? null };
+}
+function calledToolName(parsedBody) {
+    const messages = Array.isArray(parsedBody) ? parsedBody : parsedBody ? [parsedBody] : [];
+    for (const message of messages) {
+        if (!message || typeof message !== "object")
+            continue;
+        const candidate = message;
+        if (candidate.method === "tools/call" && typeof candidate.params?.name === "string")
+            return { name: candidate.params.name, id: candidate.id ?? null };
+    }
+    return null;
+}
+function sameScopes(left, right) {
+    return left.length === right.length && left.every((scope) => right.includes(scope));
+}
+function tokenMatchesSession(_context, token, sessionToken) {
+    return (sessionToken.grantId === token.grantId &&
+        sessionToken.clientId === token.clientId &&
+        sessionToken.workspaceId === token.workspaceId &&
+        sessionToken.userId === token.userId &&
+        sessionToken.sourceKind === token.sourceKind &&
+        sameScopes(sessionToken.scopes, token.scopes));
+}
+async function authenticateMcpRequest(c, config, adapters) {
+    const rawToken = parseBearerToken(c.req.raw);
+    if (!rawToken)
+        return bearerUnauthorized(config);
+    const token = await adapters.validateOAuthToken({
+        tokenHash: hashMcpToken(rawToken),
+        kind: "access",
+        resource: config.resourceUri,
+        recordLastUsed: true
+    });
+    if (!token)
+        return bearerUnauthorized(config, "Bearer token is expired, revoked, malformed, or issued for another resource");
+    return { rawToken, token };
+}
+function authInfo(rawToken, token, config) {
+    return {
+        token: rawToken,
+        clientId: token.clientId,
+        scopes: [...token.scopes],
+        expiresAt: Math.trunc(Date.parse(token.expiresAt) / 1000),
+        resource: new URL(config.resourceUri)
+    };
+}
+async function validateAuthorizationRequest(c, body, config, adapters) {
+    let clientId;
+    try {
+        clientId = clientIdFromRequest(c, body);
+    }
+    catch {
+        return oauthError("invalid_request", "client_id is required");
+    }
+    const client = await adapters.getOAuthClient(clientId);
+    if (!client)
+        return oauthError("invalid_client", "OAuth client not found", 401);
+    let redirectUri;
+    try {
+        redirectUri = validateRedirectUri(client.redirectUris, queryOrBody(c, body, "redirect_uri"));
+    }
+    catch {
+        return oauthError("invalid_request", "redirect_uri is invalid for this OAuth client");
+    }
+    const state = queryOrBody(c, body, "state");
+    if (queryOrBody(c, body, "response_type") !== "code")
+        return authorizationRequestError(redirectUri, { error: "unsupported_response_type", description: "Only response_type=code is supported", state });
+    let resource;
+    try {
+        resource = requestedResource(c, body, config);
+    }
+    catch {
+        return authorizationRequestError(redirectUri, { error: "invalid_request", description: "resource is invalid for this MCP server", state });
+    }
+    const codeChallenge = queryOrBody(c, body, "code_challenge");
+    const codeChallengeMethod = queryOrBody(c, body, "code_challenge_method");
+    if (!codeChallenge || codeChallengeMethod !== "S256")
+        return authorizationRequestError(redirectUri, { error: "invalid_request", description: "PKCE S256 code challenge is required", state });
+    const rawScope = queryOrBody(c, body, "scope");
+    const allowedScopes = client.scopes.length > 0 ? client.scopes : config.supportedScopes;
+    if (includesUnsupportedMcpScope(rawScope, allowedScopes))
+        return authorizationRequestError(redirectUri, { error: "invalid_scope", description: "Requested scope is not supported for this OAuth client", state });
+    const scopes = requestedMcpScopes(rawScope, allowedScopes, config.defaultScopes);
+    try {
+        const identity = await adapters.resolveConsentIdentity({
+            headers: c.req.raw.headers,
+            workspaceId: queryOrBody(c, body, "workspace_id"),
+            userId: queryOrBody(c, body, "user_id")
+        });
+        return { client, redirectUri, state, resource, codeChallenge, scopes, workspaceId: identity.workspaceId, userId: identity.userId };
+    }
+    catch (error) {
+        // Three different answers hide behind one throw here. A missing session is the user's to
+        // fix and gets sign-in; a refusal is terminal and goes back to the client; anything else
+        // is a malformed request, as before.
+        if (error instanceof McpConsentSignInRequiredError) {
+            const target = signInReturnTarget(c, body);
+            if (!config.routes.signInPath) {
+                return authorizationRequestError(redirectUri, { error: "server_error", description: "This authorization server has no sign-in location configured", state });
+            }
+            if (target.searchParams.has(SIGN_IN_RETURN_PARAM)) {
+                return authorizationRequestError(redirectUri, { error: "access_denied", description: "Returning from sign-in did not produce a signed-in session", state });
+            }
+            return signInRedirect(config, config.routes.signInPath, target);
+        }
+        if (error instanceof McpConsentForbiddenError) {
+            return authorizationRequestError(redirectUri, { error: "access_denied", description: error.message, state });
+        }
+        // Anything else is a fault, not an answer. The message belongs to the product's identity
+        // stack — a database, a session provider, a repository — and this endpoint delivers it to
+        // whatever redirect URI a self-registered client asked for, so it is logged here and never
+        // sent. `server_error` is also the truthful code: nothing about the request was wrong.
+        reportServerFault(adapters, "[saas-mcp] resolveConsentIdentity failed", error);
+        return authorizationRequestError(redirectUri, {
+            error: "server_error",
+            description: CONSENT_IDENTITY_FAILED,
+            state,
+            status: 500
+        });
+    }
+}
+async function handleMcpRequest(c, options, activeSessions, sessionTokens) {
+    const config = options.resolveConfig(c.req.url);
+    const envelope = validateMcpHttpEnvelope({
+        url: new URL(c.req.url),
+        method: c.req.method,
+        headers: c.req.raw.headers,
+        requireHttps: config.requireHttps,
+        allowedHosts: config.allowedHosts,
+        allowedOrigins: config.allowedOrigins,
+        supportedProtocolVersions: config.supportedProtocolVersions,
+        forwardedProto: forwardedProto(c)
+    });
+    if (!envelope.ok) {
+        if (envelope.reason === "query_token")
+            return bearerUnauthorized(config, envelope.message);
+        return jsonRpcErrorResponse(envelope.status, ErrorCode.InvalidRequest, envelope.message);
+    }
+    const auth = await authenticateMcpRequest(c, config, options.adapters);
+    if (auth instanceof Response)
+        return auth;
+    const parsed = await parseMcpBody(c.req.raw);
+    const sessionId = c.req.header("mcp-session-id") ?? undefined;
+    if (!parsed?.isInitialize && !sessionId) {
+        return jsonRpcErrorResponse(400, ErrorCode.InvalidRequest, "Mcp-Session-Id header is required after initialization", parsed?.id ?? null);
+    }
+    const toolCall = calledToolName(parsed?.body);
+    if (toolCall && options.adapters.getToolByName) {
+        const tool = options.adapters.getToolByName(toolCall.name);
+        if (tool && !hasRequiredMcpScopes(auth.token.scopes, tool.requiredScopes)) {
+            await options.adapters.recordMcpAuditEvent({
+                workspaceId: auth.token.workspaceId,
+                userId: auth.token.userId,
+                clientId: auth.token.clientId,
+                accessTokenId: auth.token.id,
+                sourceKind: auth.token.sourceKind,
+                activityKind: tool.annotations?.readOnlyHint ? "read" : "write",
+                toolName: tool.name,
+                outcome: "rejected",
+                metadata: { reason: "insufficient_scope", requiredScopes: tool.requiredScopes }
+            });
+            return jsonRpcErrorResponse(403, ErrorCode.InvalidRequest, `insufficient_scope: requires ${tool.requiredScopes.join(" ")}`, toolCall.id);
+        }
+        if (tool?.annotations?.readOnlyHint) {
+            await options.adapters.recordMcpAuditEvent({
+                workspaceId: auth.token.workspaceId,
+                userId: auth.token.userId,
+                clientId: auth.token.clientId,
+                accessTokenId: auth.token.id,
+                sourceKind: auth.token.sourceKind,
+                activityKind: "read",
+                toolName: tool.name,
+                outcome: "matched",
+                metadata: { method: "tools/call" }
+            });
+        }
+    }
+    if (sessionId) {
+        const active = activeSessions.get(sessionId);
+        const sessionToken = sessionTokens.get(sessionId);
+        if (!active || !sessionToken)
+            return jsonRpcErrorResponse(404, ErrorCode.InvalidRequest, "MCP session not found", parsed?.id ?? null);
+        if (!tokenMatchesSession(active.context, auth.token, sessionToken))
+            return bearerUnauthorized(config, "Bearer token does not match this MCP session");
+        const refreshed = options.adapters.refreshMcpContext?.(active.context, auth.token);
+        if (refreshed)
+            active.context = refreshed;
+        sessionTokens.set(sessionId, auth.token);
+        await options.adapters.touchMcpSession(sessionId, { accessTokenId: auth.token.id, scopes: [...auth.token.scopes] });
+        const response = await active.transport.handleRequest(c.req.raw, { authInfo: authInfo(auth.rawToken, auth.token, config) });
+        if (c.req.raw.method === "DELETE") {
+            activeSessions.delete(sessionId);
+            sessionTokens.delete(sessionId);
+            await options.adapters.closeMcpSession(sessionId);
+        }
+        return response;
+    }
+    let context;
+    try {
+        context = await options.adapters.createMcpContext({ token: auth.token, config });
+    }
+    catch (error) {
+        if (!(error instanceof McpContextUnauthorizedError))
+            throw error;
+        return bearerUnauthorized(config, error.message, "invalid_token");
+    }
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: options.sessionIdGenerator,
+        enableJsonResponse: true,
+        onsessioninitialized: (newSessionId) => {
+            void options.adapters.trackMcpSession({
+                id: newSessionId,
+                accessTokenId: auth.token.id,
+                clientId: auth.token.clientId,
+                workspaceId: auth.token.workspaceId,
+                userId: auth.token.userId,
+                scopes: [...auth.token.scopes],
+                protocolVersion: c.req.header("mcp-protocol-version") ?? config.latestProtocolVersion
+            });
+            activeSessions.set(newSessionId, { transport, context });
+            sessionTokens.set(newSessionId, auth.token);
+        },
+        onsessionclosed: (closedSessionId) => {
+            activeSessions.delete(closedSessionId);
+            sessionTokens.delete(closedSessionId);
+            void options.adapters.closeMcpSession(closedSessionId);
+        }
+    });
+    const server = options.adapters.createMcpServer(context);
+    await server.connect(transport);
+    return transport.handleRequest(c.req.raw, { authInfo: authInfo(auth.rawToken, auth.token, config) });
+}
+/** The host-absolute address RFC 8414 §3.1 derives from an issuer identifier. */
+function authorizationServerMetadataAddress(issuer) {
+    return new URL(authorizationServerMetadataUrlForIssuer(trimTrailingSlash(issuer))).pathname;
+}
+/**
+ * Where to register authorization-server metadata on this app, so that it answers at the
+ * address a client derives from the issuer.
+ *
+ * Derived rather than configured. Every other route can be advertised wherever it is served,
+ * but this one is pinned by RFC 8414 to a location computed from the `issuer` in the document
+ * itself, so a mount the product chooses independently is a mount that can disagree with the
+ * metadata — which is the whole failure this change exists to fix. Taking the mount out of the
+ * product's hands is what turns "serve it in the right place" from an instruction into a
+ * property of the router.
+ *
+ * The issuer is read once here, from `resolveConfig` with no request URL. Only its *path* is
+ * used, and the router requires that path not to vary by request: a deployment answering on
+ * several hosts publishes a different issuer per host but the same path under each. That is a
+ * property of the product's resolver rather than of the router, so it is not assumed — the
+ * metadata handler re-derives the address per request and refuses on disagreement, which is
+ * what `authorizationServerMetadataAddress` exists for.
+ */
+function authorizationServerMetadataMountPath(options) {
+    const issuer = trimTrailingSlash(options.resolveConfig().appBaseUrl);
+    const required = authorizationServerMetadataAddress(issuer);
+    const basePath = trimTrailingSlash(options.mounts.basePath ?? "");
+    if (!basePath)
+        return required;
+    if (required === basePath || required.startsWith(`${basePath}/`))
+        return required.slice(basePath.length);
+    // Refused rather than mounted somewhere that cannot be reached: an app mounted under a
+    // prefix that the derived address does not fall inside has no way to serve it, so the
+    // deployment needs a second registration at the host root. Better to say so at boot than
+    // to publish an `authorization_servers` entry that answers nothing.
+    throw new Error(`Authorization-server metadata for issuer ${issuer} must be served at ${required}, which is outside this app's basePath ${basePath}. Register the MCP routes on an app mounted at the host root, or set basePath to a prefix that contains ${required}.`);
+}
+/**
+ * Register OAuth discovery, dynamic client registration, authorization-code
+ * flow, token revocation, and Streamable HTTP MCP routes on a Hono app.
+ *
+ * The function is intentionally adapter-driven: it does not import product
+ * repositories, auth systems, or tool handlers. Consumers mount these routes
+ * inside their own API surface and supply product-specific adapters.
+ */
+export function registerMcpHonoRoutes(app, options) {
+    const activeSessions = new Map();
+    const sessionTokens = new Map();
+    const authorizationServerMetadataMount = authorizationServerMetadataMountPath(options);
+    app.get(options.mounts.protectedResourceMetadata, (c) => {
+        const config = options.resolveConfig(c.req.url);
+        return configuredResponse(buildMcpProtectedResourceMetadata({
+            appBaseUrl: config.appBaseUrl,
+            resourceUri: config.resourceUri,
+            supportedScopes: config.supportedScopes,
+            routes: config.routes
+        }));
+    });
+    app.get(`${options.mounts.protectedResourceMetadata}/*`, (c) => {
+        const config = options.resolveConfig(c.req.url);
+        return configuredResponse(buildMcpProtectedResourceMetadata({
+            appBaseUrl: config.appBaseUrl,
+            resourceUri: config.resourceUri,
+            supportedScopes: config.supportedScopes,
+            routes: config.routes
+        }));
+    });
+    app.get(authorizationServerMetadataMount, (c) => {
+        const config = options.resolveConfig(c.req.url);
+        // The mount was computed once, at registration, from the issuer this resolver returns with
+        // no request URL. A resolver whose issuer *path* varies by request — per-tenant prefixes,
+        // the case RFC 8414 §3.1 path insertion exists for — makes that one mount wrong for every
+        // tenant but one, and the document served here would name an issuer no client could have
+        // derived this address from. Serving it anyway is the original failure one level up, so it
+        // is refused instead, loudly enough to be found.
+        const derived = authorizationServerMetadataAddress(config.appBaseUrl);
+        const registered = `${trimTrailingSlash(options.mounts.basePath ?? "")}${authorizationServerMetadataMount}`;
+        if (derived !== registered) {
+            reportServerFault(options.adapters, `[saas-mcp] authorization-server metadata is registered at ${registered}, but issuer ${trimTrailingSlash(config.appBaseUrl)} derives ${derived}. resolveConfig must return an issuer whose path does not vary by request.`, new Error("mcp_authorization_server_metadata_mount_mismatch"));
+            return oauthError("server_error", "Authorization server metadata is not served at its issuer-derived address", 500);
+        }
+        return configuredResponse(buildMcpAuthorizationServerMetadata({
+            appBaseUrl: config.appBaseUrl,
+            resourceUri: config.resourceUri,
+            supportedScopes: config.supportedScopes,
+            routes: config.routes
+        }));
+    });
+    app.get(options.mounts.authorize, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const request = await validateAuthorizationRequest(c, {}, config, options.adapters);
+        if (request instanceof Response)
+            return request;
+        return consentRedirect(config, request);
+    });
+    app.post(options.mounts.authorize, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const request = await validateAuthorizationRequest(c, body, config, options.adapters);
+        if (request instanceof Response)
+            return request;
+        const consentAction = queryOrBody(c, body, "consent_action") ?? queryOrBody(c, body, "decision") ?? queryOrBody(c, body, "action");
+        if (consentAction === "cancel" || consentAction === "deny")
+            return redirectWithError(request.redirectUri, { error: "access_denied", description: "The user declined to authorize this client", state: request.state });
+        if (consentAction !== "approve")
+            return consentRedirect(config, request);
+        const rawCode = randomMcpToken(config.tokenPrefixes?.authorizationCode ?? "mcp_code");
+        await options.adapters.createOAuthAuthorizationCode({
+            codeHash: hashMcpToken(rawCode),
+            clientId: request.client.id,
+            redirectUri: request.redirectUri,
+            workspaceId: request.workspaceId,
+            userId: request.userId,
+            scopes: request.scopes,
+            resource: request.resource,
+            codeChallenge: request.codeChallenge,
+            codeChallengeMethod: "S256",
+            expiresAt: addSeconds(new Date(), config.authorizationCodeTtlSeconds)
+        });
+        const redirect = new URL(request.redirectUri);
+        redirect.searchParams.set("code", rawCode);
+        if (request.state)
+            redirect.searchParams.set("state", request.state);
+        return Response.redirect(redirect, 302);
+    });
+    app.post(options.mounts.registration, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const redirectUris = Array.isArray(body.redirect_uris) ? body.redirect_uris.filter((uri) => typeof uri === "string") : [];
+        if (redirectUris.length === 0)
+            return oauthError("invalid_client_metadata", "redirect_uris is required");
+        const rawScope = typeof body.scope === "string" ? body.scope : undefined;
+        const rawScopes = Array.isArray(body.scopes) ? body.scopes.filter((scope) => typeof scope === "string") : undefined;
+        const scopes = normalizeMcpScopes(rawScopes ?? rawScope, config.supportedScopes);
+        const client = await options.adapters.registerOAuthClient({
+            name: typeof body.client_name === "string" ? body.client_name : "MCP client",
+            displayName: typeof body.client_name === "string" ? body.client_name : undefined,
+            redirectUris,
+            scopes: scopes.length > 0 ? scopes : [...config.supportedScopes]
+        });
+        return json({
+            client_id: client.id,
+            client_name: client.name,
+            redirect_uris: client.redirectUris,
+            scope: formatMcpScopeString(client.scopes),
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            client_id_issued_at: Math.trunc(Date.parse(client.createdAt) / 1000)
+        }, 201, { "cache-control": "no-store" });
+    });
+    app.post(options.mounts.token, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const grantType = body.grant_type;
+        const clientId = clientIdFromRequest(c, body);
+        const client = await options.adapters.getOAuthClient(clientId);
+        if (!client)
+            return oauthError("invalid_client", "OAuth client not found", 401);
+        if (grantType === "authorization_code") {
+            const redirectUri = validateRedirectUri(client.redirectUris, queryOrBody(c, body, "redirect_uri"));
+            const resource = requestedResource(c, body, config);
+            const code = queryOrBody(c, body, "code");
+            const codeVerifier = queryOrBody(c, body, "code_verifier");
+            if (!code || !codeVerifier)
+                return oauthError("invalid_request", "code and code_verifier are required");
+            const grant = await options.adapters.consumeOAuthAuthorizationCode({ codeHash: hashMcpToken(code), clientId, redirectUri, resource });
+            if (!grant)
+                return oauthError("invalid_grant", "Authorization code is expired, reused, or invalid");
+            if (!verifyPkceS256(codeVerifier, grant.codeChallenge))
+                return oauthError("invalid_grant", "PKCE verification failed");
+            if (!(await options.adapters.hasWorkspaceMembership({ workspaceId: grant.workspaceId, userId: grant.userId })))
+                return oauthError("invalid_grant", "Workspace membership required");
+            const accessToken = randomMcpToken(config.tokenPrefixes?.accessToken ?? "mcp_at");
+            const refreshToken = randomMcpToken(config.tokenPrefixes?.refreshToken ?? "mcp_rt");
+            await options.adapters.issueOAuthToken({
+                tokenHash: hashMcpToken(accessToken),
+                kind: "access",
+                grantId: grant.id,
+                clientId,
+                workspaceId: grant.workspaceId,
+                userId: grant.userId,
+                scopes: [...grant.scopes],
+                resource,
+                expiresAt: addSeconds(new Date(), config.accessTokenTtlSeconds)
+            });
+            await options.adapters.issueOAuthToken({
+                tokenHash: hashMcpToken(refreshToken),
+                kind: "refresh",
+                grantId: grant.id,
+                clientId,
+                workspaceId: grant.workspaceId,
+                userId: grant.userId,
+                scopes: [...grant.scopes],
+                resource,
+                expiresAt: addSeconds(new Date(), config.refreshTokenTtlSeconds)
+            });
+            return tokenResponse({
+                access_token: accessToken,
+                token_type: "Bearer",
+                expires_in: config.accessTokenTtlSeconds,
+                refresh_token: refreshToken,
+                scope: formatMcpScopeString(grant.scopes),
+                resource
+            });
+        }
+        if (grantType === "refresh_token") {
+            const resource = requestedResource(c, body, config);
+            const refreshToken = queryOrBody(c, body, "refresh_token");
+            if (!refreshToken)
+                return oauthError("invalid_request", "refresh_token is required");
+            const tokenRecord = await options.adapters.validateOAuthToken({ tokenHash: hashMcpToken(refreshToken), kind: "refresh", resource });
+            if (!tokenRecord || tokenRecord.clientId !== clientId)
+                return oauthError("invalid_grant", "Refresh token is expired, revoked, or invalid");
+            const accessToken = randomMcpToken(config.tokenPrefixes?.accessToken ?? "mcp_at");
+            await options.adapters.issueOAuthToken({
+                tokenHash: hashMcpToken(accessToken),
+                kind: "access",
+                grantId: tokenRecord.grantId,
+                clientId,
+                workspaceId: tokenRecord.workspaceId,
+                userId: tokenRecord.userId,
+                scopes: [...tokenRecord.scopes],
+                resource,
+                expiresAt: addSeconds(new Date(), config.accessTokenTtlSeconds)
+            });
+            return tokenResponse({
+                access_token: accessToken,
+                token_type: "Bearer",
+                expires_in: config.accessTokenTtlSeconds,
+                scope: formatMcpScopeString(tokenRecord.scopes),
+                resource
+            });
+        }
+        return oauthError("unsupported_grant_type", "Only authorization_code and refresh_token grants are supported");
+    });
+    app.post(options.mounts.revocation, async (c) => {
+        const config = options.resolveConfig(c.req.url);
+        const body = await readBody(c);
+        const tokenValue = queryOrBody(c, body, "token");
+        if (!tokenValue)
+            return new Response(null, { status: 200 });
+        const tokenHash = hashMcpToken(tokenValue);
+        const tokenRecord = await options.adapters.getOAuthTokenByHash({ tokenHash, resource: config.resourceUri });
+        const clientId = queryOrBody(c, body, "client_id");
+        if (tokenRecord && clientId && tokenRecord.clientId !== clientId)
+            return oauthError("invalid_client", "client_id does not match token owner", 401);
+        if (tokenRecord && (await options.adapters.revokeOAuthToken(tokenHash, { revokedReason: "oauth_revocation_endpoint" }))) {
+            await options.adapters.recordMcpAuditEvent({
+                workspaceId: tokenRecord.workspaceId,
+                userId: tokenRecord.userId,
+                clientId: tokenRecord.clientId,
+                accessTokenId: tokenRecord.kind === "access" ? tokenRecord.id : null,
+                sourceKind: tokenRecord.sourceKind,
+                activityKind: "management",
+                toolName: "oauth.revoke",
+                outcome: "revoked",
+                metadata: { tokenKind: tokenRecord.kind, grantId: tokenRecord.grantId, tokenName: tokenRecord.displayName }
+            });
+        }
+        return new Response(null, { status: 200 });
+    });
+    app.all(options.mounts.mcp, async (c) => handleMcpRequest(c, options, activeSessions, sessionTokens));
+}