@agent-native/core 0.128.3 → 0.129.0

package/corpus/core/src/mcp/embed-app.ts

@@ -2,7 +2,7 @@ import type { ActionMcpAppResourceConfig } from "../action.js";
 import { MCP_APP_CHAT_BRIDGE_QUERY_PARAM } from "../shared/embed-auth.js";
 
 const MCP_APP_IMPORT =
-  "https://esm.sh/@modelcontextprotocol/ext-apps@1.7.2/app-with-deps";
+  "https://esm.sh/@modelcontextprotocol/ext-apps@1.7.5/app-with-deps";
 
 export const MCP_APP_REQUEST_ORIGIN_CSP_SOURCE = "$requestOrigin";
 const MCP_APP_WRAPPER_CHROME_HEIGHT = 44;

package/corpus/core/src/mcp/oauth-client-metadata.ts

@@ -0,0 +1,380 @@
+import { ssrfSafeFetch } from "../extensions/url-safety.js";
+
+const CLIENT_METADATA_MAX_BYTES = 64 * 1024;
+const CLIENT_METADATA_TIMEOUT_MS = 5_000;
+const CLIENT_METADATA_MAX_REDIRECTS = 2;
+const CLIENT_METADATA_MAX_CACHE_ENTRIES = 128;
+const CLIENT_METADATA_MAX_CACHE_TTL_MS = 5 * 60_000;
+
+const DISALLOWED_REDIRECT_SCHEMES = new Set([
+  "javascript:",
+  "data:",
+  "vbscript:",
+  "file:",
+  "blob:",
+  "about:",
+]);
+
+export interface OAuthClientMetadataDocument {
+  clientId: string;
+  clientName: string;
+  redirectUris: string[];
+  grantTypes: string[];
+  responseTypes: string[];
+  tokenEndpointAuthMethod: "none";
+  applicationType: "native" | "web";
+}
+
+interface CachedClientMetadata {
+  expiresAt: number;
+  metadata: OAuthClientMetadataDocument;
+}
+
+const clientMetadataCache = new Map<string, CachedClientMetadata>();
+
+export function isUrlBasedOAuthClientId(clientId: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(clientId);
+}
+
+export function validateOAuthClientMetadataUrl(clientId: string): URL {
+  if (!clientId || clientId !== clientId.trim() || clientId.length > 2048) {
+    throw new Error("Client metadata URL is invalid");
+  }
+  let url: URL;
+  try {
+    url = new URL(clientId);
+  } catch {
+    throw new Error("Client metadata URL is invalid");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.pathname === "/" ||
+    !url.pathname ||
+    url.hash ||
+    url.username ||
+    url.password
+  ) {
+    throw new Error("Client metadata URL must be HTTPS with a non-root path");
+  }
+  const authorityEnd = clientId.indexOf("/", "https://".length);
+  const queryStart = clientId.indexOf("?", authorityEnd);
+  const rawPath = clientId.slice(
+    authorityEnd,
+    queryStart === -1 ? undefined : queryStart,
+  );
+  if (
+    rawPath.split("/").some((segment) => {
+      try {
+        const decoded = decodeURIComponent(segment);
+        return decoded === "." || decoded === "..";
+      } catch {
+        return true;
+      }
+    })
+  ) {
+    throw new Error("Client metadata URL must not contain dot path segments");
+  }
+  return url;
+}
+
+export function isAllowedOAuthRedirectUri(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > 2048) return false;
+  try {
+    const url = new URL(value);
+    if (url.hash || url.username || url.password) return false;
+    if (url.protocol === "https:") return true;
+    if (url.protocol === "http:") {
+      return (
+        url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "::1" ||
+        url.hostname === "[::1]"
+      );
+    }
+    return (
+      !DISALLOWED_REDIRECT_SCHEMES.has(url.protocol) &&
+      /^[a-z][a-z0-9+.-]*:$/.test(url.protocol)
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function applicationTypeForRedirectUris(
+  redirectUris: string[],
+): "native" | "web" {
+  return redirectUris.some((value) => {
+    const url = new URL(value);
+    return (
+      url.protocol !== "https:" ||
+      url.hostname === "localhost" ||
+      url.hostname === "127.0.0.1" ||
+      url.hostname === "::1" ||
+      url.hostname === "[::1]"
+    );
+  })
+    ? "native"
+    : "web";
+}
+
+function parseStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function validateClientMetadataDocument(
+  clientId: string,
+  value: unknown,
+): OAuthClientMetadataDocument {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Client metadata document must be a JSON object");
+  }
+  const document = value as Record<string, unknown>;
+  if (document.client_id !== clientId) {
+    throw new Error(
+      "Client metadata document client_id does not match its URL",
+    );
+  }
+  const clientName =
+    typeof document.client_name === "string" ? document.client_name.trim() : "";
+  if (
+    !clientName ||
+    clientName.length > 120 ||
+    /[\u0000-\u001f\u007f]/.test(clientName)
+  ) {
+    throw new Error("Client metadata document client_name is invalid");
+  }
+
+  const rawRedirectUris = document.redirect_uris;
+  const redirectUris = parseStringArray(rawRedirectUris);
+  if (
+    !Array.isArray(rawRedirectUris) ||
+    redirectUris.length === 0 ||
+    redirectUris.length > 20 ||
+    redirectUris.length !== rawRedirectUris.length ||
+    !redirectUris.every(isAllowedOAuthRedirectUri)
+  ) {
+    throw new Error("Client metadata document redirect_uris are invalid");
+  }
+
+  const tokenEndpointAuthMethod =
+    typeof document.token_endpoint_auth_method === "string"
+      ? document.token_endpoint_auth_method
+      : "none";
+  if (
+    document.token_endpoint_auth_method !== undefined &&
+    typeof document.token_endpoint_auth_method !== "string"
+  ) {
+    throw new Error(
+      "Client metadata document token_endpoint_auth_method is invalid",
+    );
+  }
+  if (tokenEndpointAuthMethod !== "none") {
+    throw new Error("Only public Client ID Metadata clients are supported");
+  }
+
+  const grantTypes = parseStringArray(document.grant_types);
+  if (
+    (document.grant_types !== undefined &&
+      (!Array.isArray(document.grant_types) ||
+        grantTypes.length !== document.grant_types.length)) ||
+    grantTypes.length > 10 ||
+    !grantTypes.every(
+      (grant) => grant === "authorization_code" || grant === "refresh_token",
+    )
+  ) {
+    throw new Error("Client metadata document grant_types are unsupported");
+  }
+
+  const responseTypes = parseStringArray(document.response_types);
+  if (
+    (document.response_types !== undefined &&
+      (!Array.isArray(document.response_types) ||
+        responseTypes.length !== document.response_types.length)) ||
+    responseTypes.length > 10 ||
+    !responseTypes.every((responseType) => responseType === "code")
+  ) {
+    throw new Error("Client metadata document response_types are unsupported");
+  }
+
+  const requestedApplicationType =
+    typeof document.application_type === "string"
+      ? document.application_type
+      : undefined;
+  if (
+    (document.application_type !== undefined &&
+      typeof document.application_type !== "string") ||
+    (requestedApplicationType &&
+      requestedApplicationType !== "native" &&
+      requestedApplicationType !== "web")
+  ) {
+    throw new Error("Client metadata document application_type is unsupported");
+  }
+  const applicationType: "native" | "web" =
+    requestedApplicationType === "native" || requestedApplicationType === "web"
+      ? requestedApplicationType
+      : applicationTypeForRedirectUris(redirectUris);
+
+  return {
+    clientId,
+    clientName,
+    redirectUris: [...new Set(redirectUris)],
+    grantTypes: grantTypes.length
+      ? [...new Set(grantTypes)]
+      : ["authorization_code", "refresh_token"],
+    responseTypes: responseTypes.length
+      ? [...new Set(responseTypes)]
+      : ["code"],
+    tokenEndpointAuthMethod: "none",
+    applicationType,
+  };
+}
+
+async function readBoundedResponseBody(response: Response): Promise<string> {
+  const contentLength = Number(response.headers.get("content-length"));
+  if (
+    Number.isFinite(contentLength) &&
+    contentLength > CLIENT_METADATA_MAX_BYTES
+  ) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new Error("Client metadata document is too large");
+  }
+  if (!response.body) return "";
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let bytesRead = 0;
+  let text = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytesRead += value.byteLength;
+      if (bytesRead > CLIENT_METADATA_MAX_BYTES) {
+        await reader.cancel().catch(() => undefined);
+        throw new Error("Client metadata document is too large");
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+    text += decoder.decode();
+    return text;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function cacheTtlMs(headers: Headers, now: number): number {
+  const cacheControl = headers.get("cache-control")?.toLowerCase() ?? "";
+  if (/(?:^|,)\s*(?:no-store|no-cache|private)(?:\s|,|$)/.test(cacheControl)) {
+    return 0;
+  }
+  const maxAge = cacheControl.match(/(?:^|,)\s*max-age=(\d+)/)?.[1];
+  if (maxAge) {
+    return Math.min(Number(maxAge) * 1_000, CLIENT_METADATA_MAX_CACHE_TTL_MS);
+  }
+  const expiresAt = Date.parse(headers.get("expires") ?? "");
+  if (Number.isFinite(expiresAt) && expiresAt > now) {
+    return Math.min(expiresAt - now, CLIENT_METADATA_MAX_CACHE_TTL_MS);
+  }
+  return 0;
+}
+
+function cacheClientMetadata(
+  clientId: string,
+  metadata: OAuthClientMetadataDocument,
+  response: Response,
+  now: number,
+): void {
+  const ttlMs = cacheTtlMs(response.headers, now);
+  if (ttlMs <= 0) return;
+  clientMetadataCache.delete(clientId);
+  clientMetadataCache.set(clientId, {
+    expiresAt: now + ttlMs,
+    metadata,
+  });
+  while (clientMetadataCache.size > CLIENT_METADATA_MAX_CACHE_ENTRIES) {
+    const oldest = clientMetadataCache.keys().next().value;
+    if (typeof oldest !== "string") break;
+    clientMetadataCache.delete(oldest);
+  }
+}
+
+async function fetchOAuthClientMetadataDocument(
+  clientId: string,
+  signal: AbortSignal,
+): Promise<{ metadata: OAuthClientMetadataDocument; response: Response }> {
+  const response = await ssrfSafeFetch(
+    clientId,
+    {
+      headers: {
+        Accept: "application/json, application/client-metadata+json",
+      },
+      signal,
+    },
+    {
+      maxRedirects: CLIENT_METADATA_MAX_REDIRECTS,
+      httpsOnly: true,
+    },
+  );
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new Error(
+      `Client metadata document request failed with ${response.status}`,
+    );
+  }
+  const contentType =
+    response.headers.get("content-type")?.split(";", 1)[0]?.trim() ?? "";
+  if (
+    contentType !== "application/json" &&
+    contentType !== "application/client-metadata+json"
+  ) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new Error("Client metadata document content type is invalid");
+  }
+
+  const body = await readBoundedResponseBody(response);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error("Client metadata document is not valid JSON");
+  }
+  return {
+    metadata: validateClientMetadataDocument(clientId, parsed),
+    response,
+  };
+}
+
+export async function resolveOAuthClientMetadataDocument(
+  clientId: string,
+): Promise<OAuthClientMetadataDocument> {
+  validateOAuthClientMetadataUrl(clientId);
+  const now = Date.now();
+  const cached = clientMetadataCache.get(clientId);
+  if (cached && cached.expiresAt > now) {
+    clientMetadataCache.delete(clientId);
+    clientMetadataCache.set(clientId, cached);
+    return cached.metadata;
+  }
+  if (cached) clientMetadataCache.delete(clientId);
+
+  const abort = new AbortController();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timedOut = new Promise<never>((_, reject) => {
+      timeout = setTimeout(() => {
+        abort.abort();
+        reject(new Error("Client metadata document request timed out"));
+      }, CLIENT_METADATA_TIMEOUT_MS);
+    });
+    const { metadata, response } = await Promise.race([
+      fetchOAuthClientMetadataDocument(clientId, abort.signal),
+      timedOut,
+    ]);
+    cacheClientMetadata(clientId, metadata, response, now);
+    return metadata;
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}

package/corpus/core/src/mcp/oauth-route.ts

@@ -17,6 +17,12 @@ import { getOrgDomain } from "../org/context.js";
 import { getConfiguredLoginHtml, getSession } from "../server/auth.js";
 import { getAuthSecret } from "../server/better-auth-instance.js";
 import { readBody } from "../server/h3-helpers.js";
+import {
+  applicationTypeForRedirectUris,
+  isAllowedOAuthRedirectUri,
+  isUrlBasedOAuthClientId,
+  resolveOAuthClientMetadataDocument,
+} from "./oauth-client-metadata.js";
 import {
   createOAuthCode,
   createOAuthRefreshToken,
@@ -30,7 +36,6 @@ import {
 } from "./oauth-store.js";
 import {
   MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS,
-  MCP_OAUTH_DEFAULT_SCOPE,
   MCP_OAUTH_SCOPES,
   normalizeOAuthScope,
   signMcpOAuthAccessToken,
@@ -42,6 +47,11 @@ export interface McpOAuthRouteOptions {
   appName?: string;
 }
 
+const MCP_OAUTH_RESOURCE_SCOPES = MCP_OAUTH_SCOPES.filter(
+  (scope) => scope !== "offline_access",
+);
+const MCP_OAUTH_RESOURCE_SCOPE = MCP_OAUTH_RESOURCE_SCOPES.join(" ");
+
 function json(body: unknown, status = 200): Response {
   return new Response(JSON.stringify(body), {
     status,
@@ -229,7 +239,7 @@ export function getMcpOAuthProtectedResourceMetadataUrl(
 
 export function buildMcpOAuthChallenge(event: H3Event): string {
   const metadata = getMcpOAuthProtectedResourceMetadataUrl(event);
-  const scope = MCP_OAUTH_DEFAULT_SCOPE;
+  const scope = MCP_OAUTH_RESOURCE_SCOPE;
   return metadata
     ? `Bearer resource_metadata="${metadata}", scope="${scope}"`
     : `Bearer scope="${scope}"`;
@@ -268,7 +278,7 @@ export function handleMcpOAuthProtectedResourceMetadata(
   return json({
     resource,
     authorization_servers: [issuer],
-    scopes_supported: MCP_OAUTH_SCOPES,
+    scopes_supported: MCP_OAUTH_RESOURCE_SCOPES,
     resource_documentation: issuer,
   });
 }
@@ -296,54 +306,11 @@ export function handleMcpOAuthAuthorizationServerMetadata(
     code_challenge_methods_supported: ["S256"],
     token_endpoint_auth_methods_supported: ["none"],
     scopes_supported: MCP_OAUTH_SCOPES,
+    authorization_response_iss_parameter_supported: true,
+    client_id_metadata_document_supported: true,
   });
 }
 
-// Schemes that must never be accepted as a redirect target: they can execute
-// script or read local resources if a redirect is ever rendered in a browser
-// or webview context.
-const DISALLOWED_REDIRECT_SCHEMES = new Set([
-  "javascript:",
-  "data:",
-  "vbscript:",
-  "file:",
-  "blob:",
-  "about:",
-]);
-
-// Native/desktop IDE clients (Cursor, VS Code, …) register a private-use URI
-// scheme callback such as `cursor://` or `vscode://` (RFC 8252 §7.1) instead of
-// an https/loopback URL. The authorization code is bound by PKCE (S256), so
-// delivering it through a client-registered app scheme is safe.
-function isPrivateUseRedirectScheme(protocol: string): boolean {
-  if (DISALLOWED_REDIRECT_SCHEMES.has(protocol)) return false;
-  // RFC 3986 scheme grammar: ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ), with a
-  // trailing ":" from URL.protocol. Require a non-http(s) custom scheme here;
-  // http/https are handled explicitly above.
-  return /^[a-z][a-z0-9+.-]*:$/.test(protocol);
-}
-
-function isAllowedRedirectUri(value: unknown): value is string {
-  if (typeof value !== "string" || value.length > 2048) return false;
-  try {
-    const url = new URL(value);
-    if (url.hash) return false;
-    if (url.username || url.password) return false;
-    if (url.protocol === "https:") return true;
-    if (url.protocol === "http:") {
-      return (
-        url.hostname === "localhost" ||
-        url.hostname === "127.0.0.1" ||
-        url.hostname === "::1" ||
-        url.hostname === "[::1]"
-      );
-    }
-    return isPrivateUseRedirectScheme(url.protocol);
-  } catch {
-    return false;
-  }
-}
-
 function parseStringArray(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((item): item is string => typeof item === "string")
@@ -362,7 +329,7 @@ async function handleRegister(event: H3Event): Promise<Response> {
   if (
     redirectUris.length === 0 ||
     redirectUris.length > 20 ||
-    !redirectUris.every(isAllowedRedirectUri)
+    !redirectUris.every(isAllowedOAuthRedirectUri)
   ) {
     return oauthError(
       "invalid_client_metadata",
@@ -393,6 +360,22 @@ async function handleRegister(event: H3Event): Promise<Response> {
       "Only public OAuth clients are supported",
     );
   }
+  const requestedApplicationType =
+    typeof body.application_type === "string"
+      ? body.application_type
+      : undefined;
+  if (
+    requestedApplicationType &&
+    requestedApplicationType !== "native" &&
+    requestedApplicationType !== "web"
+  ) {
+    return oauthError(
+      "invalid_client_metadata",
+      "application_type must be native or web",
+    );
+  }
+  const applicationType =
+    requestedApplicationType ?? applicationTypeForRedirectUris(redirectUris);
 
   const clientName =
     typeof body.client_name === "string"
@@ -422,6 +405,7 @@ async function handleRegister(event: H3Event): Promise<Response> {
       grant_types: client.grantTypes,
       response_types: client.responseTypes,
       token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+      application_type: applicationType,
     },
     201,
   );
@@ -429,12 +413,14 @@ async function handleRegister(event: H3Event): Promise<Response> {
 
 function redirectWithOAuthError(params: {
   redirectUri: string;
+  issuer: string;
   state?: string;
   error: string;
   description?: string;
 }): Response {
   const url = new URL(params.redirectUri);
   url.searchParams.set("error", params.error);
+  url.searchParams.set("iss", params.issuer);
   if (params.description) {
     url.searchParams.set("error_description", params.description);
   }
@@ -444,17 +430,20 @@ function redirectWithOAuthError(params: {
 
 function buildCodeRedirectUrl(params: {
   redirectUri: string;
+  issuer: string;
   code: string;
   state?: string;
 }): string {
   const url = new URL(params.redirectUri);
   url.searchParams.set("code", params.code);
+  url.searchParams.set("iss", params.issuer);
   if (params.state) url.searchParams.set("state", params.state);
   return url.toString();
 }
 
 function redirectWithCode(params: {
   redirectUri: string;
+  issuer: string;
   code: string;
   state?: string;
 }): Response {
@@ -574,6 +563,7 @@ function renderConsentPage(params: {
   appName: string;
   email: string;
   clientName: string;
+  redirectUri: string;
   scopes: string[];
   fields: Record<string, string>;
 }): string {
@@ -602,6 +592,7 @@ function renderConsentPage(params: {
   <h1>Authorize ${escapeHtml(params.clientName)}</h1>
   <p>${escapeHtml(params.appName)} will let this MCP client act as ${escapeHtml(params.email)} for these scopes:</p>
   <ul>${scopes}</ul>
+  <p>After authorization, your browser will return to <code>${escapeHtml(params.redirectUri)}</code>.</p>
   <form method="post">
     ${hidden}
     <div class="actions">
@@ -721,6 +712,7 @@ async function handleAuthorize(
     );
   }
   const params = await readOAuthParams(event);
+  const issuer = getMcpOAuthIssuer(event);
   const state = params.state;
   const clientId = params.client_id;
   const redirectUri = params.redirect_uri;
@@ -739,6 +731,7 @@ async function handleAuthorize(
   if (
     !clientId ||
     !redirectUri ||
+    !issuer ||
     !resource ||
     !expectedResources.includes(resource)
   ) {
@@ -748,7 +741,9 @@ async function handleAuthorize(
     return oauthError("invalid_request", "PKCE S256 is required");
   }
 
-  const client = await getOAuthClient(clientId);
+  const client = isUrlBasedOAuthClientId(clientId)
+    ? await resolveOAuthClientMetadataDocument(clientId).catch(() => null)
+    : await getOAuthClient(clientId);
   if (!client || !client.redirectUris.includes(redirectUri)) {
     return oauthError("invalid_client", "Unknown client or redirect_uri");
   }
@@ -758,6 +753,7 @@ async function handleAuthorize(
     if (params.prompt === "none") {
       return redirectWithOAuthError({
         redirectUri,
+        issuer,
         state,
         error: "login_required",
       });
@@ -772,6 +768,7 @@ async function handleAuthorize(
   if (!scope) {
     return redirectWithOAuthError({
       redirectUri,
+      issuer,
       state,
       error: "invalid_scope",
     });
@@ -782,6 +779,7 @@ async function handleAuthorize(
         appName: options.appName || options.appId || "Agent Native",
         email: session.email,
         clientName: client.clientName || client.clientId,
+        redirectUri,
         scopes: scope.split(/\s+/),
         fields: {
           response_type: "code",
@@ -821,6 +819,7 @@ async function handleAuthorize(
   if (params.decision !== "approve") {
     return redirectWithOAuthError({
       redirectUri,
+      issuer,
       state,
       error: "access_denied",
     });
@@ -850,7 +849,7 @@ async function handleAuthorize(
     isDeepLinkRedirect =
       protocol !== "http:" &&
       protocol !== "https:" &&
-      isPrivateUseRedirectScheme(protocol);
+      /^[a-z][a-z0-9+.-]*:$/.test(protocol);
   } catch {
     isDeepLinkRedirect = false;
   }
@@ -861,13 +860,19 @@ async function handleAuthorize(
         clientName: client.clientName ?? null,
         redirectUrl: buildCodeRedirectUrl({
           redirectUri,
+          issuer,
           state,
           code: code.code,
         }),
       }),
     );
   }
-  return redirectWithCode({ redirectUri, state, code: code.code });
+  return redirectWithCode({
+    redirectUri,
+    issuer,
+    state,
+    code: code.code,
+  });
 }
 
 async function issueTokenSet(params: {