Skip to content

fix: share OAuth refreshes across server processes via a lock file - #52

Merged
beautyfree merged 4 commits into
tacticlaunch:mainfrom
myro-june:fix/oauth-refresh-across-processes
Nov 13, 2026
Merged

beautyfree merged 4 commits into
tacticlaunch:mainfrom
myro-june:fix/oauth-refresh-across-processes

Conversation

@myro-june

@myro-june myro-june commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem

With stored OAuth credentials (mcp-linear auth login), Linear tools start failing after a while with:

Failed to refresh the stored Linear access token (Linear OAuth token request failed (HTTP 400)). Run `mcp-linear auth login` again.

It happens whenever more than one server process uses the same config directory, which is the normal case: every MCP client session (each Claude Code or Codex window, for example) starts its own stdio server. I had 45 server processes running on one machine, all reading the same credentials.json, and hit the error in five sessions over three days. Reconnecting the MCP server in the failing session made it work again, and logging in again was not needed.

Cause

  1. createStoredCredentialAuth reads credentials.json once at startup and keeps the credentials in memory.
  2. refresh() sends the in-memory refresh token. Linear rotates the refresh token on every refresh, so the old one stops working as soon as any process refreshes.
  3. When process A refreshes, it writes the rotated token to the file, but process B still holds the old refresh token in memory. B's next refresh sends that revoked token and gets HTTP 400. B never re-reads the file, so it keeps failing until it restarts.

pendingRefresh only serializes refreshes inside one process, so it cannot prevent this.

Fix

  • Serialize refresh, login writes, and logout with an operating-system file lock using fs-native-extensions. The permanent lock file is not removed or reclaimed by age; the OS releases the lock on process exit. A waiter times out after 75 seconds.
  • After obtaining the lock, refresh reads the current credentials and reuses a fresh access token or rotates the latest refresh token. If credentials have been removed, refresh does not recreate them.
  • If an older process that does not use the lock rotates a token during a rejected refresh, reread the file and adopt the fresh token or retry once.
  • Credential writes still use an atomic temporary-file rename.
  • The Docker image uses Node 24 on Debian Bookworm so the native lock library has glibc available. Both build and runtime stages install from the lockfile with npm ci.

Verification

  • Local macOS run: npm test passed (284 tests and MCP smoke test); npm run build passed.
  • Tests using separate Node processes cover concurrent refresh, a live lock with an old timestamp, lock release after process termination, and login/logout waiting for a refresh. The login case runs runAuthCli with the real loopback OAuth callback and a controlled token response. Removing the production login lock makes this test fail.
  • Auth lock portability workflow covers macOS, Linux, and Windows on Node 20 and 24. A separate Docker job runs the full suite, builds the production image, acquires the native credential lock inside it, and runs the MCP smoke test against the server inside it.
  • Live refresh against Linear has not been tested.

Notes

  • The OS lock is advisory. Older server processes that do not use it can still race with the new version during rollout; restart old processes after upgrading.
  • The lock file must remain in place while processes are running. Removing or replacing it externally can bypass the lock.
  • Network errors and 5xx responses still suggest logging in again, as before.
  • npm run lint fails because ESLint 9 finds no flat config; the same configuration issue was reported on main.

Every MCP client session starts its own server process, and all of them
read one credentials.json. Each process read the file once at startup
and refreshed with the refresh token it held in memory. Linear rotates
the refresh token on every refresh, so once one process refreshed, the
others sent a revoked token and failed with "Failed to refresh the
stored Linear access token (... HTTP 400)" until the client reconnected.

Refreshes now run under a cross-process lock (credentials.json.lock,
created with O_EXCL; a lock older than 60s is reclaimed). Under the
lock the file is read again: a token another process already refreshed
is reused without a request, and an expired one is refreshed with the
newest refresh token from the file. If Linear still rejects the refresh
and the file now holds a different refresh token (a server build that
does not take the lock rotated it meanwhile), that token is adopted or
retried exactly once.

`auth login` and `auth logout` also write or delete under the lock, and
a refresh no longer recreates credentials that were logged out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@myro-june myro-june changed the title fix(auth): share OAuth refreshes across server processes via a lock file fix: share OAuth refreshes across server processes via a lock file Nov 13, 2026
@beautyfree
beautyfree merged commit e45f77e into tacticlaunch:main Nov 13, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants