/**
 * Minimal OAuth 2.0 helper for authorization-code (with PKCE) and refresh flows.
 *
 * This is a transport-level skeleton: it builds the authorization URL, exchanges
 * an authorization code for tokens, and refreshes an access token. It deals only
 * in the wire shapes of RFC 6749 (the OAuth 2.0 framework) plus RFC 7636 (PKCE);
 * the surrounding browser/device redirect choreography lives in the caller.
 *
 * Network access is via the global `fetch` (Node 20+); failures are normalized
 * into the gateway's {@link GatewayError} so callers can branch on `.kind`.
 */
import type { ProviderId } from "../contract";
import type { PkcePair } from "./pkce";
/**
 * Tokens returned by a token endpoint, normalized to the gateway's vocabulary.
 * `expiresAt` is an absolute epoch-millisecond deadline (derived from the
 * server's relative `expires_in`), which is far easier to act on than a TTL.
 */
export interface OAuthTokens {
    readonly accessToken: string;
    readonly refreshToken?: string;
    readonly expiresAt?: number;
}
/**
 * Static endpoint + client configuration for a provider's OAuth flow. Held in
 * the {@link OAUTH_PROVIDERS} table and threaded through every helper.
 */
export interface OAuthConfig {
    /** Which provider this configuration authorizes against. */
    readonly provider: ProviderId;
    /** Authorization endpoint the user-agent is sent to (RFC 6749 §3.1). */
    readonly authorizeUrl: string;
    /** Token endpoint for code exchange and refresh (RFC 6749 §3.2). */
    readonly tokenUrl: string;
    /** Public client identifier registered with the provider. */
    readonly clientId: string;
    /** Where the provider redirects back with the authorization code. */
    readonly redirectUri: string;
    /** Space-joined scopes requested for the grant. */
    readonly scopes: readonly string[];
}
/** Inputs needed to assemble an authorization URL. */
export interface AuthUrlInputs {
    /** Opaque CSRF-binding value echoed back on the redirect (RFC 6749 §10.12). */
    readonly state: string;
    /** PKCE pair whose `challenge` is attached to the request (RFC 7636 §4.3). */
    readonly pkce: PkcePair;
}
/**
 * Provider-specific OAuth configuration table. Endpoints/client IDs are
 * placeholders to be supplied per deployment; the shape is what matters for the
 * flow. Only providers that actually expose an OAuth login appear here.
 */
export declare const OAUTH_PROVIDERS: Partial<Record<ProviderId, OAuthConfig>>;
/** Look up a provider's OAuth config, or `undefined` if it has no OAuth flow. */
export declare function oauthConfigFor(provider: ProviderId): OAuthConfig | undefined;
/**
 * Build the authorization-request URL (RFC 6749 §4.1.1) with PKCE parameters
 * (RFC 7636 §4.3). The returned URL is what the user-agent should be sent to.
 */
export declare function buildAuthUrl(cfg: OAuthConfig, inputs: AuthUrlInputs): string;
/**
 * Exchange an authorization `code` for tokens (RFC 6749 §4.1.3), supplying the
 * PKCE `verifier` so the server can re-derive and match the challenge
 * (RFC 7636 §4.5).
 */
export declare function exchangeCode(cfg: OAuthConfig, code: string, verifier: string): Promise<OAuthTokens>;
/**
 * Trade a `refresh` token for a fresh access token (RFC 6749 §6). Providers may
 * or may not rotate the refresh token; the normalized result reflects whatever
 * the server returned.
 */
export declare function refreshToken(cfg: OAuthConfig, refresh: string): Promise<OAuthTokens>;
