[codex] improve server auth error context

[juliusmarminge]

Summary

• narrow EnvironmentAuth method error channels to the tagged failures each operation can actually produce
• replace predicate and single-tag recovery with exhaustive catchTags mappings at HTTP and WebSocket boundaries
• attach session, pairing-link, subject, scope, and DPoP correlation fields while preserving the original cause
• map replay-store failures directly and retain their source error chain

Validation

• vp check
• vp run typecheck
• vp test apps/server/src/auth
• vp test apps/server/src/http.test.ts apps/server/src/server.test.ts
• vp test apps/server/src/cloud/http.test.ts

---

Note

Medium Risk
Touches authentication error handling and HTTP/WebSocket boundaries across the server; behavior should be equivalent but any missed catch tag could change client-visible errors.

Overview
This PR enriches server auth tagged errors with correlation fields (subjects, scopes, session/pairing-link IDs, DPoP proof metadata, credential kind) and updates messages to include that context while keeping the original cause.

EnvironmentAuth now exposes per-operation error unions instead of a broad ServerAuthInternalError, adds ServerAuthAuthenticationError / internal auth error types, and removes isServerAuthCredentialError, serverAuthCredentialReason, and similar predicate/reason helpers. Failures like scope mismatch and self-revocation now carry requested vs granted scopes and current vs target session IDs.

HTTP, WebSocket, and raw routes use a shared catchEnvironmentAuthenticationErrors plus Effect.catchTags on auth endpoints so each failure maps to the right client response or internal reason. DPoP replay mapping takes explicit proof context; tests assert the new fields.

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

Note

Add contextual fields to server auth error classes for improved error diagnostics

• Enriches auth error classes in EnvironmentAuth.ts with contextual fields (e.g. subject, scopes, sessionId, credentialKind) and updates error messages to include them.
• Adds a catchEnvironmentAuthenticationErrors helper in http.ts that centralizes auth error-to-HTTP-response mapping across all API endpoints, WS upgrade, and raw routes.
• Narrows error unions on EnvironmentAuth.Context service methods so callers receive specific error tags rather than broad ServerAuthInternalError.
• getSessionState no longer downgrades validation/internal errors to unauthenticated — only ServerAuthMissingCredentialError and ServerAuthInvalidCredentialError are treated as unauthenticated.
• DPoP errors in dpop.ts now carry proofKeyThumbprint, proofId, and replayKey for replay state and key calculation failures.
• Behavioral Change: callers observing error tags from EnvironmentAuth methods will see renamed/narrowed error tag shapes.

^{Macroscope summarized 4ec1665.}

[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: 983ebe23-3fc7-4320-9039-4b4ec2d48710

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/server-auth-error-boundaries

---

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

[macroscopeapp]

Approvability

Verdict: Needs human review

Changes to authentication error handling in the auth package warrant human review, even though the modifications appear to only add contextual information to error messages and improve type precision without altering authentication logic.

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