[COR-343] auth-go refresh tier: e2e harness (mock OAuth server + cross-process tests)

[khaong]

Summary

Closes the test gaps that COR-314's unit/component tests can't, against the v0.4.0 refresh tier. Pure test infrastructure — no production code is modified. 3,247 insertions across 9 files in 10 commits.

What lands

• internal/testoauth/ — a tiny RFC-conformant mock OAuth server:

  • MintUnsignedJWT (alg: EdDSA, deliberately invalid sig) round-trips through tokens.ParseClaims.
  • Registry + Family — refresh-token state machine implementing RFC 6749 §6 rotation with RFC 9700 reuse-detection and an optional idempotent-successor window. Concurrent-rotation test pins single-rotation-wins under contention.
  • Server (httptest-backed) routes /oauth/token by grant_type: refresh_token, urn:…:token-exchange, urn:…:device_code, plus /oauth/device_authorization. Per-grant counters and FamilyRevoked() for assertions.
  • One-shot failure injection: ForceNextRefresh(FailInvalidGrant|FailNetworkError) (the latter via TCP connection hijack), StallNextRefresh() for holding refreshes in-flight across processes.

• tokenmanager/e2e_test.go — 6 in-process composed-flow tests against the real mock: refresh-on-expiry + exchange composition, two-cycle silent refresh, goroutine coalescing under real HTTP, rotation reuse-detection revoking the family and surfacing as ErrReauthRequired, idempotency window absorbing replay, network-failure-not-misclassified-as-reauth (validates the bug Codex's adversarial review caught on PR [COR-314] auth-go refresh tier: persist refresh + refresh_token grant + single-flight #10).

• tokenmanager/e2e_subprocess_test.go — 4 cross-process tests via the standard Go os.Args[0] self-re-exec pattern:

  • TestE2ESub_CrossProcessSingleFlight — two subprocesses + shared fileStore + same LockDir → server sees exactly 1 refresh grant; both processes return the same access token (proves cross-process token sharing via the lock + persist).
  • TestE2ESub_LogoutWinsOverInFlightRefresh / _ReloginWinsOverInFlightRefresh — subprocess A holds a stalled refresh, subprocess B's DeleteCoreToken/SaveCoreToken blocks on the cross-process flock, then runs. Asserts subprocess-side elapsed_ms >= stall_window AND RefreshGrantCount == 1 after both complete — rigorously proves serialisation rather than passing on a lucky write-race. This validates the fix Codex's adversarial review flagged on PR [COR-314] auth-go refresh tier: persist refresh + refresh_token grant + single-flight #10 for the first time at the OS-process layer.
  • TestE2ESub_ProclockMutualExclusion — pure proclock, two subprocesses, shared counter file with deliberate race window; counter must end at exactly 2 × rounds.
  • Subprocess tests gated by testing.Short().

Process

Standard subagent-driven dev (7 implementer tasks + multi-agent PR review). The PR-review-toolkit found 5 substantive items worth fixing pre-merge — all closed in commits 6d35709 + 7ef645d. Highlights of what review caught:

• The original logout/relogin tests' timing assertion was a parent-side tautology that couldn't catch a broken lock — now uses subprocess-side helperResult.ElapsedMs + RefreshGrantCount == 1.
• Claims.Extra ordering was inverse of sts.buildForm's convention — flipped to match (typed fields win on collision).
• Config.RefreshTokenTTL was documented but unused — removed.
• Several spec/impl divergences synced.
• fileStore.SaveTokens now honours the Store contract's empty-token rejection.
• Subprocess stderr capture now flushes residual non-newline-terminated bytes (the case where you most need them — panic output).

Verification

• mise run check — gofmt clean, golangci-lint 0 issues, govulncheck clean, all tests pass with -race
• go test ./... -race -count=3 — no flakiness over 3 runs
• GOOS=windows go build ./... — clean
• go test -short — subprocess tests correctly skipped
• Coverage: internal/testoauth 83.7%, tokenmanager 92.9% (up from 92.5% post-v0.4.0)
• Cursor Bugbot review (post-push)

Non-goals

• Real-keyring tests (tag-gated for local manual runs only — out of scope here).
• Latency injection / hostile-server chaos (deferred unless a specific risk surfaces).
• Integration against a real provider (entire-core, zitadel docker) — that belongs in the consuming CLI; auth-go stays provider-agnostic.

🤖 Generated with Claude Code

---

Note

Low Risk
Changes are limited to internal test code and documentation; production credential handling is unchanged, though the tests exercise sensitive refresh and lock behavior.

Overview
Adds test-only end-to-end coverage for the refresh tier (COR-343): no production tokenmanager or auth paths are modified.

A new internal/testoauth package provides an httptest mock OAuth server with refresh rotation, RFC 9700-style family revocation on replay, optional idempotent-successor window, token exchange, device flow, and hooks (ForceNextRefresh, StallNextRefresh, grant counters). tokenmanager/e2e_test.go runs six in-process scenarios (refresh + exchange, two refresh cycles, goroutine single-flight, reuse → ErrReauthRequired without deleting creds, idempotency, network error ≠ reauth). tokenmanager/e2e_subprocess_test.go re-execs the test binary via AUTHGO_E2E_HELPER for cross-process single-flight, logout/relogin vs stalled refresh (with subprocess elapsed_ms assertions), and proclock mutual exclusion; subprocess tests skip under -short. An approved design spec documents the harness.

^{Reviewed by Cursor Bugbot for commit da0ccbc. Configure here.}

[khaong]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 5bb057c. Configure here.}

[khaong]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit da0ccbc. Configure here.}