Use stable /auth_metadata endpoint where homeserver supports v1.15 (#5174)

Author: hughns

spec/unit/matrix-client.spec.ts

@@ -3877,6 +3877,27 @@ describe("MatrixClient", function () {
             makeClient();
         });
 
+        it("should use stable prefix", async () => {
+            const metadata = mockOpenIdConfiguration();
+            client.getVersions = vi.fn().mockResolvedValue({
+                versions: ["v1.15"],
+            });
+            httpLookups = [
+                {
+                    method: "GET",
+                    path: `/auth_metadata`,
+                    data: metadata,
+                    prefix: "/_matrix/client/v1",
+                },
+            ];
+
+            await expect(client.getAuthMetadata()).resolves.toEqual({
+                ...metadata,
+                signingKeys: [],
+            });
+            expect(httpLookups.length).toEqual(0);
+        });
+
         it("should use unstable prefix", async () => {
             const metadata = mockOpenIdConfiguration();
             httpLookups = [

src/client.ts

@@ -8837,21 +8837,21 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }
 
     /**
-     * Discover and validate delegated auth configuration
-     * - delegated auth issuer openid-configuration is reachable
-     * - delegated auth issuer openid-configuration is configured correctly for us
+     * Discover and validate the auth metadata for the OAuth 2.0 API.
+     *
      * Fetches /auth_metadata falling back to legacy implementation using /auth_issuer followed by
      * https://oidc-issuer.example.com/.well-known/openid-configuration and other files linked therein.
-     * When successful, validated metadata is returned
+     * When successful, validated metadata is returned.
+     *
      * @returns validated authentication metadata and optionally signing keys
      * @throws when delegated auth config is invalid or unreachable
-     * @experimental - part of MSC2965
      */
     public async getAuthMetadata(): Promise<OidcClientConfig> {
         let authMetadata: unknown | undefined;
         try {
+            const useStable = await this.isVersionSupported("v1.15");
             authMetadata = await this.http.request<unknown>(Method.Get, "/auth_metadata", undefined, undefined, {
-                prefix: ClientPrefix.Unstable + "/org.matrix.msc2965",
+                prefix: useStable ? ClientPrefix.V1 : ClientPrefix.Unstable + "/org.matrix.msc2965",
             });
         } catch (e) {
             if (e instanceof MatrixError && e.errcode === "M_UNRECOGNIZED") {

src/oidc/validate.ts

@@ -22,7 +22,8 @@ import { OidcError } from "./error.ts";
 import { OAuthGrantType } from "./index.ts";
 
 /**
- * Metadata from OIDC authority discovery
+ * 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> &
@@ -36,7 +37,7 @@ export type ValidatedAuthMetadata = Partial<OidcMetadata> &
         | "grant_types_supported"
         | "code_challenge_methods_supported"
     > & {
-        // MSC2965 extensions to the OIDC spec
+        // MSC4191 extensions to the OIDC spec
         account_management_uri?: string;
         account_management_actions_supported?: string[];
         // The OidcMetadata type from oidc-client-ts does not include `prompt_values_supported`
@@ -80,9 +81,9 @@ const requiredArrayValue = (wellKnown: Record<string, unknown>, key: string, val
 };
 
 /**
- * Validates issuer `.well-known/openid-configuration`
- * As defined in RFC5785 https://openid.net/specs/openid-connect-discovery-1_0.html
- * validates that OP is compatible with Element's OIDC flow
+ * 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