From 4e032317fe80ccb8359d97237af6562d9d6cc402 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@users.noreply.github.com>
Date: Fri, 23 Jan 2026 09:50:12 +0000
Subject: [PATCH] Add support for stable OAuth2.0 aware feature from MSC3824
 (#5159)

* Add support for stable OAuth2.0 aware feature from MSC3824

* Use stable name internally

* Mark DELEGATED_OIDC_COMPATIBILITY as

* Add tsdoc config for @alias JSDoc modifier
---
 spec/unit/login.spec.ts |  3 +++
 src/@types/auth.ts      | 14 ++++++++++----
 src/client.ts           |  1 +
 tsdoc.json              | 11 +++++++++++
 4 files changed, 25 insertions(+), 4 deletions(-)
 create mode 100644 tsdoc.json

diff --git a/spec/unit/login.spec.ts b/spec/unit/login.spec.ts
index 68cea4a9e..c0a2c4fea 100644
--- a/spec/unit/login.spec.ts
+++ b/spec/unit/login.spec.ts
@@ -51,18 +51,21 @@ describe("SSO login URL", function () {
             const urlString = client.client.getSsoLoginUrl(redirectUri, undefined, undefined, undefined);
             const url = new URL(urlString);
             expect(url.searchParams.has("org.matrix.msc3824.action")).toBe(false);
+            expect(url.searchParams.has("action")).toBe(false);
         });
 
         it("register", function () {
             const urlString = client.client.getSsoLoginUrl(redirectUri, undefined, undefined, SSOAction.REGISTER);
             const url = new URL(urlString);
             expect(url.searchParams.get("org.matrix.msc3824.action")).toEqual("register");
+            expect(url.searchParams.get("action")).toEqual("register");
         });
 
         it("login", function () {
             const urlString = client.client.getSsoLoginUrl(redirectUri, undefined, undefined, SSOAction.LOGIN);
             const url = new URL(urlString);
             expect(url.searchParams.get("org.matrix.msc3824.action")).toEqual("login");
+            expect(url.searchParams.get("action")).toEqual("login");
         });
     });
 });
diff --git a/src/@types/auth.ts b/src/@types/auth.ts
index d3782e17c..21e706d36 100644
--- a/src/@types/auth.ts
+++ b/src/@types/auth.ts
@@ -48,11 +48,17 @@ export interface IPasswordFlow extends ILoginFlow {
     type: "m.login.password";
 }
 
-export const DELEGATED_OIDC_COMPATIBILITY = new UnstableValue(
-    "delegated_oidc_compatibility",
+export const OAUTH_AWARE_PREFERRED_FLOW_FIELD = new UnstableValue(
+    "oauth_aware_preferred",
     "org.matrix.msc3824.delegated_oidc_compatibility",
 );
 
+/**
+ * @alias
+ * @deprecated use `OAUTH_AWARE_PREFERRED_FLOW_FIELD` instead.
+ */
+export const DELEGATED_OIDC_COMPATIBILITY = OAUTH_AWARE_PREFERRED_FLOW_FIELD;
+
 /**
  * Representation of SSO flow as per https://spec.matrix.org/v1.3/client-server-api/#client-login-via-sso
  */
@@ -60,8 +66,8 @@ export interface ISSOFlow extends ILoginFlow {
     type: "m.login.sso" | "m.login.cas";
     // eslint-disable-next-line camelcase
     identity_providers?: IIdentityProvider[];
-    [DELEGATED_OIDC_COMPATIBILITY.name]?: boolean;
-    [DELEGATED_OIDC_COMPATIBILITY.altName]?: boolean;
+    [OAUTH_AWARE_PREFERRED_FLOW_FIELD.name]?: boolean;
+    [OAUTH_AWARE_PREFERRED_FLOW_FIELD.altName]?: boolean;
 }
 
 export enum IdentityProviderBrand {
diff --git a/src/client.ts b/src/client.ts
index e6756f9ac..cfb6e0276 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -6689,6 +6689,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
 
         const params = {
             redirectUrl,
+            [SSO_ACTION_PARAM.stable!]: action,
             [SSO_ACTION_PARAM.unstable!]: action,
         };
 
diff --git a/tsdoc.json b/tsdoc.json
new file mode 100644
index 000000000..46bc17436
--- /dev/null
+++ b/tsdoc.json
@@ -0,0 +1,11 @@
+{
+    "$schema": "https://developer.microsoft.com/en-us/json-schemas/tsdoc/v0/tsdoc.schema.json",
+    "extends": ["typedoc/tsdoc.json"],
+    "noStandardTags": false,
+    "tagDefinitions": [
+        {
+            "tagName": "@alias",
+            "syntaxKind": "modifier"
+        }
+    ]
+}