import type { FetchImpl } from "@oh-my-pi/pi-ai/types";
export interface OAuthEndpoints {
    authorizationUrl: string;
    tokenUrl: string;
    /** Authorization-server issuer URL used for metadata discovery. */
    issuerUrl?: string;
    clientId?: string;
    /** Dynamic client registration endpoint advertised by the authorization server. */
    registrationUrl?: string;
    scopes?: string;
    resource?: string;
}
export interface AuthDetectionResult {
    requiresAuth: boolean;
    authType?: "oauth" | "apikey" | "unknown";
    oauth?: OAuthEndpoints;
    authServerUrl?: string;
    resourceMetadataUrl?: string;
    /**
     * OAuth scopes advertised by the challenge (RFC 6750 `scope=` on
     * `WWW-Authenticate`) or by protected-resource metadata. Passed through
     * `discoverOAuthEndpoints` as `protectedScopes` so the eventual
     * authorization request retains the resource/challenge requirement rather
     * than adopting the authorization server's supported-scope catalogue.
     */
    scopes?: string;
    message?: string;
}
export declare function extractMcpAuthServerUrl(error: Error, serverUrl?: string): string | undefined;
/**
 * Pull the `scope`/`scopes` parameter out of a `WWW-Authenticate` challenge
 * embedded in the error message. RFC 6750 lets servers advertise the missing
 * scopes when they reject a bearer token with `insufficient_scope`, and RFC
 * 8414-adjacent MCP gateways sometimes list the required scopes there rather
 * than in `scopes_supported`. Returns the raw space-separated value, or
 * `undefined` when the challenge does not carry one.
 */
export declare function extractOAuthChallengeScopes(error: Error): string | undefined;
/**
 * Extract OAuth endpoints from error response.
 * Looks for WWW-Authenticate header format or JSON error bodies.
 */
export declare function extractOAuthEndpoints(error: Error): OAuthEndpoints | null;
/**
 * Analyze an error to determine authentication requirements.
 * Returns structured info about what auth is needed.
 */
export declare function analyzeAuthError(error: Error, serverUrl?: string): AuthDetectionResult;
/**
 * RFC 9728: insert `/.well-known/oauth-protected-resource` between the origin
 * and the resource path. Origin-root protected-resource metadata on API
 * gateways often names a shared login hub, not the issuer that minted the
 * client's `client_id`.
 */
export declare function rfc9728ProtectedResourceMetadataUrl(serverUrl: string | undefined): string | undefined;
/**
 * Fetch the RFC 9728 protected-resource metadata document at
 * {@link resourceMetadataUrl} and return any scopes it advertises. Used by
 * `/mcp add` / `/mcp reauth` on the JSON-error-body path, where the caller
 * already holds usable OAuth endpoints but the required scopes live only in
 * the advertised protected-resource metadata — a case `discoverOAuthEndpoints`
 * normally handles but that path is skipped when the body carried endpoints.
 * Returns `undefined` on any error or when no scopes are advertised.
 */
export declare function fetchResourceMetadataScopes(resourceMetadataUrl: string, opts?: {
    fetch?: FetchImpl;
    signal?: AbortSignal;
}): Promise<string | undefined>;
/** An advertised authorization server whose metadata failed RFC 8414 §3.3 issuer validation. */
export interface OAuthIssuerRejection {
    /** Server URL listed in `authorization_servers`. */
    authServer: string;
    /** Protected-resource metadata URL that listed it. */
    advertisedBy: string;
    /** `issuer` reported by the server's metadata. */
    issuer: string;
}
/**
 * Thrown by {@link discoverOAuthEndpoints} when the resource's advertised
 * authorization servers yielded no usable metadata and at least one was
 * rejected for an issuer mismatch. Names the misconfigured server so
 * `/mcp add` / `/mcp reauth` can report it instead of a generic failure.
 */
export declare class OAuthIssuerMismatchError extends Error {
    readonly rejections: OAuthIssuerRejection[];
    constructor(rejections: OAuthIssuerRejection[]);
}
/**
 * Try to discover OAuth endpoints by querying the server's well-known endpoints.
 * This is a fallback when error responses don't include OAuth metadata.
 *
 * RFC 9728 §7.6: once protected-resource metadata for this resource lists
 * `authorization_servers`, only those servers are probed. If none of them
 * yields valid metadata, discovery does not fall back to origin-root
 * documents that describe a different resource or issuer.
 *
 * @returns endpoints, or null when no usable metadata was found.
 * @throws {OAuthIssuerMismatchError} when no endpoints were found and an
 *   advertised authorization server failed issuer validation.
 */
export declare function discoverOAuthEndpoints(serverUrl: string, authServerUrl?: string, resourceMetadataUrl?: string, opts?: {
    fetch?: FetchImpl;
    protectedScopes?: string;
    signal?: AbortSignal;
}): Promise<OAuthEndpoints | null>;
/** Build ordered metadata URL candidates for OAuth and OIDC discovery. */
export declare function buildWellKnownUrls(wellKnownPath: string, baseUrl: string, issuerCandidate: boolean): URL[];