feat(messaging, web): add support for debug tokens on Web (#18057)

Lyokone · web-flow · commit b853386e987d · 2026-03-03T16:04:52.000+01:00
* feat(messaging, web): add support for debug tokens on Web

* format

* fix analyze
diff --git a/packages/firebase_app_check/firebase_app_check/example/lib/main.dart b/packages/firebase_app_check/firebase_app_check/example/lib/main.dart
@@ -23,7 +23,9 @@ Future<void> main() async {
   await FirebaseAppCheck.instance
       // Your personal reCaptcha public key goes here:
       .activate(
-    providerWeb: ReCaptchaV3Provider(kWebRecaptchaSiteKey),
+    providerWeb: kDebugMode
+        ? WebDebugProvider()
+        : ReCaptchaV3Provider(kWebRecaptchaSiteKey),
     providerAndroid: const AndroidDebugProvider(),
     providerApple: const AppleDebugProvider(),
   );
diff --git a/packages/firebase_app_check/firebase_app_check/lib/firebase_app_check.dart b/packages/firebase_app_check/firebase_app_check/lib/firebase_app_check.dart
@@ -20,7 +20,8 @@ export 'package:firebase_app_check_platform_interface/firebase_app_check_platfor
         AppleAppAttestProvider,
         AppleAppAttestWithDeviceCheckFallbackProvider,
         ReCaptchaEnterpriseProvider,
-        ReCaptchaV3Provider;
+        ReCaptchaV3Provider,
+        WebDebugProvider;
 export 'package:firebase_core_platform_interface/firebase_core_platform_interface.dart'
     show FirebaseException;
 
diff --git a/packages/firebase_app_check/firebase_app_check_platform_interface/lib/src/web_providers.dart b/packages/firebase_app_check/firebase_app_check_platform_interface/lib/src/web_providers.dart
@@ -15,3 +15,19 @@ class ReCaptchaV3Provider extends WebProvider {
 class ReCaptchaEnterpriseProvider extends WebProvider {
   ReCaptchaEnterpriseProvider(String siteKey) : super(siteKey);
 }
+
+/// Debug provider for Web.
+///
+/// Sets `self.FIREBASE_APPCHECK_DEBUG_TOKEN` before initializing App Check.
+/// If [debugToken] is provided, that token is used. Otherwise the Firebase JS
+/// SDK auto-generates one and prints it to the browser console — you then
+/// register that token in the Firebase Console.
+///
+/// See documentation: https://firebase.google.com/docs/app-check/web/debug-provider
+class WebDebugProvider extends WebProvider {
+  /// Creates a web debug provider with an optional debug token.
+  WebDebugProvider({this.debugToken}) : super('');
+
+  /// The debug token for this provider.
+  final String? debugToken;
+}
diff --git a/packages/firebase_app_check/firebase_app_check_web/lib/firebase_app_check_web.dart b/packages/firebase_app_check/firebase_app_check_web/lib/firebase_app_check_web.dart
@@ -22,6 +22,7 @@ class FirebaseAppCheckWeb extends FirebaseAppCheckPlatform {
   static const String _libraryName = 'flutter-fire-app-check';
   static const recaptchaTypeV3 = 'recaptcha-v3';
   static const recaptchaTypeEnterprise = 'enterprise';
+  static const recaptchaTypeDebug = 'debug';
   static Map<String, StreamController<String?>> _tokenChangesListeners = {};
 
   /// Stub initializer to allow the [registerWith] to create an instance without
@@ -56,14 +57,22 @@ class FirebaseAppCheckWeb extends FirebaseAppCheckPlatform {
               .getItem(_sessionKeyRecaptchaSiteKey(firebaseApp.name));
         }
 
-        if (recaptchaType != null && recaptchaSiteKey != null) {
+        if (recaptchaType != null) {
           final WebProvider provider;
-          if (recaptchaType == recaptchaTypeV3) {
-            provider = ReCaptchaV3Provider(recaptchaSiteKey);
-          } else if (recaptchaType == recaptchaTypeEnterprise) {
-            provider = ReCaptchaEnterpriseProvider(recaptchaSiteKey);
+          if (recaptchaType == recaptchaTypeDebug) {
+            final debugToken =
+                recaptchaSiteKey?.isNotEmpty ?? false ? recaptchaSiteKey : null;
+            provider = WebDebugProvider(debugToken: debugToken);
+          } else if (recaptchaSiteKey != null) {
+            if (recaptchaType == recaptchaTypeV3) {
+              provider = ReCaptchaV3Provider(recaptchaSiteKey);
+            } else if (recaptchaType == recaptchaTypeEnterprise) {
+              provider = ReCaptchaEnterpriseProvider(recaptchaSiteKey);
+            } else {
+              throw Exception('Invalid recaptcha type: $recaptchaType');
+            }
           } else {
-            throw Exception('Invalid recaptcha type: $recaptchaType');
+            return;
           }
           await instance.activate(webProvider: provider);
         }
@@ -127,7 +136,9 @@ class FirebaseAppCheckWeb extends FirebaseAppCheckPlatform {
     // save the recaptcha type and site key for future startups
     if (webProvider != null) {
       final String recaptchaType;
-      if (webProvider is ReCaptchaV3Provider) {
+      if (webProvider is WebDebugProvider) {
+        recaptchaType = recaptchaTypeDebug;
+      } else if (webProvider is ReCaptchaV3Provider) {
         recaptchaType = recaptchaTypeV3;
       } else if (webProvider is ReCaptchaEnterpriseProvider) {
         recaptchaType = recaptchaTypeEnterprise;
@@ -136,8 +147,11 @@ class FirebaseAppCheckWeb extends FirebaseAppCheckPlatform {
       }
       web.window.localStorage
           .setItem(_sessionKeyRecaptchaType(app.name), recaptchaType);
-      web.window.localStorage
-          .setItem(_sessionKeyRecaptchaSiteKey(app.name), webProvider.siteKey);
+      web.window.localStorage.setItem(
+          _sessionKeyRecaptchaSiteKey(app.name),
+          webProvider is WebDebugProvider
+              ? webProvider.debugToken ?? ''
+              : webProvider.siteKey);
     }
 
     // activate API no longer exists, recaptcha key has to be passed on initialization of app-check instance.
diff --git a/packages/firebase_app_check/firebase_app_check_web/lib/src/interop/app_check.dart b/packages/firebase_app_check/firebase_app_check_web/lib/src/interop/app_check.dart
@@ -18,7 +18,24 @@ export 'app_check_interop.dart';
 AppCheck? getAppCheckInstance([App? app, WebProvider? provider]) {
   late app_check_interop.ReCaptchaProvider jsProvider;
 
-  if (provider is ReCaptchaV3Provider) {
+  if (provider is WebDebugProvider) {
+    // Set the debug token global before initializing App Check.
+    // The Firebase JS SDK reads this and creates a DebugProvider internally.
+    if (provider.debugToken != null) {
+      globalContext.setProperty(
+        'FIREBASE_APPCHECK_DEBUG_TOKEN'.toJS,
+        provider.debugToken!.toJS,
+      );
+    } else {
+      globalContext.setProperty(
+        'FIREBASE_APPCHECK_DEBUG_TOKEN'.toJS,
+        true.toJS,
+      );
+    }
+    // A provider is still required by initializeAppCheck, but the debug
+    // token global overrides it.
+    jsProvider = app_check_interop.ReCaptchaV3Provider('debug'.toJS);
+  } else if (provider is ReCaptchaV3Provider) {
     jsProvider = app_check_interop.ReCaptchaV3Provider(provider.siteKey.toJS);
   } else if (provider is ReCaptchaEnterpriseProvider) {
     jsProvider =
