/**
 * @module
 *
 * Implements the OpenID Connect Authorization Code flow, extending the base
 * OAuth 2.0 Authorization Code grant with OIDC-specific request parameters,
 * ID token enforcement, UserInfo support, and a discovery document.
 *
 * @see https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
 */
import { OAuth2FlowTokenResponse, OAuth2GenerateAccessTokenFromRefreshTokenFunction, OAuth2GenerateAccessTokenFunction, OAuth2GetClientFunction } from "../grants/flow.js";
import { AbstractAuthorizationCodeFlow, AuthorizationCodeAccessTokenResult, AuthorizationCodeEndpointContext, AuthorizationCodeEndpointRequest, AuthorizationCodeEndpointResponse, AuthorizationCodeFlowOptions, AuthorizationCodeGrantContext, AuthorizationCodeInitiationResponse, AuthorizationCodeModel, AuthorizationCodeProcessResponse, AuthorizationCodeReqData, GenerateAuthorizationCodeFunction, GetUserForAuthenticationFunction } from "../grants/authorization_code.js";
import { OIDCFlow, OIDCFlowExtendedOptions, OIDCUserInfo } from "./types.js";
/**
 * OIDC-specific authentication request parameters that extend the base OAuth 2.0
 * authorization request. These correspond to the additional query parameters
 * defined by the OpenID Connect Core specification.
 *
 * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
 */
export interface OIDCAuthenticationRequestParams {
    /**
     * The `nonce` parameter is a string value used to associate a client session with an ID token,
     * and to mitigate replay attacks. It is included in the authorization request and should be
     * returned in the ID token.
     */
    nonce?: string;
    /**
     * The `display` parameter specifies how the authorization server should display the
     * authentication and consent UI:
     * - `page`: Full-page view (default).
     * - `popup`: Popup window.
     * - `touch`: Optimized for touch devices.
     * - `wap`: Optimized for feature phones.
     */
    display?: "page" | "popup" | "touch" | "wap";
    /**
     * The `prompt` parameter controls whether the authorization server prompts the user
     * for re-authentication and/or consent:
     * - `none`: Must not display any UI; fails if user is not already authenticated.
     * - `login`: Prompt the user to re-authenticate.
     * - `consent`: Prompt the user for consent before issuing tokens.
     * - `select_account`: Prompt the user to select an account.
     *
     * Multiple values may be combined (e.g. `["login", "consent"]`).
     */
    prompt?: ("none" | "login" | "consent" | "select_account")[];
    /**
     * The `max_age` parameter specifies the maximum age in seconds of the user's authentication.
     * If the user's last authentication is older than this value, the server should prompt
     * re-authentication.
     */
    maxAge?: number;
    /**
     * The `ui_locales` parameter specifies the client's preferred languages and scripts
     * for the authorization server UI, as a list of BCP47 language tags
     * (e.g. `["en-US", "fr"]`).
     */
    uiLocales?: string[];
    /**
     * The `id_token_hint` parameter passes an existing ID token as a hint to the authorization
     * server about the user's current authentication state, potentially skipping re-authentication.
     */
    idTokenHint?: string;
    /**
     * The `login_hint` parameter provides a hint to the authorization server about the user's
     * identifier (e.g. email address or username) to pre-fill login forms.
     */
    loginHint?: string;
    /**
     * The `acr_values` parameter specifies desired Authentication Class Reference values,
     * indicating the authentication methods or levels of assurance the client requires.
     */
    acrValues?: string[];
}
/**
 * Raw OIDC authorization endpoint request parameters, combining the base OAuth 2.0
 * authorization endpoint request with OIDC-specific parameters.
 */
export interface OIDCAuthorizationCodeEndpointRequest extends AuthorizationCodeEndpointRequest, OIDCAuthenticationRequestParams {
}
/**
 * Validation context for the OpenID Connect authorization code flow,
 * passed to `getUserForAuthentication()` and `generateAuthorizationCode()`.
 *
 * Extends the base authorization code endpoint context with OIDC-specific parameters.
 *
 * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint
 */
export interface OIDCAuthorizationCodeEndpointContext extends AuthorizationCodeEndpointContext, OIDCAuthenticationRequestParams {
}
/**
 * The result of `initiateAuthorization()` for the OIDC Authorization Code flow.
 * On success, contains the validated {@link OIDCAuthorizationCodeEndpointContext}.
 */
export type OIDCAuthorizationCodeInitiationResponse = AuthorizationCodeInitiationResponse<OIDCAuthorizationCodeEndpointContext>;
/**
 * The result of `processAuthorization()` for the OIDC Authorization Code flow.
 * A discriminated union of all possible outcomes after the user submits credentials.
 */
export type OIDCAuthorizationCodeProcessResponse = AuthorizationCodeProcessResponse<OIDCAuthorizationCodeEndpointContext>;
/**
 * The union of all possible outcomes from `handleAuthorizationEndpoint()` for the
 * OIDC Authorization Code flow.
 */
export type OIDCAuthorizationCodeEndpointResponse = AuthorizationCodeEndpointResponse<OIDCAuthorizationCodeEndpointContext>;
/**
 * The access token result shape for the OIDC Authorization Code flow.
 * Extends the base result to make `idToken` required, as the OpenID Connect
 * specification requires an ID token in the token response.
 *
 * @see https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint
 */
export interface OIDCAuthorizationCodeAccessTokenResult extends AuthorizationCodeAccessTokenResult {
    /**
     * The ID token issued by the authorization server for this authentication.
     * Required for the OIDC Authorization Code flow token response.
     *
     * @see https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint
     */
    idToken: string;
}
/**
 * Model interface for the OIDC Authorization Code flow.
 *
 * Extends {@link AuthorizationCodeModel} to use OIDC-specific context and request types,
 * and adds an optional `getUserInfo()` method for the UserInfo endpoint.
 *
 * @template AuthReqData - The shape of user-submitted data at the authorization endpoint.
 */
export interface OIDCAuthorizationCodeModel<AuthReqData extends AuthorizationCodeReqData = AuthorizationCodeReqData> extends AuthorizationCodeModel<AuthReqData> {
    /**
     * Retrieves and validates the client for an OIDC authorization endpoint request.
     * Should verify `clientId`, `redirectUri`, and any requested scopes.
     */
    getClientForAuthentication: OAuth2GetClientFunction<OIDCAuthorizationCodeEndpointRequest>;
    /**
     * Generates an access token (and required ID token) for the authenticated grant context.
     * The returned result MUST include an `idToken` for OIDC compliance.
     */
    generateAccessToken: OAuth2GenerateAccessTokenFunction<AuthorizationCodeGrantContext, OIDCAuthorizationCodeAccessTokenResult>;
    /**
     * Generates a new access token from a refresh token.
     * Optional - only implement if the flow supports refresh token grants.
     * The ID token is optional in refresh token responses per the OIDC specification.
     */
    generateAccessTokenFromRefreshToken?: OAuth2GenerateAccessTokenFromRefreshTokenFunction<AuthorizationCodeAccessTokenResult>;
    /**
     * Authenticates the end-user from the submitted OIDC authorization request data.
     * Receives the full OIDC context including `nonce`, `prompt`, `max_age`, etc.
     */
    getUserForAuthentication: GetUserForAuthenticationFunction<OIDCAuthorizationCodeEndpointContext, AuthReqData>;
    /**
     * Generates (or denies) an authorization code for the authenticated user.
     * Receives the full OIDC context so the code can be associated with OIDC parameters
     * (e.g. `nonce`) for later inclusion in the ID token.
     */
    generateAuthorizationCode: GenerateAuthorizationCodeFunction<OIDCAuthorizationCodeEndpointContext>;
    /**
     * Retrieves the user information associated with the given access token.
     * Implement to support the UserInfo endpoint in the OpenID Connect flow.
     *
     * @param accessToken - The access token for which to retrieve user information.
     * @returns The UserInfo claims, or `undefined` if not supported.
     *
     * @see https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
     */
    getUserInfo?: (accessToken: string) => Promise<OIDCUserInfo | undefined> | OIDCUserInfo | undefined;
}
/**
 * Options for configuring the OpenID Connect Authorization Code flow.
 */
export interface OIDCAuthorizationCodeFlowOptions<AuthReqData extends AuthorizationCodeReqData = AuthorizationCodeReqData> extends AuthorizationCodeFlowOptions<AuthReqData>, OIDCFlowExtendedOptions {
    /** The OIDC model implementation. */
    model: OIDCAuthorizationCodeModel<AuthReqData>;
    /**
     * The URL of the JWKS endpoint used for token validation.
     * Can be an absolute URL or a relative path (e.g. `"/jwks"`) resolved against
     * the discovery URL's origin.
     */
    jwksEndpoint: string;
    /**
     * The URL of the UserInfo endpoint.
     * Included in the discovery document if provided.
     *
     * @see https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
     */
    userInfoEndpoint?: string;
    /**
     * The URL of the dynamic client registration endpoint.
     * Included in the discovery document if provided.
     *
     * @see https://openid.net/specs/openid-connect-registration-1_0.html
     */
    registrationEndpoint?: string;
}
/**
 * OpenID Connect Authorization Code flow implementation.
 *
 * Extends {@link AbstractAuthorizationCodeFlow} with:
 * - OIDC-specific request parameter parsing (`nonce`, `prompt`, `max_age`, etc.)
 * - Enforcement of the `openid` scope
 * - ID token requirement in the token response
 * - OpenID Connect discovery document generation
 * - Optional UserInfo endpoint support
 *
 * @template AuthReqData - The shape of user-submitted data at the authorization endpoint.
 *
 * @see https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
 */
export declare class OIDCAuthorizationCodeFlow<AuthReqData extends AuthorizationCodeReqData = AuthorizationCodeReqData> extends AbstractAuthorizationCodeFlow<AuthReqData> implements OIDCFlow {
    protected discoveryUrl: string;
    protected jwksEndpoint: string;
    protected userInfoEndpoint?: string;
    protected registrationEndpoint?: string;
    protected openIdConfiguration?: Record<string, string | string[] | undefined>;
    constructor(options: OIDCAuthorizationCodeFlowOptions<AuthReqData>);
    /**
     * Returns the URL of the OpenID Connect discovery document.
     */
    getDiscoveryUrl(): string;
    /**
     * Returns the URL of the JWKS endpoint.
     */
    getJwksEndpoint(): string;
    /**
     * Returns the static OpenID configuration overrides merged into the discovery document,
     * or `undefined` if none were set.
     */
    getOpenIdConfiguration(): Record<string, string | string[] | undefined> | undefined;
    /**
     * Returns the URL of the UserInfo endpoint, or `undefined` if not configured.
     */
    getUserInfoEndpoint(): string | undefined;
    /**
     * Returns the URL of the dynamic client registration endpoint, or `undefined` if not configured.
     */
    getRegistrationEndpoint(): string | undefined;
    /**
     * Retrieves the UserInfo claims for the given access token by delegating to
     * `model.getUserInfo()`. Returns `undefined` if the model does not implement `getUserInfo`.
     *
     * @param accessToken - The access token for which to retrieve user information.
     * @returns The UserInfo claims, or `undefined`.
     *
     * @see https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
     */
    getUserInfo(accessToken: string): Promise<OIDCUserInfo | undefined>;
    /**
     * Returns the OpenAPI security scheme definition for this flow.
     * Uses the `openIdConnect` scheme type pointing to the discovery URL.
     *
     * @returns An object keyed by the security scheme name with the scheme definition.
     */
    toOpenAPISecurityScheme(): Record<string, {
        type: "openIdConnect";
        description?: string;
        openIdConnectUrl: string;
    }>;
    /**
     * Retrieves the OpenID Connect discovery configuration document.
     *
     * Builds the standard provider metadata fields from the flow's configuration and
     * merges in any static overrides set via `openIdConfiguration`. Relative endpoint
     * URLs are resolved against the request's origin (or the discovery URL's origin if
     * no request is provided).
     *
     * @param req - Optional request used to determine the full base URL for relative endpoints.
     * @returns The OpenID Connect discovery document fields.
     * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
     */
    getDiscoveryConfiguration(req?: Request): Record<string, string | string[] | undefined>;
    protected getAuthorizationCodeEndpointContext(request: Request): Promise<OIDCAuthorizationCodeInitiationResponse>;
    /**
     * Validates an incoming OIDC authorization endpoint `GET` request and returns the
     * OIDC authorization context including all OIDC-specific parameters.
     *
     * Enforces that the `openid` scope is present.
     *
     * @param request - The incoming `GET` request to the authorization endpoint.
     * @returns The initiation response with the OIDC context, or a non-redirectable error.
     */
    initiateAuthorization(request: Request): Promise<OIDCAuthorizationCodeInitiationResponse>;
    /**
     * Processes the user's submitted credentials at the OIDC authorization endpoint.
     *
     * Delegates to the base implementation with the OIDC-typed context.
     *
     * @param request - The incoming HTTP request to the authorization endpoint.
     * @param reqData - The user-submitted data (e.g. login form fields).
     * @returns The OIDC process response - code, continue, unauthenticated, or error.
     */
    processAuthorization(request: Request, reqData: AuthReqData): Promise<OIDCAuthorizationCodeProcessResponse>;
    /**
     * Unified handler for `GET` and `POST` requests to the OIDC authorization endpoint.
     *
     * Delegates to `initiateAuthorization()` (`GET`) or `processAuthorization()` (`POST`).
     *
     * @param request - The incoming HTTP request to the authorization endpoint.
     * @param reqData - The user-submitted data (used for `POST` requests only).
     * @returns The OIDC endpoint response - a discriminated union of all possible outcomes.
     */
    handleAuthorizationEndpoint(request: Request, reqData: AuthReqData): Promise<OIDCAuthorizationCodeEndpointResponse>;
    /**
     * Returns the scopes for this flow, always ensuring the `openid` scope is present
     * as required by the OpenID Connect specification.
     *
     * @returns The scopes map with `openid` guaranteed to be included.
     */
    getScopes(): Record<string, string> | undefined;
    /**
     * Handles a token endpoint request for the OIDC Authorization Code flow.
     *
     * Enforces OIDC compliance by verifying that the `openid` scope is present and
     * that the token response includes an ID token. For refresh token grants, the ID
     * token is optional per the OIDC specification.
     *
     * @param request - The incoming token endpoint HTTP request.
     * @returns A token response with the access token and ID token, or a failure with an error.
     */
    token(request: Request): Promise<OAuth2FlowTokenResponse>;
}
//# sourceMappingURL=oidc_authorization_code.d.ts.map