[codex] Share safe URL diagnostics

[juliusmarminge]

Summary

Error context often needs enough URL information to correlate failures without retaining secrets. Several clients had independently added local URL parsers, increasing the chance that credentials, paths, query parameters, fragments, or signed tokens would leak into logs and telemetry.

This shared foundation adds two deliberately separate helpers:

• getUrlDiagnostics from the explicit @t3tools/shared/urlDiagnostics subpath returns only { inputLength, protocol?, hostname? }. Invalid input returns length only; it never exposes path, userinfo, query, or fragment data.
• redactDpopRequestTarget remains in @t3tools/shared/dpop for the narrower DPoP use case, where scheme/host/port/path are part of the request-target diagnostics while credentials/query/fragment are removed.

Focused tests cover sensitive valid URLs and invalid input for both policies.

Validation

• vp test run packages/shared/src/urlDiagnostics.test.ts packages/shared/src/dpop.test.ts (10 tests)
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

Note

Redact sensitive URL data from errors and logs across client, server, and relay

• Introduces getUrlDiagnostics and redactDpopRequestTarget utilities in packages/shared that extract safe fields (input length, protocol, hostname) from URLs without exposing credentials, paths, or query strings.
• Replaces generic Data.TaggedError error classes with Schema.TaggedErrorClass across the codebase, adding structured fields (URL diagnostics, operation stage, cause) and stable message getters that avoid embedding raw URLs or cause messages.
• Structured errors are added or updated across relay, managed relay, DPoP, connection storage, RPC, environment connector, browser target resolution, OTLP tracing, keybindings, and update manifest merging.
• Logging sites in AgentAwarenessRelay, RelayEnvironmentDiscovery, ManagedRelayClient, and linkEnvironment are updated to spread redacted diagnostic attributes instead of logging raw URL strings or full Cause.pretty output.
• ConnectionBlockedError, ConnectionTransientError, and ConnectionPersistenceError are extended with structured storage operation context, cause fields, and a fromStorageFailure factory used by web, mobile, and desktop storage backends.
• Behavioral Change: several error constructors changed to factory methods (e.g. fromRequestUrl, fromTarget, fromEndpoint, fromStorageFailure); direct construction or instanceof checks at call sites must be updated to use the new factories and Schema.is type guards.

^{Macroscope summarized a2c3536.}

---

Note

Medium Risk
Wide cross-cutting change to error tags, fields, and messages (including DPoP and connection storage); callers that match on old shapes need updates, but runtime paths are mostly observability and failure reporting.

Overview
Rolls out shared getUrlDiagnostics and redactDpopRequestTarget so failures can be correlated without logging credentials, signed paths, query tokens, or full URLs.

Error model: Ad-hoc strings and Data.TaggedError are replaced with Schema.TaggedErrorClass types that carry operation/stage fields, a typed cause, and generic message text. Raw URLs are dropped from error objects and log attributes in favor of length, protocol, hostname, hashes, or redacted DPoP requestTarget values.

Notable behavior shifts: Desktop ElectronShell.openExternal / copyText now surface typed failures instead of swallowing them as false; window handlers log via Effect.ignore. Mobile connection/catalog/shell persistence, legacy migration, DPoP, image prefetch, and composer image paths use the new storage/persistence errors. Server keybindings, OTLP trace proxy, relay activity publishing, and web browser targets / cloud linking follow the same logging and error-shape rules.

Tests assert secrets stay out of messages and structured fields while causes and safe context are preserved.

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

[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: 3c00b2c1-ff29-4b83-a000-bbb22baaa87b

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/redact-dpop-request-target

---

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

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

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

Dismissing prior approval to re-evaluate ef9ed1e

Dismissing prior approval to re-evaluate e445dc2

Dismissing prior approval to re-evaluate 9e3a040

Dismissing prior approval to re-evaluate c41bc6c

Dismissing prior approval to re-evaluate 6dabb2f

[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: Catalog errors mislabel failure stage
  • Added resolvePersistenceStage() helper that derives the correct stage from the underlying ConnectionStorageOperationError, replacing the hardcoded 'read'/'write' stage values in catalog operations across both web and mobile storage files.

Or push these changes by commenting:

@cursor push b41df4da87

Preview (b41df4da87)

diff --git a/apps/mobile/src/connection/storage.ts b/apps/mobile/src/connection/storage.ts
--- a/apps/mobile/src/connection/storage.ts
+++ b/apps/mobile/src/connection/storage.ts
@@ -7,6 +7,7 @@
   removeConnectionFromCatalog,
   removeCatalogValue,
   replaceCatalogValue,
+  resolvePersistenceStage,
 } from "@t3tools/client-runtime/platform";
 import { TokenStore } from "@t3tools/client-runtime/authorization";
 import {
@@ -212,7 +213,7 @@
           (cause) =>
             new ConnectionPersistenceError({
               operation: "list-targets",
-              stage: "read",
+              stage: resolvePersistenceStage(cause, "read"),
               resource: "connection-catalog",
               cause,
             }),
@@ -228,7 +229,7 @@
               (cause) =>
                 new ConnectionPersistenceError({
                   operation: "register-connection",
-                  stage: "write",
+                  stage: resolvePersistenceStage(cause, "write"),
                   resource: "connection-catalog",
                   environmentId: registration.target.environmentId,
                   cause,
@@ -243,7 +244,7 @@
               (cause) =>
                 new ConnectionPersistenceError({
                   operation: "remove-connection",
-                  stage: "write",
+                  stage: resolvePersistenceStage(cause, "write"),
                   resource: "connection-catalog",
                   environmentId: target.environmentId,
                   cause,

diff --git a/apps/web/src/connection/storage.ts b/apps/web/src/connection/storage.ts
--- a/apps/web/src/connection/storage.ts
+++ b/apps/web/src/connection/storage.ts
@@ -10,6 +10,7 @@
   removeCatalogValue,
   removeConnectionFromCatalog,
   replaceCatalogValue,
+  resolvePersistenceStage,
 } from "@t3tools/client-runtime/platform";
 import { TokenStore } from "@t3tools/client-runtime/authorization";
 import {
@@ -402,7 +403,7 @@
           (cause) =>
             new ConnectionPersistenceError({
               operation: "list-targets",
-              stage: "read",
+              stage: resolvePersistenceStage(cause, "read"),
               resource: "connection-catalog",
               cause,
             }),
@@ -418,7 +419,7 @@
               (cause) =>
                 new ConnectionPersistenceError({
                   operation: "register-connection",
-                  stage: "write",
+                  stage: resolvePersistenceStage(cause, "write"),
                   resource: "connection-catalog",
                   environmentId: registration.target.environmentId,
                   cause,
@@ -433,7 +434,7 @@
               (cause) =>
                 new ConnectionPersistenceError({
                   operation: "remove-connection",
-                  stage: "write",
+                  stage: resolvePersistenceStage(cause, "write"),
                   resource: "connection-catalog",
                   environmentId: target.environmentId,
                   cause,

diff --git a/packages/client-runtime/src/platform/persistence.ts b/packages/client-runtime/src/platform/persistence.ts
--- a/packages/client-runtime/src/platform/persistence.ts
+++ b/packages/client-runtime/src/platform/persistence.ts
@@ -10,6 +10,7 @@
 import * as Schema from "effect/Schema";
 
 import type { ConnectionRegistration } from "../connection/catalog.ts";
+import type { ConnectionStorageOperation } from "../connection/model.ts";
 import type { ConnectionTarget } from "../connection/model.ts";
 
 export class ConnectionPersistenceError extends Schema.TaggedErrorClass<ConnectionPersistenceError>()(
@@ -48,6 +49,40 @@
   }
 }
 
+const storageOperationToStage: Record<
+  ConnectionStorageOperation,
+  ConnectionPersistenceError["stage"]
+> = {
+  open: "read",
+  read: "read",
+  load: "read",
+  decode: "decode",
+  migrate: "decode",
+  encode: "encode",
+  write: "write",
+  save: "write",
+  remove: "remove",
+  delete: "remove",
+};
+
+export function resolvePersistenceStage(
+  error: { readonly cause?: unknown },
+  fallback: ConnectionPersistenceError["stage"],
+): ConnectionPersistenceError["stage"] {
+  const inner = error.cause;
+  if (
+    inner != null &&
+    typeof inner === "object" &&
+    "_tag" in inner &&
+    inner._tag === "ConnectionStorageOperationError" &&
+    "operation" in inner
+  ) {
+    const operation = (inner as { operation: ConnectionStorageOperation }).operation;
+    return storageOperationToStage[operation] ?? fallback;
+  }
+  return fallback;
+}
+
 export class ConnectionTargetStore extends Context.Service<
   ConnectionTargetStore,
   {

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

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