feat(customers): add a non-production verification-code bypass

[roncodes]

Why

Signing up a customer locally means waiting on a real email or paying for a real SMS: the three code-checking endpoints (POST /v1/customers, /customers/verify-code, /customers/reset-password) match against real VerificationCode rows with no way to short-circuit them.

Navigator already has fleetops.navigator.bypass_verification_code for exactly this need on the driver side. This is the customer equivalent, for local development and staging QA.

This is optional. It is not needed for the API-contract run — that seeds real verification codes instead (fleetbase/fleetbase#581), deliberately, so CI needs no production diff. Review this on its own merits.

The guard

Adds fleetops.customers.verification_bypass_code, read from FLEETOPS_CUSTOMER_VERIFICATION_BYPASS_CODE, with the same three conditions the console uses in AuthController::authenticateWithVerificationCode:

• a code must be configured — unset (the default) means the bypass cannot fire;
• the app must not be in production;
• the comparison is constant-time.

Fails safe: config/app.php resolves env to production when neither APP_ENV nor ENVIRONMENT is set, so an unconfigured install cannot be bypassed even accidentally.

Deliberately a distinct env var, not SMS_AUTH_BYPASS_CODE — that one already gates operator console login and driver login, and sharing it would make a single leaked value unlock three privilege tiers. No fallback chain, for the same reason.

!== null && !== '' rather than !empty(), so a configured code of "0" still works.

Two deliberate choices worth reviewing

The guard is not folded into verificationCodeExists() / findVerificationCode(). Those are test seams the controller contract tests override on a subclass — a policy living inside them would be stubbed away precisely where it needs asserting. And findVerificationCode() must return a model (resetPassword calls ->delete() on it), so there is no honest "bypassed" return value.

CreateCustomerRequest's code rule is relaxed from exists:verification_codes,code to required|string. This is the part most likely to draw fire, so to be explicit — it is not a weakening:

• the controller matches code + for + meta->identity, whereas exists:verification_codes,code accepts any live code issued for any purpose to any user;
• the rule is already unenforced on the proxy path, since verifyCode() with for=fleetops_create_customer calls create(CreateCustomerRequest::createFrom($request)), which never runs validateResolved();
• left in place it would reject the bypass before the controller ever saw the request.

Tests

ApiCustomerControllerContractsTest 10/10, RequestContractsTest 21/21. New coverage:

• inert when unset and when empty, across all three endpoints;
• accepted for all three when configured and matching;
• a non-matching code still rejected while the bypass is live;
• rejected in production even when configured;
• resetPassword surviving the null VerificationCode on the bypass path while still revoking sessions.

The harness binds a bare Illuminate\Container\Container with no environment(), so the tests swap in a container subclass — same pattern as fleetOpsNotificationWithEnvironment() in NotificationAndMailContractsTest, extended to carry all bindings across.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (fa37e78) to head (a0de4f9).

Additional details and impacted files

@@             Coverage Diff             @@
##                main      #294   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity      9766      9774    +8     
===========================================
  Files            521       521           
  Lines          37762     37769    +7     
===========================================
+ Hits           37762     37769    +7     

Flag	Coverage Δ
backend	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.