server: atomic claim on setup-token redemption

[erikolsson]

Summary

• The previous redemption flow in /v1/auth/exchange read a setupTokens row with redeemed=false, then UPDATEd to redeemed=true keyed only by id. There was no re-assertion of the predicate, no transaction, and no row lock — two concurrent calls with the same token both passed the check, both proceeded, and the downstream delete apiKeys WHERE deviceId=? + insert apiKeys path could leave two valid keys for the same device. Each caller walked away with a working long-lived API key.
• Replace with a single atomic UPDATE … SET redeemed=true WHERE token=? AND redeemed=false AND expires_at > now() RETURNING *. Postgres serializes the row lock; one caller's UPDATE matches and returns the row, the loser matches zero rows and gets a 400. Expiry moves into the WHERE so an expired token also fails atomically (the prior code had a tiny window where it could redeem-then-fail-on-expiry).

Why this shape

The codebase already uses the same atomic-claim pattern in:

• apps/server/src/oauth/mcp.ts — auth-code consumption + refresh-token rotation
• apps/server/src/auth/sessions.ts — refresh-token rotation via DELETE … RETURNING

This brings setup-token redemption into line with that prior art. No shared helper extracted because each callsite uses different tables/predicates and abstracting prematurely would obscure the per-table invariants.

Stacked on #280

Branched on top of security/hash-setup-tokens (#280) so reviewers can read the two changes independently. GitHub will auto-retarget to main when #280 merges.

Audit context

PR 2 of 3 from the desktop pairing security review. PR 3 will add a unique index on api_keys.device_id so the corrupted state above is unrepresentable at the schema level even if a future regression reintroduces the race.

Test plan

• bun run typecheck (apps/server) — clean
• bun run test (apps/server) — 290 pass / 0 fail
• Manual: redeem a setup token end-to-end; confirm replaying the same token returns 400; confirm an expired token returns 400

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches authentication/token-issuance flow and changes database write semantics; mistakes could block legitimate setup-token redemption or allow unintended replays if predicates are wrong.

Overview
Fixes a race in POST /v1/auth/exchange by replacing the SELECT-then-UPDATE setup-token redemption with a single atomic UPDATE … WHERE token AND redeemed=false AND expiresAt>now() RETURNING.

This makes setup-token redemption one-time under concurrency and folds expiry validation into the claim step, returning 400 when no row is claimed.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d3405b39-719c-4307-90f1-a157ec1befe1

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 security/atomic-token-redemption

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[giuseppecrj]

closing due to #289