feat: Add Multi-Resource Refresh Token (MRRT) support for Flutter Web (#864)

Author: utkrishtsahu

auth0_flutter/lib/auth0_flutter_web.dart

@@ -2,7 +2,7 @@ import 'package:auth0_flutter_platform_interface/auth0_flutter_platform_interfac
 import 'src/version.dart';
 
 export 'package:auth0_flutter_platform_interface/auth0_flutter_platform_interface.dart'
-    show WebException, CacheLocation;
+    show WebException, CacheLocation, ApiCredentials;
 
 /// Primary interface for interacting with Auth0 on web platforms.
 class Auth0Web {
@@ -66,6 +66,12 @@ class Auth0Web {
   /// to learn more.
   /// * [scopes] defaults to `openid profile email`. You can override these
   /// scopes, but `openid` is always requested regardless of this setting.
+  /// * [useMrrt] enables Multi-Resource Refresh Tokens, allowing a single
+  /// refresh token to be reused to obtain access tokens for multiple APIs
+  /// (audiences). Once enabled, request per-audience tokens via
+  /// [getApiCredentials]. Enabling this forces [useRefreshTokens] on (even if
+  /// it was explicitly set to `false`), and requires MRRT to be enabled on your
+  /// Auth0 tenant.
   Future<Credentials?> onLoad(
       {final int? authorizeTimeoutInSeconds,
       final CacheLocation? cacheLocation,
@@ -79,6 +85,7 @@ class Auth0Web {
       final bool? useFormData,
       final bool? useRefreshTokens,
       final bool? useRefreshTokensFallback,
+      final bool? useMrrt,
       final String? audience,
       final Set<String>? scopes,
       final Map<String, String> parameters = const {}}) async {
@@ -98,6 +105,7 @@ class Auth0Web {
             useFormData: useFormData,
             useRefreshTokens: useRefreshTokens,
             useRefreshTokensFallback: useRefreshTokensFallback,
+            useMrrt: useMrrt,
             audience: audience,
             scopes: scopes,
             parameters: {
@@ -369,6 +377,53 @@ class Auth0Web {
         ),
       );
 
+  /// Retrieves a set of [ApiCredentials] scoped to a specific API ([audience])
+  /// by reusing the stored refresh token via Multi-Resource Refresh Tokens
+  /// (MRRT).
+  ///
+  /// Enable MRRT by passing `useMrrt: true` to [onLoad]. This exchanges the
+  /// single refresh token obtained at login for an access token valid for the
+  /// requested [audience], without requiring the user to log in again.
+  ///
+  /// Additional notes:
+  /// * [scopes] are the scopes to request for the new access token. If empty,
+  /// the default scopes configured for the API are used.
+  /// * Arbitrary [parameters] can be specified and then picked up in a custom
+  /// Auth0 [Action](https://auth0.com/docs/customize/actions).
+  ///
+  /// **Prerequisites:**
+  /// * MRRT must be enabled on your Auth0 tenant.
+  /// * The user must have logged in with the `offline_access` scope so that a
+  /// refresh token is available for the exchange.
+  ///
+  /// **Throws** a [WebException] if the exchange fails.
+  Future<ApiCredentials> getApiCredentials({
+    required final String audience,
+    final Set<String> scopes = const {},
+    final Map<String, String> parameters = const {},
+  }) =>
+      Auth0FlutterWebPlatform.instance.getApiCredentials(
+        GetApiCredentialsOptions(
+          audience: audience,
+          scopes: scopes,
+          parameters: parameters,
+        ),
+      );
+
+  /// No-op on the web, kept for cross-platform API parity.
+  ///
+  /// `auth0-spa-js` manages API token caching internally and exposes no
+  /// single-audience eviction API, so this completes without removing anything
+  /// and logs a warning to the browser console. The [audience] and [scope]
+  /// arguments are accepted only for consistency with the mobile API.
+  Future<void> clearApiCredentials({
+    required final String audience,
+    final String? scope,
+  }) =>
+      Auth0FlutterWebPlatform.instance.clearApiCredentials(
+        ClearApiCredentialsOptions(audience: audience, scope: scope),
+      );
+
   /// Indicates whether a user is currently authenticated.
   Future<bool> hasValidCredentials() =>
       Auth0FlutterWebPlatform.instance.hasValidCredentials();

auth0_flutter/lib/src/web/auth0_flutter_plugin_real.dart

@@ -6,6 +6,7 @@ import 'package:flutter_web_plugins/flutter_web_plugins.dart';
 import 'package:web/web.dart';
 
 import 'auth0_flutter_web_platform_proxy.dart';
+import 'extensions/api_credentials_extension.dart';
 import 'extensions/client_options_extensions.dart';
 import 'extensions/credentials_extension.dart';
 import 'extensions/credentials_options_extension.dart';
@@ -173,6 +174,37 @@ class Auth0FlutterPlugin extends Auth0FlutterWebPlatform {
     }
   }
 
+  @override
+  Future<ApiCredentials> getApiCredentials(
+      final GetApiCredentialsOptions options) async {
+    final clientProxy = _ensureClient();
+    final tokenOptions = interop.GetTokenSilentlyOptions(
+        authorizationParams: JsInteropUtils.stripNulls(
+            JsInteropUtils.addCustomParams(
+                interop.GetTokenSilentlyAuthParams(
+                    audience: options.audience,
+                    scope: options.scopes.isNotEmpty
+                        ? options.scopes.join(' ')
+                        : null),
+                options.parameters)),
+        detailedResponse: true);
+    try {
+      final result = await clientProxy.getTokenSilently(tokenOptions);
+      return ApiCredentialsExtension.fromWeb(result);
+    } catch (e) {
+      throw WebExceptionExtension.fromJsObject(JSObject.fromInteropObject(e));
+    }
+  }
+
+  @override
+  Future<void> clearApiCredentials(
+      final ClearApiCredentialsOptions options) async {
+    console.warn(
+        "'clearApiCredentials' is not supported on the web. auth0-spa-js "
+                'handles credential storage automatically.'
+            .toJS);
+  }
+
   @override
   Future<bool> hasValidCredentials() => clientProxy!.isAuthenticated();
 

auth0_flutter/lib/src/web/extensions/api_credentials_extension.dart

@@ -0,0 +1,18 @@
+import 'dart:js_interop';
+
+import 'package:auth0_flutter_platform_interface/auth0_flutter_platform_interface.dart';
+
+import '../js_interop.dart';
+import 'string_extension.dart';
+
+extension ApiCredentialsExtension on ApiCredentials {
+  static ApiCredentials fromWeb(final WebCredentials webCredentials) {
+    final expiresIn = webCredentials.expires_in.toDartInt;
+    final expiresAt = DateTime.now().add(Duration(seconds: expiresIn));
+    return ApiCredentials(
+        accessToken: webCredentials.access_token,
+        tokenType: webCredentials.token_type ?? 'Bearer',
+        expiresAt: expiresAt,
+        scopes: {...webCredentials.scope?.splitBySingleSpace() ?? []});
+  }
+}

auth0_flutter/lib/src/web/extensions/client_options_extensions.dart

@@ -19,9 +19,14 @@ extension ClientOptionsExtension on ClientOptions {
           sessionCheckExpiryDays: sessionCheckExpiryInDays,
           useCookiesForTransactions: useCookiesForTransactions,
           useFormData: useFormData,
-          useRefreshTokens: useRefreshTokens,
+          // MRRT requires refresh tokens, so enabling it forces them on even
+          // if `useRefreshTokens` was explicitly set to false. `== true`
+          // null-guards the nullable flag (a bare `useMrrt ?` is not a valid
+          // bool condition).
+          useRefreshTokens: useMrrt == true ? true : useRefreshTokens,
           useRefreshTokensFallback: useRefreshTokensFallback,
           useDpop: useDPoP,
+          useMrrt: useMrrt,
           authorizationParams: JsInteropUtils.stripNulls(
               JsInteropUtils.addCustomParams(
                   AuthorizationParams(

auth0_flutter/lib/src/web/js_interop.dart

@@ -107,6 +107,7 @@ extension type Auth0ClientOptions._(JSObject _) implements JSObject {
       final bool? useRefreshTokens,
       final bool? useRefreshTokensFallback,
       final bool? useDpop,
+      final bool? useMrrt,
       final AuthorizationParams? authorizationParams});
 }
 

auth0_flutter/test/web/auth0_flutter_web_test.dart

@@ -316,6 +316,49 @@ void main() {
             e.message == 'test exception')));
   });
 
+  test('getApiCredentials exchanges the refresh token for an audience',
+      () async {
+    when(mockClientProxy.getTokenSilently(any))
+        .thenAnswer((final _) => Future.value(webCredentials));
+
+    final result = await auth0.getApiCredentials(
+        audience: 'http://my.api',
+        scopes: {'read:messages', 'write:messages'},
+        parameters: {'prompt': 'none'});
+
+    final options =
+        verify(mockClientProxy.getTokenSilently(captureAny)).captured.first;
+
+    expect(options.authorizationParams.audience, 'http://my.api');
+    expect(options.authorizationParams.scope, 'read:messages write:messages');
+    expect(options.authorizationParams.prompt, 'none');
+    expect(options.detailedResponse, true);
+
+    expect(result, isA<ApiCredentials>());
+    expect(result.accessToken, jwt);
+    expect(result.scopes, {'openid', 'read_messages'});
+  });
+
+  test('getApiCredentials is called and throws', () async {
+    when(mockClientProxy.getTokenSilently(any))
+        .thenThrow(createJsException('test', 'test exception'));
+
+    expect(
+        () async => auth0.getApiCredentials(audience: 'http://my.api'),
+        throwsA(predicate((final e) =>
+            e is WebException &&
+            e.code == 'test' &&
+            e.message == 'test exception')));
+  });
+
+  test('clearApiCredentials is a no-op and completes without throwing',
+      () async {
+    await expectLater(
+        auth0.clearApiCredentials(audience: 'http://my.api'), completes);
+
+    verifyNever(mockClientProxy.getTokenSilently(any));
+  });
+
   test('logout is called and succeeds', () async {
     when(mockClientProxy.logout(any)).thenAnswer((final _) => Future.value());
     await auth0.logout(federated: true, returnToUrl: 'http://returnto.url');

auth0_flutter/test/web/extensions/api_credentials_extension_test.dart

@@ -0,0 +1,51 @@
+@Tags(['browser'])
+
+import 'dart:js_interop';
+import 'package:auth0_flutter/src/web/extensions/api_credentials_extension.dart';
+import 'package:auth0_flutter/src/web/extensions/string_extension.dart';
+import 'package:auth0_flutter/src/web/js_interop.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  group('ApiCredentialsExtension', () {
+    test('creates ApiCredentials from WebCredentials with required values', () {
+      const accessToken = 'foo';
+      const expiresIn = 8400;
+      const expectedTokenType = 'Bearer';
+      final webCredentials = WebCredentials(
+        access_token: accessToken,
+        id_token: 'id',
+        expires_in: expiresIn.toJS,
+      );
+
+      final result = ApiCredentialsExtension.fromWeb(webCredentials);
+
+      expect(result.accessToken, accessToken);
+      expect(result.tokenType, expectedTokenType);
+      expect(
+          result.expiresAt.difference(
+            DateTime.now().add(const Duration(seconds: expiresIn)),
+          ),
+          lessThan(const Duration(seconds: 1)));
+      expect(result.scopes, isEmpty);
+    });
+
+    test('creates ApiCredentials from WebCredentials with optional values', () {
+      const accessToken = 'token';
+      const expiresIn = 1;
+      const scope = 'openid profile read:messages';
+      const tokenType = 'DPoP';
+      final webCredentials = WebCredentials(
+          access_token: accessToken,
+          id_token: 'id',
+          expires_in: expiresIn.toJS,
+          scope: scope,
+          token_type: tokenType);
+
+      final result = ApiCredentialsExtension.fromWeb(webCredentials);
+
+      expect(result.tokenType, tokenType);
+      expect(result.scopes, {...scope.splitBySingleSpace()});
+    });
+  });
+}

auth0_flutter/test/web/extensions/client_options_extension_test.dart

@@ -0,0 +1,46 @@
+@Tags(['browser'])
+
+import 'dart:js_interop';
+import 'dart:js_interop_unsafe';
+
+import 'package:auth0_flutter/src/web/extensions/client_options_extensions.dart';
+import 'package:auth0_flutter_platform_interface/auth0_flutter_platform_interface.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+bool? _readBool(final JSObject object, final String key) =>
+    (object.getProperty(key.toJS) as JSBoolean?)?.toDart;
+
+void main() {
+  final userAgent = UserAgent(name: 'auth0-flutter', version: '1.0.0');
+  const account = Account('test-domain', 'test-client-id');
+
+  group('ClientOptionsExtension MRRT', () {
+    test('useMrrt is forwarded and auto-enables refresh tokens', () {
+      final options = ClientOptions(account: account, useMrrt: true);
+
+      final result = options.toAuth0ClientOptions(userAgent) as JSObject;
+
+      expect(_readBool(result, 'useMrrt'), true);
+      // MRRT requires refresh tokens, so they are implicitly enabled.
+      expect(_readBool(result, 'useRefreshTokens'), true);
+    });
+
+    test('useMrrt forces refresh tokens on even when set to false', () {
+      final options = ClientOptions(
+          account: account, useMrrt: true, useRefreshTokens: false);
+
+      final result = options.toAuth0ClientOptions(userAgent) as JSObject;
+
+      expect(_readBool(result, 'useMrrt'), true);
+      expect(_readBool(result, 'useRefreshTokens'), true);
+    });
+
+    test('useMrrt is not enabled by default', () {
+      final options = ClientOptions(account: account);
+
+      final result = options.toAuth0ClientOptions(userAgent) as JSObject;
+
+      expect(_readBool(result, 'useMrrt'), isNull);
+    });
+  });
+}

auth0_flutter_platform_interface/lib/src/auth0_flutter_web_platform.dart

@@ -46,6 +46,16 @@ abstract class Auth0FlutterWebPlatform extends PlatformInterface {
     );
   }
 
+  Future<ApiCredentials> getApiCredentials(
+      final GetApiCredentialsOptions options) {
+    throw UnimplementedError('web.getApiCredentials has not been implemented');
+  }
+
+  Future<void> clearApiCredentials(final ClearApiCredentialsOptions options) {
+    throw UnimplementedError(
+        'web.clearApiCredentials has not been implemented');
+  }
+
   Future<bool> hasValidCredentials() {
     throw UnimplementedError(
       'web.hasValidCredentials has not been implemented',

auth0_flutter_platform_interface/lib/src/web/client_options.dart

@@ -111,6 +111,16 @@ class ClientOptions {
   /// Enables DPoP for token security. Defaults to `false`.
   final bool useDPoP;
 
+  /// Whether Multi-Resource Refresh Tokens (MRRT) are enabled, allowing a
+  /// single refresh token to be reused to obtain access tokens for multiple
+  /// APIs (audiences).
+  ///
+  /// MRRT requires refresh tokens, so enabling this forces [useRefreshTokens]
+  /// on, overriding it even if it was explicitly set to `false`.
+  ///
+  /// Defaults to `false`. Requires MRRT to be enabled on the Auth0 tenant.
+  final bool? useMrrt;
+
   ClientOptions(
       {required this.account,
       this.authorizeTimeoutInSeconds,
@@ -127,5 +137,6 @@ class ClientOptions {
       this.audience,
       this.scopes,
       this.parameters = const {},
-      this.useDPoP = false});
+      this.useDPoP = false,
+      this.useMrrt});
 }