fix(cli): serialize token refresh across processes

[appleboy]

Summary

Two concurrent authgate-cli invocations that both see an expired access token race to call the refresh endpoint with the same refresh token. On servers that rotate refresh tokens (the go-authgate default), the first request consumes the token and the second gets invalid_grant, forcing the second CLI back into an interactive login. This PR serialises the refresh critical section across processes so only one refresh happens.

How it works

• Cross-process advisory lock (github.com/gofrs/flock) wraps the load → refresh → save critical section. It relies on kernel fcntl/LockFileEx and is released automatically if the holder crashes — no stale-lock heuristics required.
• Peer-refresh shortcut: after taking the lock the CLI re-reads the store; if a peer process already refreshed (the stored token is usable and differs from the stale copy), that fresh token is returned without a network call. If the peer rotated the refresh token, the rotated value is picked up before the exchange.
• Signature change: refreshAccessToken now takes the full stale credstore.Token (instead of just the refresh-token string) so peer-refresh detection can compare both the access and refresh token fields.
• Lock placement: the lock lives in refreshAccessToken, which every refresh path (run, ensureFreshToken, makeAPICallWithAutoRefresh) funnels through. For an explicit absolute token-file path the lock sits next to the file; for relative paths (the default, and keyring/auto backends where the token never touches disk) it is anchored under the user cache dir, so refresh never requires a writable working directory and concurrent runs from different directories still serialise. The client ID is hashed into the lock filename so it can never escape the lock directory.

Test plan

• go test ./... passes (incl. existing TestRefreshAccessToken_RotationMode)
• New TestRefreshAccessToken_PeerAlreadyRefreshed asserts no network call is made when the store already contains a peer-refreshed token
• New lock_test.go covers acquire/release, hostile client IDs (path traversal), and relative-path placement
• make lint is clean (golangci-lint: 0 issues)
• Manual: run two CLI instances against a rotation-mode server with an expired access token — confirm only one refresh request hits the server

Notes

• Reviewed with a multi-angle pass; behavior-preserving cleanups were folded in: the redundant lock-wrapper struct was dropped (*flock.Flock already satisfies io.Closer), and the peer-check reuses the shared tokenUsable predicate.
• Copilot review fixes folded in: the lock is now anchored in a cwd-independent, reliably-writable location for keyring/relative-path runs, and the client ID is hashed into a filesystem-safe lock filename (no path-traversal or invalid-character risk).

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

❌ Patch coverage is 67.44186% with 14 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
lock.go	66.66%	4 Missing and 4 partials ⚠️
auth.go	81.25%	2 Missing and 1 partial ⚠️
config.go	0.00%	2 Missing ⚠️
main.go	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR prevents concurrent authgate-cli processes from racing during refresh-token rotation by serializing the refresh-and-save critical section using a cross-process advisory lock, and adds coverage to ensure peer-refreshed tokens short-circuit the network call.

Changes:

• Add lockTokenStore (gofrs/flock-based) to serialize refresh across CLI processes.
• Update refreshAccessToken to accept the full stale token, re-load the store after lock acquisition, and return peer-refreshed tokens without a refresh request.
• Add a new test ensuring no network call occurs when a peer already refreshed, and update existing tests/call sites to the new refresh API.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
main_test.go	Updates test config to include TokenFile, adjusts refresh tests to new signature, and adds peer-refresh short-circuit test.
main.go	Updates refresh call site to pass the full stored token.
auth.go	Implements lock + peer-check logic in refreshAccessToken; updates auto-refresh call site.
config.go	Adds TokenFile to AppConfig and wires it through config/store initialization.
lock.go	Introduces cross-process advisory lock implementation used by refresh flow.
go.mod	Adds github.com/gofrs/flock dependency.
go.sum	Adds checksums for the new dependency.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.