feat: Add Recaptcha attestation provider

[ncooke3]

Add ReCAPTCHA Enterprise Attestation Provider

Metadata

• b/416109761
• firebase-ios-sdk PR that depends on this one:
  • feat(appcheck): implement RecaptchaEnterpriseProvider and tests firebase/firebase-ios-sdk#16155

Description

This PR introduces the RecaptchaEnterpriseProvider to the App Check SDK, enabling developers to use reCAPTCHA Enterprise for app attestation on iOS. It includes the core implementation in Swift, integration with the Objective-C core, and a comprehensive test suite.

Integration Approach

The following is the approach for each package manager.

• Swift Package Manager (SPM): Followed a Modular Path. The provider is exposed as a separate library product (RecaptchaEnterpriseProvider). This ensures users (the firebase-ios-sdk package) only pull in the RecaptchaInterop dependency if they explicitly use this provider. Mainly, this prevents the need of creating a third target to selectively re-export both the Objective-C and Swift API.
• CocoaPods: Followed a Monolithic Path. The sources are included in the main AppCheckCore target for iOS to maintain consistency and avoid the complexity of new pods or subspecs.

Dependencies

• Added a new dependency on interop-ios-for-google-sdks (specifically the RecaptchaInterop product) to support decoupled interaction with the reCAPTCHA Enterprise SDK.

New APIs

• AppCheckCoreRecaptchaEnterpriseProvider (Swift) / GACRecaptchaEnterpriseProvider (Obj-C)
  • init(siteKey:resourceName:APIKey:requestHooks:)
  • getToken(completion:)
  • getLimitedUseToken(completion:)

Error Handling & Edge Cases (CUJ)

• Missing reCAPTCHA SDK in Production: If the SDK is not linked in a release build, the provider returns GACAppCheckErrorCodeUnsupported with a specific, actionable message directing the developer to the setup documentation:

  "The reCAPTCHA Enterprise SDK is not linked. See https://cloud.google.com/recaptcha/docs/instrument-ios-apps#prepare-environment"

• Swift Interoperability: Consolidated the missing SDK error message into a centralized constant (kGACAppCheckMissingRecaptchaSDKMessage) and applied NS_SWIFT_NAME for more idiomatic Swift usage.
• Network/Server Errors: Specific reCAPTCHA errors (network and internal) are mapped to AppCheckCoreErrorCodeServerUnreachable to trigger the SDK's exponential backoff retry logic correctly.

Headers Moved to Public

To allow the Swift implementation to interact with the Objective-C core, the following headers were moved to AppCheckCore/Sources/Public/AppCheckCore:

• GACAppCheckAPIService.h
• GACAppCheckBackoffWrapper.h
• GACAppCheckErrorUtil.h
• GACURLSessionDataResponse.h

Tests Added

A new test target RecaptchaEnterpriseProviderUnit was added with 17 new tests covering:

• AppCheckCoreRecaptchaEnterpriseProviderTests: Verifies missing SDK handling, success flows, and limited-use token success flows.
• RecaptchaEnterpriseCoreAPIServiceTests: Verifies token exchange API requests and JSON body structure.
• RecaptchaEnterpriseCoreTokenGeneratorTests: Verifies token generation, backoff application, and error mapping.

Other Changes

• Added agents.md to define workflow instructions for AI agents in this repo.
• Updated .github/workflows/spm.yml to use the AppCheck-Package target.

cc: @weixifan @rlazo

[ncooke3]

/gemini review

[ncooke3]

todo: Decide whether to add platform guards.

• Option 1: Keep it as is (No availability guards)
  The provider relies on reflection to load the reCAPTCHA SDK at runtime.

  • Pros: Allows the provider to be used in cross-platform code (e.g., shared between iOS and macOS) without wrapping it in #if os(iOS) or if #available. It compiles on all platforms and fails gracefully at runtime if the SDK is missing.
  • Cons: Developers can attempt to use it on platforms where it will never work (like macOS), and they will only find out at runtime.

• Option 2: Add availability guards (e.g., @available(iOS 15.0, *))
  Mark the class or initializers with explicit OS version or platform constraints.

  • Pros: Prevents developers from using the provider on platforms or OS versions where it is not supported, catching mistakes at compile time.
  • Cons: Forces developers to use availability checks (if #available(...)) or platform checks (#if os(iOS)) in their code if they are building for multiple platforms, even though the provider itself is safe to compile everywhere due to reflection.

[ncooke3]

Curious what reviewers think here?

[ncooke3]

todo: Update the doc comment pending discussion.

[andrewheard]

I think my personal preference would be Option 1 with the addition of - (BOOL)isSupported; to GACAppCheckProvider (and bubbling it up to FIRAppCheckProvider) before release. It'd have to be in the @optional section in FIRAppCheckProvider to avoid breaking custom providers but it would allow accurate availability checks at runtime.

Our current documentation shows this code snippet

class YourAppCheckProviderFactory: NSObject, AppCheckProviderFactory {
  func createProvider(with app: FirebaseApp) -> AppCheckProvider? {
    if #available(iOS 14.0, *) {
      return AppAttestProvider(app: app)
    } else {
      return DeviceCheckProvider(app: app)
    }
  }
}

which, even if updated to include other Apple platforms, would return an instance of AppAttestProvider on macOS, even though it doesn't work on the platform. Being able to check AppAttestProvider.isSupported (wrapping DCAppAttestService.shared.isSupported) and RecaptchaEnterpriseProvider.isSupported (or whatever names), would allow developers to create a functional chain of fallbacks.

[ncooke3]

Self

[ncooke3]

Self

[ncooke3]

fyi: @weixifan, this is the networking layer.