fix(auth): serialize token refresh to prevent self-inflicted logout

[m-abdelwahab]

Problem

The Railway CLI logs users out frequently, forcing repeated railway login.

Root cause is a concurrency race in credential refresh:

• The CLI persists OAuth credentials to ~/.railway/config.json with a whole-file, last-writer-wins write and no lock.
• The server rotates the refresh token on every refresh and reuse-detects it: presenting an already-consumed (rotated) refresh token revokes the entire grant.
• So two concurrent CLI invocations past the 1h access-token expiry (e.g. a long-running railway mcp process alongside an interactive command, or a shell-prompt integration) both read the same refresh token and both POST grant_type=refresh_token. The second presents a now-consumed token → grant revoked → hard logout. Last-writer-wins can also overwrite a freshly-rotated token with a stale one.

Confirmed in production: ~128k/7d refresh token not found failures on the server's token endpoint, 99.6% from the CLI's OAuth client.

Change

• Serialize refresh behind an exclusive file lock (~/.railway/.config.lock, a dedicated lockfile — never config.json itself). After acquiring the lock, re-read the config and re-check expiry: only the lock winner refreshes; the others pick up its freshly-rotated token.
  • RAII guard releases the lock on every path (including errors / early returns).
  • 10s acquisition timeout with a graceful unlocked fallback (warn + refresh anyway) so a stale lock can never wedge the CLI.
  • Fast path (token still valid) is unchanged and takes no lock.
• Preserve the existing refresh token when a refresh response omits one, instead of nulling it.

Companion

This is the client-side half. The complementary server-side change (stop rotating public-client refresh tokens on every refresh) is in railwayapp/mono: railwayapp/mono#32205.

Testing

• cargo check clean; cargo fmt --check clean.
• cargo test --bin railway config:: (24 passed) and client:: (4 passed).
• clippy failures in this tree are pre-existing (graphql_client-generated code) and unrelated — confirmed by re-running on a clean tree.

Review notes

• fs2 advisory locks coordinate correctly between cooperating CLI processes (the race in scope). On network filesystems advisory locking can be unreliable, but ~/.railway is normally local; the unlocked fallback degrades to today's behavior rather than wedging.
• Lock timeout is 10s (CONFIG_LOCK_TIMEOUT) — comfortably covers a refresh round-trip; bump if refreshes can ever exceed that.

🤖 Generated with Claude Code