fix(server): do not burn pairing grants on a scope mismatch

[Adolanium]

What Changed

Token exchange now checks requested scopes before it consumes the one-time pairing grant.

A client that asks for scopes the grant does not include still gets ServerAuthScopeNotGrantedError. The grant stays unused, so a later exchange with allowed scopes still works.

Why

Web and mobile always ask for standard client scopes. A constrained pairing plus that request burned the QR: one "invalid credential", mint another link. The unit test encoded the burn.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes (N/A)
• I included a video for animation/interaction changes (N/A)

---

Note

Medium Risk
Touches OAuth-style bootstrap token exchange in auth, but authorization rules are unchanged—only the order of scope validation vs. one-time consumption.

Overview
Bootstrap access-token exchange no longer consumes a one-time pairing grant when the client asks for scopes the grant does not allow.

exchangeBootstrapCredentialForAccessToken now calls a new PairingGrantStore.inspect (read-only lookup with the same expiry, proof-key, and availability checks as consume) before consume whenever requestedScopes is set. Over-scoped requests still return ServerAuthScopeNotGrantedError, but the QR/link stays valid for a later exchange with permitted scopes.

Tests now assert a failed over-scope exchange followed by a successful narrower exchange; environment-auth.md documents that rejected scope requests leave the grant unused.

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

Note

Fix scope mismatch burning pairing grants in exchangeBootstrapCredentialForAccessToken

• Adds PairingGrantStore.inspect to read a grant's scopes without consuming it, with proper error handling for unknown, consumed, revoked, expired, or proof-key-mismatched credentials
• exchangeBootstrapCredentialForAccessToken now calls inspect first; if requested scopes exceed the grant, it returns ServerAuthScopeNotGrantedError and leaves the grant usable for a subsequent valid exchange
• Only after scope validation passes does the function call PairingGrantStore.consume and issue a session
• Behavioral Change: a pairing grant is no longer consumed on scope mismatch; a grant that previously would have been burned remains valid for a later exchange with correct or subset scopes

^{Macroscope summarized 023d4e2.}

[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 Plus

Run ID: eb8ac92e-cbef-4533-a4b6-8292fc5bf96d

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

---

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

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a narrowly scoped fix that preserves pairing grants after rejected scope requests and includes targeted tests. It changes production authentication behavior and touches the authentication package, so the auth safety rule warrants human review.

^{You can add or adjust custom eligibility rules. Learn more.}