@textrp/briij-js-sdk 41.0.0

package/src/oidc/authorize.ts

@@ -0,0 +1,279 @@
+/*
+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, 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";
+
+// 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}.
+ * @returns a Promise with the url as a string
+ */
+export const generateOidcAuthorizationUrl = async ({
+    metadata,
+    redirectUri,
+    clientId,
+    homeserverUrl,
+    identityServerUrl,
+    nonce,
+    prompt,
+    urlState,
+    loginHint,
+}: {
+    clientId: string;
+    metadata: ValidatedAuthMetadata;
+    homeserverUrl: string;
+    identityServerUrl?: string;
+    redirectUri: string;
+    nonce: string;
+    prompt?: string;
+    urlState?: string;
+    loginHint?: string;
+}): Promise<string> => {
+    const scope = generateScope();
+    const oidcClient = new OidcClient({
+        ...metadata,
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        authority: metadata.issuer,
+        response_mode: "query",
+        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 storedAuthorizationParams - stored params from start of oidc login flow
+ * @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,
+): 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);
+    reconstructedUrl.searchParams.append("code", code);
+    reconstructedUrl.searchParams.append("state", state);
+
+    // set oidc-client to use our logger
+    Log.setLogger(logger);
+    try {
+        const response = new SigninResponse(reconstructedUrl.searchParams);
+
+        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);
+        // 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);
+    }
+};

package/src/oidc/discovery.ts

@@ -0,0 +1,67 @@
+/*
+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 BriijClient#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: await metadataService.getSigningKeys(),
+    };
+};

package/src/oidc/error.ts

@@ -0,0 +1,33 @@
+/*
+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.
+*/
+
+/**
+ * Errors expected to be encountered during OIDC discovery, client registration, and authentication.
+ * Not intended to be displayed directly to the user.
+ */
+export enum OidcError {
+    NotSupported = "OIDC authentication not supported",
+    Misconfigured = "OIDC is misconfigured",
+    General = "Something went wrong with OIDC discovery",
+    OpSupport = "Configured OIDC OP does not support required functions",
+    DynamicRegistrationNotSupported = "Dynamic registration not supported",
+    DynamicRegistrationFailed = "Dynamic registration failed",
+    DynamicRegistrationInvalid = "Dynamic registration invalid response",
+    CodeExchangeFailed = "Failed to exchange code for token",
+    InvalidBearerTokenResponse = "Invalid bearer token response",
+    InvalidIdToken = "Invalid ID token",
+    MissingOrInvalidStoredState = "State required to finish logging in is not found in storage.",
+}

package/src/oidc/index.ts

@@ -0,0 +1,33 @@
+/*
+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;
+}

package/src/oidc/register.ts

@@ -0,0 +1,163 @@
+/*
+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);
+    }
+
+    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);
+        }
+    }
+};