Function discoverMetadataWithFallback

src/client/auth.ts:828–856

* Generic function for discovering OAuth metadata with fallback support

(
    serverUrl: string | URL,
    wellKnownType: 'oauth-authorization-server' | 'oauth-protected-resource',
    fetchFn: FetchLike,
    opts?: { protocolVersion?: string; metadataUrl?: string | URL; metadataServerUrl?: string | URL }
)

 * Generic function for discovering OAuth metadata with fallback support
 */
async function discoverMetadataWithFallback(
    serverUrl: string | URL,
    wellKnownType: 'oauth-authorization-server' | 'oauth-protected-resource',
    fetchFn: FetchLike,
    opts?: { protocolVersion?: string; metadataUrl?: string | URL; metadataServerUrl?: string | URL }
): Promise<Response | undefined> {
    const issuer = new URL(serverUrl);
    const protocolVersion = opts?.protocolVersion ?? LATEST_PROTOCOL_VERSION;

    let url: URL;
    if (opts?.metadataUrl) {
        url = new URL(opts.metadataUrl);
    } else {
        // Try path-aware discovery first
        const wellKnownPath = buildWellKnownPath(wellKnownType, issuer.pathname);
        url = new URL(wellKnownPath, opts?.metadataServerUrl ?? issuer);
        url.search = issuer.search;
    }

    let response = await tryMetadataDiscovery(url, protocolVersion, fetchFn);

    // If path-aware discovery fails with 404 and we're not already at root, try fallback to root discovery
    if (!opts?.metadataUrl && shouldAttemptFallback(response, issuer.pathname)) {
        const rootUrl = new URL(`/.well-known/${wellKnownType}`, issuer);
        response = await tryMetadataDiscovery(rootUrl, protocolVersion, fetchFn);
    }

    return response;
}

/**
 * Looks up RFC 8414 OAuth 2.0 Authorization Server Metadata.