[codex] Structure relay auth persistence errors

[juliusmarminge]

Summary

• add structured operation, stage, and safe correlation identifiers to environment-link, environment-credential, and DPoP replay persistence failures
• map failures at the exact crypto or database boundary while preserving the immediate underlying cause
• keep credential tokens, DPoP proofs, and public-key material out of error payloads
• replace the remaining environment credential catchTag boundary with catchTags
• add focused external-database layer regression tests

Why

These services previously collapsed every persistence and crypto failure into a cause-only error. The resulting errors did not identify the affected user, environment, credential, DPoP operation, or failing stage, and broad outer mappings obscured where the failure occurred.

Validation

• vp check (passes with 20 pre-existing warnings outside this scope)
• vp run typecheck
• 21 focused relay tests across the five affected suites

---

Note

Medium Risk
Touches authentication-adjacent persistence and error mapping paths; behavior for clients should stay the same, but mis-mapped errors could affect ops/debugging or leak context if schemas drift.

Overview
Relay DPoP replay, environment credentials, and environment links persistence failures now carry structured context—operation or stage, plus safe identifiers such as environmentId, userId, and DPoP thumbprint/jti—instead of a bare cause. Errors are built at each crypto/DB step via localized Effect.mapError, and messages name the failing step; tokens, proofs, and public-key material stay out of payloads.

Tests assert the new fields, prune/consume failure shapes, and that sensitive inputs are not retained on errors. HTTP uses catchTags for environment credential auth persistence failures, and APNS delivery job error mapping in Api.ts is inlined (removing mapApnsDeliveryJobInternalError) without changing client-facing reasons.

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

Note

Enrich relay auth and environment persistence errors with operation context and identifiers

• Extends persistence error classes across DpopProofs, EnvironmentCredentials, EnvironmentLinks, and related modules to include operation stage, entity identifiers (e.g. environmentId, userId, thumbprint), and a more specific error message.
• Replaces generic top-level Effect.mapError wrappers with stage-specific error mapping at each database operation, so errors carry precise context about where in the flow they occurred.
• Updates tests to assert on the new operation/stage fields and confirm sensitive fields (e.g. tokens, public keys) are not retained in errors.
• Removes the mapApnsDeliveryJobInternalError helper in Api.ts, inlining the mapping directly into publishAgentActivity.

^{Macroscope summarized cda9aed.}

[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: b881dd03-0156-4ccd-be55-35bd027bd895

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/audit-relay-persistence-errors

---

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

[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: Re-link keeps stale linkedAt
  • Added createdAt: now back to the onConflictDoUpdate set block so that re-linking an environment resets the timestamp exposed as linkedAt in list/get responses.

Or push these changes by commenting:

@cursor push 0435e7e401

Preview (0435e7e401)

diff --git a/infra/relay/src/environments/EnvironmentLinks.ts b/infra/relay/src/environments/EnvironmentLinks.ts
--- a/infra/relay/src/environments/EnvironmentLinks.ts
+++ b/infra/relay/src/environments/EnvironmentLinks.ts
@@ -204,6 +204,7 @@
             managedTunnelsEnabled: request.managedTunnelsEnabled,
             createdByDeviceId: request.deviceId ?? null,
             revokedAt: null,
+            createdAt: now,
             updatedAt: now,
           },
         })

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

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR adds structured context (operation stage, identifiers) to persistence error classes for better debugging. No authentication logic or success paths are modified - only what metadata gets captured when errors occur. Tests verify sensitive data is excluded from errors.

No code changes detected at cda9aed. Prior analysis still applies.

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