feat: add support for OAuth 2.0 discovery, registration, resource indicators, and custom auth

pkgs/oauth2/lib/oauth2.dart

@@ -5,7 +5,10 @@
 export 'src/authorization_code_grant.dart';
 export 'src/authorization_exception.dart';
 export 'src/client.dart';
+export 'src/client_authenticator.dart';
 export 'src/client_credentials_grant.dart';
 export 'src/credentials.dart';
+export 'src/discovery.dart';
 export 'src/expiration_exception.dart';
+export 'src/registration.dart';
 export 'src/resource_owner_password_grant.dart';

pkgs/oauth2/lib/src/authorization_code_grant.dart

@@ -12,6 +12,7 @@ import 'package:http_parser/http_parser.dart';
 
 import 'authorization_exception.dart';
 import 'client.dart';
+import 'client_authenticator.dart';
 import 'credentials.dart';
 import 'handle_access_token_response.dart';
 import 'parameters.dart';
@@ -80,6 +81,9 @@ class AuthorizationCodeGrant {
   /// This will be passed as-is to the constructed [Client].
   final CredentialsRefreshedCallback? _onCredentialsRefreshed;
 
+  /// Custom client authenticator for injecting assertions or specific headers.
+  final ClientAuthenticator? _customAuth;
+
   /// Whether to use HTTP Basic authentication for authorizing the client.
   final bool _basicAuth;
 
@@ -155,12 +159,14 @@ class AuthorizationCodeGrant {
       CredentialsRefreshedCallback? onCredentialsRefreshed,
       Map<String, dynamic> Function(MediaType? contentType, String body)?
           getParameters,
-      String? codeVerifier})
+      String? codeVerifier,
+      ClientAuthenticator? customAuth})
       : _basicAuth = basicAuth,
         _httpClient = httpClient ?? http.Client(),
         _delimiter = delimiter ?? ' ',
         _getParameters = getParameters ?? parseJsonParameters,
         _onCredentialsRefreshed = onCredentialsRefreshed,
+        _customAuth = customAuth,
         _codeVerifier = codeVerifier ?? _createCodeVerifier();
 
   /// Returns the URL to which the resource owner should be redirected to
@@ -183,7 +189,7 @@ class AuthorizationCodeGrant {
   ///
   /// It is a [StateError] to call this more than once.
   Uri getAuthorizationUrl(Uri redirect,
-      {Iterable<String>? scopes, String? state}) {
+      {Iterable<String>? scopes, String? state, Iterable<Uri>? resources}) {
     if (_state != _State.initial) {
       throw StateError('The authorization URL has already been generated.');
     }
@@ -197,7 +203,7 @@ class AuthorizationCodeGrant {
     _redirectEndpoint = redirect;
     _scopes = scopeList;
     _stateString = state;
-    var parameters = {
+    var parameters = <String, dynamic>{
       'response_type': 'code',
       'client_id': identifier,
       'redirect_uri': redirect.toString(),
@@ -207,6 +213,9 @@ class AuthorizationCodeGrant {
 
     if (state != null) parameters['state'] = state;
     if (scopeList.isNotEmpty) parameters['scope'] = scopeList.join(_delimiter);
+    if (resources != null && resources.isNotEmpty) {
+      parameters['resource'] = resources.map((r) => r.toString()).toList();
+    }
 
     return addQueryParameters(authorizationEndpoint, parameters);
   }
@@ -297,15 +306,18 @@ class AuthorizationCodeGrant {
 
     var headers = <String, String>{};
 
-    var body = {
+    var body = <String, String>{
       'grant_type': 'authorization_code',
-      'code': authorizationCode,
-      'redirect_uri': _redirectEndpoint.toString(),
+      if (authorizationCode != null) 'code': authorizationCode,
+      if (_redirectEndpoint != null)
+        'redirect_uri': _redirectEndpoint.toString(),
       'code_verifier': _codeVerifier
     };
 
     var secret = this.secret;
-    if (_basicAuth && secret != null) {
+    if (_customAuth != null) {
+      await _customAuth(headers, body);
+    } else if (_basicAuth && secret != null) {
       headers['Authorization'] = basicAuthHeader(identifier, secret);
     } else {
       // The ID is required for this request any time basic auth isn't being
@@ -325,6 +337,7 @@ class AuthorizationCodeGrant {
         secret: secret,
         basicAuth: _basicAuth,
         httpClient: _httpClient,
+        customAuth: _customAuth,
         onCredentialsRefreshed: _onCredentialsRefreshed);
   }
 

pkgs/oauth2/lib/src/client.dart

@@ -9,6 +9,7 @@ import 'package:http/http.dart' as http;
 import 'package:http_parser/http_parser.dart';
 
 import 'authorization_exception.dart';
+import 'client_authenticator.dart';
 import 'credentials.dart';
 import 'expiration_exception.dart';
 
@@ -69,6 +70,9 @@ class Client extends http.BaseClient {
   /// Callback to be invoked whenever the credentials refreshed.
   final CredentialsRefreshedCallback? _onCredentialsRefreshed;
 
+  /// Custom client authenticator for injecting assertions or specific headers.
+  final ClientAuthenticator? _customAuth;
+
   /// Whether to use HTTP Basic authentication for authorizing the client.
   final bool _basicAuth;
 
@@ -90,11 +94,13 @@ class Client extends http.BaseClient {
       this.secret,
       CredentialsRefreshedCallback? onCredentialsRefreshed,
       bool basicAuth = true,
+      ClientAuthenticator? customAuth,
       http.Client? httpClient})
       : _basicAuth = basicAuth,
         _onCredentialsRefreshed = onCredentialsRefreshed,
+        _customAuth = customAuth,
         _httpClient = httpClient ?? http.Client() {
-    if (identifier == null && secret != null) {
+    if (_customAuth == null && identifier == null && secret != null) {
       throw ArgumentError('secret may not be passed without identifier.');
     }
   }
@@ -164,6 +170,7 @@ class Client extends http.BaseClient {
           secret: secret,
           newScopes: newScopes,
           basicAuth: _basicAuth,
+          customAuth: _customAuth,
           httpClient: _httpClient,
         );
         _credentials = await _refreshingFuture!;

pkgs/oauth2/lib/src/client_authenticator.dart

@@ -0,0 +1,10 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async';
+
+/// A callback used to add additional client authentication headers or body
+/// parameters to a token request (e.g., for JWT assertions per RFC 7523).
+typedef ClientAuthenticator = FutureOr<void> Function(
+    Map<String, String> headers, Map<String, String> body);

pkgs/oauth2/lib/src/client_credentials_grant.dart

@@ -8,6 +8,7 @@ import 'package:http/http.dart' as http;
 import 'package:http_parser/http_parser.dart';
 
 import 'client.dart';
+import 'client_authenticator.dart';
 import 'handle_access_token_response.dart';
 import 'utils.dart';
 
@@ -45,6 +46,8 @@ Future<Client> clientCredentialsGrant(
     bool basicAuth = true,
     http.Client? httpClient,
     String? delimiter,
+    ClientAuthenticator? customAuth,
+    Iterable<Uri>? resources,
     Map<String, dynamic> Function(MediaType? contentType, String body)?
         getParameters}) async {
   delimiter ??= ' ';
@@ -54,7 +57,10 @@ Future<Client> clientCredentialsGrant(
 
   var headers = <String, String>{};
 
-  if (identifier != null) {
+  if (customAuth != null) {
+    if (identifier != null) body['client_id'] = identifier;
+    await customAuth(headers, body);
+  } else if (identifier != null) {
     if (basicAuth) {
       headers['Authorization'] = basicAuthHeader(identifier, secret!);
     } else {
@@ -67,6 +73,34 @@ Future<Client> clientCredentialsGrant(
     body['scope'] = scopes.join(delimiter);
   }
 
+  if (resources != null && resources.isNotEmpty) {
+    // http.post doesn't support Map<String, Iterable> for x-www-form-urlencoded
+    // bodies, so we construct the body string manually to allow
+    // multiple 'resource' parameters per RFC 8707.
+    final encodedBody = body.entries
+        .map((e) => '${Uri.encodeQueryComponent(e.key)}='
+            '${Uri.encodeQueryComponent(e.value)}')
+        .toList();
+    for (final r in resources) {
+      encodedBody.add('resource=${Uri.encodeQueryComponent(r.toString())}');
+    }
+
+    httpClient ??= http.Client();
+    var response = await httpClient.post(authorizationEndpoint,
+        headers: headers
+          ..['content-type'] = 'application/x-www-form-urlencoded',
+        body: encodedBody.join('&'));
+
+    var credentials = handleAccessTokenResponse(response, authorizationEndpoint,
+        startTime, scopes?.toList() ?? [], delimiter,
+        getParameters: getParameters);
+    return Client(credentials,
+        identifier: identifier,
+        secret: secret,
+        httpClient: httpClient,
+        customAuth: customAuth);
+  }
+
   httpClient ??= http.Client();
   var response = await httpClient.post(authorizationEndpoint,
       headers: headers, body: body);
@@ -75,5 +109,8 @@ Future<Client> clientCredentialsGrant(
       startTime, scopes?.toList() ?? [], delimiter,
       getParameters: getParameters);
   return Client(credentials,
-      identifier: identifier, secret: secret, httpClient: httpClient);
+      identifier: identifier,
+      secret: secret,
+      httpClient: httpClient,
+      customAuth: customAuth);
 }

pkgs/oauth2/lib/src/credentials.dart

@@ -9,6 +9,7 @@ import 'dart:convert';
 import 'package:http/http.dart' as http;
 import 'package:http_parser/http_parser.dart';
 
+import 'client_authenticator.dart';
 import 'handle_access_token_response.dart';
 import 'parameters.dart';
 import 'utils.dart';
@@ -216,6 +217,8 @@ class Credentials {
       String? secret,
       Iterable<String>? newScopes,
       bool basicAuth = true,
+      ClientAuthenticator? customAuth,
+      Iterable<Uri>? resources,
       http.Client? httpClient}) async {
     var scopes = this.scopes;
     if (newScopes != null) scopes = newScopes.toList();
@@ -238,16 +241,44 @@ class Credentials {
 
     var headers = <String, String>{};
 
-    var body = {'grant_type': 'refresh_token', 'refresh_token': refreshToken};
+    var body = <String, String>{
+      'grant_type': 'refresh_token',
+      'refresh_token': refreshToken!,
+    };
     if (scopes.isNotEmpty) body['scope'] = scopes.join(_delimiter);
-
-    if (basicAuth && secret != null) {
+    if (customAuth != null) {
+      if (identifier != null) body['client_id'] = identifier;
+      await customAuth(headers, body);
+    } else if (basicAuth && secret != null) {
       headers['Authorization'] = basicAuthHeader(identifier!, secret);
     } else {
       if (identifier != null) body['client_id'] = identifier;
       if (secret != null) body['client_secret'] = secret;
     }
 
+    if (resources != null && resources.isNotEmpty) {
+      final encodedBody = body.entries
+          .map((e) => '${Uri.encodeQueryComponent(e.key)}='
+              '${Uri.encodeQueryComponent(e.value)}')
+          .toList();
+      for (final r in resources) {
+        encodedBody.add('resource=${Uri.encodeQueryComponent(r.toString())}');
+      }
+      headers['content-type'] = 'application/x-www-form-urlencoded';
+      var response = await httpClient.post(tokenEndpoint,
+          headers: headers, body: encodedBody.join('&'));
+      var credentials = handleAccessTokenResponse(
+          response, tokenEndpoint, startTime, scopes, _delimiter,
+          getParameters: _getParameters);
+      if (credentials.refreshToken != null) return credentials;
+      return Credentials(credentials.accessToken,
+          refreshToken: refreshToken,
+          idToken: credentials.idToken,
+          tokenEndpoint: credentials.tokenEndpoint,
+          scopes: credentials.scopes,
+          expiration: credentials.expiration);
+    }
+
     var response =
         await httpClient.post(tokenEndpoint, headers: headers, body: body);
     var credentials = handleAccessTokenResponse(