Find Firebase user(s) by federated user id

src/Firebase/Auth.php

@@ -59,7 +59,7 @@
 /**
  * @internal
  */
-final class Auth implements Contract\Auth
+final class Auth implements Contract\Auth, Contract\Transitional\FederatedUserFetcher
 {
     private readonly Parser $jwtParser;
 
@@ -210,6 +210,22 @@ public function getUserByPhoneNumber(Stringable|string $phoneNumber): UserRecord
         return UserRecord::fromResponseData($data['users'][0]);
     }
 
+    public function getUserByProviderUid(Stringable|string $providerId, Stringable|string $providerUid): UserRecord
+    {
+        $providerId = (string) $providerId;
+        $providerUid = (string) $providerUid;
+
+        $response = $this->client->getUserByProviderUid($providerId, $providerUid);
+
+        $data = Json::decode((string) $response->getBody(), true);
+
+        if (empty($data['users'][0])) {
+            throw new UserNotFound("No user with federated account ID '{$providerId}:{$providerUid}' found.");
+        }
+
+        return UserRecord::fromResponseData($data['users'][0]);
+    }
+
     public function createAnonymousUser(): UserRecord
     {
         return $this->createUser(CreateUser::new());

src/Firebase/Auth/ApiClient.php

@@ -118,6 +118,16 @@ public function getUserByPhoneNumber(string $phoneNumber): ResponseInterface
         return $this->requestApi($url, ['phoneNumber' => [$phoneNumber]]);
     }
 
+    /**
+     * @throws AuthException
+     */
+    public function getUserByProviderUid(string $providerId, string $uid): ResponseInterface
+    {
+        $url = $this->awareAuthResourceUrlBuilder->getUrl('/accounts:lookup');
+
+        return $this->requestApi($url, ['federatedUserId' => [['providerId' => $providerId, 'rawId' => $uid]]]);
+    }
+
     /**
      * @throws AuthException
      */

src/Firebase/Contract/Transitional/FederatedUserFetcher.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Contract\Transitional;
+
+use Kreait\Firebase\Auth\UserRecord;
+use Kreait\Firebase\Exception;
+use Stringable;
+
+/**
+ * @TODO: This interface is intended to be integrated into the Auth interface on the next major release.
+ */
+interface FederatedUserFetcher
+{
+    /**
+     * @param Stringable|non-empty-string $providerId
+     * @param Stringable|non-empty-string $providerUid
+     *
+     * @throws Exception\AuthException
+     * @throws Exception\FirebaseException
+     */
+    public function getUserByProviderUid(Stringable|string $providerId, Stringable|string $providerUid): UserRecord;
+}