Cloud Recaptcha Enterprise Laravel Package

Technical Evaluation

Architecture fit

• google/cloud-recaptcha-enterprise is a GAPIC-generated Google Cloud client library, not a Laravel package. It ships Google\Cloud\RecaptchaEnterprise\V1\Client\RecaptchaEnterpriseServiceClient and the Assessment / TokenProperties / RiskAnalysis message classes. There is no service provider, no config file, no facade, no Blade/validation integration — every one of those is ours to write.
• It is a server-side SDK only. The intended flow is: browser/mobile obtains a token from the Enterprise JS (grecaptcha.enterprise.execute(siteKey, {action})), our Laravel backend calls createAssessment() with {siteKey, token, expectedAction, hashedAccountId?}, and reads tokenProperties.valid + riskAnalysis.score + reasons.
• This is a direct replacement for the recaptcha/api/siteverify call in reCAPTCHA v3. That matters: v3 is effectively on a deprecation path in favour of Enterprise, so adopting this library is as much a forward-compatibility decision as a fraud-scoring one.
• Fit inside a Laravel app is clean but manual: bind the client as a singleton in a service provider, wrap it behind our own RecaptchaVerifier interface, and expose it as a custom validation rule or a middleware/FormRequest concern. That wrapper is the actual product; the SDK is a transport detail.

Integration feasibility

• Composer-installable, Apache-2.0, semver ^1.0, requires PHP 8.x and pulls google/gax, google/protobuf, guzzlehttp/guzzle, plus either grpc/grpc or the REST transport. Verify the exact PHP floor against our Laravel version before committing.
• Auth is Application Default Credentials: a service account JSON key (GOOGLE_APPLICATION_CREDENTIALS) or Workload Identity. This is the single biggest operational difference from v3, which only needed a shared secret in .env. We now have a GCP project, an enabled API, an IAM principal (roles/recaptchaenterprise.agent), and a key-rotation story.
• The API surface we actually need is small and stable: createAssessment, annotateAssessment, createKey/getKey (or keys managed manually in console), and optionally getMetrics. Low integration risk.
• Two transports: gRPC (needs the PHP extension) and REST. If we can't guarantee the extension in every runtime, pin the REST transport explicitly rather than letting it silently fall back — the fallback behaviour is the kind of thing that only shows up in one environment at 2am.

Technical risk

• Hard runtime dependency on Google. Every form submission becomes a synchronous network call. p99 latency and outage behaviour are now our problem.
• Fail-open vs fail-closed is a product decision, not a technical one. If Google is unreachable or we're quota-exhausted, do we block checkout or let it through? We need an explicit, documented policy plus a circuit breaker.
• Token semantics are unforgiving. Tokens are short-lived (~2 minutes) and validating the same token twice yields an error, not a re-score. Any retry logic or double-submit path must be tested.
• Credential blast radius. A misconfigured or expired service account fails every protected form simultaneously. There is no degraded mode unless we build one.
• Wrapper ownership. Since nothing Laravel-native exists on Packagist for this, the glue is bespoke. Tests, mocking, and the interface boundary are on us and must be designed in from day one, or this becomes untestable dead weight.

Key questions

1. Which GCP project(s) and service account model — one shared SA, or per-environment with separate keys? Who owns rotation?
2. Is grpc installed and permitted in prod, or do we mandate the REST transport?
3. Fail-open or fail-closed on timeout/quota/5xx, and per surface (login vs checkout vs signup vs contact form)?
4. Where are tokens minted — Blade/JS, a SPA, mobile apps, or a WAF/load balancer? That determines whether we even need this library or should use the WAF integration.
5. Do we need Account Defender (accountId) and password-leak verification, or is plain score+action sufficient for phase 1?
6. Is the generated-code dependency acceptable under our dependency/licence policy (Renovate churn, proto version pinning)?
7. What is the assessment volume and therefore the cost line? (Roughly: first 1M assessments/month at no cost, then ~$1 per 1,000 — verify against current GCP pricing.)
8. Do we have a GCP support plan, or are we relying on public docs when this breaks?

Integration Approach

Stack fit

• Laravel 9/10/11 on PHP 8.1+ is a comfortable fit. Standard shape:
  • config/recaptcha.php — project id, site key(s), credentials path, score thresholds, enabled surfaces, timeout, fail-open flag.
  • RecaptchaServiceProvider — binds a singleton RecaptchaEnterpriseServiceClient and a RecaptchaVerifier implementation.
  • RecaptchaVerifier interface — verify(string $token, string $action, ?string $accountId): VerificationResult. This is the seam that lets us mock in tests and swap to REST/HTTP later without touching call sites.
  • ValidRecaptcha validation rule + a EnsureRecaptcha middleware for non-form endpoints.
  • A queued AnnotateAssessment job for the feedback loop.
• The client is a thin, stateless wrapper over a channel; a singleton in the container is correct and Octane-safe, but the underlying channel must be reusable across workers.

Migration path (from reCAPTCHA v3)

1. In GCP: enable the reCAPTCHA Enterprise API, create a score-based key per environment/brand, create the service account, grant roles/recaptchaenterprise.agent.
2. Add the composer dependency, service provider, config, and the RecaptchaVerifier wrapper — no call sites changed yet.
3. Shadow mode: keep v3 as the blocking control, additionally call createAssessment and log score/action/reasons/latency for N weeks. This is the most valuable step and the one most likely to be skipped.
4. Calibrate thresholds and action-name checks against the shadow data. Enterprise scores do not map 1:1 onto v3 scores.
5. Flip one low-risk surface, then login, then checkout/payment, then everything. Each flip is a config flag, not a deploy.
6. Add annotateAssessment on downstream outcomes (signup completed, order paid, chargeback, account banned) — this is where Enterprise earns its keep over v3, and it requires product/risk to own the label definitions.
7. Optionally add Account Defender later; it is a separate createAssessment parameter and does not require re-integration.

Compatibility

• Front-end must move to the Enterprise JS (grecaptcha.enterprise) with a site key from the Enterprise key. Old v3 site keys do not work here — this is a coordinated front-end/back-end release, not a backend-only change.
• CSP, ad blockers, and the render/execute lifecycle all change; budget front-end time.
• Any mobile client has its own Enterprise SDK variant; do not assume the web integration covers it.

Sequencing

• Week 1: GCP provisioning, IaC for keys/SA, wrapper + tests, shadow-mode logging.
• Week 2–4: shadow data collection, threshold calibration, runbook, alerts.
• Week 5: surface-by-surface rollout behind flags.
• Week 6+: annotation loop, then evaluate Account Defender and getMetrics dashboards.

Operational Impact

Maintenance

• The library itself is low-drama: generated code, monthly-ish minor releases, semver-respecting. Treat it as infrastructure — Renovate with auto-merge on patch/minor, manual review on major.
• The real maintenance burden is ours: the Laravel wrapper, the config, the threshold tuning, and the feedback-label semantics. Thresholds are not set-and-forget; they drift as traffic and attack patterns change, and someone must own that review cadence.
• Version pinning matters: google/protobuf, google/gax, and grpc are all in the tree and can conflict with other Google dependencies (BigQuery, Pub/Sub, Firebase). If we already pull google/cloud-* anywhere, resolve the whole tree together.

Support

• Public support for this specific split repo is effectively nil (13 stars, thin issue traffic) — but that is misleading, because the package is machine-generated and the support channel is really GCP documentation plus a Cloud support plan. Confirm we have a paid GCP support tier before this sits in the checkout path; without it, a quota or IAM incident means Stack Overflow.
• Internal support is the wrapper owner. Name a DRI.

Scaling

• One assessment per protected user action. At our volume this is comfortably inside the 1M/month free tier; the constraint is request-per-minute quota, not cost, unless we start assessing every request rather than every action.
• Added latency per protected request is typically tens to low hundreds of milliseconds depending on region and transport. gRPC is materially faster than REST here; if checkout latency is a KPI, install the extension.
• Scale the client, not the client library: singleton client, reuse the channel, and never call createAssessment inside a loop over form fields.

Failure modes

• Every one of these should map to a metric and an alert. Emit assessment latency, score distribution, invalid-token rate, and error code counts.

Ramp-up

• A mid-level Laravel developer familiar with GCP can wire the happy path in 1–2 days. The realistic 5–7 day estimate covers the wrapper, tests, shadow mode, and the runbook.
• GCP-side ramp-up (IAM, key creation, quotas, console familiarity) is the non-obvious cost and typically lands on whoever owns cloud infra, not the app team. Involve them at kickoff.
• Total time-to-confidence is 4–6 weeks, and it is dominated by shadow-mode observation, not engineering. Commit to that window or accept a blind threshold.

Bottom line for the product decision

• Technically low-risk, strategically sound (v3 is on the way out), operationally medium-risk because it moves an availability dependency into the request path and introduces GCP IAM as a hard requirement.
• Approve on the condition that we get: an explicit fail-open/fail-closed policy per surface, a circuit breaker, a named owner for threshold tuning, and confirmed GCP support coverage. Without those, we are trading a shared-secret .env variable for a cloud dependency we cannot operate.