/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 *
 * @param {ProviderDefinition} def
 * @returns {(appOptions: ProviderAppOptions) => ResolvedProvider}
 *
 * @typedef {Object} ProviderDefinition
 * @property {string} id                        default provider key (`'google'`)
 * @property {'oidc'|'oauth2'} kind
 * @property {string} [authorizationEndpoint]
 * @property {string} [tokenEndpoint]
 * @property {string} [userinfoEndpoint]
 * @property {string} [jwksUri]
 * @property {string} [revocationEndpoint]
 * @property {string | ((claimed: string) => boolean)} [issuer]   OIDC issuer — exact string, or a validator (multi-tenant)
 * @property {string} [expectedIssuer]          overrides `issuer` for the RFC 9207 `iss` param
 * @property {boolean} [requireIssParam]        require the RFC 9207 `iss` response param (a provider known to send it)
 * @property {string} [emailEndpoint]           secondary email fetch (github)
 * @property {boolean} [discover]               resolve endpoints from `issuer` discovery
 * @property {boolean} [supportsPkce]           default true
 * @property {string[]} [defaultScopes]
 * @property {boolean} [autoOpenidScope]        prepend `openid` for OIDC (default true; Apple sets false)
 * @property {string[]} [idTokenAlgs]
 * @property {import('@exortek/jwks').RemoteJWKSOptions} [jwksOptions]  forwarded to the JWKS resolver
 * @property {'post'|'basic'} [clientAuth]                   client authentication at the token endpoint (default `post`)
 * @property {Record<string,string>} [authorizationParams]  extra static auth-request params
 * @property {Record<string,string>} [tokenHeaders]         extra headers on the token/refresh/revoke calls
 * @property {Record<string,string>} [userinfoHeaders]      extra headers on the userinfo/email calls (falls back to tokenHeaders)
 * @property {(raw: Record<string, unknown>, claims?: Record<string, unknown>) => NormalizedUserFields} mapUser
 *
 * @typedef {Object} ProviderAppOptions
 * @property {string} clientId
 * @property {string} [clientSecret]
 * @property {string[]} [scope]
 * @property {string} [redirectUri]
 * @property {string} [id]
 *
 * @typedef {Object} NormalizedUserFields
 * @property {string} sub
 * @property {string} [email]
 * @property {boolean} [emailVerified]
 * @property {string} [name]
 * @property {string} [picture]
 */
export function defineProvider(def: ProviderDefinition): (appOptions: ProviderAppOptions) => ResolvedProvider;
/**
 * @typedef {Object} ResolvedEndpoints
 * @property {string} authorizationEndpoint
 * @property {string} tokenEndpoint
 * @property {string} [userinfoEndpoint]
 * @property {string} [jwksUri]
 * @property {string} [revocationEndpoint]
 * @property {string} [issuer]
 * @property {boolean} [issParameterSupported]   the AS returns the RFC 9207 `iss` on the authz response
 */
/**
 * Resolve (and cache on the provider) the endpoint set — from discovery
 * when `def.discover`, otherwise from the static preset. Explicit preset
 * endpoints always win over discovered ones.
 *
 * @param {ResolvedProvider} provider
 * @returns {Promise<ResolvedEndpoints>}
 */
export function resolveEndpoints(provider: ResolvedProvider): Promise<ResolvedEndpoints>;
/**
 * Build the authorization-request URL and the flow session.
 *
 * @param {ResolvedProvider} provider
 * @param {{ redirectUri: string, scope?: string[], sessionBinding?: string, params?: Record<string,string>, jwksOptions?: object }} opts
 * @returns {Promise<{ url: string, session: import('../internal/session.js').FlowSession, warnings: Warning[] }>}
 */
export function buildAuthorization(provider: ResolvedProvider, opts: {
    redirectUri: string;
    scope?: string[];
    sessionBinding?: string;
    params?: Record<string, string>;
    jwksOptions?: object;
}): Promise<{
    url: string;
    session: import("../internal/session.js").FlowSession;
    warnings: Warning[];
}>;
/**
 * Validate the callback, exchange the code, verify the id_token (OIDC),
 * resolve and normalize the user.
 *
 * @param {ResolvedProvider} provider
 * @param {{
 *   redirectUri: string,
 *   query: Record<string, unknown>,
 *   session: import('../internal/session.js').FlowSession,
 *   sessionBinding?: string,
 *   clockTolerance?: string|number,
 * }} opts
 * @returns {Promise<{ tokens: Record<string, unknown>, user: NormalizedUser, warnings: Warning[] }>}
 */
export function handleCallback(provider: ResolvedProvider, opts: {
    redirectUri: string;
    query: Record<string, unknown>;
    session: import("../internal/session.js").FlowSession;
    sessionBinding?: string;
    clockTolerance?: string | number;
}): Promise<{
    tokens: Record<string, unknown>;
    user: NormalizedUser;
    warnings: Warning[];
}>;
/**
 * Apply client authentication to a set of token-endpoint params. The
 * default is `client_secret_post` (credentials in the body); a provider
 * can declare `clientAuth: 'basic'` to send HTTP Basic instead (some
 * providers, e.g. X/Twitter, require it). `client_id` always rides in
 * the body — providers accept it there regardless of the auth style.
 *
 * @param {ResolvedProvider} provider
 * @param {Record<string,string>} params
 * @returns {{ params: Record<string,string>, headers: Record<string,string> }}
 */
export function applyClientAuth(provider: ResolvedProvider, params: Record<string, string>): {
    params: Record<string, string>;
    headers: Record<string, string>;
};
/**
 * Non-fatal, degraded-but-not-blocked conditions. Surfaced in
 * `warnings[]` so the caller can react without the flow hard-failing.
 */
export const WarningCode: Readonly<{
    PKCE_UNSUPPORTED: "PKCE_UNSUPPORTED";
    SCOPE_NARROWED: "SCOPE_NARROWED";
    EMAIL_UNVERIFIED: "EMAIL_UNVERIFIED";
}>;
/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 */
export type ProviderDefinition = {
    /**
     * default provider key (`'google'`)
     */
    id: string;
    kind: "oidc" | "oauth2";
    authorizationEndpoint?: string | undefined;
    tokenEndpoint?: string | undefined;
    userinfoEndpoint?: string | undefined;
    jwksUri?: string | undefined;
    revocationEndpoint?: string | undefined;
    /**
     * OIDC issuer — exact string, or a validator (multi-tenant)
     */
    issuer?: string | ((claimed: string) => boolean) | undefined;
    /**
     * overrides `issuer` for the RFC 9207 `iss` param
     */
    expectedIssuer?: string | undefined;
    /**
     * require the RFC 9207 `iss` response param (a provider known to send it)
     */
    requireIssParam?: boolean | undefined;
    /**
     * secondary email fetch (github)
     */
    emailEndpoint?: string | undefined;
    /**
     * resolve endpoints from `issuer` discovery
     */
    discover?: boolean | undefined;
    /**
     * default true
     */
    supportsPkce?: boolean | undefined;
    defaultScopes?: string[] | undefined;
    /**
     * prepend `openid` for OIDC (default true; Apple sets false)
     */
    autoOpenidScope?: boolean | undefined;
    idTokenAlgs?: string[] | undefined;
    /**
     * forwarded to the JWKS resolver
     */
    jwksOptions?: import("@exortek/jwks").RemoteJWKSOptions;
    /**
     * client authentication at the token endpoint (default `post`)
     */
    clientAuth?: "post" | "basic" | undefined;
    /**
     * extra static auth-request params
     */
    authorizationParams?: Record<string, string> | undefined;
    /**
     * extra headers on the token/refresh/revoke calls
     */
    tokenHeaders?: Record<string, string> | undefined;
    /**
     * extra headers on the userinfo/email calls (falls back to tokenHeaders)
     */
    userinfoHeaders?: Record<string, string> | undefined;
    mapUser: (raw: Record<string, unknown>, claims?: Record<string, unknown>) => NormalizedUserFields;
};
/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 */
export type ProviderAppOptions = {
    clientId: string;
    clientSecret?: string | undefined;
    scope?: string[] | undefined;
    redirectUri?: string | undefined;
    id?: string | undefined;
};
/**
 * Define a provider. Returns a factory that a consumer calls with their
 * per-app credentials; the result is passed to `createOAuth`.
 */
export type NormalizedUserFields = {
    sub: string;
    email?: string | undefined;
    emailVerified?: boolean | undefined;
    name?: string | undefined;
    picture?: string | undefined;
};
export type ResolvedEndpoints = {
    authorizationEndpoint: string;
    tokenEndpoint: string;
    userinfoEndpoint?: string | undefined;
    jwksUri?: string | undefined;
    revocationEndpoint?: string | undefined;
    issuer?: string | undefined;
    /**
     * the AS returns the RFC 9207 `iss` on the authz response
     */
    issParameterSupported?: boolean | undefined;
};
export type Warning = {
    code: string;
    message: string;
};
export type NormalizedUser = NormalizedUserFields & {
    provider: string;
    raw: Record<string, unknown>;
};
export type ResolvedProvider = ReturnType<ReturnType<typeof defineProvider>>;