feat: Add Recaptcha attestation provider by ncooke3 · Pull Request #94 · google/app-check

ncooke3 · 2026-04-22T19:15:56Z

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

…Provider (#85) Signed-off-by: Nick Cooke <36927374+ncooke3@users.noreply.github.com> Co-authored-by: Paul Beusterien <paulbeusterien@google.com> Co-authored-by: Nick Cooke <nickcooke@google.com> Co-authored-by: Nick Cooke <36927374+ncooke3@users.noreply.github.com>

…a provider - Change implicitly unwrapped optionals to standard optionals or constants to prevent runtime crashes. - Handle Recaptcha SDK dynamic lookups safely without force-unwrapping. - Standardize error handling to use GACAppCheckErrorUtil and AppCheckCoreErrorDomain. - Add missing AppCheckCore imports to fix scope build errors. - Remove outdated TODO from AppCheckCore.podspec.

…a provider

…d environment guidelines - Add new Communication Guidelines section prioritizing categorized bullet points and visual indicators. - Add Environment & Troubleshooting section for dealing with sandboxes, Python paths, and Ruby version conflicts. - Standardize Git & Commits guidance to encourage frequent, scoped commits.

…e provider - Add `RecaptchaEnterpriseProviderUnit` test target to SPM package. - Verify provider initialization, dynamic SDK loading, and graceful error states. - Validate API token exchange payload formatting and responses, including limited-use configurations. - Ensure strict compatibility with Objective-C `FBLPromise` and `AppCheckCoreErrorCode` APIs. - Apply standard formatting via style.sh.

… guidelines - Document known compiler issues with `FBLPromise` generics in Swift bridging. - Add exact syntax workarounds for unlabeled Obj-C static methods and dynamic dispatch fallbacks. - Specify SPM target scoping requirements and `swift test --filter` syntax in TDD step.

- Deleted forwarding headers in `AppCheckCore/Sources/Core/...` - Updated imports in all Objective-C sources and tests to use `AppCheckCore/Sources/Public/AppCheckCore/...` - Verified build is successful via `swift test --list-tests`

- Added requirement for final report (summary + commit message) - Added mandate for updating agents.md with learnings - Documented fixture loading issue on macOS with SPM

- Added Step 5 for style application and Step 6 for doc formatting - Removed redundant style instructions from Quality Gates - Wrapped long lines in `agents.md` to 80 characters

ncooke3 · 2026-05-01T15:07:38Z

/gemini review

…p-check

…ants

Rename all types and files with the RecaptchaEnterprise substring to instead be Recaptcha.

paulb777 · 2026-05-28T20:28:26Z

Looks like the repo ci infra needs updates

ncooke3

Self

…ider.swift Signed-off-by: Nick Cooke <36927374+ncooke3@users.noreply.github.com>

ncooke3 · 2026-06-09T22:57:52Z

Created CocoaPods-11.3.0 tag and staged the podspec to SpecsStaging: firebase/SpecsStaging@780b6af

This comment was marked as outdated.

Sign in to view

ncooke3 and others added 10 commits April 22, 2026 15:52

moves

01170d0

todos

0f548c2

fixes

eb4effd

fix custom action name

bfb35e3

umbrella header fixes

157bd6d

Add agents workflow guide

a3ee169

fix(recaptcha): improve safety and fix compilation issues in Recaptch…

4c6523e

…a provider