matrix-js-sdk 41.9.0 → 42.0.0

package/src/oidc/register.ts

@@ -1,168 +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 OidcClientConfig } from "./index.ts";
-import { OidcError } from "./error.ts";
-import { Method } from "../http-api/index.ts";
-import { logger } from "../logger.ts";
-import { type NonEmptyArray } from "../@types/common.ts";
-
-/**
- * Client metadata passed to registration endpoint
- */
-export type OidcRegistrationClientMetadata = {
-    clientName: OidcRegistrationRequestBody["client_name"];
-    clientUri: OidcRegistrationRequestBody["client_uri"];
-    logoUri?: OidcRegistrationRequestBody["logo_uri"];
-    applicationType: OidcRegistrationRequestBody["application_type"];
-    redirectUris: OidcRegistrationRequestBody["redirect_uris"];
-    contacts: OidcRegistrationRequestBody["contacts"];
-    tosUri: OidcRegistrationRequestBody["tos_uri"];
-    policyUri: OidcRegistrationRequestBody["policy_uri"];
-};
-
-/**
- * Request body for dynamic registration as defined by https://github.com/matrix-org/matrix-spec-proposals/pull/2966
- */
-interface OidcRegistrationRequestBody {
-    client_name?: string;
-    client_uri: string;
-    logo_uri?: string;
-    contacts?: string[];
-    tos_uri?: string;
-    policy_uri?: string;
-    redirect_uris?: NonEmptyArray<string>;
-    response_types?: NonEmptyArray<string>;
-    grant_types?: NonEmptyArray<string>;
-    id_token_signed_response_alg?: string;
-    token_endpoint_auth_method: string;
-    application_type: "web" | "native";
-}
-
-/**
- * The OAuth 2.0 grant types that are defined for Matrix in https://spec.matrix.org/v1.17/client-server-api/#grant-types
- */
-export enum OAuthGrantType {
-    /**
-     * See https://spec.matrix.org/v1.17/client-server-api/#authorization-code-grant
-     */
-    AuthorizationCode = "authorization_code",
-    /**
-     * https://spec.matrix.org/v1.17/client-server-api/#refresh-token-grant
-     */
-    RefreshToken = "refresh_token",
-    /**
-     * The OAuth 2.0 Device Authorization Grant type identifier as per
-     * https://www.rfc-editor.org/rfc/rfc8628.html#section-7.2 from
-     * [MSC4341](https://github.com/matrix-org/matrix-spec-proposals/pull/4341).
-     *
-     * @experimental Note that this is UNSTABLE and may have breaking changes without notice.
-     */
-    DeviceAuthorization = "urn:ietf:params:oauth:grant-type:device_code",
-}
-
-/**
- * The name "scope" is a misnomer here as it is actually a "grant type".
- *
- * @deprecated use `OAuthGrantType.DeviceAuthorization` instead
- */
-export const DEVICE_CODE_SCOPE: string = OAuthGrantType.DeviceAuthorization;
-
-// Check that URIs have a common base, as per the MSC2966 definition
-const urlHasCommonBase = (base: URL, urlStr?: string): boolean => {
-    if (!urlStr) return false;
-    const url = new URL(urlStr);
-    if (url.protocol !== base.protocol) return false;
-    if (url.hostname !== base.hostname && !url.hostname.endsWith(`.${base.hostname}`)) return false;
-    return true;
-};
-
-/**
- * Attempts dynamic registration against the configured registration endpoint.
- * Will ignore any URIs that do not use client_uri as a common base as per the spec.
- * @param delegatedAuthConfig - Auth config from {@link discoverAndValidateOIDCIssuerWellKnown}
- * @param clientMetadata - The metadata for the client which to register
- * @returns Promise<string> resolved with registered clientId
- * @throws when registration is not supported, on failed request or invalid response
- */
-export const registerOidcClient = async (
-    delegatedAuthConfig: OidcClientConfig,
-    clientMetadata: OidcRegistrationClientMetadata,
-): Promise<string> => {
-    if (!delegatedAuthConfig.registration_endpoint) {
-        throw new Error(OidcError.DynamicRegistrationNotSupported);
-    }
-
-    const grantTypes: NonEmptyArray<string> = [OAuthGrantType.AuthorizationCode, OAuthGrantType.RefreshToken];
-    if (grantTypes.some((scope) => !delegatedAuthConfig.grant_types_supported.includes(scope))) {
-        throw new Error(OidcError.DynamicRegistrationNotSupported);
-    }
-
-    // ask for device authorization grant if supported
-    if (delegatedAuthConfig.grant_types_supported.includes(OAuthGrantType.DeviceAuthorization)) {
-        grantTypes.push(OAuthGrantType.DeviceAuthorization);
-    }
-
-    const commonBase = new URL(clientMetadata.clientUri);
-
-    // https://openid.net/specs/openid-connect-registration-1_0.html
-    const metadata: OidcRegistrationRequestBody = {
-        client_name: clientMetadata.clientName,
-        client_uri: clientMetadata.clientUri,
-        response_types: ["code"],
-        grant_types: grantTypes,
-        redirect_uris: clientMetadata.redirectUris,
-        id_token_signed_response_alg: "RS256",
-        token_endpoint_auth_method: "none",
-        application_type: clientMetadata.applicationType,
-        contacts: clientMetadata.contacts,
-        logo_uri: urlHasCommonBase(commonBase, clientMetadata.logoUri) ? clientMetadata.logoUri : undefined,
-        policy_uri: urlHasCommonBase(commonBase, clientMetadata.policyUri) ? clientMetadata.policyUri : undefined,
-        tos_uri: urlHasCommonBase(commonBase, clientMetadata.tosUri) ? clientMetadata.tosUri : undefined,
-    };
-
-    const headers = {
-        "Accept": "application/json",
-        "Content-Type": "application/json",
-    };
-
-    try {
-        const response = await fetch(delegatedAuthConfig.registration_endpoint, {
-            method: Method.Post,
-            headers,
-            body: JSON.stringify(metadata),
-        });
-
-        if (response.status >= 400) {
-            throw new Error(OidcError.DynamicRegistrationFailed);
-        }
-
-        const body = await response.json();
-        const clientId = body["client_id"];
-        if (!clientId || typeof clientId !== "string") {
-            throw new Error(OidcError.DynamicRegistrationInvalid);
-        }
-
-        return clientId;
-    } catch (error) {
-        if (Object.values(OidcError).includes((error as Error).message as OidcError)) {
-            throw error;
-        } else {
-            logger.error("Dynamic registration request failed", error);
-            throw new Error(OidcError.DynamicRegistrationFailed);
-        }
-    }
-};

package/src/oidc/tokenRefresher.ts

@@ -1,184 +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, OidcClient, WebStorageStateStore, ErrorResponse } from "oidc-client-ts";
-
-import { type AccessTokens, TokenRefreshLogoutError } from "../http-api/index.ts";
-import { generateScope } from "./authorize.ts";
-import { discoverAndValidateOIDCIssuerWellKnown } from "./discovery.ts";
-import { logger } from "../logger.ts";
-
-/**
- * @experimental
- * Class responsible for refreshing OIDC access tokens
- *
- * Client implementations will likely want to override {@link persistTokens} to persist tokens after successful refresh
- *
- */
-export class OidcTokenRefresher {
-    /**
-     * This is now just a resolved promise and will be removed in a future version.
-     * Initialisation is done lazily at token refresh time.
-     * @deprecated Consumers no longer need to wait for this promise.
-     */
-    public readonly oidcClientReady!: Promise<void>;
-
-    // If there is a initialisation attempt in progress, we keep track of it here.
-    private initPromise?: Promise<void>;
-
-    private oidcClient!: OidcClient;
-    private inflightRefreshRequest?: Promise<AccessTokens>;
-
-    public constructor(
-        /**
-         * The OIDC issuer as returned by the /auth_issuer API
-         */
-        private issuer: string,
-        /**
-         * id of this client as registered with the OP
-         */
-        private clientId: string,
-        /**
-         * redirectUri as registered with OP
-         */
-        private redirectUri: string,
-        /**
-         * Device ID of current session
-         */
-        protected deviceId: string,
-        /**
-         * idTokenClaims as returned from authorization grant
-         * used to validate tokens
-         */
-        private readonly idTokenClaims: IdTokenClaims,
-    ) {
-        this.oidcClientReady = Promise.resolve();
-    }
-
-    /**
-     * Ensures that the client is initialised.
-     * @returns Promise that resolves when initialisation is complete
-     * @throws if initialisation fails
-     */
-    private async ensureInit(): Promise<void> {
-        if (!this.oidcClient) {
-            if (this.initPromise) {
-                return this.initPromise;
-            }
-
-            this.initPromise = this.initialiseOidcClient(this.issuer, this.clientId, this.deviceId, this.redirectUri);
-            try {
-                await this.initPromise;
-            } finally {
-                this.initPromise = undefined;
-            }
-        }
-    }
-
-    private async initialiseOidcClient(
-        issuer: string,
-        clientId: string,
-        deviceId: string,
-        redirectUri: string,
-    ): Promise<void> {
-        try {
-            const config = await discoverAndValidateOIDCIssuerWellKnown(issuer);
-
-            const scope = generateScope(deviceId);
-
-            this.oidcClient = new OidcClient({
-                metadata: config,
-                signingKeys: config.signingKeys ?? undefined,
-                client_id: clientId,
-                scope,
-                redirect_uri: redirectUri,
-                authority: config.issuer,
-                stateStore: new WebStorageStateStore({ prefix: "mx_oidc_", store: window.sessionStorage }),
-            });
-        } catch (error) {
-            logger.error("Failed to initialise OIDC client.", error);
-            throw new Error("Failed to initialise OIDC client.");
-        }
-    }
-
-    /**
-     * Attempt token refresh using given refresh token
-     * @param refreshToken - refresh token to use in request with token issuer
-     * @returns tokens - Promise that resolves with new access and refresh tokens
-     * @throws when token refresh fails
-     */
-    public async doRefreshAccessToken(refreshToken: string): Promise<AccessTokens> {
-        await this.ensureInit();
-
-        if (!this.inflightRefreshRequest) {
-            this.inflightRefreshRequest = this.getNewTokens(refreshToken);
-        }
-        try {
-            const tokens = await this.inflightRefreshRequest;
-            return tokens;
-        } catch (e) {
-            // If we encounter an OIDC error then signal that it should cause a logout by upgrading it to a TokenRefreshLogoutError
-            if (e instanceof ErrorResponse) {
-                throw new TokenRefreshLogoutError(e);
-            }
-            throw e;
-        } finally {
-            this.inflightRefreshRequest = undefined;
-        }
-    }
-
-    /**
-     * Persist the new tokens, called after tokens are successfully refreshed.
-     *
-     * This function is intended to be overriden by the consumer when persistence is necessary.
-     *
-     * @param tokens.accessToken - new access token
-     * @param tokens.refreshToken - OPTIONAL new refresh token
-     */
-    protected async persistTokens(tokens: { accessToken: string; refreshToken?: string }): Promise<void> {
-        // NOOP
-    }
-
-    private async getNewTokens(refreshToken: string): Promise<AccessTokens> {
-        if (!this.oidcClient) {
-            throw new Error("Cannot get new token before OIDC client is initialised.");
-        }
-
-        const refreshTokenState = {
-            refresh_token: refreshToken,
-            session_state: "test",
-            data: undefined,
-            profile: this.idTokenClaims,
-        };
-
-        const requestStart = Date.now();
-        const response = await this.oidcClient.useRefreshToken({
-            state: refreshTokenState,
-            timeoutInSeconds: 300,
-        });
-
-        const tokens = {
-            accessToken: response.access_token,
-            refreshToken: response.refresh_token,
-            // We use the request start time to calculate the expiry time as we don't know when the server received our request
-            expiry: response.expires_in ? new Date(requestStart + response.expires_in * 1000) : undefined,
-        } satisfies AccessTokens;
-
-        await this.persistTokens(tokens);
-
-        return tokens;
-    }
-}

package/src/oidc/validate.ts

@@ -1,265 +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 { jwtDecode } from "jwt-decode";
-import { type IdTokenClaims, type OidcMetadata, type SigninResponse } from "oidc-client-ts";
-
-import { logger } from "../logger.ts";
-import { OidcError } from "./error.ts";
-import { OAuthGrantType } from "./index.ts";
-
-/**
- * Metadata from OAuth 2.0 client authentication API as per
- * https://spec.matrix.org/v1.17/client-server-api/#get_matrixclientv1auth_metadata
- * With validated properties required in type
- */
-export type ValidatedAuthMetadata = Partial<OidcMetadata> &
-    Pick<
-        // These values are from [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414#section-2)
-        // so we can reuse the OidcMetadata definitions from oidc-client-ts
-        OidcMetadata,
-        | "issuer"
-        | "authorization_endpoint"
-        | "token_endpoint"
-        | "revocation_endpoint"
-        | "response_types_supported"
-        | "grant_types_supported"
-        | "code_challenge_methods_supported"
-    > & {
-        // These values aren't part of RFC8414 so we add them here
-        // Account management fields from stable MSC4191:
-        account_management_uri?: string;
-        account_management_actions_supported?: string[];
-        // Value from [Initiating User Registration via OpenID Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html):
-        prompt_values_supported?: string[];
-        // Experimental MSC4341 value from [RFC8628](https://datatracker.ietf.org/doc/html/rfc8628#section-4):
-        device_authorization_endpoint?: string;
-    };
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-    !!value && typeof value === "object" && !Array.isArray(value);
-const requiredStringProperty = (wellKnown: Record<string, unknown>, key: string): boolean => {
-    if (!wellKnown[key] || !optionalStringProperty(wellKnown, key)) {
-        logger.error(`Missing or invalid property: ${key}`);
-        return false;
-    }
-    return true;
-};
-const optionalStringProperty = (wellKnown: Record<string, unknown>, key: string): boolean => {
-    if (!!wellKnown[key] && typeof wellKnown[key] !== "string") {
-        logger.error(`Invalid property: ${key}`);
-        return false;
-    }
-    return true;
-};
-const optionalStringArrayProperty = (wellKnown: Record<string, unknown>, key: string): boolean => {
-    if (
-        !!wellKnown[key] &&
-        (!Array.isArray(wellKnown[key]) || !(<unknown[]>wellKnown[key]).every((v) => typeof v === "string"))
-    ) {
-        logger.error(`Invalid property: ${key}`);
-        return false;
-    }
-    return true;
-};
-const requiredArrayValue = (wellKnown: Record<string, unknown>, key: string, value: any): boolean => {
-    const array = wellKnown[key];
-    if (!array || !Array.isArray(array) || !array.includes(value)) {
-        logger.error(`Invalid property: ${key}. ${value} is required.`);
-        return false;
-    }
-    return true;
-};
-
-/**
- * Validates OAuth 2.0 auth metadata as defined by
- * https://spec.matrix.org/v1.17/client-server-api/#get_matrixclientv1auth_metadata
- * is compatible with Element's OAuth/OIDC flow
- * @param authMetadata - json object
- * @returns valid issuer config
- * @throws Error - when issuer config is not found or is invalid
- */
-export const validateAuthMetadata = (authMetadata: unknown): ValidatedAuthMetadata => {
-    if (!isRecord(authMetadata)) {
-        logger.error("Issuer configuration not found or malformed");
-        throw new Error(OidcError.OpSupport);
-    }
-
-    const isInvalid = [
-        requiredStringProperty(authMetadata, "issuer"),
-        requiredStringProperty(authMetadata, "authorization_endpoint"),
-        requiredStringProperty(authMetadata, "token_endpoint"),
-        requiredStringProperty(authMetadata, "revocation_endpoint"),
-        optionalStringProperty(authMetadata, "registration_endpoint"),
-        optionalStringProperty(authMetadata, "account_management_uri"),
-        optionalStringProperty(authMetadata, "device_authorization_endpoint"),
-        optionalStringArrayProperty(authMetadata, "account_management_actions_supported"),
-        requiredArrayValue(authMetadata, "response_types_supported", "code"),
-        requiredArrayValue(authMetadata, "grant_types_supported", OAuthGrantType.AuthorizationCode),
-        requiredArrayValue(authMetadata, "code_challenge_methods_supported", "S256"),
-        optionalStringArrayProperty(authMetadata, "prompt_values_supported"),
-    ].some((isValid) => !isValid);
-
-    if (!isInvalid) {
-        return authMetadata as ValidatedAuthMetadata;
-    }
-
-    logger.error("Issuer configuration not valid");
-    throw new Error(OidcError.OpSupport);
-};
-
-export const decodeIdToken = (token: string): IdTokenClaims => {
-    try {
-        return jwtDecode<IdTokenClaims>(token);
-    } catch (error) {
-        logger.error("Could not decode id_token", error);
-        throw error;
-    }
-};
-
-/**
- * Validate idToken
- * https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation
- * @param idToken - id token from token endpoint
- * @param issuer - issuer for the OP as found during discovery
- * @param clientId - this client's id as registered with the OP
- * @param nonce - nonce used in the authentication request
- * @throws when id token is invalid
- */
-export const validateIdToken = (
-    idToken: string | undefined,
-    issuer: string,
-    clientId: string,
-    nonce: string | undefined,
-): void => {
-    try {
-        if (!idToken) {
-            throw new Error("No ID token");
-        }
-        const claims = decodeIdToken(idToken);
-
-        // The Issuer Identifier for the OpenID Provider MUST exactly match the value of the iss (issuer) Claim.
-        if (claims.iss !== issuer) {
-            throw new Error("Invalid issuer");
-        }
-        /**
-         * The Client MUST validate that the aud (audience) Claim contains its client_id value registered at the Issuer identified by the iss (issuer) Claim as an audience.
-         * The aud (audience) Claim MAY contain an array with more than one element.
-         * The ID Token MUST be rejected if the ID Token does not list the Client as a valid audience, or if it contains additional audiences not trusted by the Client.
-         * EW: Don't accept tokens with other untrusted audiences
-         * */
-        const sanitisedAuds = typeof claims.aud === "string" ? [claims.aud] : claims.aud;
-        if (!sanitisedAuds.includes(clientId)) {
-            throw new Error("Invalid audience");
-        }
-
-        /**
-         * If a nonce value was sent in the Authentication Request, a nonce Claim MUST be present and its value checked
-         * to verify that it is the same value as the one that was sent in the Authentication Request.
-         */
-        if (nonce !== undefined && claims.nonce !== nonce) {
-            throw new Error("Invalid nonce");
-        }
-
-        /**
-         * The current time MUST be before the time represented by the exp Claim.
-         *  exp is an epoch timestamp in seconds
-         * */
-        if (!claims.exp || Date.now() > claims.exp * 1000) {
-            throw new Error("Invalid expiry");
-        }
-    } catch (error) {
-        logger.error("Invalid ID token", error);
-        throw new Error(OidcError.InvalidIdToken);
-    }
-};
-
-/**
- * State we ask OidcClient to store when starting oidc authorization flow (in `generateOidcAuthorizationUrl`)
- * so that we can access it on return from the OP and complete login
- */
-export type UserState = {
-    /**
-     * Remember which server we were trying to login to
-     */
-    homeserverUrl: string;
-    identityServerUrl?: string;
-    /**
-     * Used to validate id token
-     */
-    nonce: string;
-};
-/**
- * Validate stored user state exists and is valid
- * @param userState - userState returned by oidcClient.processSigninResponse
- * @throws when userState is invalid
- */
-export function validateStoredUserState(userState: unknown): asserts userState is UserState {
-    if (!isRecord(userState)) {
-        logger.error("Stored user state not found");
-        throw new Error(OidcError.MissingOrInvalidStoredState);
-    }
-    const isInvalid = [
-        requiredStringProperty(userState, "homeserverUrl"),
-        requiredStringProperty(userState, "nonce"),
-        optionalStringProperty(userState, "identityServerUrl"),
-    ].some((isValid) => !isValid);
-
-    if (isInvalid) {
-        throw new Error(OidcError.MissingOrInvalidStoredState);
-    }
-}
-
-/**
- * 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,
- * https://openid.net/specs/openid-connect-basic-1_0.html#TokenOK.
- */
-export type BearerTokenResponse = {
-    token_type: "Bearer";
-    access_token: string;
-    scope: string;
-    refresh_token?: string;
-    expires_in?: number;
-    // from oidc-client-ts
-    expires_at?: number;
-    id_token: string;
-};
-
-/**
- * Make required properties required in type
- */
-type ValidSignInResponse = SigninResponse &
-    BearerTokenResponse & {
-        token_type: "Bearer" | "bearer";
-    };
-
-const isValidBearerTokenResponse = (response: unknown): response is ValidSignInResponse =>
-    isRecord(response) &&
-    requiredStringProperty(response, "token_type") &&
-    // token_type is case insensitive, some OPs return `token_type: "bearer"`
-    (response["token_type"] as string).toLowerCase() === "bearer" &&
-    requiredStringProperty(response, "access_token") &&
-    requiredStringProperty(response, "refresh_token") &&
-    (!("expires_in" in response) || typeof response["expires_in"] === "number");
-
-export function validateBearerTokenResponse(response: unknown): asserts response is ValidSignInResponse {
-    if (!isValidBearerTokenResponse(response)) {
-        throw new Error(OidcError.InvalidBearerTokenResponse);
-    }
-}