[codex] Structure pairing grant failures

[juliusmarminge]

Summary

• retain pairing-link identity and requested subject when persistence fails
• distinguish random credential generation, atomic consumption, and state lookup failures
• preserve the exact repository or platform cause through every error boundary

Tests

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

---

Note

Medium Risk
Touches bootstrap/pairing credential consumption in auth; behavior on success paths is unchanged but failure types and wrapping differ, which may affect downstream error mapping and logging.

Overview
Pairing grant persistence and crypto failures are now surfaced as specific tagged errors instead of generic wrappers, with pairing link id, subject, and optional label on issue/revoke failures and separate types for random generation, atomic consume, and credential lookup.

consume maps consumeAvailable and getByCredential failures to BootstrapCredentialConsumeAvailableError and BootstrapCredentialLookupError respectively, and drops the previous catch-all that re-wrapped unknown errors as BootstrapCredentialConsumeError. Repository/platform causes are attached at each mapError site.

Tests add a mock AuthPairingLinkRepository layer and assert that a failed consumeAvailable yields BootstrapCredentialConsumeAvailableError with the original PersistenceSqlError as cause.

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

Note

Structure pairing grant failures with typed errors in PairingGrantStore

• Adds BootstrapCredentialConsumeAvailableError and BootstrapCredentialLookupError to distinguish repository failures in PairingGrantStore.consume, preserving the underlying cause in each.
• Adds PairingCredentialRandomGenerationError for failures in random ID or token generation within issueOneTimeToken and generatePairingToken.
• Enriches existing PairingLinkRevokeError and PairingCredentialIssueError with contextual fields (pairingLinkId, subject, label) and updates their messages accordingly.
• Extends the BootstrapCredentialInternalError union to include all new error types.
• Behavioral Change: consume no longer wraps all unrecognized failures into BootstrapCredentialConsumeError; callers that matched on that catch-all will need to handle the new error types.

^{Macroscope summarized 6438a45.}

[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: 64a9a307-fab9-4336-b5b6-bc21ed2deb1e

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-pairing-grant-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR improves error handling structure in PairingGrantStore by adding specific error classes with more context (IDs, subjects) and moving error mapping to individual operation points. No runtime behavior changes beyond error formatting - a straightforward refactor with corresponding tests.

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