matrix-js-sdk 41.9.0 → 42.0.0

package/lib/oauth/error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Errors expected to be encountered during OAuth2 discovery, client registration, and authentication.
+ * Not intended to be displayed directly to the user.
+ */
+export declare enum OAuth2Error {
+    General = "Something went wrong with OAuth2 discovery",
+    OpSupport = "Configured OAuth2 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",
+    InvalidDeviceAuthorizationResponse = "Invalid device authorization response",
+    MissingOrInvalidStoredState = "State required to finish logging in is not found in storage.",
+    RefreshTokenFailed = "Failed to refresh token",
+    RevokeTokenFailed = "Failed to revoke token",
+    DeviceAuthorizationGrantFailed = "Failed to perform device authorization grant"
+}
+//# sourceMappingURL=error.d.ts.map

package/lib/oauth/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/oauth/error.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,oBAAY,WAAW;IACnB,OAAO,+CAA+C;IACtD,SAAS,6DAA6D;IACtE,+BAA+B,uCAAuC;IACtE,yBAAyB,gCAAgC;IACzD,0BAA0B,0CAA0C;IACpE,kBAAkB,sCAAsC;IACxD,0BAA0B,kCAAkC;IAC5D,kCAAkC,0CAA0C;IAC5E,2BAA2B,iEAAiE;IAC5F,kBAAkB,4BAA4B;IAC9C,iBAAiB,2BAA2B;IAC5C,8BAA8B,iDAAiD;CAClF"}

package/lib/oauth/error.js

@@ -0,0 +1,36 @@
+/*
+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 OAuth2 discovery, client registration, and authentication.
+ * Not intended to be displayed directly to the user.
+ */
+export let OAuth2Error = /*#__PURE__*/function (OAuth2Error) {
+  OAuth2Error["General"] = "Something went wrong with OAuth2 discovery";
+  OAuth2Error["OpSupport"] = "Configured OAuth2 OP does not support required functions";
+  OAuth2Error["DynamicRegistrationNotSupported"] = "Dynamic registration not supported";
+  OAuth2Error["DynamicRegistrationFailed"] = "Dynamic registration failed";
+  OAuth2Error["DynamicRegistrationInvalid"] = "Dynamic registration invalid response";
+  OAuth2Error["CodeExchangeFailed"] = "Failed to exchange code for token";
+  OAuth2Error["InvalidBearerTokenResponse"] = "Invalid bearer token response";
+  OAuth2Error["InvalidDeviceAuthorizationResponse"] = "Invalid device authorization response";
+  OAuth2Error["MissingOrInvalidStoredState"] = "State required to finish logging in is not found in storage.";
+  OAuth2Error["RefreshTokenFailed"] = "Failed to refresh token";
+  OAuth2Error["RevokeTokenFailed"] = "Failed to revoke token";
+  OAuth2Error["DeviceAuthorizationGrantFailed"] = "Failed to perform device authorization grant";
+  return OAuth2Error;
+}({});
+//# sourceMappingURL=error.js.map

package/lib/oauth/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","names":[],"sources":["../../src/oauth/error.ts"],"sourcesContent":["/*\nCopyright 2023 The Matrix.org Foundation C.I.C.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n*/\n\n/**\n * Errors expected to be encountered during OAuth2 discovery, client registration, and authentication.\n * Not intended to be displayed directly to the user.\n */\nexport enum OAuth2Error {\n    General = \"Something went wrong with OAuth2 discovery\",\n    OpSupport = \"Configured OAuth2 OP does not support required functions\",\n    DynamicRegistrationNotSupported = \"Dynamic registration not supported\",\n    DynamicRegistrationFailed = \"Dynamic registration failed\",\n    DynamicRegistrationInvalid = \"Dynamic registration invalid response\",\n    CodeExchangeFailed = \"Failed to exchange code for token\",\n    InvalidBearerTokenResponse = \"Invalid bearer token response\",\n    InvalidDeviceAuthorizationResponse = \"Invalid device authorization response\",\n    MissingOrInvalidStoredState = \"State required to finish logging in is not found in storage.\",\n    RefreshTokenFailed = \"Failed to refresh token\",\n    RevokeTokenFailed = \"Failed to revoke token\",\n    DeviceAuthorizationGrantFailed = \"Failed to perform device authorization grant\",\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA,WAAY,WAAW,0BAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAX,WAAW;EAAA,OAAX,WAAW;AAAA","ignoreList":[]}

package/lib/oauth/index.d.ts

@@ -0,0 +1,87 @@
+import { type BearerTokenResponse, type DeviceAccessTokenError, type DeviceAccessTokenResponse, type DeviceAuthorizationResponse } from "./authorize.ts";
+import type { ValidatedAuthMetadata } from "./discover.ts";
+import { type OAuthRegistrationRequest } from "./register.ts";
+export * from "./authorize.ts";
+export * from "./error.ts";
+export * from "./register.ts";
+export * from "./tokenRefresher.ts";
+export * from "./discover.ts";
+/**
+ * Type representing the persistent context needed for typical OAuth flows
+ */
+type Context = {
+    /** The OAuth client ID */
+    clientId: string;
+    /** The desired device ID */
+    deviceId?: string;
+    /** The seed used to generate the challenge code */
+    codeVerifier?: string;
+    /** The URI to redirect the user to with credentials after auth */
+    redirectUri: string;
+};
+export declare class OAuth2 {
+    readonly metadata: ValidatedAuthMetadata;
+    /**
+     * 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 authMetadata - Auth config from {@link MatrixClient.getAuthMetadata}
+     * @param clientMetadata - The metadata for the client which to register,
+     *     grant_types & response_types & token_endpoint_auth_method will be sanely calculated if omitted.
+     * @returns Promise<string> resolved with registered clientId
+     * @throws when registration is not supported, on failed request or invalid response
+     */
+    static registerClient(authMetadata: ValidatedAuthMetadata, clientMetadata: OAuthRegistrationRequest): Promise<string>;
+    readonly context: Required<Context>;
+    constructor(metadata: ValidatedAuthMetadata, context: Context);
+    /**
+     * Generate a URL to attempt authorization with the OP
+     * See https://spec.matrix.org/v1.18/client-server-api/#authorization-code-flow
+     * @param state - A unique opaque identifier, like a transaction ID,
+     *     that will allow the client to maintain state between the authorization request and the callback.
+     *     The app should use this to key the storage for where the rest of the auth context is saved.
+     * @param responseMode - The manner in which the IdP should send the secrets back to the app. Defaults to `fragment` for privacy.
+     * @param prompt - Optional prompt parameter to pass to the IdP to signal intent, e.g. `create` for User registration.
+     * @param scope - The OAuth2 scope to request, will be generated based on the device ID if omitted.
+     * @returns a Promise with the url as a string
+     */
+    generateAuthorizationCodeGrantUrl(state: string, responseMode?: "fragment" | "query", prompt?: string, scope?: string): Promise<string>;
+    /**
+     * Attempt to exchange authorization code for bearer token.
+     *
+     * Takes the authorization code returned by the OAuth2 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 IdP during authorization
+     * @returns a validated bearer token response
+     * @throws An `Error` with `message` set to an entry in {@link OAuth2Error},
+     *      when the request fails, or the returned token response is invalid.
+     */
+    completeAuthorizationCodeGrant(code: string): Promise<BearerTokenResponse>;
+    /**
+     * Refresh the access token using the given refresh token and the refresh token grant
+     * @param refreshToken - the token to use to refresh the access token
+     */
+    performRefreshTokenGrant(refreshToken: string): Promise<BearerTokenResponse>;
+    /**
+     * Revokes the given token
+     * @param token - the token to remove
+     * @param type - the type of token, acts as a hint to the IdP
+     */
+    revokeToken(token: string, type?: "access_token" | "refresh_token"): Promise<void>;
+    /**
+     * Begin OAuth2 device authorization flow.
+     * @param scope - the scope to request for authorization.
+     * @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.
+     */
+    startDeviceAuthorizationGrant(scope?: string): Promise<DeviceAuthorizationResponse>;
+    /**
+     * Polls the OAuth2 token endpoint until we get a device access token response, or encounter an unrecoverable error.
+     * @param session - The session returned from a previous call to {@link OAuth2.startDeviceAuthorizationGrant}.
+     * @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.
+     */
+    waitForDeviceAuthorizationGrant(session: DeviceAuthorizationResponse): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError>;
+    private fetch;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EACH,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAMnC,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAEH,KAAK,wBAAwB,EAGhC,MAAM,eAAe,CAAC;AASvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAE9B;;GAEG;AACH,KAAK,OAAO,GAAG;IACX,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,qBAAa,MAAM;aA0EK,QAAQ,EAAE,qBAAqB;IAzEnD;;;;;;;;OAQG;IACH,OAAoB,cAAc,CAC9B,YAAY,EAAE,qBAAqB,EACnC,cAAc,EAAE,wBAAwB,GACzC,OAAO,CAAC,MAAM,CAAC,CAwDjB;IAED,SAAgB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAE3C,YACoB,QAAQ,EAAE,qBAAqB,EAC/C,OAAO,EAAE,OAAO,EAQnB;IAED;;;;;;;;;;OAUG;IACU,iCAAiC,CAC1C,KAAK,EAAE,MAAM,EACb,YAAY,GAAE,UAAU,GAAG,OAAoB,EAC/C,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAkBjB;IAED;;;;;;;;;;OAUG;IACU,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAatF;IAED;;;OAGG;IACU,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAWxF;IAED;;;;OAIG;IACU,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9F;IAED;;;;;OAKG;IACU,6BAA6B,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAM/F;IAED;;;;;OAKG;IACU,+BAA+B,CACxC,OAAO,EAAE,2BAA2B,GACrC,OAAO,CAAC,yBAAyB,GAAG,sBAAsB,CAAC,CAM7D;YAEa,KAAK;CAqBtB"}

package/lib/oauth/index.js

@@ -0,0 +1,234 @@
+import _objectSpread from "@babel/runtime/helpers/objectSpread2";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+/*
+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 { generateScope, normalizeBearerTokenResponseTokenType, startDeviceAuthorization, validateBearerTokenResponse, waitForDeviceAuthorization } from "./authorize.js";
+import { OAuthGrantType, urlHasCommonBase, validateRegistrationResponse } from "./register.js";
+import { encodeUnpaddedBase64Url } from "../base64.js";
+import { sha256 } from "../digest.js";
+import { HTTPError, Method } from "../http-api";
+import { logger } from "../logger.js";
+import { OAuth2Error } from "./error.js";
+import { secureRandomString } from "../randomstring.js";
+export * from "./authorize.js";
+export * from "./error.js";
+export * from "./register.js";
+export * from "./tokenRefresher.js";
+export * from "./discover.js";
+
+/**
+ * Type representing the persistent context needed for typical OAuth flows
+ */
+
+export class OAuth2 {
+  /**
+   * 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 authMetadata - Auth config from {@link MatrixClient.getAuthMetadata}
+   * @param clientMetadata - The metadata for the client which to register,
+   *     grant_types & response_types & token_endpoint_auth_method will be sanely calculated if omitted.
+   * @returns Promise<string> resolved with registered clientId
+   * @throws when registration is not supported, on failed request or invalid response
+   */
+  static async registerClient(authMetadata, clientMetadata) {
+    const defaultGrantTypes = [OAuthGrantType.AuthorizationCode, OAuthGrantType.RefreshToken];
+    // ask for device authorization grant if supported
+    if (authMetadata.grant_types_supported.includes(OAuthGrantType.DeviceAuthorization)) {
+      defaultGrantTypes.push(OAuthGrantType.DeviceAuthorization);
+    }
+    const grantTypes = clientMetadata.grant_types ?? defaultGrantTypes;
+    if (grantTypes.some(scope => !authMetadata.grant_types_supported.includes(scope))) {
+      throw new Error(OAuth2Error.DynamicRegistrationNotSupported);
+    }
+    const commonBase = new URL(clientMetadata.client_uri);
+    const request = _objectSpread(_objectSpread({
+      // Apply some defaults
+      response_types: ["code"],
+      token_endpoint_auth_method: "none"
+    }, clientMetadata), {}, {
+      grant_types: grantTypes,
+      logo_uri: urlHasCommonBase(commonBase, clientMetadata.logo_uri) ? clientMetadata.logo_uri : undefined,
+      policy_uri: urlHasCommonBase(commonBase, clientMetadata.policy_uri) ? clientMetadata.policy_uri : undefined,
+      tos_uri: urlHasCommonBase(commonBase, clientMetadata.tos_uri) ? clientMetadata.tos_uri : undefined
+    });
+    try {
+      const response = await fetch(authMetadata.registration_endpoint, {
+        method: Method.Post,
+        headers: {
+          "Accept": "application/json",
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(request)
+      });
+      if (response.status >= 400) {
+        throw new Error(OAuth2Error.DynamicRegistrationFailed);
+      }
+      const registrationResponse = await response.json();
+      if (validateRegistrationResponse(registrationResponse)) {
+        return registrationResponse.client_id;
+      }
+      throw new Error(OAuth2Error.DynamicRegistrationInvalid);
+    } catch (error) {
+      if (Object.values(OAuth2Error).includes(error.message)) {
+        throw error;
+      } else {
+        logger.error("Dynamic registration request failed", error);
+        throw new Error(OAuth2Error.DynamicRegistrationFailed);
+      }
+    }
+  }
+  constructor(metadata, context) {
+    _defineProperty(this, "context", void 0);
+    this.metadata = metadata;
+    this.context = {
+      clientId: context.clientId,
+      redirectUri: context.redirectUri,
+      deviceId: context.deviceId ?? secureRandomString(10),
+      codeVerifier: context.codeVerifier ?? secureRandomString(96)
+    };
+  }
+
+  /**
+   * Generate a URL to attempt authorization with the OP
+   * See https://spec.matrix.org/v1.18/client-server-api/#authorization-code-flow
+   * @param state - A unique opaque identifier, like a transaction ID,
+   *     that will allow the client to maintain state between the authorization request and the callback.
+   *     The app should use this to key the storage for where the rest of the auth context is saved.
+   * @param responseMode - The manner in which the IdP should send the secrets back to the app. Defaults to `fragment` for privacy.
+   * @param prompt - Optional prompt parameter to pass to the IdP to signal intent, e.g. `create` for User registration.
+   * @param scope - The OAuth2 scope to request, will be generated based on the device ID if omitted.
+   * @returns a Promise with the url as a string
+   */
+  async generateAuthorizationCodeGrantUrl(state, responseMode = "fragment", prompt, scope) {
+    const challenge = encodeUnpaddedBase64Url(await sha256(this.context.codeVerifier));
+    const url = new URL(this.metadata.authorization_endpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("response_mode", responseMode);
+    url.searchParams.set("client_id", this.context.clientId);
+    url.searchParams.set("redirect_uri", this.context.redirectUri);
+    url.searchParams.set("scope", scope ?? generateScope(this.context.deviceId));
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("code_challenge", challenge);
+    if (prompt) {
+      url.searchParams.set("prompt", prompt);
+    }
+    return url.toString();
+  }
+
+  /**
+   * Attempt to exchange authorization code for bearer token.
+   *
+   * Takes the authorization code returned by the OAuth2 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 IdP during authorization
+   * @returns a validated bearer token response
+   * @throws An `Error` with `message` set to an entry in {@link OAuth2Error},
+   *      when the request fails, or the returned token response is invalid.
+   */
+  async completeAuthorizationCodeGrant(code) {
+    const params = new URLSearchParams();
+    params.append("grant_type", "authorization_code");
+    params.append("client_id", this.context.clientId);
+    params.append("code_verifier", this.context.codeVerifier);
+    params.append("redirect_uri", this.context.redirectUri);
+    params.append("code", code);
+    const tokenResponse = await this.fetch("token", params, OAuth2Error.CodeExchangeFailed);
+
+    // throws when response is invalid
+    validateBearerTokenResponse(tokenResponse);
+    return normalizeBearerTokenResponseTokenType(tokenResponse);
+  }
+
+  /**
+   * Refresh the access token using the given refresh token and the refresh token grant
+   * @param refreshToken - the token to use to refresh the access token
+   */
+  async performRefreshTokenGrant(refreshToken) {
+    const params = new URLSearchParams();
+    params.append("grant_type", "refresh_token");
+    params.append("client_id", this.context.clientId);
+    params.append("refresh_token", refreshToken);
+    const tokenResponse = await this.fetch("token", params, OAuth2Error.RefreshTokenFailed);
+
+    // throws when response is invalid
+    validateBearerTokenResponse(tokenResponse);
+    return normalizeBearerTokenResponseTokenType(tokenResponse);
+  }
+
+  /**
+   * Revokes the given token
+   * @param token - the token to remove
+   * @param type - the type of token, acts as a hint to the IdP
+   */
+  async revokeToken(token, type) {
+    const params = new URLSearchParams();
+    params.append("token", token);
+    params.append("client_id", this.context.clientId);
+    if (type) {
+      params.append("token_type_hint", type);
+    }
+    await this.fetch("revocation", params, OAuth2Error.RevokeTokenFailed);
+    const headers = new Headers();
+    headers.set("Content-Type", "application/x-www-form-urlencoded");
+  }
+
+  /**
+   * Begin OAuth2 device authorization flow.
+   * @param scope - the scope to request for authorization.
+   * @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.
+   */
+  async startDeviceAuthorizationGrant(scope) {
+    return startDeviceAuthorization({
+      scope: scope ?? generateScope(this.context.deviceId),
+      metadata: this.metadata,
+      clientId: this.context.clientId
+    });
+  }
+
+  /**
+   * Polls the OAuth2 token endpoint until we get a device access token response, or encounter an unrecoverable error.
+   * @param session - The session returned from a previous call to {@link OAuth2.startDeviceAuthorizationGrant}.
+   * @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.
+   */
+  async waitForDeviceAuthorizationGrant(session) {
+    return waitForDeviceAuthorization({
+      session,
+      metadata: this.metadata,
+      clientId: this.context.clientId
+    });
+  }
+  async fetch(target, params, error) {
+    const url = this.metadata[`${target}_endpoint`];
+    const res = await fetch(url, {
+      method: Method.Post,
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": "application/json"
+      },
+      body: params
+    });
+    if (res.status >= 400) {
+      throw new HTTPError(error, res.status, res.headers);
+    }
+    return await res.json();
+  }
+}
+//# sourceMappingURL=index.js.map

package/lib/oauth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/oauth/index.ts"],"sourcesContent":["/*\nCopyright 2023 The Matrix.org Foundation C.I.C.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n*/\n\nimport {\n    type BearerTokenResponse,\n    type DeviceAccessTokenError,\n    type DeviceAccessTokenResponse,\n    type DeviceAuthorizationResponse,\n    generateScope,\n    normalizeBearerTokenResponseTokenType,\n    startDeviceAuthorization,\n    validateBearerTokenResponse,\n    waitForDeviceAuthorization,\n} from \"./authorize.ts\";\nimport type { ValidatedAuthMetadata } from \"./discover.ts\";\nimport {\n    OAuthGrantType,\n    type OAuthRegistrationRequest,\n    urlHasCommonBase,\n    validateRegistrationResponse,\n} from \"./register.ts\";\nimport { encodeUnpaddedBase64Url } from \"../base64.ts\";\nimport { sha256 } from \"../digest.ts\";\nimport { HTTPError, Method } from \"../http-api\";\nimport { logger } from \"../logger.ts\";\nimport { OAuth2Error } from \"./error.ts\";\nimport { secureRandomString } from \"../randomstring.ts\";\nimport { type NonEmptyArray } from \"../@types/common.ts\";\n\nexport * from \"./authorize.ts\";\nexport * from \"./error.ts\";\nexport * from \"./register.ts\";\nexport * from \"./tokenRefresher.ts\";\nexport * from \"./discover.ts\";\n\n/**\n * Type representing the persistent context needed for typical OAuth flows\n */\ntype Context = {\n    /** The OAuth client ID */\n    clientId: string;\n    /** The desired device ID */\n    deviceId?: string;\n    /** The seed used to generate the challenge code */\n    codeVerifier?: string;\n    /** The URI to redirect the user to with credentials after auth */\n    redirectUri: string;\n};\n\nexport class OAuth2 {\n    /**\n     * Attempts dynamic registration against the configured registration endpoint.\n     * Will ignore any URIs that do not use client_uri as a common base as per the spec.\n     * @param authMetadata - Auth config from {@link MatrixClient.getAuthMetadata}\n     * @param clientMetadata - The metadata for the client which to register,\n     *     grant_types & response_types & token_endpoint_auth_method will be sanely calculated if omitted.\n     * @returns Promise<string> resolved with registered clientId\n     * @throws when registration is not supported, on failed request or invalid response\n     */\n    public static async registerClient(\n        authMetadata: ValidatedAuthMetadata,\n        clientMetadata: OAuthRegistrationRequest,\n    ): Promise<string> {\n        const defaultGrantTypes: NonEmptyArray<string> = [\n            OAuthGrantType.AuthorizationCode,\n            OAuthGrantType.RefreshToken,\n        ];\n        // ask for device authorization grant if supported\n        if (authMetadata.grant_types_supported.includes(OAuthGrantType.DeviceAuthorization)) {\n            defaultGrantTypes.push(OAuthGrantType.DeviceAuthorization);\n        }\n\n        const grantTypes = clientMetadata.grant_types ?? defaultGrantTypes;\n        if (grantTypes.some((scope) => !authMetadata.grant_types_supported.includes(scope))) {\n            throw new Error(OAuth2Error.DynamicRegistrationNotSupported);\n        }\n\n        const commonBase = new URL(clientMetadata.client_uri);\n\n        const request: OAuthRegistrationRequest = {\n            // Apply some defaults\n            response_types: [\"code\"],\n            token_endpoint_auth_method: \"none\",\n            ...clientMetadata,\n            grant_types: grantTypes,\n            logo_uri: urlHasCommonBase(commonBase, clientMetadata.logo_uri) ? clientMetadata.logo_uri : undefined,\n            policy_uri: urlHasCommonBase(commonBase, clientMetadata.policy_uri) ? clientMetadata.policy_uri : undefined,\n            tos_uri: urlHasCommonBase(commonBase, clientMetadata.tos_uri) ? clientMetadata.tos_uri : undefined,\n        };\n\n        try {\n            const response = await fetch(authMetadata.registration_endpoint, {\n                method: Method.Post,\n                headers: {\n                    \"Accept\": \"application/json\",\n                    \"Content-Type\": \"application/json\",\n                },\n                body: JSON.stringify(request),\n            });\n\n            if (response.status >= 400) {\n                throw new Error(OAuth2Error.DynamicRegistrationFailed);\n            }\n\n            const registrationResponse = await response.json();\n            if (validateRegistrationResponse(registrationResponse)) {\n                return registrationResponse.client_id;\n            }\n\n            throw new Error(OAuth2Error.DynamicRegistrationInvalid);\n        } catch (error) {\n            if (Object.values(OAuth2Error).includes((error as Error).message as OAuth2Error)) {\n                throw error;\n            } else {\n                logger.error(\"Dynamic registration request failed\", error);\n                throw new Error(OAuth2Error.DynamicRegistrationFailed);\n            }\n        }\n    }\n\n    public readonly context: Required<Context>;\n\n    public constructor(\n        public readonly metadata: ValidatedAuthMetadata,\n        context: Context,\n    ) {\n        this.context = {\n            clientId: context.clientId,\n            redirectUri: context.redirectUri,\n            deviceId: context.deviceId ?? secureRandomString(10),\n            codeVerifier: context.codeVerifier ?? secureRandomString(96),\n        };\n    }\n\n    /**\n     * Generate a URL to attempt authorization with the OP\n     * See https://spec.matrix.org/v1.18/client-server-api/#authorization-code-flow\n     * @param state - A unique opaque identifier, like a transaction ID,\n     *     that will allow the client to maintain state between the authorization request and the callback.\n     *     The app should use this to key the storage for where the rest of the auth context is saved.\n     * @param responseMode - The manner in which the IdP should send the secrets back to the app. Defaults to `fragment` for privacy.\n     * @param prompt - Optional prompt parameter to pass to the IdP to signal intent, e.g. `create` for User registration.\n     * @param scope - The OAuth2 scope to request, will be generated based on the device ID if omitted.\n     * @returns a Promise with the url as a string\n     */\n    public async generateAuthorizationCodeGrantUrl(\n        state: string,\n        responseMode: \"fragment\" | \"query\" = \"fragment\",\n        prompt?: string,\n        scope?: string,\n    ): Promise<string> {\n        const challenge = encodeUnpaddedBase64Url(await sha256(this.context.codeVerifier));\n\n        const url = new URL(this.metadata.authorization_endpoint);\n        url.searchParams.set(\"response_type\", \"code\");\n        url.searchParams.set(\"response_mode\", responseMode);\n        url.searchParams.set(\"client_id\", this.context.clientId);\n        url.searchParams.set(\"redirect_uri\", this.context.redirectUri);\n        url.searchParams.set(\"scope\", scope ?? generateScope(this.context.deviceId));\n        url.searchParams.set(\"state\", state);\n        url.searchParams.set(\"code_challenge_method\", \"S256\");\n        url.searchParams.set(\"code_challenge\", challenge);\n\n        if (prompt) {\n            url.searchParams.set(\"prompt\", prompt);\n        }\n\n        return url.toString();\n    }\n\n    /**\n     * Attempt to exchange authorization code for bearer token.\n     *\n     * Takes the authorization code returned by the OAuth2 Provider via the authorization URL, and makes a\n     * request to the Token Endpoint, to obtain the access token, refresh token, etc.\n     *\n     * @param code - authorization code as returned by IdP during authorization\n     * @returns a validated bearer token response\n     * @throws An `Error` with `message` set to an entry in {@link OAuth2Error},\n     *      when the request fails, or the returned token response is invalid.\n     */\n    public async completeAuthorizationCodeGrant(code: string): Promise<BearerTokenResponse> {\n        const params = new URLSearchParams();\n        params.append(\"grant_type\", \"authorization_code\");\n        params.append(\"client_id\", this.context.clientId);\n        params.append(\"code_verifier\", this.context.codeVerifier);\n        params.append(\"redirect_uri\", this.context.redirectUri);\n        params.append(\"code\", code);\n\n        const tokenResponse = await this.fetch(\"token\", params, OAuth2Error.CodeExchangeFailed);\n\n        // throws when response is invalid\n        validateBearerTokenResponse(tokenResponse);\n        return normalizeBearerTokenResponseTokenType(tokenResponse);\n    }\n\n    /**\n     * Refresh the access token using the given refresh token and the refresh token grant\n     * @param refreshToken - the token to use to refresh the access token\n     */\n    public async performRefreshTokenGrant(refreshToken: string): Promise<BearerTokenResponse> {\n        const params = new URLSearchParams();\n        params.append(\"grant_type\", \"refresh_token\");\n        params.append(\"client_id\", this.context.clientId);\n        params.append(\"refresh_token\", refreshToken);\n\n        const tokenResponse = await this.fetch(\"token\", params, OAuth2Error.RefreshTokenFailed);\n\n        // throws when response is invalid\n        validateBearerTokenResponse(tokenResponse);\n        return normalizeBearerTokenResponseTokenType(tokenResponse);\n    }\n\n    /**\n     * Revokes the given token\n     * @param token - the token to remove\n     * @param type - the type of token, acts as a hint to the IdP\n     */\n    public async revokeToken(token: string, type?: \"access_token\" | \"refresh_token\"): Promise<void> {\n        const params = new URLSearchParams();\n        params.append(\"token\", token);\n        params.append(\"client_id\", this.context.clientId);\n        if (type) {\n            params.append(\"token_type_hint\", type);\n        }\n\n        await this.fetch(\"revocation\", params, OAuth2Error.RevokeTokenFailed);\n\n        const headers = new Headers();\n        headers.set(\"Content-Type\", \"application/x-www-form-urlencoded\");\n    }\n\n    /**\n     * Begin OAuth2 device authorization flow.\n     * @param scope - the scope to request for authorization.\n     * @returns a promise that resolves to a device access token response,\n     *   or an error response if the user denies authorization or the device code expires.\n     */\n    public async startDeviceAuthorizationGrant(scope?: string): Promise<DeviceAuthorizationResponse> {\n        return startDeviceAuthorization({\n            scope: scope ?? generateScope(this.context.deviceId),\n            metadata: this.metadata,\n            clientId: this.context.clientId,\n        });\n    }\n\n    /**\n     * Polls the OAuth2 token endpoint until we get a device access token response, or encounter an unrecoverable error.\n     * @param session - The session returned from a previous call to {@link OAuth2.startDeviceAuthorizationGrant}.\n     * @returns a promise that resolves to a device access token response,\n     *   or an error response if the user denies authorization or the device code expires.\n     */\n    public async waitForDeviceAuthorizationGrant(\n        session: DeviceAuthorizationResponse,\n    ): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError> {\n        return waitForDeviceAuthorization({\n            session,\n            metadata: this.metadata,\n            clientId: this.context.clientId,\n        });\n    }\n\n    private async fetch(\n        target: \"token\" | \"registration\" | \"revocation\",\n        params: URLSearchParams,\n        error: OAuth2Error,\n    ): Promise<unknown> {\n        const url = this.metadata[`${target}_endpoint`];\n        const res = await fetch(url, {\n            method: Method.Post,\n            headers: {\n                \"Content-Type\": \"application/x-www-form-urlencoded\",\n                \"Accept\": \"application/json\",\n            },\n            body: params,\n        });\n\n        if (res.status >= 400) {\n            throw new HTTPError(error, res.status, res.headers);\n        }\n\n        return await res.json();\n    }\n}\n"],"mappings":"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","ignoreList":[]}

package/lib/oauth/register.d.ts

@@ -0,0 +1,136 @@
+import { type NonEmptyArray } from "../@types/common.ts";
+type LocalizableKeys = "client_name" | "client_uri" | "policy_uri" | "tos_uri" | "logo_uri";
+/**
+ * Request body for dynamic registration as defined by https://spec.matrix.org/v1.18/client-server-api/#client-registration
+ */
+export type OAuthRegistrationRequest = {
+    /**
+     * Kind of the application.
+     *
+     * The homeserver MUST support the web and native values to be able to perform redirect URI validation.
+     *
+     * Defaults to web if omitted.
+     */
+    application_type?: "web" | "native";
+    /**
+     * Human-readable name of the client to be presented to the user.
+     *
+     * This field can be localized by specifying `client_name#$lang`.
+     */
+    client_name?: string;
+    /**
+     * A URL to a valid web page that SHOULD give the user more information about the client.
+     *
+     * This URL MUST use the https scheme and SHOULD NOT require authentication to access.
+     * It MUST NOT use a user or password in the authority component of the URI.
+     *
+     * The server MAY reject client registrations if this field is invalid or missing.
+     *
+     * This URI is a common base for all the other URIs in the metadata:
+     * those MUST be either on the same host or on a subdomain of the host of the client_uri.
+     * The port number, path and query components MAY be different.
+     *
+     * For example, if the client_uri is https://example.com/,
+     * then one of the redirect_uris can be https://example.com/callback or https://app.example.com/callback,
+     * but not https://app.com/callback.
+     *
+     * This field can be localized by specifying `client_uri#$lang`.
+     */
+    client_uri: string;
+    /**
+     * Array of the OAuth 2.0 grant types that the client may use.
+     *
+     * This MUST include:
+     *
+     * the authorization_code value to use the authorization code grant,
+     * the refresh_token value to use the refresh token grant.
+     */
+    grant_types?: NonEmptyArray<string>;
+    /**
+     * URL that references a logo for the client.
+     *
+     * This URL MUST use the https scheme.
+     *
+     * This field can be localized by specifying `logo_uri#$lang`.
+     */
+    logo_uri?: string;
+    /**
+     * URL that points to a human-readable policy document for the client.
+     *
+     * This URL MUST use the https scheme and SHOULD NOT require authentication to access.
+     * It MUST NOT use a user or password in the authority component of the URI.
+     *
+     * This field can be localized by specifying `policy_uri#$lang`.
+     */
+    policy_uri?: string;
+    /**
+     * Array of redirection URIs for use in redirect-based flows.
+     *
+     * At least one URI is required to use the authorization code grant.
+     */
+    redirect_uris?: NonEmptyArray<string>;
+    /**
+     * Array of the OAuth 2.0 response types that the client may use.
+     *
+     * This MUST include the code value to use the authorization code grant.
+     */
+    response_types?: NonEmptyArray<string>;
+    /**
+     * String indicator of the requested authentication method for the token endpoint.
+     */
+    token_endpoint_auth_method?: string;
+    /**
+     * URL that points to a human-readable terms of service document for the client.
+     *
+     * This URL MUST use the https scheme and SHOULD NOT require authentication to access.
+     * It MUST NOT use a user or password in the authority component of the URI.
+     *
+     * This field can be localized by specifying `tos_uri#$lang`.
+     */
+    tos_uri?: string;
+} & {
+    [K in `${LocalizableKeys}#${string}`]?: string;
+};
+/**
+ * The OAuth 2.0 grant types that are defined for Matrix in https://spec.matrix.org/v1.17/client-server-api/#grant-types
+ */
+export declare enum OAuthGrantType {
+    /**
+     * As per RFC 6749 section 4.1, the authorization code grant lets the client obtain an access token through a browser redirect.
+     *
+     * See https://spec.matrix.org/v1.18/client-server-api/#authorization-code-grant
+     */
+    AuthorizationCode = "authorization_code",
+    /**
+     * As per RFC 6749 section 6, the refresh token grant lets the client exchange a refresh token for an access token.
+     *
+     * https://spec.matrix.org/v1.18/client-server-api/#refresh-token-grant
+     */
+    RefreshToken = "refresh_token",
+    /**
+     * As per RFC 8628, the device authorization grant lets clients on devices with limited input capabilities obtain
+     * an access token by having the user complete authorization on a separate device with a web browser.
+     *
+     * See https://spec.matrix.org/v1.18/client-server-api/#device-authorization-grant
+     */
+    DeviceAuthorization = "urn:ietf:params:oauth:grant-type:device_code"
+}
+/**
+ * Check that URIs have a common base,
+ * as per https://spec.matrix.org/v1.18/client-server-api/#redirect-uri-validation
+ */
+export declare function urlHasCommonBase(base: URL, urlStr?: string): boolean;
+/**
+ * Response from dynamic registration
+ */
+type RegistrationResponse = {
+    client_id: string;
+};
+/**
+ * Validate the given response matches the format expected for a {@link RegistrationResponse}
+ * @param response - the response to validate
+ * @throws if the response does not match the expected format
+ */
+export declare function validateRegistrationResponse(response: unknown): response is RegistrationResponse;
+export {};
+//# sourceMappingURL=register.d.ts.map

package/lib/oauth/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/oauth/register.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,KAAK,eAAe,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5F;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACpC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;OAEG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG;KAEC,CAAC,IAAI,GAAG,eAAe,IAAI,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM;CACjD,CAAC;AAEF;;GAEG;AACH,oBAAY,cAAc;IACtB;;;;OAIG;IACH,iBAAiB,uBAAuB;IACxC;;;;OAIG;IACH,YAAY,kBAAkB;IAC9B;;;;;OAKG;IACH,mBAAmB,iDAAiD;CACvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAMpE;AAED;;GAEG;AACH,KAAK,oBAAoB,GAAG;IACxB,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,oBAAoB,CAEhG"}

package/lib/oauth/register.js

@@ -0,0 +1,73 @@
+/*
+Copyright 2023-2026 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 { hasRequiredStringProperty, isRecord } from "../@types/type-guards.js";
+
+/**
+ * Request body for dynamic registration as defined by https://spec.matrix.org/v1.18/client-server-api/#client-registration
+ */
+
+/**
+ * The OAuth 2.0 grant types that are defined for Matrix in https://spec.matrix.org/v1.17/client-server-api/#grant-types
+ */
+export let OAuthGrantType = /*#__PURE__*/function (OAuthGrantType) {
+  /**
+   * As per RFC 6749 section 4.1, the authorization code grant lets the client obtain an access token through a browser redirect.
+   *
+   * See https://spec.matrix.org/v1.18/client-server-api/#authorization-code-grant
+   */
+  OAuthGrantType["AuthorizationCode"] = "authorization_code";
+  /**
+   * As per RFC 6749 section 6, the refresh token grant lets the client exchange a refresh token for an access token.
+   *
+   * https://spec.matrix.org/v1.18/client-server-api/#refresh-token-grant
+   */
+  OAuthGrantType["RefreshToken"] = "refresh_token";
+  /**
+   * As per RFC 8628, the device authorization grant lets clients on devices with limited input capabilities obtain
+   * an access token by having the user complete authorization on a separate device with a web browser.
+   *
+   * See https://spec.matrix.org/v1.18/client-server-api/#device-authorization-grant
+   */
+  OAuthGrantType["DeviceAuthorization"] = "urn:ietf:params:oauth:grant-type:device_code";
+  return OAuthGrantType;
+}({});
+
+/**
+ * Check that URIs have a common base,
+ * as per https://spec.matrix.org/v1.18/client-server-api/#redirect-uri-validation
+ */
+export function urlHasCommonBase(base, urlStr) {
+  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;
+}
+
+/**
+ * Response from dynamic registration
+ */
+
+/**
+ * Validate the given response matches the format expected for a {@link RegistrationResponse}
+ * @param response - the response to validate
+ * @throws if the response does not match the expected format
+ */
+export function validateRegistrationResponse(response) {
+  return isRecord(response) && hasRequiredStringProperty(response, "client_id");
+}
+//# sourceMappingURL=register.js.map