Support for stable OAuth 2.0 API discovery with fallback to unstable MSC2965 .well-known

Uses the  /_matrix/client/v1/auth_metadata endpoint if available.
Uses discovery to choose the MSC4191 action parameter.

Author: hughns

MatrixSDK/Background/MXBackgroundStore.swift

@@ -253,6 +253,10 @@ class MXBackgroundStore: NSObject, MXStore {
     func storeHomeserverCapabilities(_ homeserverCapabilities: MXCapabilities) {
     }
 
+    var authMetadata: MXAuthMetadata?
+    func store(_ authMetadata: MXAuthMetadata) {
+    }
+
     var supportedMatrixVersions: MXMatrixVersions?
     func storeSupportedMatrixVersions(_ supportedMatrixVersions: MXMatrixVersions) {
     }

MatrixSDK/Data/Store/MXFileStore/MXFileStore.m

@@ -493,6 +493,20 @@ - (void)storeHomeserverCapabilities:(MXCapabilities *)capabilities
     }
 }
 
+- (MXAuthMetadata *)authMetadata
+{
+    return metaData.authMetadata;
+}
+
+- (void)storeAuthMetadata:(MXAuthMetadata *)authMetadata
+{
+    if (metaData)
+    {
+        metaData.authMetadata = authMetadata;
+        metaDataHasChanged = YES;
+    }
+}
+
 - (MXMatrixVersions *)supportedMatrixVersions
 {
     return metaData.supportedMatrixVersions;

MatrixSDK/Data/Store/MXFileStore/MXFileStoreMetaData.h

@@ -19,6 +19,7 @@
 #import "MXWellKnown.h"
 #import "MXCapabilities.h"
 #import "MXMatrixVersions.h"
+#import "MXAuthMetadata.h"
 
 @interface MXFileStoreMetaData : NSObject <NSCoding, NSCopying>
 
@@ -78,4 +79,9 @@
  */
 @property (nonatomic) NSInteger maxUploadSize;
 
+/**
+ OAuth 2.0 server metadata.
+ */
+@property (nonatomic) MXAuthMetadata *authMetadata;
+
 @end

MatrixSDK/Data/Store/MXMemoryStore/MXMemoryStore.m

@@ -41,6 +41,7 @@ @implementation MXMemoryStore
 @synthesize storeService, eventStreamToken, userAccountData, syncFilterId, homeserverWellknown, areAllIdentityServerTermsAgreed;
 @synthesize homeserverCapabilities;
 @synthesize supportedMatrixVersions;
+@synthesize authMetadata;
 
 - (instancetype)init
 {
@@ -410,6 +411,11 @@ - (void)storeSupportedMatrixVersions:(MXMatrixVersions *)supportedMatrixVersions
     supportedMatrixVersions = supportedMatrixVersions;
 }
 
+- (void)storeAuthMetadata:(MXAuthMetadata *)authMetadata
+{
+    authMetadata = authMetadata;
+}
+
 - (NSInteger)maxUploadSize
 {
     return self->maxUploadSize;

MatrixSDK/Data/Store/MXNoStore/MXNoStore.m

@@ -480,6 +480,14 @@ - (void)storeHomeserverCapabilities:(MXCapabilities *)homeserverCapabilities
 {
 }
 
+- (MXAuthMetadata *)authMetadata
+{
+    return nil;
+}
+- (void)storeAuthMetadata:(MXAuthMetadata *)authMetadata
+{
+}
+
 - (MXMatrixVersions *)supportedMatrixVersions
 {
     return nil;

MatrixSDK/Data/Store/MXStore.h

@@ -34,6 +34,7 @@
 @class MXStoreService;
 @class MXCapabilities;
 @class MXMatrixVersions;
+@class MXAuthMetadata;
 
 /**
  The `MXStore` protocol defines an interface that must be implemented in order to store
@@ -407,6 +408,18 @@
  */
 - (void)storeSupportedMatrixVersions:(nonnull MXMatrixVersions*)supportedMatrixVersions;
 
+/**
+ The homeserver OAuth 2.0 server metadata.
+ */
+@property (nonatomic, readonly) MXAuthMetadata * _Nullable authMetadata;
+
+/**
+ Store the homeserver OAuth 2.0 server metadata.
+
+ @param authMetadata the homeserver OAuth 2.0 server metadata to store.
+ */
+- (void)storeAuthMetadata:(nonnull MXAuthMetadata*)authMetadata;
+
 #pragma mark - Room Messages
 
 /**

MatrixSDK/JSONModels/Authentication/MXAuthMetadata.h

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 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 <Foundation/Foundation.h>
+
+#import "MXJSONModel.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ Subset of OAuth 2.0 API Server metadata: https://spec.matrix.org/v1.16/client-server-api/#server-metadata-discovery
+ {
+    "issuer": "https://example.com/",
+    "account_management_uri": "https://example.com/account",
+    "account_management_actions_supported": ["org.matrix.profile", "org.matrix.device_delete"]
+ }
+ */
+
+@interface MXAuthMetadata : MXJSONModel<NSCoding>
+
+@property (nonatomic, readonly) NSString *issuer;
+@property (nonatomic, readonly, nullable) NSString *accountManagementUri;
+@property (nonatomic, readonly, nullable) NSArray<NSString*> *accountManagementActionsSupported;
+
+-(NSURL * _Nullable) getLogoutDeviceURLFromID: (NSString * ) deviceID;
+
+@end
+
+NS_ASSUME_NONNULL_END

MatrixSDK/JSONModels/Authentication/MXAuthMetadata.m

@@ -0,0 +1,99 @@
+//
+// Copyright 2025 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 "MXAuthMetadata.h"
+
+static NSString *const kMXIssuer = @"issuer";
+static NSString *const kMXAccountManagementUri = @"account_management_uri";
+static NSString *const kMXAccountManagementActionsSupported = @"account_management_actions_supported";
+
+@interface MXAuthMetadata ()
+
+@property (nonatomic, readwrite) NSString *issuer;
+@property (nonatomic, readwrite, nullable) NSString *accountManagementUri;
+@property (nonatomic, readwrite, nullable) NSArray<NSString*> *accountManagementActionsSupported;
+
+@end
+
+@implementation MXAuthMetadata
+
++ (instancetype)modelFromJSON:(NSDictionary *)JSONDictionary
+{
+    MXAuthMetadata *oauthMetadata;
+
+    NSString *issuer;
+    MXJSONModelSetString(issuer, JSONDictionary[kMXIssuer]);
+    
+    if (issuer)
+    {
+        oauthMetadata = [[MXAuthMetadata alloc] init];
+        oauthMetadata.issuer = issuer;
+        MXJSONModelSetString(oauthMetadata.accountManagementUri, JSONDictionary[kMXAccountManagementUri])
+        MXJSONModelSetArray(oauthMetadata.accountManagementActionsSupported, JSONDictionary[kMXAccountManagementActionsSupported])
+    }
+
+    return oauthMetadata;
+}
+
+-(NSURL * _Nullable) getLogoutDeviceURLFromID: (NSString * ) deviceID
+{
+    if (!_accountManagementUri)
+    {
+        return nil;
+    }
+    NSURLComponents *components = [NSURLComponents componentsWithString:_accountManagementUri];
+    // default to the stable value
+    NSString *actionParam = @"org.matrix.device_delete";
+    if ([_accountManagementActionsSupported containsObject: @"org.matrix.delete_device"]) {
+        // use the stable value
+    } else if ([_accountManagementActionsSupported containsObject: @"org.matrix.session_end"]) {
+        // earlier version of MSC4191
+        actionParam = @"org.matrix.session_end";
+    } else if ([_accountManagementActionsSupported containsObject: @"session_end"]) {
+        // previous unspecced version
+        actionParam = @"session_end";
+    }
+
+    components.queryItems = @[
+        [NSURLQueryItem queryItemWithName:@"device_id" value:deviceID],
+        [NSURLQueryItem queryItemWithName:@"action" value:actionParam]
+    ];
+    return components.URL;
+}
+
+
+#pragma mark - NSCoding
+
+- (id)initWithCoder:(NSCoder *)aDecoder
+{
+    self = [super init];
+    if (self)
+    {
+        _issuer = [aDecoder decodeObjectForKey:kMXIssuer];
+        _accountManagementUri = [aDecoder decodeObjectForKey: kMXAccountManagementUri];
+        _accountManagementActionsSupported = [aDecoder decodeObjectForKey: kMXAccountManagementActionsSupported];
+    }
+    return self;
+}
+
+- (void)encodeWithCoder:(NSCoder *)aCoder
+{
+    [aCoder encodeObject:_issuer forKey:kMXIssuer];
+    [aCoder encodeObject:_accountManagementUri forKey:kMXAccountManagementUri];
+    [aCoder encodeObject:_accountManagementActionsSupported forKey:kMXAccountManagementActionsSupported];
+}
+
+@end

MatrixSDK/MXRestClient.h

@@ -45,6 +45,7 @@
 #import "MXTaggedEvents.h"
 #import "MXCredentials.h"
 #import "MXRoomAliasResolution.h"
+#import "MXAuthMetadata.h"
 
 @class MXThirdpartyProtocolsResponse;
 @class MXThirdPartyUsersResponse;
@@ -3107,6 +3108,20 @@ Note: Clients should consider avoiding this endpoint for URLs posted in encrypte
 - (MXHTTPOperation*)homeServerCapabilitiesWithSuccess:(void (^)(MXHomeserverCapabilities *capabilities))success
                                               failure:(void (^)(NSError *error))failure NS_REFINED_FOR_SWIFT;
 
+#pragma mark - Homeserver OAuth 2.0 server metadata
+
+/**
+ Get the homeserver OAuth 2.0 server metadata.
+
+ @param success A block object called when the operation succeeds. It provides
+                the metadata.
+ @param failure A block object called when the operation fails.
+
+ @return a MXHTTPOperation instance.
+ */
+- (MXHTTPOperation*)authMetadata:(void (^)(MXAuthMetadata *authMetadata))success
+                         failure:(void (^)(NSError *error))failure;
+
 @end
 
 MX_ASSUME_MISSING_NULLABILITY_END

MatrixSDK/MXRestClient.m

@@ -601,6 +601,34 @@ - (MXHTTPOperation *)capabilities:(void (^)(MXCapabilities *))success
     return operation;
 }
 
+- (MXHTTPOperation*)authMetadata:(void (^)(MXAuthMetadata *authMetadata))success
+                        failure:(void (^)(NSError *error))failure
+{
+    NSString *path = @"_matrix/client/v1/auth_metadata";
+
+    MXWeakify(self);
+    return [httpClient requestWithMethod:@"GET"
+                                    path:path
+                              parameters:nil
+                                 success:^(NSDictionary *JSONResponse) {
+                                     MXStrongifyAndReturnIfNil(self);
+
+                                     if (success)
+                                     {
+                                         __block MXAuthMetadata *authMetadata;
+                                         [self dispatchProcessing:^{
+                                             MXJSONModelSetMXJSONModel(authMetadata, MXAuthMetadata, JSONResponse);
+                                         } andCompletion:^{
+                                             success(authMetadata);
+                                         }];
+                                     }
+                                 }
+                                 failure:^(NSError *error) {
+                                     MXStrongifyAndReturnIfNil(self);
+                                     [self dispatchFailure:error inBlock:failure];
+                                 }];
+}
+
 #pragma mark - Registration operations
 - (MXHTTPOperation *)testUserRegistration:(NSString *)username callback:(void (^)(MXError *mxError))callback
 {