[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, token exchange, DPoP replay, and cross-version HTTP error shapes; behavior is mostly additive but any client that strictly validates error JSON may need to tolerate new optional fields.

Overview
This PR replaces broad auth/internal error handling with tag-specific Effect error channels and catchTags mappings at HTTP, WebSocket, and cloud boundaries, and enriches failures with operation, reason, session, scope, and secret-path context while keeping original causes on in-process errors.

Contracts and wire behavior: Environment and cloud HTTP errors gain stable reason / operation codes (plus relay phase metadata). User-facing message strings are derived from those codes; cause is kept server-side where encoded responses omit it. Decoders still accept legacy message-only payloads for rolling deploys. Unauthorized cloud link flows now expose cloud_cli_authorization_required with the t3 connect link guidance.

Implementation areas: EnvironmentAuth narrows per-method error unions and drops predicate helpers like isServerAuthCredentialError in favor of explicit tags. ServerSecretStore errors name secretName, secretPath, and persist operation. CliTokenManager and relay client code classify OAuth/relay failures by stage/phase and log redacted URL diagnostics (no credentials in messages or JSON). New CloudRelayRequestError and shared catchEnvironmentAuthenticationErrors centralize mapping to API errors. AuthAccessStreamError and related tests assert structural fields instead of echoing upstream text.

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

Note

Add structured error context to server auth and cloud HTTP error classes

• Replaces generic internal error strings across auth and cloud HTTP handlers with structured error classes carrying operation identifiers, phase labels, reason codes, and diagnostic fields (e.g. URL length, protocol, hostname) that avoid leaking sensitive data.
• Introduces new error classes (CloudRelayConfigurationError, CloudRelayRequestError) and expands existing ones (ServerAuthDpopReplayStateRecordError, CloudCliCredentialRefreshError, etc.) with typed fields and computed message getters.
• Replaces broad catchIf/catchTag error handling throughout handlers with catchTags mappings to specific error classes, ensuring unmatched tags propagate rather than being swallowed.
• Adds structured reason codes (e.g. invalid_relay_url, cloud_cli_authorization_required) across validation helpers and HTTP error constructors in place of freeform message strings.
• Risk: error message text and payloads have changed across many endpoints; callers or tests that match on message strings or error shapes will need updating.

^{Macroscope summarized 55e9cd5.}

[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: 95dc9ced-4c1e-4a1e-878e-af266eeb2383

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: Approved

Refactoring PR that adds diagnostic context to error classes and improves type safety by replacing generic error catching with explicit tag-based patterns. No runtime behavior changes — only improved error messages and observability for debugging.

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Auth stream RPC lacks compatibility
  • Restored message: Schema.String to the wire schema, made operation optional for decode, and removed cause: Schema.Defect() from the schema to ensure backward-compatible decoding across mismatched client/server versions.

Or push these changes by commenting:

@cursor push 9bf0ab9608

Preview (9bf0ab9608)

diff --git a/packages/contracts/src/auth.ts b/packages/contracts/src/auth.ts
--- a/packages/contracts/src/auth.ts
+++ b/packages/contracts/src/auth.ts
@@ -285,15 +285,29 @@
 export class AuthAccessStreamError extends Schema.TaggedErrorClass<AuthAccessStreamError>()(
   "AuthAccessStreamError",
   {
-    operation: AuthAccessStreamOperation,
+    operation: Schema.optional(AuthAccessStreamOperation),
     currentSessionId: Schema.optional(AuthSessionId),
-    cause: Schema.Defect(),
+    message: Schema.String,
   },
 ) {
-  override get message(): string {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(props: {
+    readonly operation: AuthAccessStreamOperation;
+    readonly currentSessionId?: string | undefined;
+    readonly cause?: unknown;
+  }) {
     const session =
-      this.currentSessionId === undefined ? "" : ` for session ${this.currentSessionId}`;
-    return `Authentication access stream operation ${this.operation} failed${session}.`;
+      props.currentSessionId === undefined ? "" : ` for session ${props.currentSessionId}`;
+    const message =
+      "message" in props && typeof (props as any).message === "string"
+        ? (props as any).message
+        : `Authentication access stream operation ${props.operation} failed${session}.`;
+    super({
+      operation: props.operation,
+      ...(props.currentSessionId === undefined ? {} : { currentSessionId: props.currentSessionId }),
+      message,
+      ...(props.cause === undefined ? {} : { cause: props.cause }),
+    } as any);
   }
 }

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: WebSocket RPC leaks auth causes
  • Sanitized the cause passed to AuthAccessStreamError by wrapping internal errors in a plain Error with only the message string, preventing full internal error chains from being serialized to WebSocket clients via Schema.Defect().

Or push these changes by commenting:

@cursor push 0b147a7013

Preview (0b147a7013)

diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -514,7 +514,7 @@
               (cause) =>
                 new AuthAccessStreamError({
                   operation: "list-pairing-links",
-                  cause,
+                  cause: new Error(cause.message),
                 }),
             ),
           ),
@@ -524,7 +524,7 @@
                 new AuthAccessStreamError({
                   operation: "list-client-sessions",
                   currentSessionId,
-                  cause,
+                  cause: new Error(cause.message),
                 }),
             ),
           ),

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Wrong reconcile operation labels
  • Moved error handlers into per-operation inner catchTags so makeCloudLinkProof errors are labeled 'generate_link_proof' and applyCloudRelayConfig errors are labeled 'persist_relay_configuration', leaving only setCliDesiredCloudLink errors mapped to 'persist_desired_link_state' in the outer handler.

Or push these changes by commenting:

@cursor push 51e27c9846

Preview (51e27c9846)

diff --git a/apps/server/src/cloud/http.ts b/apps/server/src/cloud/http.ts
--- a/apps/server/src/cloud/http.ts
+++ b/apps/server/src/cloud/http.ts
@@ -723,6 +723,17 @@
         },
       },
       localOrigin,
+    ).pipe(
+      Effect.catchTags({
+        ServerAuthCloudLinkJwtSigningError: (error) =>
+          failEnvironmentCloudInternalError("sign_cloud_link_jwt")(error),
+        SecretStoreReadError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStoreDecodeError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStoreEncodeError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStorePersistError: failEnvironmentCloudInternalError("generate_link_proof"),
+        SecretStoreConcurrentReadError: failEnvironmentCloudInternalError("generate_link_proof"),
+        PlatformError: failEnvironmentCloudInternalError("generate_link_proof"),
+      }),
     );
     const link = yield* relayClientRequest(dependencies, {
       operation: "create-environment-link",
@@ -744,24 +755,25 @@
       environmentCredential: link.environmentCredential,
       cloudMintPublicKey: link.cloudMintPublicKey,
       endpointRuntime: link.endpointRuntime,
-    });
+    }).pipe(
+      Effect.catchTags({
+        ServerAuthLinkedCloudAccountVerificationError: (error) =>
+          failEnvironmentCloudInternalError("verify_linked_cloud_account")(error),
+        SecretStoreTemporaryPathGenerationError: failEnvironmentCloudInternalError(
+          "persist_relay_configuration",
+        ),
+        SecretStorePersistError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+        SecretStoreRemoveError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+        SchemaError: failEnvironmentCloudInternalError("persist_relay_configuration"),
+      }),
+    );
   },
   Effect.catchTags({
-    ServerAuthLinkedCloudAccountVerificationError: (error) =>
-      failEnvironmentCloudInternalError("verify_linked_cloud_account")(error),
-    ServerAuthCloudLinkJwtSigningError: (error) =>
-      failEnvironmentCloudInternalError("sign_cloud_link_jwt")(error),
-    SecretStoreReadError: failEnvironmentCloudInternalError("persist_desired_link_state"),
     SecretStoreTemporaryPathGenerationError: failEnvironmentCloudInternalError(
       "persist_desired_link_state",
     ),
     SecretStorePersistError: failEnvironmentCloudInternalError("persist_desired_link_state"),
     SecretStoreRemoveError: failEnvironmentCloudInternalError("persist_desired_link_state"),
-    SecretStoreDecodeError: failEnvironmentCloudInternalError("persist_desired_link_state"),
-    SecretStoreEncodeError: failEnvironmentCloudInternalError("persist_desired_link_state"),
-    SecretStoreConcurrentReadError: failEnvironmentCloudInternalError("persist_desired_link_state"),
-    SchemaError: failEnvironmentCloudInternalError("persist_desired_link_state"),
-    PlatformError: failEnvironmentCloudInternalError("persist_desired_link_state"),
     CloudRelayConfigurationError: (error) =>
       failEnvironmentCloudInternalError("read_relay_url_configuration")(error),
     CloudRelayRequestError: (error) =>

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 2b5e1cf. Configure here.}