131 lines
5.6 KiB
TypeScript
131 lines
5.6 KiB
TypeScript
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
|