Refreshable tokens (2/7): refresher domain, OAuth refresher, storage, and wiring - #14451

Part of #14449. Based on #14450 (foundation).

Description

The domain and orchestration layer for refreshable tokens: the machinery that acquires, stores, and refreshes a short-lived credential, and the factory wiring that injects the refresher. It is still not reachable by a user, because nothing yet requests a refreshable token (that arrives with --short-lived in PR 3), so on its own this PR changes no observable behavior.

It introduces, bottom to top:

1. Refreshable credential types and a TokenRefresher interface (plus its generated mock).
2. An OAuth token refresher in internal/authflow that exchanges a refresh token for a new credential.
3. Refreshable credential storage in internal/config, persisted only in the per-user slot.
4. Integration of refreshable credentials into the auth config, including the serialized refresh path (lock, reload, rotate, persist).
5. An API-request hook that refreshes an expired token before the request goes out.
6. Factory wiring that injects the refresher so the consumer seams in later PRs can use it.

How did you test this change?

This feature is verified end to end as a whole rather than per PR. End-to-end tests should pass.

Key points

The refresh lock: what it guards and why its scope is narrow

The cross-process config lock (withFreshConfigForRefresh) exists to protect a single-use, rotating refresh token from double-spend. A rotating refresh token is a single-use secret: if two actors present the same refresh token to the OAuth server, one exchange succeeds and the other is rejected, and many providers respond to reuse by revoking the entire token family, logging the user fully out with no recovery except re-authenticating. With today's extensive use of agents and concurrent workflows, two gh processes sharing an account (or two goroutines on the shared AuthConfig) can realistically hit an expired token at the same moment, read the same refresh token from disk, and both POST it. The lock plus a reload guarantees each refresh observes the latest on-disk token before spending it.

Only the refresh path and LoginRefreshable participate in that read-modify-write cycle, so only they take the lock. LoginRefreshable writes into the same rotating-credential slot, so it must serialize against a concurrent refresh as well.

login, switch, and logout are deliberately not wrapped, for three reasons:

1. They do not consume a single-use secret. They overwrite credentials wholesale, so their worst concurrent outcome is a benign last-writer-wins that still leaves the config in a valid, usable state, which is exactly what a user who is re-authenticating wants anyway.
2. They are user-initiated and interactive, effectively one-at-a-time. Refresh is the only operation that fires automatically in the background of ordinary commands, so it is the only one realistically prone to firing twice at once.
3. An honest incremental reason: withFreshConfigForRefresh calls Reload, which discards unwritten in-memory state. Wrapping the lifecycle methods would change their contract and require reworking the tests that build state in memory rather than persisting via disk. We deliberately deferred that broader wrapping.

A refresh racing a manual login is possible but harmless: both write valid credentials, last-writer-wins yields a working state, and the only cost is a possible re-auth, never a revoked token family. So serializing refresh-against-refresh (in-process mutex plus cross-process flock) covers the only race that can corrupt the rotating-token chain; guarding the other operations would add contention for no additional safety.

To make the scope obvious in the code, the lock artifacts are refresh-specific rather than general-config: the lock file is refresh.lock, the constants are refreshLockFile and refreshLockTimeout, and the guard method is withFreshConfigForRefresh.

Storage: refreshable credentials live only in the per-user slot

Unlike non-expiring tokens, a refreshable credential is persisted only in the per-user slot (keyring service gh:_refreshable:<host> under the username key, or config hosts.<host>.users.<user>.<refreshable key>). There is deliberately no per-host active copy (no keyring "" key, no hosts.<host>.oauth_token) for refreshable credentials.

1. Single source of truth. The credential rotates on every refresh. Keeping one authoritative copy per user avoids the risk of a stale duplicate in a host-level active slot outranking the freshly rotated token. The active user is surfaced through the hosts.<host>.user pointer, and resolution reads the credential back through the per-user slot, so activation only needs to confirm the per-user record exists (see setActiveCredential).
2. Login and activation actively clear the host-level active representations for refreshable credentials, so a previously stored non-expiring active token can never shadow a refreshable one.
3. Consequences for removal. Because there is no host-level active copy, wiping a rejected refreshable credential only needs to clear the per-user records; removeCredentialForUser does not touch the host-level active slot. Likewise persistRefreshedCredential writes back only to the per-user slot it was read from.

Factory wiring: keeping refresh traffic out of the debug log

GH_DEBUG=api prints a verbose trace of HTTP traffic, but the token-refresh exchange is deliberately kept out of it. The factory builds the refresher on a dedicated HTTP client (tokenRefresherHttpClientFunc) configured for headline-only logging, so even under GH_DEBUG=api a refresh emits at most a single head line (the token endpoint URL and its timing), never the request and response bodies. Those bodies carry live secrets: the refresh token going out and a freshly issued access token coming back. Debug logs tend to be long, and users routinely paste them into issues or share them while troubleshooting without scrubbing every line, so dumping a full refresh trace would leak rotating credentials into a trail that outlives the exchange. Keeping the refresh exchange headline-only is a deliberate privacy-hardening choice, not an oversight. A testing-only override, GH_DEBUG_REFRESH_TOKEN, forces the verbose refresh trace for local debugging, and it is removed in the polish PR.

Notes for reviewers

internal/authflow/flow.go is touched here and again in PR 3. In this PR only the local api-client config adapter is updated (needed by the API refresh hook). The public AuthFlow signature change lands in PR 3 alongside its callers, so this PR's tip stays green.

Suggested reading order: the gh credential/refresher types, then the authflow refresher, then config storage, then the auth-config integration (where the lock lives), then the API hook, then factory wiring.

Commits (review in order):

• fix(gh): add refreshable credential types and token refresher interface
• fix(gh): add generated TokenRefresher mock
• fix(authflow): add OAuth token refresher
• fix(config): add refreshable credential storage
• fix(config): integrate refreshable credentials into auth config
• fix(api): refresh expired tokens on API requests
• fix(factory): wire the token refresher into the default factory

Authorship and follow-up

Who wrote this:

• A human wrote it.
• An agent wrote it under close human direction.
• An agent wrote it independently, and no human has guided the implementation beyond the initial prompt.

Who answers review comments:

• @babakks will read and reply directly.
• An agent will draft replies and @username will read them before they are posted.
• Nobody has explicitly committed to replying.