matrix-js-sdk 41.9.0 → 42.0.0

package/src/oidc/authorize.ts

@@ -1,431 +0,0 @@
-/*
-Copyright 2023 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import {
-    type IdTokenClaims,
-    Log,
-    OidcClient,
-    type SigninRequestCreateArgs,
-    SigninResponse,
-    SigninState,
-    WebStorageStateStore,
-} from "oidc-client-ts";
-
-import { logger } from "../logger.ts";
-import { secureRandomString } from "../randomstring.ts";
-import { OidcError } from "./error.ts";
-import {
-    type BearerTokenResponse,
-    type UserState,
-    validateBearerTokenResponse,
-    type ValidatedAuthMetadata,
-    validateIdToken,
-    validateStoredUserState,
-} from "./validate.ts";
-import { sha256 } from "../digest.ts";
-import { encodeUnpaddedBase64Url } from "../base64.ts";
-import { OAuthGrantType } from "./register.ts";
-import { sleep } from "../utils.ts";
-import { Method } from "../http-api/index.ts";
-
-// reexport for backwards compatibility
-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 const generateScope = (deviceId?: string): string => {
-    const safeDeviceId = deviceId ?? secureRandomString(10);
-    return `openid urn:matrix:org.matrix.msc2967.client:api:* urn:matrix:org.matrix.msc2967.client:device:${safeDeviceId}`;
-};
-
-// https://www.rfc-editor.org/rfc/rfc7636
-const generateCodeChallenge = async (codeVerifier: string): Promise<string> => {
-    if (!globalThis.crypto.subtle) {
-        // @TODO(kerrya) should this be allowed? configurable?
-        logger.warn("A secure context is required to generate code challenge. Using plain text code challenge");
-        return codeVerifier;
-    }
-
-    const hashBuffer = await sha256(codeVerifier);
-    return encodeUnpaddedBase64Url(hashBuffer);
-};
-
-/**
- * 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 const generateAuthorizationParams = ({ redirectUri }: { redirectUri: string }): AuthorizationParams => ({
-    scope: generateScope(),
-    redirectUri,
-    state: secureRandomString(8),
-    nonce: secureRandomString(8),
-    codeVerifier: secureRandomString(64), // https://tools.ietf.org/html/rfc7636#section-4.1 length needs to be 43-128 characters
-});
-
-/**
- * @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 const generateAuthorizationUrl = async (
-    authorizationUrl: string,
-    clientId: string,
-    { scope, redirectUri, state, nonce, codeVerifier }: AuthorizationParams,
-): Promise<string> => {
-    const url = new URL(authorizationUrl);
-    url.searchParams.append("response_mode", "query");
-    url.searchParams.append("response_type", "code");
-    url.searchParams.append("redirect_uri", redirectUri);
-    url.searchParams.append("client_id", clientId);
-    url.searchParams.append("state", state);
-    url.searchParams.append("scope", scope);
-    url.searchParams.append("nonce", nonce);
-
-    url.searchParams.append("code_challenge_method", "S256");
-    url.searchParams.append("code_challenge", await generateCodeChallenge(codeVerifier));
-
-    return url.toString();
-};
-
-/**
- * @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 const generateOidcAuthorizationUrl = async ({
-    metadata,
-    redirectUri,
-    clientId,
-    homeserverUrl,
-    identityServerUrl,
-    nonce,
-    prompt,
-    urlState,
-    loginHint,
-    responseMode = "query",
-}: {
-    clientId: string;
-    metadata: ValidatedAuthMetadata;
-    homeserverUrl: string;
-    identityServerUrl?: string;
-    redirectUri: string;
-    nonce: string;
-    prompt?: string;
-    urlState?: string;
-    loginHint?: string;
-    responseMode?: SigninRequestCreateArgs["response_mode"];
-}): Promise<string> => {
-    const scope = generateScope();
-    const oidcClient = new OidcClient({
-        ...metadata,
-        client_id: clientId,
-        redirect_uri: redirectUri,
-        authority: metadata.issuer,
-        response_mode: responseMode,
-        response_type: "code",
-        scope,
-        stateStore: new WebStorageStateStore({ prefix: "mx_oidc_", store: window.sessionStorage }),
-    });
-    const userState: UserState = { homeserverUrl, nonce, identityServerUrl };
-    const request = await oidcClient.createSigninRequest({
-        state: userState,
-        nonce,
-        prompt,
-        url_state: urlState,
-        login_hint: loginHint,
-    });
-
-    return request.url;
-};
-
-/**
- * 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'
- */
-const normalizeBearerTokenResponseTokenType = (response: SigninResponse): BearerTokenResponse =>
-    ({
-        id_token: response.id_token,
-        scope: response.scope,
-        expires_at: response.expires_at,
-        refresh_token: response.refresh_token,
-        access_token: response.access_token,
-        token_type: "Bearer",
-    }) as BearerTokenResponse;
-
-/**
- * @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 const completeAuthorizationCodeGrant = async (
-    code: string,
-    state: string,
-    responseMode: SigninRequestCreateArgs["response_mode"] = "query",
-): Promise<{
-    oidcClientSettings: { clientId: string; issuer: string };
-    tokenResponse: BearerTokenResponse;
-    homeserverUrl: string;
-    idTokenClaims: IdTokenClaims;
-    identityServerUrl?: string;
-}> => {
-    /**
-     * Element Web strips and changes the url on starting the app
-     * Use the code and state from query params to rebuild a url
-     * so that oidc-client can parse it
-     */
-    const reconstructedUrl = new URL(window.location.origin);
-
-    const params = new URLSearchParams({ code, state });
-    if (responseMode === "query") {
-        reconstructedUrl.search = params.toString();
-    } else {
-        reconstructedUrl.hash = `#${params.toString()}`;
-    }
-
-    // set oidc-client to use our logger
-    Log.setLogger(logger);
-    try {
-        const response = new SigninResponse(params);
-
-        const stateStore = new WebStorageStateStore({ prefix: "mx_oidc_", store: window.sessionStorage });
-
-        // retrieve the state we put in storage at the start of oidc auth flow
-        const stateString = await stateStore.get(response.state!);
-        if (!stateString) {
-            throw new Error(OidcError.MissingOrInvalidStoredState);
-        }
-
-        // hydrate the sign in state and create a client
-        // the stored sign in state includes oidc configuration we set at the start of the oidc login flow
-        const signInState = await SigninState.fromStorageString(stateString);
-        const client = new OidcClient({ ...signInState, stateStore });
-
-        // validate the code and state, and attempt to swap the code for tokens
-        const signinResponse = await client.processSigninResponse(reconstructedUrl.href);
-
-        // extra values we stored at the start of the login flow
-        // used to complete login in the client
-        const userState = signinResponse.userState;
-        validateStoredUserState(userState);
-
-        // throws when response is invalid
-        validateBearerTokenResponse(signinResponse);
-        if (signinResponse.id_token) {
-            // The token is not yet in the Matrix spec so consider it optional
-            // throws when token is invalid
-            validateIdToken(
-                signinResponse.id_token,
-                client.settings.authority,
-                client.settings.client_id,
-                userState.nonce,
-            );
-        }
-        const normalizedTokenResponse = normalizeBearerTokenResponseTokenType(signinResponse);
-
-        return {
-            oidcClientSettings: {
-                clientId: client.settings.client_id,
-                issuer: client.settings.authority,
-            },
-            tokenResponse: normalizedTokenResponse,
-            homeserverUrl: userState.homeserverUrl,
-            identityServerUrl: userState.identityServerUrl,
-            idTokenClaims: signinResponse.profile,
-        };
-    } catch (error) {
-        logger.error("Oidc login failed", error);
-        const errorType = (error as Error).message;
-
-        // rethrow errors that we recognise
-        if (Object.values(OidcError).includes(errorType as any)) {
-            throw error;
-        }
-        throw new Error(OidcError.CodeExchangeFailed);
-    }
-};
-
-/**
- * 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 const startDeviceAuthorization = async ({
-    clientId,
-    scope,
-    metadata,
-}: {
-    clientId: string;
-    scope: string;
-    metadata: ValidatedAuthMetadata;
-}): Promise<DeviceAuthorizationResponse> => {
-    const body = new URLSearchParams({ client_id: clientId, scope: scope }).toString();
-
-    const url = metadata.device_authorization_endpoint;
-    if (!url) {
-        throw new Error("No device_authorization_endpoint given");
-    }
-
-    const response = await fetch(url, {
-        method: Method.Post,
-        headers: {
-            "Content-Type": "application/x-www-form-urlencoded",
-        },
-        body,
-    });
-
-    return (await response.json()) as 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 const waitForDeviceAuthorization = async ({
-    session,
-    metadata,
-    clientId,
-}: {
-    session: DeviceAuthorizationResponse;
-    metadata: ValidatedAuthMetadata;
-    clientId: string;
-}): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError> => {
-    let interval = (session.interval ?? 5) * 1000; // poll interval
-    const expiration = Date.now() + session.expires_in * 1000;
-    do {
-        const body = new URLSearchParams({
-            device_code: session.device_code,
-            grant_type: OAuthGrantType.DeviceAuthorization,
-            client_id: clientId,
-        }).toString();
-        const response = await fetch(metadata.token_endpoint, {
-            method: Method.Post,
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body,
-        });
-
-        if (response.ok) {
-            return (await response.json()) as DeviceAccessTokenResponse;
-        }
-        const errorResponse = (await response.json()) as DeviceAccessTokenError;
-        switch (errorResponse.error) {
-            case "authorization_pending":
-                break;
-            case "slow_down":
-                interval += 5000;
-                break;
-            case "access_denied":
-            case "expired_token":
-                return errorResponse;
-        }
-        await sleep(interval);
-    } while (Date.now() < expiration);
-    return { error: "expired" };
-};

package/src/oidc/discovery.ts

@@ -1,67 +0,0 @@
-/*
-Copyright 2023 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import { MetadataService, OidcClientSettingsStore } from "oidc-client-ts";
-
-import { validateAuthMetadata } from "./validate.ts";
-import { Method, timeoutSignal } from "../http-api/index.ts";
-import { type OidcClientConfig } from "./index.ts";
-
-/**
- * @experimental
- * Discover and validate delegated auth configuration
- * - delegated auth issuer openid-configuration is reachable
- * - delegated auth issuer openid-configuration is configured correctly for us
- * Fetches https://oidc-issuer.example.com/.well-known/openid-configuration and other files linked therein.
- * When successful, validated metadata is returned
- * @param issuer - the OIDC issuer as returned by the /auth_issuer API
- * @returns validated authentication metadata and optionally signing keys
- * @throws when delegated auth config is invalid or unreachable
- * @deprecated in favour of {@link MatrixClient#getAuthMetadata}
- */
-export const discoverAndValidateOIDCIssuerWellKnown = async (issuer: string): Promise<OidcClientConfig> => {
-    const issuerOpenIdConfigUrl = new URL(".well-known/openid-configuration", issuer);
-    const issuerWellKnownResponse = await fetch(issuerOpenIdConfigUrl, {
-        method: Method.Get,
-        signal: timeoutSignal(5000),
-    });
-    const issuerWellKnown = await issuerWellKnownResponse.json();
-    return validateAuthMetadataAndKeys(issuerWellKnown);
-};
-
-/**
- * @experimental
- * Validate the authentication metadata and fetch the signing keys from the jwks_uri in the metadata
- * @param authMetadata - the authentication metadata to validate
- * @returns validated authentication metadata and signing keys
- */
-export const validateAuthMetadataAndKeys = async (authMetadata: unknown): Promise<OidcClientConfig> => {
-    const validatedIssuerConfig = validateAuthMetadata(authMetadata);
-
-    // create a temporary settings store, so we can use metadata service for discovery
-    const settings = new OidcClientSettingsStore({
-        authority: validatedIssuerConfig.issuer,
-        metadata: validatedIssuerConfig,
-        redirect_uri: "", // Not known yet, this is here to make the type checker happy
-        client_id: "", // Not known yet, this is here to make the type checker happy
-    });
-    const metadataService = new MetadataService(settings);
-
-    return {
-        ...validatedIssuerConfig,
-        signingKeys: validatedIssuerConfig.jwks_uri ? await metadataService.getSigningKeys() : null,
-    };
-};

package/src/oidc/index.ts

@@ -1,33 +0,0 @@
-/*
-Copyright 2023 The Matrix.org Foundation C.I.C.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
-
-import type { SigningKey } from "oidc-client-ts";
-import { type ValidatedAuthMetadata } from "./validate.ts";
-
-export * from "./authorize.ts";
-export * from "./discovery.ts";
-export * from "./error.ts";
-export * from "./register.ts";
-export * from "./tokenRefresher.ts";
-export * from "./validate.ts";
-
-/**
- * Validated config for native OIDC authentication, as returned by {@link discoverAndValidateOIDCIssuerWellKnown}.
- * Contains metadata and signing keys from the issuer's well-known (https://oidc-issuer.example.com/.well-known/openid-configuration).
- */
-export interface OidcClientConfig extends ValidatedAuthMetadata {
-    signingKeys: SigningKey[] | null;
-}