Add App Check replay protection with transitional contract

Author: jeromegamez

CHANGELOG.md

@@ -7,6 +7,19 @@ If it saves you or your team time, please consider [sponsoring its development](
 The namespace remains `Kreait\Firebase` and the package name remains `kreait/firebase-php`.
 Please update your remote URL if you have forked or cloned the repository.
 
+## Unreleased
+
+### App Check
+
+* Added replay-protection verification for App Check tokens via `verifyTokenWithReplayProtection()`.
+  The response now includes `alreadyConsumed` when replay protection is used.
+* Added transitional contract `Kreait\Firebase\Contract\AppCheckWithReplayProtection`.
+  This was introduced to preserve backwards compatibility by avoiding a signature change to
+  `Kreait\Firebase\Contract\AppCheck::verifyToken()` in the current major release.
+* Added dedicated exception `Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckReplayProtection`
+  for replay-protection verification failures. It extends
+  `Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckToken` for backwards compatibility.
+
 ## 8.1.0 - 2026-01-23
 
 * Added support for `firebase/php-jwt:^7.0.2` 

NEXT_MAJOR_TODO.md

@@ -0,0 +1,9 @@
+# Next Major TODO
+
+## App Check Replay Protection
+
+- Context: `Kreait\Firebase\Contract\AppCheckWithReplayProtection` was introduced as a transitional contract
+  to preserve backwards compatibility in the current major release.
+- Fold replay protection into `Kreait\Firebase\Contract\AppCheck::verifyToken()` (e.g. argument/options),
+  and remove the transitional `Kreait\Firebase\Contract\AppCheckWithReplayProtection` contract.
+- Update docs and integration tests accordingly after the API consolidation.

docs/app-check.rst

@@ -35,11 +35,38 @@ See https://firebase.google.com/docs/app-check/custom-resource-backend for more
     $appCheckTokenString = '...';
 
     try {
-        $appCheck->verifyToken($appCheckTokenString);
+        $verification = $appCheck->verifyToken($appCheckTokenString);
     } catch (FailedToVerifyAppCheckToken $e) {
         // The token is invalid
     }
 
+To enable replay protection for a security-critical endpoint, use the replay-protection contract method.
+This performs an additional call to the App Check API and reports whether the token has already been consumed.
+
+.. note::
+   Replay protection is currently exposed through ``Kreait\Firebase\Contract\AppCheckWithReplayProtection`` as
+   a transitional API to avoid a backwards-incompatible signature change in ``AppCheck::verifyToken()`` and
+   preserve backwards compatibility in the current major version.
+   In the next major release, this should be folded into ``AppCheck::verifyToken()``.
+
+.. code-block:: php
+    use Kreait\Firebase\Contract\AppCheck;
+    use Kreait\Firebase\Contract\AppCheckWithReplayProtection;
+    use Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckReplayProtection;
+
+    /** @var AppCheck&AppCheckWithReplayProtection $appCheck */
+    $verification = null;
+
+    try {
+        $verification = $appCheck->verifyTokenWithReplayProtection($appCheckTokenString);
+    } catch (FailedToVerifyAppCheckReplayProtection $e) {
+        // The token could not be consumed for replay protection.
+    }
+
+    if ($verification?->alreadyConsumed === true) {
+        // Reject the request as a replay attempt.
+    }
+
 .. _create-a-custom-provider:
 
 ************************

src/AppCheck.php

@@ -10,14 +10,15 @@
 use Kreait\Firebase\AppCheck\AppCheckTokenOptions;
 use Kreait\Firebase\AppCheck\AppCheckTokenVerifier;
 use Kreait\Firebase\AppCheck\VerifyAppCheckTokenResponse;
+use Kreait\Firebase\Contract\AppCheckWithReplayProtection;
 use SensitiveParameter;
 
 use function is_array;
 
 /**
  * @internal
  */
-final readonly class AppCheck implements Contract\AppCheck
+final readonly class AppCheck implements Contract\AppCheck, AppCheckWithReplayProtection
 {
     public function __construct(
         private ApiClient $client,
@@ -40,8 +41,11 @@ public function createToken(string $appId, AppCheckTokenOptions|array|null $opti
 
     public function verifyToken(#[SensitiveParameter] string $appCheckToken): VerifyAppCheckTokenResponse
     {
-        $decodedToken = $this->tokenVerifier->verifyToken($appCheckToken);
+        return $this->tokenVerifier->verifyToken($appCheckToken);
+    }
 
-        return new VerifyAppCheckTokenResponse($decodedToken->app_id, $decodedToken);
+    public function verifyTokenWithReplayProtection(#[SensitiveParameter] string $appCheckToken): VerifyAppCheckTokenResponse
+    {
+        return $this->tokenVerifier->verifyToken($appCheckToken, true);
     }
 }

src/AppCheck/ApiClient.php

@@ -6,10 +6,13 @@
 
 use Beste\Json;
 use GuzzleHttp\ClientInterface;
+use Kreait\Firebase\Exception\AppCheck\AppCheckError;
 use Kreait\Firebase\Exception\AppCheckApiExceptionConverter;
 use Kreait\Firebase\Exception\AppCheckException;
 use Psr\Http\Message\ResponseInterface;
+use SensitiveParameter;
 use Throwable;
+use function is_bool;
 
 /**
  * @internal
@@ -46,6 +49,37 @@ public function exchangeCustomToken(string $appId, string $customToken): array
         return $decoded;
     }
 
+    /**
+     * @param non-empty-string $projectId
+     *
+     * @throws AppCheckException
+     */
+    public function verifyReplayProtection(#[SensitiveParameter] string $token, string $projectId): bool
+    {
+        $response = $this->post(
+            'https://firebaseappcheck.googleapis.com/v1beta/projects/'.$projectId.':verifyAppCheckToken',
+            [
+                'headers' => [
+                    'Content-Type' => 'application/json; UTF-8',
+                ],
+                'body' => Json::encode([
+                    'app_check_token' => $token,
+                ]),
+            ],
+        );
+
+        /** @var array{alreadyConsumed?: mixed} $decoded */
+        $decoded = Json::decode((string) $response->getBody(), true);
+
+        $alreadyConsumed = $decoded['alreadyConsumed'] ?? false;
+
+        if (!is_bool($alreadyConsumed)) {
+            throw new AppCheckError('The App Check API returned an invalid "alreadyConsumed" value.');
+        }
+
+        return $alreadyConsumed;
+    }
+
     /**
      * @param non-empty-string $path
      * @param array<string, mixed>|null $options

src/AppCheck/AppCheckTokenVerifier.php

@@ -6,6 +6,7 @@
 
 use Firebase\JWT\CachedKeySet;
 use Firebase\JWT\JWT;
+use Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckReplayProtection;
 use Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckToken;
 use Kreait\Firebase\Exception\AppCheck\InvalidAppCheckToken;
 use LogicException;
@@ -30,24 +31,40 @@
     public function __construct(
         private string $projectId,
         private CachedKeySet $keySet,
+        private ApiClient $apiClient,
     ) {
     }
 
     /**
      * Verifies the format and signature of a Firebase App Check token.
      *
      * @param string $token the Firebase Auth JWT token to verify
+     * @param bool $consume whether the token should be consumed for replay protection
      *
      * @throws FailedToVerifyAppCheckToken if the token could not be verified
+     * @throws FailedToVerifyAppCheckReplayProtection if replay protection could not be verified
      * @throws InvalidAppCheckToken if the token is invalid
      */
-    public function verifyToken(#[SensitiveParameter] string $token): DecodedAppCheckToken
+    public function verifyToken(#[SensitiveParameter] string $token, bool $consume = false): VerifyAppCheckTokenResponse
     {
         $decodedToken = $this->decodeJwt($token);
 
         $this->verifyContent($decodedToken);
 
-        return $decodedToken;
+        $alreadyConsumed = null;
+
+        if ($consume) {
+            try {
+                $alreadyConsumed = $this->apiClient->verifyReplayProtection($token, $this->projectId);
+            } catch (Throwable $e) {
+                throw new FailedToVerifyAppCheckReplayProtection(
+                    message: 'Unable to verify App Check token replay protection: '.$e->getMessage(),
+                    previous: $e,
+                );
+            }
+        }
+
+        return new VerifyAppCheckTokenResponse($decodedToken->app_id, $decodedToken, $alreadyConsumed);
     }
 
     /**

src/AppCheck/VerifyAppCheckTokenResponse.php

@@ -10,6 +10,7 @@
  * @phpstan-type VerifyAppCheckTokenResponseShape array{
  *     appId: non-empty-string,
  *     token: DecodedAppCheckTokenShape,
+ *     alreadyConsumed?: bool,
  * }
  */
 final readonly class VerifyAppCheckTokenResponse
@@ -20,6 +21,7 @@
     public function __construct(
         public string $appId,
         public DecodedAppCheckToken $token,
+        public ?bool $alreadyConsumed = null,
     ) {
     }
 }

src/Contract/AppCheckWithReplayProtection.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Contract;
+
+use Kreait\Firebase\AppCheck\VerifyAppCheckTokenResponse;
+use Kreait\Firebase\Exception;
+use Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckReplayProtection;
+use Kreait\Firebase\Exception\AppCheck\FailedToVerifyAppCheckToken;
+use Kreait\Firebase\Exception\AppCheck\InvalidAppCheckToken;
+use SensitiveParameter;
+
+/**
+ * Transitional contract for replay protection support.
+ *
+ * This interface exists to provide replay protection without changing the
+ * existing AppCheck::verifyToken() signature in a backwards-incompatible way.
+ * In a future major release, replay protection should be moved into
+ * AppCheck::verifyToken() as an additional argument/options parameter.
+ */
+interface AppCheckWithReplayProtection
+{
+    /**
+     * Verifies an App Check token and consumes it for replay protection.
+     *
+     * @param non-empty-string $appCheckToken
+     *
+     * @throws InvalidAppCheckToken
+     * @throws FailedToVerifyAppCheckToken
+     * @throws FailedToVerifyAppCheckReplayProtection
+     * @throws Exception\FirebaseException
+     */
+    public function verifyTokenWithReplayProtection(#[SensitiveParameter] string $appCheckToken): VerifyAppCheckTokenResponse;
+}

src/Exception/AppCheck/FailedToVerifyAppCheckReplayProtection.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Exception\AppCheck;
+
+final class FailedToVerifyAppCheckReplayProtection extends FailedToVerifyAppCheckToken
+{
+}

src/Exception/AppCheck/FailedToVerifyAppCheckToken.php

@@ -7,6 +7,6 @@
 use Kreait\Firebase\Exception\AppCheckException;
 use Kreait\Firebase\Exception\RuntimeException;
 
-final class FailedToVerifyAppCheckToken extends RuntimeException implements AppCheckException
+class FailedToVerifyAppCheckToken extends RuntimeException implements AppCheckException
 {
 }