init

node_modules/matrix-js-sdk/lib/oauth/authorize.d.ts

@@ -0,0 +1,131 @@
+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