import { type OAuth2ErrorResponse } from "./error.ts";
import { type ValidatedAuthMetadata } from "./discover.ts";
/**
 * The expected response type from the token endpoint during authorization code flow
 * Normalized to always use capitalized 'Bearer' for token_type
 *
 * See https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.4
 */
export type BearerTokenResponse = Omit<ValidTokenResponse, "token_type"> & {
    token_type: "Bearer";
};
/**
 * Metadata from OAuth 2.0 token_endpoint as per
 * https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
 * With validated properties required in type
 *
 * This response is expected for the authorization code grant and refresh token grant,
 * as defined in the Matrix spec.
 */
interface ValidTokenResponse {
    token_type: "Bearer" | "bearer";
    access_token: string;
    expires_in?: number;
    refresh_token?: string;
    scope?: string;
}
/**
 * Validate the given response matches the format expected for a {@link ValidTokenResponse}
 * @param response - the response to validate
 * @throws if the response does not match the expected format
 */
export declare function validateBearerTokenResponse(response: unknown): asserts response is ValidTokenResponse;
/**
 * Generate the scope used in authorization request with OAuth2 IdP
 * @returns scope
 */
export declare const generateScope: (deviceId?: string) => string;
/**
 * Normalize token_type to use capital case to make consuming the token response easier
 * token_type is case insensitive, and it is spec-compliant for OPs to return token_type: "bearer"
 * Later, when used in auth headers it is case sensitive and must be Bearer
 * See: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.4
 *
 * @param response - validated token response
 * @returns response with token_type set to 'Bearer'
 */
export declare const normalizeBearerTokenResponseTokenType: (response: ValidTokenResponse) => BearerTokenResponse;
/**
 * Response from the OAuth2 token endpoint when exchanging a token for grant_type device_code.
 */
export interface DeviceAccessTokenResponse {
    access_token: string;
    token_type: string;
    refresh_token?: string;
    scope?: string;
    expires_in?: number;
}
/**
 * Validate the given response matches the format expected for a {@link DeviceAccessTokenResponse}
 * @param response - the response to validate
 * @throws if the response does not match the expected format
 */
export declare function isValidDeviceAccessTokenResponse(response: unknown): response is DeviceAccessTokenResponse;
/**
 * Error from the OAuth2 token endpoint when exchanging a token for grant_type device_code.
 */
export interface DeviceAccessTokenError extends OAuth2ErrorResponse {
    session_state?: string;
}
/**
 * Response from the OAuth2 device authorization endpoint.
 * As specified in https://datatracker.ietf.org/doc/html/rfc8628#section-3.2
 */
export interface DeviceAuthorizationResponse {
    /** The device verification code. */
    device_code: string;
    /** The end-user verification code. */
    user_code: string;
    /**
     * The end-user verification URI on the authorization server.
     * The URI should be short and easy to remember as end users will be asked to manually type it into their user agent.
     */
    verification_uri: string;
    /**
     * The URI which doesn’t require the user to manually type the user_code, designed for non-textual transmission.
     */
    verification_uri_complete?: string;
    /** The lifetime in seconds of the "device_code" and "user_code". */
    expires_in: number;
    /**
     * The minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint.
     * If no value is provided, clients MUST use 5 as the default.
     */
    interval?: number;
}
/**
 * Validate the given response matches the format expected for a {@link DeviceAuthorizationResponse}
 * @param response - the response to validate
 * @throws if the response does not match the expected format
 */
export declare function validateDeviceAuthorizationResponse(response: unknown): asserts response is DeviceAuthorizationResponse;
/**
 * Begin OAuth2 device authorization flow.
 * @param options - The device authorization parameters.
 * @param options.clientId - the client ID returned from client registration.
 * @param options.scope - the scope to request for authorization.
 * @param options.metadata - the validated OAuth2 metadata for the Identity Provider.
 * @returns a promise that resolves to a device access token response,
 *   or an error response if the user denies authorization or the device code expires.
 */
export declare const startDeviceAuthorization: ({ clientId, scope, metadata, }: {
    clientId: string;
    scope: string;
    metadata: ValidatedAuthMetadata;
}) => Promise<DeviceAuthorizationResponse>;
/**
 * Polls the OAuth2 token endpoint until we get a device access token response, or encounter an unrecoverable error.
 * @param options - The device authorization parameters.
 * @param options.session - The session returned from a previous call to {@link startDeviceAuthorization}.
 * @param options.metadata - The validated OAuth2 metadata for the Identity Provider.
 * @param options.clientId - The client ID returned from client registration.
 * @returns a promise that resolves to a device access token response,
 *   or an error response if the user denies authorization or the device code expires.
 */
export declare const waitForDeviceAuthorization: ({ session, metadata, clientId, }: {
    session: DeviceAuthorizationResponse;
    metadata: ValidatedAuthMetadata;
    clientId: string;
}) => Promise<DeviceAccessTokenResponse | DeviceAccessTokenError>;
export {};
//# sourceMappingURL=authorize.d.ts.map