matrix-js-sdk/lib/oidc/authorize.d.ts

Matrix Client-Server SDK for Javascript

import { type IdTokenClaims, type SigninRequestCreateArgs } from "oidc-client-ts";
import { type BearerTokenResponse, type ValidatedAuthMetadata } from "./validate.ts";
export type { BearerTokenResponse };
/**
 * Authorization parameters which are used in the authentication request of an OIDC auth code flow.
 *
 * See https://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters.
 */
export type AuthorizationParams = {
    state: string;
    scope: string;
    redirectUri: string;
    codeVerifier: string;
    nonce: string;
};
/**
 * @experimental
 * Generate the scope used in authorization request with OIDC OP
 * @returns scope
 */
export declare const generateScope: (deviceId?: string) => string;
/**
 * Generate authorization params to pass to {@link generateAuthorizationUrl}.
 *
 * Used as part of an authorization code OIDC flow: see https://openid.net/specs/openid-connect-basic-1_0.html#CodeFlow.
 *
 * @param redirectUri - absolute url for OP to redirect to after authorization
 * @returns AuthorizationParams
 */
export declare const generateAuthorizationParams: ({ redirectUri }: {
    redirectUri: string;
}) => AuthorizationParams;
/**
 * @deprecated use generateOidcAuthorizationUrl
 * Generate a URL to attempt authorization with the OP
 * See https://openid.net/specs/openid-connect-basic-1_0.html#CodeRequest
 * @param authorizationUrl - endpoint to attempt authorization with the OP
 * @param clientId - id of this client as registered with the OP
 * @param authorizationParams - params to be used in the url
 * @returns a Promise with the url as a string
 */
export declare const generateAuthorizationUrl: (authorizationUrl: string, clientId: string, { scope, redirectUri, state, nonce, codeVerifier }: AuthorizationParams) => Promise<string>;
/**
 * @experimental
 * Generate a URL to attempt authorization with the OP
 * See https://openid.net/specs/openid-connect-basic-1_0.html#CodeRequest
 * @param metadata - validated metadata from OP discovery
 * @param clientId - this client's id as registered with the OP
 * @param homeserverUrl - used to establish the session on return from the OP
 * @param identityServerUrl - used to establish the session on return from the OP
 * @param nonce - state
 * @param prompt - indicates to the OP which flow the user should see - eg login or registration
 *          See https://openid.net/specs/openid-connect-prompt-create-1_0.html#name-prompt-parameter
 * @param urlState - value to append to the opaque state identifier to uniquely identify the callback
 * @param loginHint - value to send as the `login_hint` to the OP, giving a hint about the login identifier the user might use to log in.
 *          See {@link https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest OIDC core 3.1.2.1}.
 * @param responseMode - value to send as the `response_mode` to the OP, selecting how auth is passed back during redirect.
 *          See {@link https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest OIDC core 3.1.2.1}.
 * @returns a Promise with the url as a string
 */
export declare const generateOidcAuthorizationUrl: ({ metadata, redirectUri, clientId, homeserverUrl, identityServerUrl, nonce, prompt, urlState, loginHint, responseMode, }: {
    clientId: string;
    metadata: ValidatedAuthMetadata;
    homeserverUrl: string;
    identityServerUrl?: string;
    redirectUri: string;
    nonce: string;
    prompt?: string;
    urlState?: string;
    loginHint?: string;
    responseMode?: SigninRequestCreateArgs["response_mode"];
}) => Promise<string>;
/**
 * @experimental
 * Attempt to exchange authorization code for bearer token.
 *
 * Takes the authorization code returned by the OpenID Provider via the authorization URL, and makes a
 * request to the Token Endpoint, to obtain the access token, refresh token, etc.
 *
 * @param code - authorization code as returned by OP during authorization
 * @param state - authorization state param as returned by OP during authorization
 * @param responseMode - the response mode used for authentication
 * @returns valid bearer token response
 * @throws An `Error` with `message` set to an entry in {@link OidcError},
 *      when the request fails, or the returned token response is invalid.
 */
export declare const completeAuthorizationCodeGrant: (code: string, state: string, responseMode?: SigninRequestCreateArgs["response_mode"]) => Promise<{
    oidcClientSettings: {
        clientId: string;
        issuer: string;
    };
    tokenResponse: BearerTokenResponse;
    homeserverUrl: string;
    idTokenClaims: IdTokenClaims;
    identityServerUrl?: string;
}>;
/**
 * Response from the OIDC token endpoint when exchanging a token for grant_type device_code.
 */
export interface DeviceAccessTokenResponse {
    id_token?: string;
    access_token: string;
    token_type: string;
    refresh_token?: string;
    scope?: string;
    expires_in?: number;
    session_state?: string;
}
/**
 * Error from the OIDC token endpoint when exchanging a token for grant_type device_code.
 */
export interface DeviceAccessTokenError {
    error: string;
    error_description?: string;
    error_uri?: string;
    session_state?: string;
}
/**
 * Response from the OIDC device authorization endpoint.
 */
export interface DeviceAuthorizationResponse {
    device_code: string;
    user_code: string;
    verification_uri: string;
    verification_uri_complete?: string;
    expires_in: number;
    interval?: number;
}
/**
 * Begin OIDC 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 OIDC 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 OIDC 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 OIDC 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>;
//# sourceMappingURL=authorize.d.ts.map