feat(app-check): Debug token support for the activate method (#17723)

* feat(app-check): Debug token support for the activate method

* feat(app-check): Refactor activate method to use new provider classes

* feat(app-check): Update debug provider usage and parameters in documentation

* chore: remove deprecated AndroidSafetyNetProvider and update documentation

* chore: rename webProvider to providerWeb for consistency across the codebase

* chore: add webProvider parameter to MockFirebaseAppCheck.activate method

---------

Co-authored-by: Furkan KURT <fkurt97@gmail.com>

Author: SelaseKay

docs/app-check/debug-provider.md

@@ -37,8 +37,8 @@ To use the debug provider while running your app in a simulator interactively
       WidgetsFlutterBinding.ensureInitialized();
       await Firebase.initializeApp();
       await FirebaseAppCheck.instance.activate(
-        // Set appleProvider to `AppleProvider.debug`
-        appleProvider: AppleProvider.debug,
+      // Set providerApple to use AppleDebugProvider
+      providerApple: AppleDebugProvider('123a4567-b89c-12d3-e456-789012345678'),
       );
       runApp(App());
     }
@@ -83,9 +83,9 @@ Future<void> main() async {
   WidgetsFlutterBinding.ensureInitialized();
   await Firebase.initializeApp();
   await FirebaseAppCheck.instance.activate(
-    webRecaptchaSiteKey: 'recaptcha-v3-site-key',
-    // Set androidProvider to `AndroidProvider.debug`
-    androidProvider: AndroidProvider.debug,
+    webProvider: ReCaptchaV3Provider('recaptcha-v3-site-key'),
+    // Set providerAndroid to use AndroidDebugProvider
+    providerAndroid: AndroidDebugProvider('123a4567-b89c-12d3-e456-789012345678'),
   );
   runApp(App());
 }
@@ -146,3 +146,44 @@ Because this token allows access to your Firebase resources without a
 valid device, it is crucial that you keep it private. Don't commit it to a
 public repository, and if a registered token is ever compromised, revoke it
 immediately in the Firebase console.
+
+## Manually setting up the App Check Debug Token for CI environment or development
+
+If you want to use the debug provider in a testing environment or CI, you can
+manually set the debug token in your app. This is useful when you want to run
+your app in an environment where the debug token is not automatically generated.
+
+To manually set the debug token, pass your debug token directly to the debug provider
+classes when activating App Check. For example:
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:firebase_core/firebase_core.dart';
+
+// Import the firebase_app_check plugin
+import 'package:firebase_app_check/firebase_app_check.dart';
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+  await FirebaseAppCheck.instance.activate(
+    webProvider: ReCaptchaV3Provider('recaptcha-v3-site-key'),
+    // Set providerAndroid with debug token
+    providerAndroid: AndroidDebugProvider('123a4567-b89c-12d3-e456-789012345678'),
+    // Set providerApple with debug token
+    providerApple: AppleDebugProvider('123a4567-b89c-12d3-e456-789012345678'),
+  );
+  runApp(App());
+}
+
+```
+
+{# Google-internal common file: #}
+<<../_includes/manage-debug-tokens.md>>
+
+After you register the token, Firebase backend services will accept it as valid.
+
+Because this token allows access to your Firebase resources without a
+valid device, it is crucial that you keep it private. Don't commit it to a
+public repository, and if a registered token is ever compromised, revoke it
+immediately in the Firebase console.

docs/app-check/default-providers.md

@@ -81,19 +81,18 @@ Future<void> main() async {
     // You can also use a `ReCaptchaEnterpriseProvider` provider instance as an
     // argument for `webProvider`
     webProvider: ReCaptchaV3Provider('recaptcha-v3-site-key'),
-    // Default provider for Android is the Play Integrity provider. You can use the "AndroidProvider" enum to choose
+    // Default provider for Android is the Play Integrity provider. You can use the "providerAndroid" parameter to choose
     // your preferred provider. Choose from:
-    // 1. Debug provider
-    // 2. Safety Net provider
-    // 3. Play Integrity provider
-    androidProvider: AndroidProvider.debug,
-    // Default provider for iOS/macOS is the Device Check provider. You can use the "AppleProvider" enum to choose
-        // your preferred provider. Choose from:
-        // 1. Debug provider
-        // 2. Device Check provider
-        // 3. App Attest provider
-        // 4. App Attest provider with fallback to Device Check provider (App Attest provider is only available on iOS 14.0+, macOS 14.0+)
-    appleProvider: AppleProvider.appAttest,
+    // 1. AndroidDebugProvider for debug environments
+    // 2. AndroidPlayIntegrityProvider
+    providerAndroid: AndroidDebugProvider(),
+    // Default provider for iOS/macOS is the Device Check provider. You can use the "providerApple" parameter to choose
+    // your preferred provider. Choose from:
+    // 1. AppleDebugProvider for debug environments
+    // 2. AppleDeviceCheckProvider
+    // 3. AppleAppAttestProvider
+    // 4. AppleAppAttestProviderWithDeviceCheckFallback (App Attest provider is only available on iOS 14.0+, macOS 14.0+)
+    providerApple: AppleAppAttestProvider(),
   );
   runApp(App());
 }

packages/firebase_app_check/firebase_app_check/android/src/main/java/io/flutter/plugins/firebase/appcheck/FlutterFirebaseAppCheckPlugin.java

@@ -98,6 +98,8 @@ private Task<Void> activate(Map<String, Object> arguments) {
               case debugProvider:
                 {
                   FirebaseAppCheck firebaseAppCheck = getAppCheck(arguments);
+                  FlutterFirebaseAppRegistrar.debugToken =
+                      (String) arguments.get("androidDebugToken");
                   firebaseAppCheck.installAppCheckProviderFactory(
                       DebugAppCheckProviderFactory.getInstance());
                   break;

packages/firebase_app_check/firebase_app_check/android/src/main/java/io/flutter/plugins/firebase/appcheck/FlutterFirebaseAppRegistrar.java

@@ -5,17 +5,38 @@
 package io.flutter.plugins.firebase.appcheck;
 
 import androidx.annotation.Keep;
+import androidx.annotation.Nullable;
+import com.google.firebase.appcheck.debug.InternalDebugSecretProvider;
 import com.google.firebase.components.Component;
 import com.google.firebase.components.ComponentRegistrar;
 import com.google.firebase.platforminfo.LibraryVersionComponent;
-import java.util.Collections;
+import java.util.Arrays;
 import java.util.List;
 
 @Keep
-public class FlutterFirebaseAppRegistrar implements ComponentRegistrar {
+public class FlutterFirebaseAppRegistrar
+    implements ComponentRegistrar, InternalDebugSecretProvider {
+
+  private static final String DEBUG_SECRET_NAME = "fire-app-check-debug-secret";
+  public static String debugToken;
+
   @Override
   public List<Component<?>> getComponents() {
-    return Collections.<Component<?>>singletonList(
-        LibraryVersionComponent.create(BuildConfig.LIBRARY_NAME, BuildConfig.LIBRARY_VERSION));
+    Component<?> library =
+        LibraryVersionComponent.create(BuildConfig.LIBRARY_NAME, BuildConfig.LIBRARY_VERSION);
+
+    Component<InternalDebugSecretProvider> debugSecretProvider =
+        Component.builder(InternalDebugSecretProvider.class)
+            .name(DEBUG_SECRET_NAME)
+            .factory(container -> this)
+            .build();
+
+    return Arrays.asList(library, debugSecretProvider);
+  }
+
+  @Nullable
+  @Override
+  public String getDebugSecret() {
+    return debugToken;
   }
 }

packages/firebase_app_check/firebase_app_check/example/lib/main.dart

@@ -2,11 +2,11 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'package:cloud_firestore/cloud_firestore.dart';
 import 'package:firebase_app_check/firebase_app_check.dart';
 import 'package:firebase_core/firebase_core.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
-import 'package:cloud_firestore/cloud_firestore.dart';
 
 import 'firebase_options.dart';
 
@@ -25,7 +25,9 @@ Future<void> main() async {
       .activate(
     androidProvider: AndroidProvider.debug,
     appleProvider: AppleProvider.debug,
-    webProvider: ReCaptchaV3Provider(kWebRecaptchaSiteKey),
+    providerWeb: ReCaptchaV3Provider(kWebRecaptchaSiteKey),
+    providerAndroid: const AndroidDebugProvider(debugToken: 'androidDebug'),
+    providerApple: const AppleDebugProvider(debugToken: 'appleDebug'),
   );
 
   runApp(MyApp());
@@ -115,7 +117,7 @@ class _FirebaseAppCheck extends State<FirebaseAppCheckExample> {
                   );
                 }
                 await appCheck.activate(
-                  webProvider: ReCaptchaV3Provider(kWebRecaptchaSiteKey),
+                  providerWeb: ReCaptchaV3Provider(kWebRecaptchaSiteKey),
                 );
                 setMessage('activated!!');
               },

packages/firebase_app_check/firebase_app_check/ios/firebase_app_check/Sources/firebase_app_check/FLTAppCheckProvider.m

@@ -14,10 +14,18 @@ - (id)initWithApp:app {
   return self;
 }
 
-- (void)configure:(FIRApp *)app providerName:(NSString *)providerName {
+- (void)configure:(FIRApp *)app
+     providerName:(NSString *)providerName
+       debugToken:(NSString *)debugToken {
   if ([providerName isEqualToString:@"debug"]) {
+    if (debugToken != nil) {
+      // We have a debug token, so just need to stuff it in the environment and it will hook up
+      char *key = "FIRAAppCheckDebugToken", *value = (char *)[debugToken UTF8String];
+      int overwrite = 1;
+      setenv(key, value, overwrite);
+    }
     FIRAppCheckDebugProvider *provider = [[FIRAppCheckDebugProvider alloc] initWithApp:app];
-    NSLog(@"Firebase App Check Debug Token: %@", [provider localDebugToken]);
+    if (debugToken == nil) NSLog(@"Firebase App Check Debug Token: %@", [provider localDebugToken]);
     self.delegateProvider = provider;
   }
 

packages/firebase_app_check/firebase_app_check/ios/firebase_app_check/Sources/firebase_app_check/FLTAppCheckProviderFactory.m

@@ -25,13 +25,15 @@ @implementation FLTAppCheckProviderFactory
     self.providers[app.name] = [FLTAppCheckProvider new];
     FLTAppCheckProvider *provider = self.providers[app.name];
     // We set "deviceCheck" as this is currently what is default. Backward compatible.
-    [provider configure:app providerName:@"deviceCheck"];
+    [provider configure:app providerName:@"deviceCheck" debugToken:nil];
   }
 
   return self.providers[app.name];
 }
 
-- (void)configure:(FIRApp *)app providerName:(NSString *)providerName {
+- (void)configure:(FIRApp *)app
+     providerName:(NSString *)providerName
+       debugToken:(NSString *)debugToken {
   if (self.providers == nil) {
     self.providers = [NSMutableDictionary new];
   }
@@ -41,7 +43,7 @@ - (void)configure:(FIRApp *)app providerName:(NSString *)providerName {
   }
 
   FLTAppCheckProvider *provider = self.providers[app.name];
-  [provider configure:app providerName:providerName];
+  [provider configure:app providerName:providerName debugToken:debugToken];
 }
 
 @end

packages/firebase_app_check/firebase_app_check/ios/firebase_app_check/Sources/firebase_app_check/FLTFirebaseAppCheckPlugin.m

@@ -123,9 +123,10 @@ - (void)handleMethodCall:(FlutterMethodCall *)call result:(FlutterResult)flutter
 - (void)activate:(id)arguments withMethodCallResult:(FLTFirebaseMethodCallResult *)result {
   NSString *appNameDart = arguments[@"appName"];
   NSString *providerName = arguments[@"appleProvider"];
+  NSString *debugToken = arguments[@"appleDebugToken"];
 
   FIRApp *app = [FLTFirebasePlugin firebaseAppNamed:appNameDart];
-  [self->providerFactory configure:app providerName:providerName];
+  [self->providerFactory configure:app providerName:providerName debugToken:debugToken];
   result.success(nil);
 }
 

packages/firebase_app_check/firebase_app_check/ios/firebase_app_check/Sources/firebase_app_check/include/FLTAppCheckProvider.h

@@ -10,7 +10,9 @@
 
 @property id<FIRAppCheckProvider> delegateProvider;
 
-- (void)configure:(FIRApp *)app providerName:(NSString *)providerName;
+- (void)configure:(FIRApp *)app
+     providerName:(NSString *)providerName
+       debugToken:(NSString *)debugToken;
 
 - (id)initWithApp:(FIRApp *)app;
 

packages/firebase_app_check/firebase_app_check/ios/firebase_app_check/Sources/firebase_app_check/include/FLTAppCheckProviderFactory.h

@@ -7,6 +7,8 @@
 
 @property NSMutableDictionary *_Nullable providers;
 
-- (void)configure:(FIRApp *_Nonnull)app providerName:(NSString *_Nonnull)providerName;
+- (void)configure:(FIRApp *_Nonnull)app
+     providerName:(NSString *_Nonnull)providerName
+       debugToken:(NSString *_Nullable)debugToken;
 
 @end