Yandex Smartcaptcha Php Laravel Package

Technical Evaluation

Architecture fit

• Purpose-built Laravel package: Service Provider, Facade, publishable config with env vars, and example custom validation rule — maps cleanly onto Laravel's native validation pipeline, which is where captcha checks belong.
• SDK wraps two distinct surfaces: (1) server-side token validation (the only piece most applications need) and (2) the captcha management API (create/read/update/delete/list, secret key retrieval). The management surface is control-plane tooling for provisioning keys, not a runtime dependency — treat these as separate adoption decisions.
• Adds a transitive dependency on tigusigalpa/yandex-cloud-client-php for OAuth/IAM token lifecycle. This is the real architectural coupling: the captcha package cannot authenticate without that client, so we inherit its release cadence, bug surface, and maintainer risk.
• Type-safe DTOs (CaptchaInfo, ValidationResult, SecretKey) and PSR-3 logging are the right shape for testable business logic; isValid() gives a clean boolean seam at the controller/FormRequest boundary.

Integration feasibility

• Installation is a single Composer require with no infrastructure footprint — no sidecar, no queue worker, no migration. Integration effort is measured in hours, not sprints.
• Requires a Yandex Cloud service account with OAuth/IAM credentials plus a server secret key per captcha. Two credential types to provision, rotate, and store — plan for a secrets-manager path, not .env in production.
• Frontend widget integration is delivered as examples rather than a Blade component or published JS asset. Expect our team to own the client-side markup, script loading, CSP allowances, and the "token missing / widget failed to render" branch.
• Custom validation rule is described as an "example," not a shipped rule class. Verify whether a first-class SmartCaptcha rule exists; if not, we own that thin wrapper (and its failure semantics).

Technical risk

• Vendor and jurisdictional exposure (high): All validation traffic transits Yandex infrastructure. For any product with EU/UK/US users or enterprise customers, this is a data-transfer, sanctions-screening, and procurement conversation, not a technical one. Resolve the legal/compliance position before any code is written.
• Single-maintainer dependency chain (high): Both the captcha package and the cloud client are authored by the same individual under a personal namespace, MIT-licensed, at v1.0.0 with no release history. No foundation, no corporate backer, no published support SLA or security disclosure policy.
• Runtime availability coupling (medium-high): Every protected form submission becomes a synchronous outbound call to a third-party API. Latency and uptime now sit on the critical path of login and signup. Fail-open versus fail-closed is a policy decision the package cannot make for us.
• Token lifecycle complexity (medium): Auto-refreshing 12-hour IAM tokens is genuinely useful, but it introduces a shared mutable credential in the process. Under multi-worker/octane deployments, confirm refresh is concurrency-safe and not stampeding the token endpoint.
• Unverified production claims (medium): "Comprehensive test coverage" and "production-ready" are self-asserted in release notes. No coverage figures, no CI badge referenced, no independent consumer evidence.
• Platform currency (low-medium): PHP 8.0+ and Laravel 8.0+ signal a floor set by 2021-era runtimes; both are past end-of-life. The floor is permissive, not restrictive, but it hints the maintainer's compatibility matrix is conservative — verify against our actual Laravel version.

Key questions

1. What is our compliance position on routing end-user traffic (including IP addresses, which the example passes explicitly) to Yandex infrastructure? Does this differ per region or customer segment?
2. Does the package expose configurable timeouts, retry policy, and a circuit breaker — or is the HTTP call to Yandex unbounded? Can we inject a custom HTTP client?
3. Is there a test double (fake/stub) so CI and local dev don't hit the live API or require real credentials?
4. Is the validation rule shipped as a class, or must we write it? What exception types surface, and do they let us distinguish "invalid token" from "Yandex is down"?
5. Are we adopting the management API at all, or only token validation? If only validation, can we avoid the cloud-client dependency entirely by supplying the secret directly?
6. Who is the bus factor here, and what is the maintainer's stated policy on security reports, breaking changes, and deprecation windows?
7. What is the token expiry window on Yandex's side, and does the package handle replay/duplicate submission correctly?
8. How do credentials get injected — config only, or is there a contract we can bind for Vault/KMS-backed retrieval?

Integration Approach

Stack fit

• Sits naturally in the Laravel HTTP layer: FormRequest → validation rule → SmartCaptchaClient::validate() → ValidationResult. No interaction with our domain model, persistence, or event bus.
• PSR-3 logging and typed DTOs mean it drops into an existing observability and static-analysis setup (PHPStan/Psalm) without bespoke glue.
• Facade + Service Provider follows framework convention; if we adopt, bind to the underlying client contract rather than the Facade so tests and future swaps stay cheap.

Migration path

• Greenfield: no migration — this is net-new bot mitigation. Scope the first integration to a single high-value form (login or signup) as a canary.
• Brownfield (replacing reCAPTCHA/hCaptcha): the seam is identical — client renders a widget, posts a token, server validates. Our existing validation rule and failure UX can be preserved; only the widget script and the server-side call change. Budget effort for the frontend swap, not the backend.
• Avoid a dual-captcha period longer than one release cycle; two widgets on one form is a measurable conversion tax.

Compatibility

• Confirm our Laravel version is within the supported range and that PHP 8.0+ floor is satisfied by our actual runtime — but treat 8.0/8.1 as out of bounds for new work regardless of what the package allows.
• Verify Composer resolution against our existing yandex-cloud-client-php constraints (if present) and our Guzzle/HTTP client version. Two packages from one author sharing a transitive dependency is a conflict vector worth checking early.
• CSP: the frontend widget will require script-src and frame-src allowances. Flag to security review before frontend work starts.

Sequencing

1. Decision gate (blocking): Compliance/legal ruling on data transfer to Yandex. No engineering effort before this clears.
2. Evaluation spike (1–2 days): Fresh Laravel app, real credentials, exercise validation plus the failure paths (bad token, expired token, network timeout, 5xx). Confirm timeout/retry configurability and test-double availability.
3. Dependency review: License, maintainer activity, open-issue posture, security policy, and whether the cloud-client dependency can be eliminated for a validation-only use case.
4. Thin internal wrapper: Bind a CaptchaVerifier contract in our codebase, with the package as one implementation. This is the single highest-leverage step — it caps our exposure if the package stalls at v1.0.0 forever.
5. Canary rollout: One form, behind a feature flag, with fail-open and fail-closed both observable before committing to a policy.
6. Expand or exit: Promote to all protected forms, or fall back to a self-maintained thin HTTP client against Yandex's documented validation endpoint.

Operational Impact

Maintenance

• Low surface area: one config file, one credential set, no schema, no background jobs. Ongoing cost is credential rotation and periodic dependency bumps.
• The real maintenance burden is upstream: we do not control the security-patch cadence of a v1.0.0 single-maintainer package. Budget a recurring review of both packages; a stalled upstream becomes our fork.
• IAM token auto-refresh reduces day-two toil but must be monitored — a silent refresh failure manifests as a total captcha outage, not a degraded one.

Support

• Documentation is bilingual EN/RU and appears substantive for a v1.0.0 — better than typical. But there is no stated support channel, SLA, or security disclosure process.
• Internal support load will concentrate in the frontend widget (rendering, CSP, ad-blockers, mobile) far more than the server-side call. Write a runbook for "widget didn't load" versus "validation failed" — they look identical to users and to support staff.
• Expect procurement questions from enterprise customers about the vendor. Pre-draft the answer or restrict rollout by segment.

Scaling

• Runtime cost scales linearly with protected form submissions: one synchronous outbound HTTP call per submission. Negligible at low volume; at high auth volume it becomes a third-party rate-limit and latency budget item.
• No built-in caching or batching is appropriate here (tokens are single-use), so the mitigation is capacity planning against Yandex rate limits and a defined timeout, not architecture.
• IAM token refresh scales fine at normal worker counts; verify behaviour under horizontal autoscaling where many cold workers may refresh simultaneously.

Failure modes

• Yandex API unavailable or slow: Blocks every protected submission unless a timeout and fail policy exist. Decide explicitly: fail-open (bot exposure, business continues) or fail-closed (users locked out of login). For auth endpoints, fail-open with alerting is usually correct; for abuse-sensitive flows, invert.
• Credential expiry / revocation: OAuth or IAM credential lapse produces a hard, total outage with a confusing error surface. Requires an alert on auth-class errors distinct from validation failures.
• Secret key compromise: Server secret is a long-lived shared secret in config. Rotation must be a rehearsed procedure, not an incident-time discovery.
• Token replay / duplicate submit: Double-submitted forms can consume a token twice; ensure the validation failure path shows a recoverable error rather than a dead end.
• Upstream abandonment: If either package stops receiving updates, we inherit an unpatched dependency in the authentication path. The internal wrapper contract is the mitigation — but only if we actually build it in step 4.
• Compliance event: A change in sanctions, data-transfer rules, or Yandex's terms could force removal with short notice. The wrapper keeps that a configuration change rather than a rewrite.

Ramp-up

• A mid-level Laravel developer is productive in under a day; the API is narrow and the README examples are sufficient.
• Team-level ramp-up is dominated by the two non-obvious areas: IAM credential mechanics and the frontend widget's failure behaviour. Cover both in the spike write-up.
• Recommend one engineer own the credential/rotation story and one own the frontend integration, with the wrapper contract as the shared interface between them.