agor-live 0.17.2 → 0.17.3

package/dist/core/tools/mcp/oauth-mcp-transport.cjs

@@ -32,12 +32,15 @@ var oauth_mcp_transport_exports = {};
 __export(oauth_mcp_transport_exports, {
   clearAuthCodeTokenCache: () => clearAuthCodeTokenCache,
   completeMCPOAuthFlow: () => completeMCPOAuthFlow,
+  discoverAuthorizationServerFromMcpOrigin: () => discoverAuthorizationServerFromMcpOrigin,
   discoverResourceMetadataUrl: () => discoverResourceMetadataUrl,
+  fetchAuthorizationServerMetadata: () => fetchAuthorizationServerMetadata,
   getAuthCodeTokenCacheStats: () => getAuthCodeTokenCacheStats,
   getCachedOAuth21Token: () => getCachedOAuth21Token,
   isOAuthRequired: () => isOAuthRequired,
   parseOAuthCallback: () => parseOAuthCallback,
   performMCPOAuthFlow: () => performMCPOAuthFlow,
+  resolveMCPOAuthDiscovery: () => resolveMCPOAuthDiscovery,
   resolveResourceMetadataUrl: () => resolveResourceMetadataUrl,
   startMCPOAuthFlow: () => startMCPOAuthFlow
 });
@@ -100,6 +103,59 @@ async function resolveResourceMetadataUrl(wwwAuthenticateHeader, mcpUrl) {
   }
   return null;
 }
+async function discoverAuthorizationServerFromMcpOrigin(mcpUrl) {
+  const url = new URL(mcpUrl);
+  const origin = url.origin;
+  const path = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+  const candidates = [];
+  if (path) {
+    candidates.push(`${origin}/.well-known/oauth-authorization-server${path}`);
+  }
+  candidates.push(`${origin}/.well-known/oauth-authorization-server`);
+  if (path) {
+    candidates.push(`${origin}${path}/.well-known/openid-configuration`);
+  }
+  candidates.push(`${origin}/.well-known/openid-configuration`);
+  const unique = Array.from(new Set(candidates));
+  for (const candidate of unique) {
+    try {
+      console.log("[MCP OAuth] Trying AS-direct discovery:", candidate);
+      const response = await fetch(candidate, { signal: AbortSignal.timeout(1e4) });
+      if (!response.ok) continue;
+      const data = await response.json();
+      if (typeof data.authorization_endpoint === "string" && typeof data.token_endpoint === "string") {
+        console.log("[MCP OAuth] \u2713 Discovered AS metadata at:", candidate);
+        return {
+          metadata: data,
+          discoveredAt: candidate
+        };
+      }
+    } catch (err) {
+      console.log(
+        "[MCP OAuth] AS-direct discovery failed for",
+        candidate,
+        ":",
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
+  return null;
+}
+async function resolveMCPOAuthDiscovery(wwwAuthenticateHeader, mcpUrl) {
+  const rfc9728 = await resolveResourceMetadataUrl(wwwAuthenticateHeader, mcpUrl);
+  if (rfc9728) {
+    return { kind: "resource-metadata", ...rfc9728 };
+  }
+  const asDirect = await discoverAuthorizationServerFromMcpOrigin(mcpUrl);
+  if (asDirect) {
+    return {
+      kind: "authorization-server",
+      authServerMetadata: asDirect.metadata,
+      discoveredAt: asDirect.discoveredAt
+    };
+  }
+  return null;
+}
 async function fetchResourceMetadata(metadataUrl) {
   const response = await fetch(metadataUrl, { signal: AbortSignal.timeout(15e3) });
   if (!response.ok) {
@@ -529,101 +585,72 @@ function getAuthCodeTokenCacheStats() {
     expiredEntries
   };
 }
-async function startMCPOAuthFlow(wwwAuthenticateHeader, clientId, redirectUri, options) {
-  console.log("[MCP OAuth] Starting two-phase OAuth 2.1 flow");
-  const metadataUrl = parseWWWAuthenticate(wwwAuthenticateHeader) || options?.resourceMetadataUrl;
-  if (!metadataUrl) {
-    throw new Error(
-      "Could not determine OAuth resource metadata URL. The WWW-Authenticate header does not contain resource_metadata, and no pre-discovered metadata URL was provided."
-    );
-  }
-  console.log("[MCP OAuth] Resource metadata URL:", metadataUrl);
-  const resourceMetadata = await fetchResourceMetadata(metadataUrl);
-  console.log("[MCP OAuth] Resource metadata:", resourceMetadata);
-  if (!resourceMetadata.authorization_servers || resourceMetadata.authorization_servers.length === 0) {
-    throw new Error("No authorization servers found in resource metadata");
-  }
-  const authServerUrl = resourceMetadata.authorization_servers[0];
-  console.log("[MCP OAuth] Authorization server:", authServerUrl);
-  const hasFullOverrides = options?.authorizationUrlOverride && options?.tokenUrlOverride;
-  let authServerMetadata = null;
-  if (hasFullOverrides) {
-    console.log("[MCP OAuth] Skipping auth server metadata fetch \u2014 manual overrides provided:", {
-      authorization: options.authorizationUrlOverride,
-      token: options.tokenUrlOverride
-    });
-  } else {
-    try {
-      authServerMetadata = await fetchAuthorizationServerMetadata(authServerUrl);
-      console.log("[MCP OAuth] Authorization server metadata:", authServerMetadata);
-    } catch (metadataError) {
-      if (options?.authorizationUrlOverride || options?.tokenUrlOverride) {
-        console.log(
-          "[MCP OAuth] Auth server metadata fetch failed, but partial overrides available:",
-          metadataError instanceof Error ? metadataError.message : String(metadataError)
-        );
-      } else {
-        throw metadataError;
-      }
-    }
-  }
+async function startMCPOAuthFlowWithAS(opts) {
+  const {
+    authServerMetadata,
+    cacheKey,
+    clientId,
+    redirectUri,
+    authorizationUrlOverride,
+    tokenUrlOverride,
+    fallbackRegistrationEndpoint,
+    resourceScopesSupported
+  } = opts;
+  const hasFullOverrides = !!(authorizationUrlOverride && tokenUrlOverride);
   const pkce = generatePKCE();
   const actualRedirectUri = redirectUri || "http://127.0.0.1:0/oauth/callback";
-  const scopeString = options?.scope ? options.scope : !clientId && resourceMetadata.scopes_supported && resourceMetadata.scopes_supported.length > 0 ? resourceMetadata.scopes_supported.join(" ") : void 0;
+  const scopeString = opts.scope ? opts.scope : !clientId && resourceScopesSupported && resourceScopesSupported.length > 0 ? resourceScopesSupported.join(" ") : void 0;
   let actualClientId = clientId;
-  let clientSecret = options?.clientSecret;
+  let resolvedClientSecret = opts.clientSecret;
   if (!actualClientId) {
-    if (authServerMetadata?.registration_endpoint) {
-      console.log("[MCP OAuth] Server supports Dynamic Client Registration");
-      const registration = await registerDynamicClient(
-        authServerMetadata.registration_endpoint,
-        actualRedirectUri,
-        "Agor MCP Client",
-        scopeString
-      );
-      actualClientId = registration.client_id;
-      clientSecret = registration.client_secret;
-    } else if (!hasFullOverrides) {
-      const mcpRegisterEndpoint = `${authServerUrl}/register`;
-      console.log("[MCP OAuth] Trying MCP-style registration endpoint:", mcpRegisterEndpoint);
+    const registrationEndpoint = authServerMetadata?.registration_endpoint || fallbackRegistrationEndpoint;
+    if (registrationEndpoint) {
+      console.log("[MCP OAuth] Using DCR endpoint:", registrationEndpoint);
       try {
         const registration = await registerDynamicClient(
-          mcpRegisterEndpoint,
+          registrationEndpoint,
           actualRedirectUri,
           "Agor MCP Client",
           scopeString
         );
         actualClientId = registration.client_id;
-        clientSecret = registration.client_secret;
-      } catch (_regError) {
+        resolvedClientSecret = registration.client_secret;
+      } catch (regError) {
+        const detail = regError instanceof Error ? regError.message : String(regError);
         throw new Error(
-          "OAuth client_id is required but the authorization server does not support Dynamic Client Registration.\n\nRegister an OAuth app in the provider's developer portal and enter the Client ID (and Client Secret if required) in the MCP server configuration."
+          `Dynamic Client Registration failed.
+
+Registration endpoint: ${registrationEndpoint}
+Error: ${detail}
+
+Register an OAuth app in the provider's developer portal and enter the Client ID (and Client Secret if required) in the MCP server configuration.`
         );
       }
-    } else {
+    } else if (hasFullOverrides) {
       throw new Error(
         "OAuth client_id is required when using manual OAuth URL overrides.\n\nPlease provide a client_id in the MCP server configuration."
       );
+    } else {
+      throw new Error(
+        "OAuth client_id is required but the authorization server does not advertise a Dynamic Client Registration endpoint (RFC 7591).\n\nRegister an OAuth app in the provider's developer portal and enter the Client ID (and Client Secret if required) in the MCP server configuration."
+      );
     }
   }
   const state = import_node_crypto.default.randomUUID();
-  const tokenEndpoint = options?.tokenUrlOverride || authServerMetadata?.token_endpoint;
+  const tokenEndpoint = tokenUrlOverride || authServerMetadata?.token_endpoint;
   if (!tokenEndpoint) {
     throw new Error(
       "No token endpoint available. Either provide oauth_token_url in the MCP server config, or ensure the authorization server supports RFC 8414 metadata discovery."
     );
   }
-  console.log("[MCP OAuth] Using token endpoint:", tokenEndpoint);
-  if (options?.tokenUrlOverride) {
-    console.log("[MCP OAuth] (overridden from:", authServerMetadata?.token_endpoint, ")");
-  }
-  const authorizationEndpoint = options?.authorizationUrlOverride || authServerMetadata?.authorization_endpoint;
+  const authorizationEndpoint = authorizationUrlOverride || authServerMetadata?.authorization_endpoint;
   if (!authorizationEndpoint) {
     throw new Error(
       "No authorization endpoint available. Either provide oauth_authorization_url in the MCP server config, or ensure the authorization server supports RFC 8414 metadata discovery."
     );
   }
   console.log("[MCP OAuth] Using authorization endpoint:", authorizationEndpoint);
+  console.log("[MCP OAuth] Using token endpoint:", tokenEndpoint);
   const authUrl = new URL(authorizationEndpoint);
   authUrl.searchParams.set("response_type", "code");
   authUrl.searchParams.set("client_id", actualClientId);
@@ -636,16 +663,88 @@ async function startMCPOAuthFlow(wwwAuthenticateHeader, clientId, redirectUri, o
   }
   console.log("[MCP OAuth] Authorization URL:", authUrl.toString());
   return {
-    metadataUrl,
+    metadataUrl: cacheKey,
     tokenEndpoint,
     redirectUri: actualRedirectUri,
     pkceVerifier: pkce.verifier,
     clientId: actualClientId,
-    clientSecret,
+    clientSecret: resolvedClientSecret,
     state,
     authorizationUrl: authUrl.toString()
   };
 }
+async function startMCPOAuthFlow(wwwAuthenticateHeader, clientId, redirectUri, options) {
+  console.log("[MCP OAuth] Starting two-phase OAuth 2.1 flow");
+  if (options?.prefetchedAuthServerMetadata) {
+    if (!options.cacheKey) {
+      throw new Error(
+        "startMCPOAuthFlow: cacheKey is required when prefetchedAuthServerMetadata is provided (typically pass the MCP server URL)."
+      );
+    }
+    console.log(
+      "[MCP OAuth] Using prefetched AS metadata (RFC 9728 skipped):",
+      options.prefetchedAuthServerMetadata
+    );
+    return startMCPOAuthFlowWithAS({
+      authServerMetadata: options.prefetchedAuthServerMetadata,
+      cacheKey: options.cacheKey,
+      clientId,
+      redirectUri,
+      authorizationUrlOverride: options.authorizationUrlOverride,
+      tokenUrlOverride: options.tokenUrlOverride,
+      clientSecret: options.clientSecret,
+      scope: options.scope
+    });
+  }
+  const metadataUrl = parseWWWAuthenticate(wwwAuthenticateHeader) || options?.resourceMetadataUrl;
+  if (!metadataUrl) {
+    throw new Error(
+      "Could not determine OAuth resource metadata URL. The WWW-Authenticate header does not contain resource_metadata, and no pre-discovered metadata URL was provided."
+    );
+  }
+  console.log("[MCP OAuth] Resource metadata URL:", metadataUrl);
+  const resourceMetadata = await fetchResourceMetadata(metadataUrl);
+  console.log("[MCP OAuth] Resource metadata:", resourceMetadata);
+  if (!resourceMetadata.authorization_servers || resourceMetadata.authorization_servers.length === 0) {
+    throw new Error("No authorization servers found in resource metadata");
+  }
+  const authServerUrl = resourceMetadata.authorization_servers[0];
+  console.log("[MCP OAuth] Authorization server:", authServerUrl);
+  const hasFullOverrides = options?.authorizationUrlOverride && options?.tokenUrlOverride;
+  let authServerMetadata = null;
+  if (hasFullOverrides) {
+    console.log("[MCP OAuth] Skipping auth server metadata fetch \u2014 manual overrides provided:", {
+      authorization: options.authorizationUrlOverride,
+      token: options.tokenUrlOverride
+    });
+  } else {
+    try {
+      authServerMetadata = await fetchAuthorizationServerMetadata(authServerUrl);
+      console.log("[MCP OAuth] Authorization server metadata:", authServerMetadata);
+    } catch (metadataError) {
+      if (options?.authorizationUrlOverride || options?.tokenUrlOverride) {
+        console.log(
+          "[MCP OAuth] Auth server metadata fetch failed, but partial overrides available:",
+          metadataError instanceof Error ? metadataError.message : String(metadataError)
+        );
+      } else {
+        throw metadataError;
+      }
+    }
+  }
+  return startMCPOAuthFlowWithAS({
+    authServerMetadata,
+    cacheKey: metadataUrl,
+    clientId,
+    redirectUri,
+    authorizationUrlOverride: options?.authorizationUrlOverride,
+    tokenUrlOverride: options?.tokenUrlOverride,
+    clientSecret: options?.clientSecret,
+    scope: options?.scope,
+    fallbackRegistrationEndpoint: hasFullOverrides ? void 0 : `${authServerUrl}/register`,
+    resourceScopesSupported: resourceMetadata.scopes_supported
+  });
+}
 async function completeMCPOAuthFlow(context, code, state) {
   console.log("[MCP OAuth] Completing OAuth flow with authorization code");
   console.log("[MCP OAuth] Token endpoint:", context.tokenEndpoint);
@@ -705,12 +804,15 @@ function parseOAuthCallback(callbackUrl) {
 0 && (module.exports = {
   clearAuthCodeTokenCache,
   completeMCPOAuthFlow,
+  discoverAuthorizationServerFromMcpOrigin,
   discoverResourceMetadataUrl,
+  fetchAuthorizationServerMetadata,
   getAuthCodeTokenCacheStats,
   getCachedOAuth21Token,
   isOAuthRequired,
   parseOAuthCallback,
   performMCPOAuthFlow,
+  resolveMCPOAuthDiscovery,
   resolveResourceMetadataUrl,
   startMCPOAuthFlow
 });

package/dist/core/tools/mcp/oauth-mcp-transport.d.cts

@@ -65,6 +65,79 @@ declare function resolveResourceMetadataUrl(wwwAuthenticateHeader: string | null
     metadataUrl: string;
     source: 'header' | 'well-known';
 } | null>;
+/**
+ * Discover OAuth Authorization Server metadata directly at the MCP server's
+ * origin (RFC 8414 / OIDC fallback when RFC 9728 isn't implemented).
+ *
+ * Some MCP servers (e.g. Reo.Dev) skip the RFC 9728 Protected Resource Metadata
+ * layer entirely and instead serve the AS metadata document at their own
+ * origin. Claude Desktop's MCP client probes this path; we mirror that
+ * behaviour so 'paste URL → click Connect' works without manual config.
+ *
+ * Probes (in order). Note that RFC 8414 and OIDC use *different* path-construction
+ * rules for path-bearing issuers:
+ *   - RFC 8414 §3.1: insert `.well-known/oauth-authorization-server` between
+ *     the host and the issuer's path → `{origin}/.well-known/...{path}`
+ *   - OIDC Discovery 1.0 §4: append `.well-known/openid-configuration` after
+ *     the issuer's path → `{origin}{path}/.well-known/...`
+ *
+ * Probe order:
+ *   1. {origin}/.well-known/oauth-authorization-server{path}   (RFC 8414 path-aware)
+ *   2. {origin}/.well-known/oauth-authorization-server         (root)
+ *   3. {origin}{path}/.well-known/openid-configuration         (OIDC path-aware)
+ *   4. {origin}/.well-known/openid-configuration               (OIDC root)
+ *
+ * @param mcpUrl - The MCP server URL
+ * @returns Discovered AS metadata + the URL it was fetched from, or null
+ */
+declare function discoverAuthorizationServerFromMcpOrigin(mcpUrl: string): Promise<{
+    metadata: AuthorizationServerMetadata;
+    discoveredAt: string;
+} | null>;
+/**
+ * Discriminated discovery result for MCP OAuth.
+ *
+ * The MCP Authorization spec layers three RFCs:
+ *   - RFC 9728 (Protected Resource Metadata) — links resource server → AS list
+ *   - RFC 8414 (Authorization Server Metadata) — describes the AS endpoints
+ *   - RFC 7591 (Dynamic Client Registration) — register a client at runtime
+ *
+ * Real-world servers vary in what they actually implement. This type lets
+ * callers distinguish:
+ *   - 'resource-metadata': RFC 9728 worked → fetch metadata URL → derive AS
+ *   - 'authorization-server': RFC 9728 absent, but AS metadata served directly
+ *     at the MCP origin (Reo.Dev pattern) → use it directly, skip RFC 9728.
+ */
+type MCPOAuthDiscoveryResult = {
+    kind: 'resource-metadata';
+    metadataUrl: string;
+    source: 'header' | 'well-known';
+} | {
+    kind: 'authorization-server';
+    authServerMetadata: AuthorizationServerMetadata;
+    discoveredAt: string;
+};
+/**
+ * Full MCP OAuth discovery cascade — the single entry point new daemon
+ * callsites should use.
+ *
+ * Walks the cascade in order:
+ *   1. WWW-Authenticate `resource_metadata="..."` (RFC 9728 via header hint)
+ *   2. `<origin>/.well-known/oauth-protected-resource` (RFC 9728 well-known)
+ *   3. `<origin>/.well-known/oauth-authorization-server` (RFC 8414 direct)
+ *   4. `<origin>/.well-known/openid-configuration` (OIDC discovery direct)
+ *
+ * Returns the first success. Each step's failure is logged but never thrown —
+ * a clean `null` lets the caller emit a single, specific error message.
+ */
+declare function resolveMCPOAuthDiscovery(wwwAuthenticateHeader: string | null, mcpUrl: string): Promise<MCPOAuthDiscoveryResult | null>;
+/**
+ * Fetch Authorization Server Metadata (RFC 8414)
+ *
+ * Implements path-aware discovery per RFC 8414 Section 3.
+ * Falls back to OIDC discovery and naive URL construction.
+ */
+declare function fetchAuthorizationServerMetadata(authServerUrl: string): Promise<AuthorizationServerMetadata>;
 /**
  * Perform MCP OAuth 2.1 Authorization Code flow with PKCE.
  *
@@ -154,21 +227,6 @@ interface OAuthFlowContext {
     state: string;
     authorizationUrl: string;
 }
-/**
- * Start the OAuth 2.1 Authorization Code flow with PKCE
- *
- * This is the first phase of a two-phase OAuth flow for remote daemon scenarios.
- * Returns the authorization URL to open in browser and context needed to complete
- * the flow later.
- *
- * @param wwwAuthenticateHeader - The WWW-Authenticate header from 401 response
- * @param clientId - OAuth client ID (optional, will use DCR if not provided)
- * @param redirectUri - Custom redirect URI (optional, defaults to a placeholder)
- * @param options - Additional options
- * @param options.authorizationUrlOverride - Override the auto-discovered authorization endpoint URL
- * @param options.tokenUrlOverride - Override the auto-discovered token endpoint URL
- * @returns Authorization URL and flow context
- */
 declare function startMCPOAuthFlow(wwwAuthenticateHeader: string, clientId?: string, redirectUri?: string, options?: {
     authorizationUrlOverride?: string;
     tokenUrlOverride?: string;
@@ -176,6 +234,24 @@ declare function startMCPOAuthFlow(wwwAuthenticateHeader: string, clientId?: str
     scope?: string;
     /** Pre-discovered resource metadata URL (used when WWW-Authenticate lacks resource_metadata) */
     resourceMetadataUrl?: string;
+    /**
+     * Pre-discovered Authorization Server metadata. Used when the MCP server
+     * doesn't implement RFC 9728 but does serve RFC 8414 / OIDC metadata
+     * directly at its own origin (e.g. Reo.Dev). When provided, both
+     * `fetchResourceMetadata` and `fetchAuthorizationServerMetadata` are
+     * skipped — `prefetchedAuthServerMetadata` is used as-is.
+     *
+     * The `cacheKey` option (or the MCP URL via the caller's redirect plumbing)
+     * is used as the token cache key in place of an RFC 9728 metadata URL.
+     */
+    prefetchedAuthServerMetadata?: AuthorizationServerMetadata;
+    /**
+     * Token cache key. When `prefetchedAuthServerMetadata` is provided there's
+     * no real RFC 9728 metadata URL to use as the key, so the caller passes a
+     * stable string (typically the MCP URL itself). `getCachedOAuth21Token`
+     * matches by URL origin, so any value sharing the MCP URL's origin works.
+     */
+    cacheKey?: string;
 }): Promise<OAuthFlowContext>;
 /**
  * Complete the OAuth 2.1 flow with authorization code
@@ -200,4 +276,4 @@ declare function parseOAuthCallback(callbackUrl: string): {
     state: string;
 };
 
-export { type AuthorizationServerMetadata, type DynamicClientRegistrationResponse, type OAuthFlowContext, type OAuthMetadata, OAuthTokenResponse, clearAuthCodeTokenCache, completeMCPOAuthFlow, discoverResourceMetadataUrl, getAuthCodeTokenCacheStats, getCachedOAuth21Token, isOAuthRequired, parseOAuthCallback, performMCPOAuthFlow, resolveResourceMetadataUrl, startMCPOAuthFlow };
+export { type AuthorizationServerMetadata, type DynamicClientRegistrationResponse, type MCPOAuthDiscoveryResult, type OAuthFlowContext, type OAuthMetadata, OAuthTokenResponse, clearAuthCodeTokenCache, completeMCPOAuthFlow, discoverAuthorizationServerFromMcpOrigin, discoverResourceMetadataUrl, fetchAuthorizationServerMetadata, getAuthCodeTokenCacheStats, getCachedOAuth21Token, isOAuthRequired, parseOAuthCallback, performMCPOAuthFlow, resolveMCPOAuthDiscovery, resolveResourceMetadataUrl, startMCPOAuthFlow };

package/dist/core/tools/mcp/oauth-mcp-transport.d.ts

@@ -65,6 +65,79 @@ declare function resolveResourceMetadataUrl(wwwAuthenticateHeader: string | null
     metadataUrl: string;
     source: 'header' | 'well-known';
 } | null>;
+/**
+ * Discover OAuth Authorization Server metadata directly at the MCP server's
+ * origin (RFC 8414 / OIDC fallback when RFC 9728 isn't implemented).
+ *
+ * Some MCP servers (e.g. Reo.Dev) skip the RFC 9728 Protected Resource Metadata
+ * layer entirely and instead serve the AS metadata document at their own
+ * origin. Claude Desktop's MCP client probes this path; we mirror that
+ * behaviour so 'paste URL → click Connect' works without manual config.
+ *
+ * Probes (in order). Note that RFC 8414 and OIDC use *different* path-construction
+ * rules for path-bearing issuers:
+ *   - RFC 8414 §3.1: insert `.well-known/oauth-authorization-server` between
+ *     the host and the issuer's path → `{origin}/.well-known/...{path}`
+ *   - OIDC Discovery 1.0 §4: append `.well-known/openid-configuration` after
+ *     the issuer's path → `{origin}{path}/.well-known/...`
+ *
+ * Probe order:
+ *   1. {origin}/.well-known/oauth-authorization-server{path}   (RFC 8414 path-aware)
+ *   2. {origin}/.well-known/oauth-authorization-server         (root)
+ *   3. {origin}{path}/.well-known/openid-configuration         (OIDC path-aware)
+ *   4. {origin}/.well-known/openid-configuration               (OIDC root)
+ *
+ * @param mcpUrl - The MCP server URL
+ * @returns Discovered AS metadata + the URL it was fetched from, or null
+ */
+declare function discoverAuthorizationServerFromMcpOrigin(mcpUrl: string): Promise<{
+    metadata: AuthorizationServerMetadata;
+    discoveredAt: string;
+} | null>;
+/**
+ * Discriminated discovery result for MCP OAuth.
+ *
+ * The MCP Authorization spec layers three RFCs:
+ *   - RFC 9728 (Protected Resource Metadata) — links resource server → AS list
+ *   - RFC 8414 (Authorization Server Metadata) — describes the AS endpoints
+ *   - RFC 7591 (Dynamic Client Registration) — register a client at runtime
+ *
+ * Real-world servers vary in what they actually implement. This type lets
+ * callers distinguish:
+ *   - 'resource-metadata': RFC 9728 worked → fetch metadata URL → derive AS
+ *   - 'authorization-server': RFC 9728 absent, but AS metadata served directly
+ *     at the MCP origin (Reo.Dev pattern) → use it directly, skip RFC 9728.
+ */
+type MCPOAuthDiscoveryResult = {
+    kind: 'resource-metadata';
+    metadataUrl: string;
+    source: 'header' | 'well-known';
+} | {
+    kind: 'authorization-server';
+    authServerMetadata: AuthorizationServerMetadata;
+    discoveredAt: string;
+};
+/**
+ * Full MCP OAuth discovery cascade — the single entry point new daemon
+ * callsites should use.
+ *
+ * Walks the cascade in order:
+ *   1. WWW-Authenticate `resource_metadata="..."` (RFC 9728 via header hint)
+ *   2. `<origin>/.well-known/oauth-protected-resource` (RFC 9728 well-known)
+ *   3. `<origin>/.well-known/oauth-authorization-server` (RFC 8414 direct)
+ *   4. `<origin>/.well-known/openid-configuration` (OIDC discovery direct)
+ *
+ * Returns the first success. Each step's failure is logged but never thrown —
+ * a clean `null` lets the caller emit a single, specific error message.
+ */
+declare function resolveMCPOAuthDiscovery(wwwAuthenticateHeader: string | null, mcpUrl: string): Promise<MCPOAuthDiscoveryResult | null>;
+/**
+ * Fetch Authorization Server Metadata (RFC 8414)
+ *
+ * Implements path-aware discovery per RFC 8414 Section 3.
+ * Falls back to OIDC discovery and naive URL construction.
+ */
+declare function fetchAuthorizationServerMetadata(authServerUrl: string): Promise<AuthorizationServerMetadata>;
 /**
  * Perform MCP OAuth 2.1 Authorization Code flow with PKCE.
  *
@@ -154,21 +227,6 @@ interface OAuthFlowContext {
     state: string;
     authorizationUrl: string;
 }
-/**
- * Start the OAuth 2.1 Authorization Code flow with PKCE
- *
- * This is the first phase of a two-phase OAuth flow for remote daemon scenarios.
- * Returns the authorization URL to open in browser and context needed to complete
- * the flow later.
- *
- * @param wwwAuthenticateHeader - The WWW-Authenticate header from 401 response
- * @param clientId - OAuth client ID (optional, will use DCR if not provided)
- * @param redirectUri - Custom redirect URI (optional, defaults to a placeholder)
- * @param options - Additional options
- * @param options.authorizationUrlOverride - Override the auto-discovered authorization endpoint URL
- * @param options.tokenUrlOverride - Override the auto-discovered token endpoint URL
- * @returns Authorization URL and flow context
- */
 declare function startMCPOAuthFlow(wwwAuthenticateHeader: string, clientId?: string, redirectUri?: string, options?: {
     authorizationUrlOverride?: string;
     tokenUrlOverride?: string;
@@ -176,6 +234,24 @@ declare function startMCPOAuthFlow(wwwAuthenticateHeader: string, clientId?: str
     scope?: string;
     /** Pre-discovered resource metadata URL (used when WWW-Authenticate lacks resource_metadata) */
     resourceMetadataUrl?: string;
+    /**
+     * Pre-discovered Authorization Server metadata. Used when the MCP server
+     * doesn't implement RFC 9728 but does serve RFC 8414 / OIDC metadata
+     * directly at its own origin (e.g. Reo.Dev). When provided, both
+     * `fetchResourceMetadata` and `fetchAuthorizationServerMetadata` are
+     * skipped — `prefetchedAuthServerMetadata` is used as-is.
+     *
+     * The `cacheKey` option (or the MCP URL via the caller's redirect plumbing)
+     * is used as the token cache key in place of an RFC 9728 metadata URL.
+     */
+    prefetchedAuthServerMetadata?: AuthorizationServerMetadata;
+    /**
+     * Token cache key. When `prefetchedAuthServerMetadata` is provided there's
+     * no real RFC 9728 metadata URL to use as the key, so the caller passes a
+     * stable string (typically the MCP URL itself). `getCachedOAuth21Token`
+     * matches by URL origin, so any value sharing the MCP URL's origin works.
+     */
+    cacheKey?: string;
 }): Promise<OAuthFlowContext>;
 /**
  * Complete the OAuth 2.1 flow with authorization code
@@ -200,4 +276,4 @@ declare function parseOAuthCallback(callbackUrl: string): {
     state: string;
 };
 
-export { type AuthorizationServerMetadata, type DynamicClientRegistrationResponse, type OAuthFlowContext, type OAuthMetadata, OAuthTokenResponse, clearAuthCodeTokenCache, completeMCPOAuthFlow, discoverResourceMetadataUrl, getAuthCodeTokenCacheStats, getCachedOAuth21Token, isOAuthRequired, parseOAuthCallback, performMCPOAuthFlow, resolveResourceMetadataUrl, startMCPOAuthFlow };
+export { type AuthorizationServerMetadata, type DynamicClientRegistrationResponse, type MCPOAuthDiscoveryResult, type OAuthFlowContext, type OAuthMetadata, OAuthTokenResponse, clearAuthCodeTokenCache, completeMCPOAuthFlow, discoverAuthorizationServerFromMcpOrigin, discoverResourceMetadataUrl, fetchAuthorizationServerMetadata, getAuthCodeTokenCacheStats, getCachedOAuth21Token, isOAuthRequired, parseOAuthCallback, performMCPOAuthFlow, resolveMCPOAuthDiscovery, resolveResourceMetadataUrl, startMCPOAuthFlow };