[codex] Structure primary auth validation failures

[juliusmarminge]

Summary

• replace the raw bootstrap-session timeout with a tagged Schema error carrying timeout and elapsed timing context
• replace blank pairing-token validation with a distinct tagged Schema error carrying the submitted length without retaining the credential
• preserve both existing user-facing messages and leave the existing request-error mapper unchanged
• add compact behavior-focused coverage for validation and timeout handling

Validation

• vp test run apps/web/src/authBootstrap.test.ts (15 passed)
• vp check
• vp run typecheck

---

Note

Medium Risk
Changes authentication error types and user-visible messages for non-pairing primary HTTP failures (generic operation/status text instead of API details); pairing and timeout copy is preserved.

Overview
Primary environment auth failures are split into tagged Schema errors instead of generic Error strings and HTTP-derived PrimaryEnvironmentRequestError.detail text.

Pairing and bootstrap: blank tokens throw PrimaryEnvironmentPairingCredentialRequiredError (with providedLength); invalid credentials from browserSession become PrimaryEnvironmentPairingCredentialRejectedError with the same user-facing copy as before. Post-bootstrap session polling throws PrimaryEnvironmentAuthSessionTimeoutError with timing fields while gate state still surfaces the existing timeout message.

Request errors: PrimaryEnvironmentRequestError drops detail and the readHttpApiErrorMessage / friendly-bootstrap mappers; fromCause only needs operation + cause, and message is derived from operation and HTTP status without leaking transport text.

Tests add installDesktopBootstrap, cover blank/rejected pairing, request message derivation, and desktop bootstrap timeout; invalid-token expectations move to the new rejected-credential type.

^{Reviewed by Cursor Bugbot for commit 1663678. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Structure primary auth validation failures into typed error classes

• Replaces generic Error throws in primary auth flows with structured error types: PrimaryEnvironmentPairingCredentialRequiredError (blank token), PrimaryEnvironmentPairingCredentialRejectedError (invalid token), and PrimaryEnvironmentAuthSessionTimeoutError (post-bootstrap polling timeout).
• Simplifies PrimaryEnvironmentRequestError.fromCause by removing the detail field and fallbackMessage parameter; the message is now a fixed, non-leaking format: 'Primary environment request failed during {operation} (HTTP {status}).'
• Removes readHttpApiErrorMessage and toFriendlyBootstrapErrorMessage helpers, consolidating error messaging into the structured error classes.
• Exports new error types and type guards (isPrimaryEnvironmentPairingCredentialRejectedError) from index.ts.
• Behavioral Change: callers that previously received a generic Error or a detailed PrimaryEnvironmentRequestError with a detail field will now receive one of the new structured types or a standardized message without detail.

^{Macroscope summarized 1663678.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 77fab46e-5a7d-4275-bb16-8706b3ac76d7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-primary-auth-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors auth validation errors from generic Error throws to structured, typed error classes. The error conditions and user-facing messages remain unchanged - only the internal error representation is improved. Changes are well-tested and don't alter authentication logic.

^{You can customize Macroscope's approvability policy. Learn more.}