feat: Implement UseUserAccessGroup for iOS

Implement the Firebase Authentication method UseUserAccessGroup in the C++ SDK.

This method allows specifying a user access group for keychain data sharing on iOS. It calls the underlying Objective-C method `[FIRAuth useUserAccessGroup:error:]`.

On other platforms (Android, Desktop), this method is a no-op stub, as the functionality is iOS-specific.

Author: google-labs-jules[bot]

auth/src/android/auth_android.cc

@@ -676,5 +676,13 @@ void DisableTokenAutoRefresh(AuthData* auth_data) {}
 void InitializeTokenRefresher(AuthData* auth_data) {}
 void DestroyTokenRefresher(AuthData* auth_data) {}
 
+#if !FIREBASE_PLATFORM_IOS
+// Stub for non-iOS platforms.
+void Auth::UseUserAccessGroup(const char* user_access_group) {
+  // This function is only implemented on iOS.
+  (void)user_access_group; // Mark as used to avoid compiler warnings.
+}
+#endif  // !FIREBASE_PLATFORM_IOS
+
 }  // namespace auth
 }  // namespace firebase

auth/src/auth.cc

@@ -373,5 +373,13 @@ AUTH_RESULT_FN(Auth, SignInWithEmailAndPassword, AuthResult)
 
 AUTH_RESULT_FN(Auth, CreateUserWithEmailAndPassword, AuthResult)
 
+#if !FIREBASE_PLATFORM_IOS
+// Stub for non-iOS platforms.
+void Auth::UseUserAccessGroup(const char* user_access_group) {
+  // This function is only implemented on iOS.
+  (void)user_access_group; // Mark as used to avoid compiler warnings.
+}
+#endif  // !FIREBASE_PLATFORM_IOS
+
 }  // namespace auth
 }  // namespace firebase

auth/src/desktop/auth_desktop.cc

@@ -768,5 +768,13 @@ void IdTokenRefreshThread::DisableAuthRefresh() {
   ref_count_--;
 }
 
+#if !FIREBASE_PLATFORM_IOS
+// Stub for non-iOS platforms.
+void Auth::UseUserAccessGroup(const char* user_access_group) {
+  // This function is only implemented on iOS.
+  (void)user_access_group; // Mark as used to avoid compiler warnings.
+}
+#endif  // !FIREBASE_PLATFORM_IOS
+
 }  // namespace auth
 }  // namespace firebase

auth/src/include/firebase/auth.h

@@ -428,6 +428,24 @@ class Auth {
   /// Get results of the most recent call to SendPasswordResetEmail.
   Future<void> SendPasswordResetEmailLastResult() const;
 
+  /// @brief Specifies a user access group for keychain data sharing for the
+  /// current app.
+  ///
+  /// @details This method is only functional on iOS. On other platforms, it is
+  /// a no-op.
+  ///
+  /// Setting this will allow the application to share user credentials with
+  /// other applications that are members of the same access group.
+  ///
+  /// After this is called, all future get and set keychain operations will use
+  /// the new user access group. By default, this is nil and credentials are
+  /// only accessible by the current application.
+  ///
+  /// @param[in] user_access_group The user access group string to use.
+  ///   Pass `nullptr` or an empty string to reset to the default (app-only)
+  ///   access group.
+  void UseUserAccessGroup(const char* user_access_group);
+
 #ifndef SWIG
   /// @brief Registers a listener to changes in the authentication state.
   ///

auth/src/ios/auth_ios.mm

@@ -608,5 +608,22 @@ void DisableTokenAutoRefresh(AuthData *auth_data) {}
 void InitializeTokenRefresher(AuthData *auth_data) {}
 void DestroyTokenRefresher(AuthData *auth_data) {}
 
+void Auth::UseUserAccessGroup(const char* user_access_group) {
+  if (!auth_data_) return;
+  NSString* access_group_nsstring = nil;
+  if (user_access_group != nullptr && strlen(user_access_group) > 0) {
+    access_group_nsstring = [NSString stringWithUTF8String:user_access_group];
+  }
+
+  NSError* error = nil;
+  BOOL success = [AuthImpl(auth_data_) useUserAccessGroup:access_group_nsstring error:&error];
+  if (!success || error) {
+    LogWarning("Error setting user access group: %s",
+               [[error localizedDescription] UTF8String]);
+    // Note: The C++ method is void, so we're not propagating the error further up.
+    // If specific error handling is needed in C++, the method signature would need to change.
+  }
+}
+
 }  // namespace auth
 }  // namespace firebase