Recaptcha Laravel Package

Product Decisions This Supports

• Worker-Runtime & Octane Adoption: Immutable with*() builder methods let a single ReCaptcha instance be safely shared as a DI singleton, unblocking or de-risking Laravel Octane, FrankenPHP, RoadRunner, and Swoole migrations. This is a direct enabler for roadmap items around throughput and infrastructure modernization, not just a code-style preference.
• Security Posture / Bot Mitigation Integrity: Two fail-open bugs are now fail-closed — setScoreThreshold(0.0) no longer bypasses when the API omits score (null), and setChallengeTimeout() no longer passes when challenge_ts is empty or unparseable. For a PM, this converts a silent fraud/abuse gap into a predictable E_SCORE_THRESHOLD_NOT_MET / E_CHALLENGE_TIMEOUT signal that can be alerted on.
• Market & Network Expansion: ReCaptcha::SITE_VERIFY_URL_ALTERNATIVE (www.recaptcha.net) unblocks deployment in regions and enterprise networks where www.google.com is unreachable. This is a go-to-market decision (new geographies, regulated/air-gapped-adjacent customers) that previously required forking or a proxy layer.
• SLO Control & Graceful Degradation: Configurable int $timeout = 60 on CurlPost, Post, and SocketPost, plus CURLOPT_CONNECTTIMEOUT, turns reCAPTCHA latency from a hidden tail-risk into a tunable product parameter. Enables explicit latency budgets on checkout and login flows.
• Cost & Latency Optimization: cURL handle reuse across submit() calls enables TLS session resumption and HTTP keep-alive, reducing handshake overhead on high-volume forms — measurable in both infra spend and p95 verification latency.
• Observability & Data Contracts: Response now implements \JsonSerializable, so verification results can flow directly into structured logs, audit trails, and analytics pipelines without adapters. Unified HTTP 200 validation across all three transports means one consistent failure taxonomy (E_BAD_RESPONSE) regardless of transport choice — far easier to dashboard and alert on.
• Compliance & Secret Hygiene: #[\SensitiveParameter] on $secret in ReCaptcha::__construct() and RequestParameters::__construct() prevents credentials leaking into stack traces — directly relevant to SOC 2 / ISO 27001 evidence and SIEM ingestion policies.
• Low-Friction Upgrade Path: 100% backwards-compatible with 2.0.0, verified via roave/backward-compatibility-check. This makes the upgrade an operational decision rather than a re-architecture one.

When to Consider This Package

• Adopt if:

  • You run Laravel Octane, FrankenPHP, RoadRunner, or Swoole, or plan to. The immutable builders are the difference between a per-request instantiation hack and a clean singleton binding.
  • You are on PHP 8.4+ (hard requirement in the 2.x series). If you are already on 2.0.0, adopt 2.1.0 immediately — it is BC and closes two fail-open security bugs.
  • You are upgrading from 1.x: note this crosses the 2.0.0 boundary, which dropped legacy PHP support. The 2.1.0 release itself is BC with 2.0.0, but your 1.x-to-2.1.0 jump needs a PHP-version audit and a transport review.
  • You need geo/network resilience: SITE_VERIFY_URL_ALTERNATIVE is the only supported way to verify where www.google.com is blocked.
  • Fraud detection, credential stuffing defense, or payment flows are in scope — the fail-closed fixes and unified status validation directly harden the verification path.
  • You require consistent error semantics across cURL, stream, and socket transports (e.g., multi-region deployments with different transport configs).
  • Secret leak prevention matters for audit — #[\SensitiveParameter] is a concrete, quotable compliance control.
  • You want to tune verification timeouts to a product-level latency budget instead of accepting a fixed 60s default.

• Look elsewhere if:

  • You are on PHP < 8.4. This is a hard floor, not a soft deprecation. Staying on 1.5 means accepting the now-known fail-open behavior in score-threshold and challenge-timeout handling.
  • You need self-hosted or air-gapped CAPTCHA. The package still requires Google's verification endpoint; the alternative hostname reduces network restrictions but does not remove the vendor dependency.
  • Your integration is low-risk and internal (admin dashboards, staging tools) — connection reuse and timeout tuning yield little value.
  • You need per-request secret rotation with distinct configs. The immutable pattern solves singleton safety but means you must construct variants explicitly rather than mutate shared state; teams wanting mutable global config should prefer a factory pattern instead.
  • You depend on examples/ as production code. The DOM XSS hardening and action allowlisting in examples/recaptcha-v3-verify.php are informative, but they are still examples — copy the server-side allowlist pattern, not the files.

How to Pitch It (Stakeholders)

For Executives (Business/Revenue Focus)

"Version 2.1.0 of our reCAPTCHA Laravel package is a security and infrastructure enabler with a clean, backwards-compatible upgrade from 2.0.0. Three things matter commercially:

• One supported path into new markets: the new alternative verification endpoint (www.recaptcha.net) removes the blocker for customers and regions where www.google.com is filtered. That turns a "cannot deploy" conversation into a scoping conversation.
• Two silent bypasses closed: previously, a misconfigured score threshold of 0.0 or a malformed challenge timestamp could let bot traffic through without failing. These now fail closed. That is direct fraud-loss prevention, and it is now alertable.
• Octane unblocked: safe singleton reuse removes a structural objection to our worker-runtime roadmap, which is where our throughput and hosting-cost targets live.

The migration is a composer update with verified backward compatibility against 2.0.0. The only gating factor is our own PHP version — which is already a prerequisite we have accepted.

Metrics to Track:

• Count of E_SCORE_THRESHOLD_NOT_MET and E_CHALLENGE_TIMEOUT responses post-upgrade (expected to rise from zero — those are previously invisible bypasses now surfaced).
• p95 verification latency before/after cURL connection reuse.
• Share of verification traffic routed via the alternative endpoint by region.
• Zero $secret occurrences in exception logs and error trackers.

Ask: Approve a one-sprint upgrade and a short soak period on /checkout and /login. The engineering cost is a single-line Composer bump plus targeted regression tests; the downside of staying on 1.5 is two known fail-open behaviors in our bot defense."*

For Engineering (Tech/Implementation Focus)

"2.1.0 is a minor release, 100% backwards-compatible with 2.0.0 (verified via roave/backward-compatibility-check), requiring PHP >=8.4. It hardens the transport layer and fixes two genuine fail-open security bugs.

High-value changes:

• Singleton safety: withExpectedHostname(), withExpectedApkPackageName(), withExpectedAction(), withScoreThreshold(), and withChallengeTimeout() now clone-and-return instead of mutating. ReCaptcha can be bound as a singleton in Octane, FrankenPHP, RoadRunner, and Swoole without cross-request config bleed. Note: any code relying on mutation side effects must be updated to consume the return value.
• Fail-closed fixes (security-relevant):
  • setScoreThreshold(0.0) previously bypassed when the API omitted score (null). Now returns E_SCORE_THRESHOLD_NOT_MET.
  • setChallengeTimeout() previously failed open on an empty or unparseable challenge_ts. Now returns E_CHALLENGE_TIMEOUT.
  • Both may surface new error codes in dashboards. Expected, and desirable.
• Transport hardening: unified HTTP 200 validation across CurlPost (CURLINFO_HTTP_CODE), Post (http_get_last_response_headers() with ignore_errors), and SocketPost, all returning E_BAD_RESPONSE on non-200. SocketPost now loops fwrite() for partial TLS writes and closes handles cleanly on failure.
• Performance: CurlPost lazily initializes and reuses its CurlHandle across submit() calls — TLS session resumption plus HTTP keep-alive. Expect lower p95 and fewer handshakes on high-volume endpoints.
• Configurability: int $timeout = 60 on all three transports, plus CURLOPT_CONNECTTIMEOUT on CurlPost. Set these to match your app's request budget, not the default.
• Data contract: Response implements \JsonSerializable — pass it straight to json_encode(). Response::fromJson() now filters error-codes to string elements only.
• Secret hygiene: #[\SensitiveParameter] on $secret in ReCaptcha::__construct() and RequestParameters::__construct() keeps secrets out of stack traces.
• Examples hardened: DOM XSS fixes, server-side action allowlisting in examples/recaptcha-v3-verify.php, updated CSP connect-src, and a new examples/recaptcha-v3-immutable.php demonstrating the builder pattern.

Migration Plan:

1. Audit PHP version and mutation usage: confirm >=8.4; grep the codebase for setScoreThreshold, setChallengeTimeout, setExpectedHostname, setExpectedAction, and setExpectedApkPackageName calls that ignore the return value. Convert to the with*() variants.
2. Bind as singleton: if on Octane/worker runtimes, register ReCaptcha in the container as a singleton and derive per-route variants via with*(). Reference examples/recaptcha-v3-immutable.php.
3. Set explicit timeouts: configure $timeout and CURLOPT_CONNECTTIMEOUT in line with your endpoint SLOs.
4. Evaluate the alternative endpoint: only route to SITE_VERIFY_URL_ALTERNATIVE where www.google.com is blocked; do not make it the default without a network reason.
5. Soak test: expect new E_SCORE_THRESHOLD_NOT_MET and E_CHALLENGE_TIMEOUT codes to appear in staging. Verify your error mapping and user-facing fallback handle them.
6. Deploy: composer update google/recaptcha, then prioritize /checkout, /login, and /register.

Upgrade note for 1.x users: 2.1.0 is BC with 2.0.0 only. Crossing from 1.5 also means adopting the 2.x PHP >=8.4 floor and its earlier breaking changes; scope the PHP-version and type-safety work as a separate item.

Alternatives Considered:

• Staying on 2.0.0: zero upside, keeps both fail-open bugs.
• Staying on 1.5: no PHP 8.4 requirement, but leaves known silent bypasses in bot defense and blocks Octane singleton adoption.
• Maintaining a fork for the alternative endpoint or timeout tuning: unnecessary — both are now first-class.

Proposal:

'Upgrade to 2.1.0 this sprint. It is a Composer bump with verified BC against 2.0.0, closes two fail-open security gaps, and unblocks the Octane singleton pattern we flagged as a risk.'*

Call to Action: "Block half a day: swap mutating setters for the with*() builders, bind ReCaptcha as a singleton, set explicit transport timeouts, and soak on /checkout and /login. Roll out to one high-risk endpoint first and watch for the newly-surfaced E_SCORE_THRESHOLD_NOT_MET and E_CHALLENGE_TIMEOUT codes — they represent abuse that was previously slipping through undetected."