feat(auth): send PKCE code_challenge in updateUser when changing email (#1601)

spydon · web-flow · commit 59d349e43f87 · 2026-07-15T14:04:49.000+02:00
## Summary

Under the PKCE flow, `updateUser({ email })` now generates a PKCE code
verifier and sends the corresponding `code_challenge` /
`code_challenge_method` in the request body, mirroring what `resend()`
and `getSSOSignInUrl` already do. This lets an email change started
under PKCE complete via `exchangeCodeForSession()`.

The fields are only added when an email is being changed, so no public
API surface or return type changes. Non-PKCE flows are unaffected (the
challenge is `null`).

## Outcome

implemented

## Reference

- supabase-js parity, following the already-shipped Dart `resend()` PKCE
work (SDK-1023).

## Compliance matrix

- `auth.session.update_user` → `implemented` (was
`partially_implemented`).

## Tests

- Added mock tests in `packages/gotrue/test/otp_mock_test.dart`: PKCE
email change includes the code challenge, non-email updates omit it, and
implicit flow omits it.

Closes SDK-1318
diff --git a/packages/gotrue/lib/src/gotrue_client.dart b/packages/gotrue/lib/src/gotrue_client.dart
@@ -897,7 +897,17 @@ class GoTrueClient {
       throw AuthSessionMissingException();
     }
 
-    final body = attributes.toJson();
+    final codeChallenge = attributes.email != null
+        ? await _generatePKCECodeChallenge()
+        : null;
+
+    final body = {
+      ...attributes.toJson(),
+      if (attributes.email != null) ...{
+        'code_challenge': codeChallenge,
+        'code_challenge_method': codeChallenge != null ? 's256' : null,
+      },
+    };
     final options = GotrueRequestOptions(
       headers: _headers,
       body: body,
diff --git a/packages/gotrue/test/client_test.dart b/packages/gotrue/test/client_test.dart
@@ -745,6 +745,53 @@ void main() {
         expect(await emittedEvent, AuthChangeEvent.signedIn);
       },
     );
+
+    test(
+      'updateUser email change under PKCE can be exchanged for a session',
+      () async {
+        await http.post(
+          Uri.parse(
+            'http://127.0.0.1:54421/rest/v1/rpc/reset_and_init_auth_data',
+          ),
+          headers: {
+            'x-forwarded-for': '127.0.0.1',
+            'apikey': getServiceRoleToken(env),
+            'Authorization': 'Bearer ${getServiceRoleToken(env)}',
+          },
+        );
+        await http.delete(
+          Uri.parse('http://127.0.0.1:54424/api/v1/messages'),
+        );
+
+        final pkceClient = GoTrueClient(
+          url: gotrueUrl,
+          headers: {
+            'Authorization': 'Bearer $anonToken',
+            'apikey': anonToken,
+          },
+          asyncStorage: TestAsyncStorage(),
+          flowType: AuthFlowType.pkce,
+          autoRefreshToken: false,
+        );
+
+        await pkceClient.signInWithPassword(
+          email: email1,
+          password: password,
+        );
+
+        final updatedEmail = getNewEmail();
+        final updateResponse = await pkceClient.updateUser(
+          UserAttributes(email: updatedEmail),
+        );
+        expect(updateResponse.user?.newEmail, updatedEmail);
+
+        final code = await _pkceCodeFromEmailChange(updatedEmail);
+        final exchanged = await pkceClient.exchangeCodeForSession(code);
+
+        expect(exchanged.session.user.email, updatedEmail);
+        expect(exchanged.session.accessToken, isNotEmpty);
+      },
+    );
   });
 
   group('Recovering an already refreshed session', () {
@@ -807,3 +854,51 @@ void main() {
     });
   });
 }
+
+/// Reads the email-change confirmation link that GoTrue delivered to
+/// [toEmail] via the local Mailpit server, follows it, and returns the PKCE
+/// `code` from the redirect so it can be passed to [exchangeCodeForSession].
+Future<String> _pkceCodeFromEmailChange(String toEmail) async {
+  Map<String, dynamic>? message;
+  for (var attempt = 0; attempt < 20 && message == null; attempt++) {
+    final search =
+        jsonDecode(
+              (await http.get(
+                Uri.parse(
+                  'http://127.0.0.1:54424/api/v1/search?query=to:$toEmail',
+                ),
+              )).body,
+            )
+            as Map<String, dynamic>;
+    final messages = search['messages'] as List;
+    if (messages.isNotEmpty) {
+      message =
+          jsonDecode(
+                (await http.get(
+                  Uri.parse(
+                    'http://127.0.0.1:54424/api/v1/message/${messages.first['ID']}',
+                  ),
+                )).body,
+              )
+              as Map<String, dynamic>;
+    } else {
+      await Future.delayed(const Duration(milliseconds: 250));
+    }
+  }
+
+  final link = RegExp(r'http://127\.0\.0\.1:54421/auth/v1/verify\?\S+')
+      .firstMatch(message!['Text'] as String)!
+      .group(0)!
+      .replaceAll(RegExp(r'[)>].*$'), '');
+
+  final verifyClient = http.Client();
+  try {
+    final request = http.Request('GET', Uri.parse(link))
+      ..followRedirects = false;
+    final response = await verifyClient.send(request);
+    final location = response.headers['location']!;
+    return Uri.parse(location).queryParameters['code']!;
+  } finally {
+    verifyClient.close();
+  }
+}
diff --git a/packages/gotrue/test/mocks/otp_mock_client.dart b/packages/gotrue/test/mocks/otp_mock_client.dart
@@ -11,6 +11,7 @@ class OtpMockClient extends BaseClient {
   final String refreshToken;
 
   Map<String, dynamic>? lastResendBody;
+  Map<String, dynamic>? lastUpdateUserBody;
 
   OtpMockClient({
     this.phoneNumber = '+11234567890',
@@ -69,6 +70,11 @@ class OtpMockClient extends BaseClient {
       return _handleResend(requestBody);
     }
 
+    // Simulate updating the current user
+    if (url.contains('/user') && method == 'PUT') {
+      return _handleUpdateUser(requestBody);
+    }
+
     // Default response for unhandled requests
     return StreamedResponse(
       Stream.value(
@@ -312,6 +318,37 @@ class OtpMockClient extends BaseClient {
       request: null,
     );
   }
+
+  StreamedResponse _handleUpdateUser(Map<String, dynamic>? requestBody) {
+    lastUpdateUserBody = requestBody;
+    final now = DateTime.now().toIso8601String();
+
+    return StreamedResponse(
+      Stream.value(
+        utf8.encode(
+          jsonEncode({
+            'id': userId,
+            'aud': 'authenticated',
+            'role': 'authenticated',
+            'email': requestBody?['email'] ?? email,
+            'phone': requestBody?['phone'] ?? phoneNumber,
+            'confirmed_at': now,
+            'last_sign_in_at': now,
+            'created_at': now,
+            'updated_at': now,
+            'app_metadata': {
+              'provider': 'email',
+              'providers': ['email'],
+            },
+            'user_metadata': {},
+            'identities': [],
+          }),
+        ),
+      ),
+      200,
+      request: null,
+    );
+  }
 }
 
 /// A mock HTTP client that captures the channel parameter for testing
diff --git a/packages/gotrue/test/otp_mock_test.dart b/packages/gotrue/test/otp_mock_test.dart
@@ -333,6 +333,64 @@ void main() {
       expect(mockClient.lastResendBody?['code_challenge_method'], isNull);
     });
 
+    test(
+      'updateUser() with email in PKCE flow includes code challenge',
+      () async {
+        await client.verifyOTP(
+          phone: testPhone,
+          token: '123456',
+          type: OtpType.sms,
+        );
+
+        await client.updateUser(UserAttributes(email: testEmail));
+
+        expect(mockClient.lastUpdateUserBody?['code_challenge'], isNotNull);
+        expect(mockClient.lastUpdateUserBody?['code_challenge_method'], 's256');
+      },
+    );
+
+    test('updateUser() without email omits code challenge', () async {
+      await client.verifyOTP(
+        phone: testPhone,
+        token: '123456',
+        type: OtpType.sms,
+      );
+
+      await client.updateUser(UserAttributes(data: {'name': 'Test User'}));
+
+      expect(
+        mockClient.lastUpdateUserBody?.containsKey('code_challenge'),
+        isFalse,
+      );
+      expect(
+        mockClient.lastUpdateUserBody?.containsKey('code_challenge_method'),
+        isFalse,
+      );
+    });
+
+    test(
+      'updateUser() with email in implicit flow omits code challenge',
+      () async {
+        final implicitClient = GoTrueClient(
+          url: 'https://example.com',
+          httpClient: mockClient,
+          asyncStorage: asyncStorage,
+          flowType: AuthFlowType.implicit,
+        );
+
+        await implicitClient.verifyOTP(
+          phone: testPhone,
+          token: '123456',
+          type: OtpType.sms,
+        );
+
+        await implicitClient.updateUser(UserAttributes(email: testEmail));
+
+        expect(mockClient.lastUpdateUserBody?['code_challenge'], isNull);
+        expect(mockClient.lastUpdateUserBody?['code_challenge_method'], isNull);
+      },
+    );
+
     test('resend() with wrong type for phone throws', () async {
       await expectLater(
         client.resend(
diff --git a/sdk-compliance.yaml b/sdk-compliance.yaml
@@ -59,8 +59,7 @@ features:
   auth.session.refresh_session: implemented
   auth.session.get_user: implemented
   auth.session.update_user:
-    status: partially_implemented
-    note: "Does not send a PKCE code_challenge when changing email under the PKCE flow."
+    status: implemented
     symbols:
       - UserAttributes.currentPassword
   auth.session.get_claims: implemented
