johannSoCodeyPublic

claudecode: refresh the access token, write back only on rotation

An expired login now renews itself instead of telling you to go run
claude.

The endpoint never answered — ten attempts, every one a 429, no
exchange ever completed — so whether it rotates refresh tokens is still
unknown. Rather than gamble on it, the code stops needing the answer.
Refresh keeps the result in memory, which is the common path and never
touches the file. It compares the returned refresh token to the stored
one, and writes back only when they differ: if the server rotated, the
token on disk is already dead, and leaving it there is precisely what
breaks the user's Claude Code login. Writing is the safe act in that
one case and the risky one everywhere else, so it is conditional rather
than routine.

Save is a read-modify-write, not a serialize. It rewrites a file Claude
Code owns, so every key it did not come to change goes back as found —
including rateLimitTier, which this package does not model. Numbers
decode as literals rather than float64, or the millisecond timestamps
would come back as 1.78966826946e+12 and we would have corrupted the
file we were trying to keep valid. Verified by round-tripping a copy of
a real credentials file and diffing every key.

Write-back is best effort: a store we cannot write is a worse next
session, not a failed current one.

None of this is verified against the live endpoint, because the live
endpoint has never once responded. It is verified against httptest and
against the real file's shape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Browse Files

Jjonicommitted 4 weeks ago1 parent 17474dccommitd10d851

Showing 7 changed files with 699 additions and 59 deletions.

+4−2README.mdView File

@@ -45,8 +45,10 @@ from another client is outside Anthropic's terms for it, which API keys and
45	45	gateway tokens do not carry.
46	46
47	47	On macOS Claude Code keeps this in the Keychain rather than a file, so there is
48		- nothing to borrow there. An expired access token is not refreshed — run `claude`
49		- and the harness picks up the new one.
	48	+ nothing to borrow there. An expired access token is refreshed automatically; the
	49	+ credentials file is left alone unless the server rotates the refresh token, in
	50	+ which case the replacement is written back — leaving the dead one there is what
	51	+ would break your Claude Code login.
50	52
51	53	Useful flags: `-model`, `-effort low\|medium\|high\|xhigh\|max`, `-max-turns`,
52	54	`-resume latest`, `-no-stream`, `-no-cache`, `-v`, `-yolo`, `-no-tui`, `-no-skills`,

+4−1cmd/harness/main.goView File

@@ -356,7 +356,10 @@ func resolveClaudeCode(client *llm.Client, home string, disabled bool) (func(con
356	356	return nil, "", err
357	357	}
358	358	note := fmt.Sprintf("using your Claude Code login (%s plan) from ~/%s", creds.SubscriptionType, claudecode.Filename)
359		- return claudecode.NewSource(creds).Token, note, nil
	359	+ // home is handed on so a rotated refresh token can be written back. That
	360	+ // is the only circumstance in which this process writes to Claude Code's
	361	+ // file, and not writing then is what would break its login.
	362	+ return claudecode.NewSource(creds, client.HTTP, home).Token, note, nil
360	363	}
361	364
362	365	// interactive reports whether both ends of the terminal are a real one. A

+60−24docs/superpowers/specs/2026-09-17-claude-code-oauth-design.mdView File

@@ -66,24 +66,33 @@ skips discovery entirely.
66	66
67	67	## `internal/claudecode`
68	68
69		- One package, three jobs, no ambient state:
	69	+ One package, one concern, no ambient state:
70	70
71	71	```go
72	72	type Credentials struct {
73		- AccessToken, RefreshToken string
74		- ExpiresAt time.Time
75		- Scopes []string
76		- SubscriptionType string
	73	+ AccessToken, RefreshToken string
	74	+ ExpiresAt, RefreshExpiresAt time.Time
	75	+ Scopes []string
	76	+ SubscriptionType string
77	77	}
78	78
79		- func Load(home string) (*Credentials, error) // parse. no network
80		- func (c *Credentials) Expired(now time.Time) bool // with skew
	79	+ func Load(home string) (*Credentials, error) // parse. no network
	80	+ func Save(home string, c *Credentials) error // read-modify-write, atomic
	81	+ func (c *Credentials) Expired(now time.Time) bool // with skew
	82	+ func (c *Credentials) RefreshExpired(now time.Time) bool // terminal
81	83	func Refresh(context.Context, http.Client, Credentials) (*Credentials, error)
	84	+
	85	+ // Source is the policy: refresh on expiry, write back only on rotation.
	86	+ func NewSource(c Credentials, h http.Client, home string) *Source
	87	+ func (s *Source) Token(context.Context) (string, error)
82	88	```
83	89
84	90	`Load` takes `home` rather than calling `os.UserHomeDir` so tests point it at a
85	91	fixture directory, matching how `skills.Discover` already takes its roots.
86		- `Refresh` returns new credentials and writes nothing — see below.
	92	+ `Refresh` returns new credentials and writes nothing; `Source` decides whether
	93	+ anything is persisted, because that decision is policy and `Refresh` is
	94	+ mechanism. `NewSource` takes `home` rather than a path so the "no write-back"
	95	+ case is the obvious one to express — pass `""`.
87	96
88	97	Missing file is not an error worth decorating: it means "not logged in", and the
89	98	caller falls through to `errNoCredentials`. A file that exists but does not parse
@@ -126,41 +135,68 @@ process lifetime, and is mutex-guarded: streaming and non-streaming requests can
126	135	be in flight together, and two concurrent refreshes of the same token is exactly
127	136	the scenario the next section is about.
128	137
129		- ## Refresh: not shipped, and why
	138	+ ## Refresh, and the question that could not be answered
130	139
131	140	The question was whether `POST /v1/oauth/token` rotates refresh tokens. If it
132	141	does, refreshing without writing the result back consumes the token Claude Code
133	142	still has on disk — its copy goes dead and `claude` asks you to log in again.
134	143	We would have broken a tool outside this repo to save a paste.
135	144
136		- The probe never got an answer, and that is the answer. Nine attempts to
	145	+ The probe never got an answer, and that is the answer. Ten attempts to
137	146	`https://console.anthropic.com/v1/oauth/token` with the stored refresh token and
138		- Claude Code's client id, spread over roughly six minutes, every one of them:
	147	+ Claude Code's client id — nine in a burst over roughly six minutes, then one
	148	+ more much later in case the first nine were self-inflicted — every one of them:
139	149
140	150	```
141	151	HTTP 429 {"error":{"type":"rate_limit_error","message":"Rate limited. Please try again later."}}
142	152	```
143	153
144	154	No exchange ever happened, so the refresh token was not consumed and nothing
145		- was damaged. A rejection that persists uniformly across six minutes is not
146		- throttling. And we have already seen this exact pattern once: the Messages API
147		- answers a request shape it declines with `429 rate_limit_error` too, rather than
148		- a 401. On these OAuth surfaces a 429 is not reliable evidence of a rate limit,
149		- which is worth knowing before anyone reads one as "wait and retry".
	155	+ was damaged. A rejection that persists uniformly across six minutes, and again
	156	+ long after the traffic that might have caused it, is not throttling. And we have
	157	+ already seen this exact pattern once: the Messages API answers a request shape
	158	+ it declines with `429 rate_limit_error` too, rather than a 401. On these OAuth
	159	+ surfaces a 429 is not reliable evidence of a rate limit, which is worth knowing
	160	+ before anyone reads one as "wait and retry".
150	161
151	162	The honest reading is that this request — endpoint, client id, or grant shape —
152	163	is not the one this credential is refreshed with. Finding the one that is would
153	164	mean guessing at authentication endpoints while holding someone's live refresh
154	165	token, which is not a thing to do on a hunch.
155	166
156		- So refresh is not implemented. The shipped behaviour is the fallback, and it
157		- is a complete feature: use the stored access token, and when it has expired fail
158		- with `your Claude Code login has expired, run claude to refresh it`. Tokens last
159		- around eight hours, so the cost is an occasional re-login — paid by running the
160		- tool that owns the credential, which is the right place to pay it.
161		-
162		- If refresh is wanted later, the open question is unchanged and the probe is
163		- unchanged; what is needed first is a refresh route that actually responds.
	167	+ Refresh is implemented anyway, designed for both answers. Since we cannot
	168	+ learn whether the endpoint rotates, the code stops needing to know:
	169	+
	170	+ - Refresh, and keep the result in memory. This is the common path and it never
	171	+ touches the file, which is what "keep in memory" was asking for.
	172	+ - Compare the returned refresh token to the stored one. If it is absent or
	173	+ identical, nothing is written — ever.
	174	+ - If it differs, the server rotated, and the token still on disk is already
	175	+ dead. Leaving it there is what breaks the Claude Code login. So that one case
	176	+ writes back, and writing is the safe act rather than the risky one.
	177	+
	178	+ The conditional is the whole design. Unconditional write-back makes us a routine
	179	+ writer of another tool's credential store; never writing gambles the user's
	180	+ login on an answer we could not get. Writing exactly when not writing has
	181	+ already caused harm needs no answer at all.
	182	+
	183	+ `Save` is a read-modify-write, not a serialize: the document is parsed, the
	184	+ three fields we came to change are replaced, and every other key goes back as
	185	+ found — including `rateLimitTier`, which this package does not model, and any
	186	+ key it has never heard of. Numbers decode as literals rather than float64, or
	187	+ the millisecond timestamps would return as `1.78966826946e+12` and we would have
	188	+ corrupted the file we were trying to keep valid. The write is atomic: temp file
	189	+ in the same directory, `0600`, then rename, so a crash midway leaves the
	190	+ original rather than half a credential. Verified by round-tripping a copy of a
	191	+ real credentials file and diffing every key.
	192	+
	193	+ Write-back is best effort. A store we cannot write is a worse next session, not
	194	+ a failed current one — we are holding a token that works, and refusing to use it
	195	+ would be strictly worse than a stale file.
	196	+
	197	+ Because the endpoint has never once answered, none of this is verified against
	198	+ the live service. It is verified against `httptest` and against the real file's
	199	+ shape. The first real refresh is still the first real refresh.
164	200
165	201	## The system prompt
166	202

+0−28internal/claudecode/claudecode.goView File

@@ -8,7 +8,6 @@
8	8	package claudecode
9	9
10	10	import (
11		- "context"
12	11	"encoding/json"
13	12	"errors"
14	13	"fmt"
@@ -95,30 +94,3 @@ func (c *Credentials) Expired(now time.Time) bool {
95	94	func (c *Credentials) RefreshExpired(now time.Time) bool {
96	95	return !now.Before(c.RefreshExpiresAt)
97	96	}
98		-
99		- // ErrExpired means the stored access token has lapsed. Refresh is not
100		- // implemented: probing the token endpoint got a persistent 429 on every
101		- // attempt, with no exchange ever happening, so there is no evidence of a
102		- // route that actually refreshes this credential — and guessing further at
103		- // auth endpoints while holding someone's live refresh token is not something
104		- // to do on a hunch. Falling back to "expired, run claude to refresh it" is a
105		- // complete feature on its own: tokens last hours, so the cost is an
106		- // occasional re-login, paid by the tool that owns the credential.
107		- var ErrExpired = errors.New("claudecode: your Claude Code login has expired, run `claude` to refresh it")
108		-
109		- // Source hands out the access token for as long as it is valid. It satisfies
110		- // the shape llm.WithTokenSource wants.
111		- type Source struct {
112		- creds *Credentials
113		- }
114		-
115		- // NewSource wraps credentials in a token source.
116		- func NewSource(c Credentials) Source { return &Source{creds: c} }
117		-
118		- // Token returns the access token, or ErrExpired once it has lapsed.
119		- func (s *Source) Token(context.Context) (string, error) {
120		- if s.creds.Expired(time.Now()) {
121		- return "", ErrExpired
122		- }
123		- return s.creds.AccessToken, nil
124		- }

+7−4internal/claudecode/claudecode_test.goView File

@@ -139,11 +139,13 @@ func TestRefreshExpiredIsTerminal(t *testing.T) {
139	139	}
140	140	}
141	141
	142	+ // A token that has not lapsed is handed straight back, with no refresh and no
	143	+ // network of any kind.
142	144	func TestSourceReturnsTheAccessToken(t *testing.T) {
143	145	s := NewSource(&Credentials{
144	146	AccessToken: "tok",
145	147	ExpiresAt: time.Now().Add(time.Hour),
146		- })
	148	+ }, nil, "")
147	149	got, err := s.Token(context.Background())
148	150	if err != nil {
149	151	t.Fatalf("Token: %v", err)
@@ -153,13 +155,14 @@ func TestSourceReturnsTheAccessToken(t *testing.T) {
153	155	}
154	156	}
155	157
156		- // Until refresh lands, an expired token is a clear instruction rather than a
157		- // 401 from the API.
	158	+ // An expired token with nothing to refresh it by is a clear instruction rather
	159	+ // than a puzzling rejection from the API. Refreshing when there IS a usable
	160	+ // refresh token is covered in refresh_test.go.
158	161	func TestSourceExpiredTokenSaysWhatToDo(t *testing.T) {
159	162	s := NewSource(&Credentials{
160	163	AccessToken: "tok",
161	164	ExpiresAt: time.Now().Add(-time.Hour),
162		- })
	165	+ }, nil, "")
163	166	_, err := s.Token(context.Background())
164	167	if !errors.Is(err, ErrExpired) {
165	168	t.Fatalf("err = %v, want ErrExpired", err)

+232−0internal/claudecode/refresh.goaddedView File

++ package claudecode
++ import (
++ 	"bytes"
++ 	"context"
++ 	"encoding/json"
++ 	"errors"
++ 	"fmt"
++ 	"io"
++ 	"net/http"
++ 	"os"
++ 	"path/filepath"
++ 	"strconv"
++ 	"sync"
++ 	"time"
++ )
++ // ClientID identifies Claude Code to the token endpoint.
++ const ClientID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
++ // tokenURLEnv overrides the token endpoint. It exists so tests can point at an
++ // httptest server; nothing in normal operation sets it.
++ const tokenURLEnv = "CLAUDECODE_TOKEN_URL"
++ const defaultTokenURL = "https://console.anthropic.com/v1/oauth/token"
++ // tokenURL is the endpoint a refresh is sent to.
++ func tokenURL() string {
++ 	if u := os.Getenv(tokenURLEnv); u != "" {
++ 		return u
++ 	}
++ 	return defaultTokenURL
++ }
++ // ErrExpired means the credential has lapsed and cannot be renewed here —
++ // either the refresh token is gone or itself expired. Only logging in again
++ // fixes it, and the tool that owns the credential is the one to do it.
++ var ErrExpired = errors.New("claudecode: your Claude Code login has expired, run `claude` to refresh it")
++ // Refresh exchanges the refresh token for a new access token. It returns new
++ // credentials and writes nothing — persisting is a separate decision, made by
++ // Source, because whether it is safe depends on whether the server rotated.
++ //
++ // Every failure says to run `claude`, including a 429. On these OAuth surfaces
++ // a 429 is not reliable evidence of a rate limit: the Messages API answers a
++ // request shape it declines the same way, and every probe of this endpoint has
++ // returned one without ever completing an exchange. Advising someone to wait
++ // would be advice that may never come good.
++ func Refresh(ctx context.Context, h *http.Client, c *Credentials) (*Credentials, error) {
++ 	body, err := json.Marshal(map[string]string{
++ 		"grant_type":    "refresh_token",
++ 		"refresh_token": c.RefreshToken,
++ 		"client_id":     ClientID,
++ 	})
++ 	if err != nil {
++ 		return nil, err
++ 	}
++ 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, tokenURL(), bytes.NewReader(body))
++ 	if err != nil {
++ 		return nil, err
++ 	}
++ 	req.Header.Set("content-type", "application/json")
++ 	resp, err := h.Do(req)
++ 	if err != nil {
++ 		return nil, fmt.Errorf("claudecode: refreshing: %w", err)
++ 	}
++ 	defer resp.Body.Close()
++ 	raw, err := io.ReadAll(resp.Body)
++ 	if err != nil {
++ 		return nil, fmt.Errorf("claudecode: reading refresh response: %w", err)
++ 	}
++ 	if resp.StatusCode != http.StatusOK {
++ 		return nil, fmt.Errorf("claudecode: refresh refused (%d), run `claude` to log in again: %s",
++ 			resp.StatusCode, bytes.TrimSpace(raw))
++ 	}
++ 	var out struct {
++ 		AccessToken  string `json:"access_token"`
++ 		RefreshToken string `json:"refresh_token"`
++ 		ExpiresIn    int64  `json:"expires_in"`
++ 	}
++ 	if err := json.Unmarshal(raw, &out); err != nil {
++ 		return nil, fmt.Errorf("claudecode: decoding refresh response: %w", err)
++ 	}
++ 	if out.AccessToken == "" {
++ 		return nil, errors.New("claudecode: refresh returned no access token")
++ 	}
++ 	next := *c
++ 	next.AccessToken = out.AccessToken
++ 	// An omitted refresh_token means the old one is still good. Blanking it
++ 	// would throw away the only thing that can refresh again.
++ 	if out.RefreshToken != "" {
++ 		next.RefreshToken = out.RefreshToken
++ 	}
++ 	next.ExpiresAt = time.Now().Add(time.Duration(out.ExpiresIn) * time.Second)
++ 	return &next, nil
++ }
++ // Save writes credentials back to the store.
++ //
++ // This rewrites a file Claude Code owns, so it is a read-modify-write: the
++ // document is parsed, only the three fields we came to change are replaced,
++ // and everything else — keys this package does not model, keys it has never
++ // heard of — goes back exactly as it was found. Numbers are decoded as literals
++ // rather than float64s, or the millisecond timestamps would come back as
++ // 1.78966826946e+12 and Claude Code would be reading a file we corrupted.
++ //
++ // The write is atomic: a temp file in the same directory, then a rename, so a
++ // crash midway leaves the original rather than a truncated credential.
++ func Save(home string, c *Credentials) error {
++ 	path := filepath.Join(home, Filename)
++ 	raw, err := os.ReadFile(path)
++ 	if err != nil {
++ 		return fmt.Errorf("claudecode: reading %s: %w", path, err)
++ 	}
++ 	var doc map[string]json.RawMessage
++ 	dec := json.NewDecoder(bytes.NewReader(raw))
++ 	dec.UseNumber()
++ 	if err := dec.Decode(&doc); err != nil {
++ 		return fmt.Errorf("claudecode: parsing %s: %w", path, err)
++ 	}
++ 	blob, ok := doc["claudeAiOauth"]
++ 	if !ok {
++ 		return fmt.Errorf("claudecode: %s has no claudeAiOauth object", path)
++ 	}
++ 	var oauth map[string]any
++ 	dec = json.NewDecoder(bytes.NewReader(blob))
++ 	dec.UseNumber()
++ 	if err := dec.Decode(&oauth); err != nil {
++ 		return fmt.Errorf("claudecode: parsing claudeAiOauth in %s: %w", path, err)
++ 	}
++ 	oauth["accessToken"] = c.AccessToken
++ 	oauth["refreshToken"] = c.RefreshToken
++ 	oauth["expiresAt"] = json.Number(strconv.FormatInt(c.ExpiresAt.UnixMilli(), 10))
++ 	if blob, err = json.Marshal(oauth); err != nil {
++ 		return fmt.Errorf("claudecode: encoding claudeAiOauth: %w", err)
++ 	}
++ 	doc["claudeAiOauth"] = blob
++ 	out, err := json.Marshal(doc)
++ 	if err != nil {
++ 		return fmt.Errorf("claudecode: encoding %s: %w", path, err)
++ 	}
++ 	tmp, err := os.CreateTemp(filepath.Dir(path), ".credentials-*.tmp")
++ 	if err != nil {
++ 		return fmt.Errorf("claudecode: writing %s: %w", path, err)
++ 	}
++ 	defer os.Remove(tmp.Name())
++ 	if err := tmp.Chmod(0o600); err != nil {
++ 		tmp.Close()
++ 		return fmt.Errorf("claudecode: securing %s: %w", tmp.Name(), err)
++ 	}
++ 	if _, err := tmp.Write(out); err != nil {
++ 		tmp.Close()
++ 		return fmt.Errorf("claudecode: writing %s: %w", tmp.Name(), err)
++ 	}
++ 	if err := tmp.Close(); err != nil {
++ 		return fmt.Errorf("claudecode: closing %s: %w", tmp.Name(), err)
++ 	}
++ 	if err := os.Rename(tmp.Name(), path); err != nil {
++ 		return fmt.Errorf("claudecode: replacing %s: %w", path, err)
++ 	}
++ 	return nil
++ }
++ // Source hands out an access token, refreshing it when it lapses. It satisfies
++ // the shape llm.WithTokenSource wants.
++ type Source struct {
++ 	mu    sync.Mutex
++ 	creds *Credentials
++ 	http  *http.Client
++ 	// home is where a rotated credential is written back. Empty disables
++ 	// write-back entirely.
++ 	home string
++ }
++ // NewSource wraps credentials in a token source. h is the client refreshes are
++ // sent with; home is the directory holding the credential store, or "" to
++ // refresh without ever writing.
++ func NewSource(c *Credentials, h *http.Client, home string) *Source {
++ 	if h == nil {
++ 		h = http.DefaultClient
++ 	}
++ 	return &Source{creds: c, http: h, home: home}
++ }
++ // Token returns a valid access token, refreshing first if the current one has
++ // lapsed.
++ //
++ // The refreshed credential is kept in memory. It is written back only when the
++ // server rotated the refresh token, and that is the point: if rotation
++ // happened, the token still on disk is already dead, so leaving it there is
++ // what breaks the user's Claude Code login. Writing is the safe act in that
++ // case and the risky one in every other, which is why it is conditional rather
++ // than routine.
++ //
++ // The lock means concurrent requests — streaming and buffered can be in flight
++ // together — produce one refresh rather than a thundering herd.
++ func (s *Source) Token(ctx context.Context) (string, error) {
++ 	s.mu.Lock()
++ 	defer s.mu.Unlock()
++ 	now := time.Now()
++ 	if !s.creds.Expired(now) {
++ 		return s.creds.AccessToken, nil
++ 	}
++ 	if s.creds.RefreshToken == "" || s.creds.RefreshExpired(now) {
++ 		return "", ErrExpired
++ 	}
++ 	next, err := Refresh(ctx, s.http, s.creds)
++ 	if err != nil {
++ 		return "", err
++ 	}
++ 	rotated := next.RefreshToken != s.creds.RefreshToken
++ 	s.creds = next
++ 	if rotated && s.home != "" {
++ 		// Best effort. A store we cannot write is a worse next session, not a
++ 		// failed this one — we are holding a token that works, and refusing to
++ 		// use it would be a strictly worse outcome than the stale file.
++ 		if err := Save(s.home, s.creds); err != nil {
++ 			return s.creds.AccessToken, nil
++ 		}
++ 	}
++ 	return s.creds.AccessToken, nil
++ }

+392−0internal/claudecode/refresh_test.goaddedView File

++ package claudecode
++ import (
++ 	"context"
++ 	"encoding/json"
++ 	"errors"
++ 	"io"
++ 	"net/http"
++ 	"net/http/httptest"
++ 	"os"
++ 	"path/filepath"
++ 	"strings"
++ 	"sync"
++ 	"testing"
++ 	"time"
++ )
++ // liveCreds is a credential that has lapsed but whose refresh token has not,
++ // which is the only state in which a refresh should be attempted.
++ func liveCreds() *Credentials {
++ 	return &Credentials{
++ 		AccessToken:      "stale",
++ 		RefreshToken:     "r1",
++ 		ExpiresAt:        time.Now().Add(-time.Hour),
++ 		RefreshExpiresAt: time.Now().Add(24 * time.Hour),
++ 	}
++ }
++ func TestRefreshExchangesTheToken(t *testing.T) {
++ 	var body map[string]any
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		json.NewDecoder(r.Body).Decode(&body)
++ 		io.WriteString(w, `{"access_token":"new-access","refresh_token":"new-refresh","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	got, err := Refresh(context.Background(), srv.Client(), &Credentials{AccessToken: "old", RefreshToken: "old-refresh"})
++ 	if err != nil {
++ 		t.Fatalf("Refresh: %v", err)
++ 	}
++ 	if got.AccessToken != "new-access" || got.RefreshToken != "new-refresh" {
++ 		t.Errorf("got %q/%q, want new-access/new-refresh", got.AccessToken, got.RefreshToken)
++ 	}
++ 	if body["grant_type"] != "refresh_token" || body["refresh_token"] != "old-refresh" {
++ 		t.Errorf("request body = %v", body)
++ 	}
++ 	if body["client_id"] != ClientID {
++ 		t.Errorf("client_id = %v, want %s", body["client_id"], ClientID)
++ 	}
++ 	// expires_in is a duration; the stored form is an absolute instant.
++ 	if !got.ExpiresAt.After(time.Now().Add(7 * time.Hour)) {
++ 		t.Errorf("ExpiresAt = %s, want ~8h out", got.ExpiresAt)
++ 	}
++ }
++ // A response that omits refresh_token means the old one stays valid. Blanking
++ // it would throw away the only thing that can refresh again.
++ func TestRefreshKeepsTheOldRefreshTokenWhenNoneIsReturned(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		io.WriteString(w, `{"access_token":"new-access","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	got, err := Refresh(context.Background(), srv.Client(), &Credentials{RefreshToken: "keep-me"})
++ 	if err != nil {
++ 		t.Fatalf("Refresh: %v", err)
++ 	}
++ 	if got.RefreshToken != "keep-me" {
++ 		t.Errorf("RefreshToken = %q, want the original kept", got.RefreshToken)
++ 	}
++ }
++ func TestRefreshRejectedSaysToLogInAgain(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		w.WriteHeader(http.StatusBadRequest)
++ 		io.WriteString(w, `{"error":"invalid_grant"}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	_, err := Refresh(context.Background(), srv.Client(), &Credentials{RefreshToken: "dead"})
++ 	if err == nil || !strings.Contains(err.Error(), "claude") {
++ 		t.Fatalf("err = %v, want an error telling the user to run claude", err)
++ 	}
++ }
++ // A 429 from these OAuth surfaces is not reliable evidence of a rate limit:
++ // the Messages API answers a request shape it declines the same way. Telling
++ // the user to wait would be advice that never comes good.
++ func TestRefreshRateLimitedDoesNotAdviseWaiting(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		w.WriteHeader(http.StatusTooManyRequests)
++ 		io.WriteString(w, `{"error":{"type":"rate_limit_error","message":"Rate limited. Please try again later."}}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	_, err := Refresh(context.Background(), srv.Client(), &Credentials{RefreshToken: "r"})
++ 	if err == nil {
++ 		t.Fatal("a 429 must be an error")
++ 	}
++ 	if !strings.Contains(err.Error(), "claude") {
++ 		t.Errorf("a 429 should still point at `claude`, got %q", err)
++ 	}
++ }
++ func TestRefreshTransportErrorIsReported(t *testing.T) {
++ 	t.Setenv(tokenURLEnv, "http://127.0.0.1:1")
++ 	_, err := Refresh(context.Background(), &http.Client{Timeout: time.Second}, &Credentials{RefreshToken: "r"})
++ 	if err == nil {
++ 		t.Fatal("a transport error must be reported")
++ 	}
++ }
++ // The point of the feature: an expired token becomes a working one without the
++ // caller knowing anything happened, and only one exchange is spent doing it.
++ func TestSourceRefreshesOnExpiryAndCaches(t *testing.T) {
++ 	var hits int
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		hits++
++ 		io.WriteString(w, `{"access_token":"fresh","refresh_token":"r1","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	s := NewSource(liveCreds(), srv.Client(), "")
++ 	for i := 0; i < 3; i++ {
++ 		tok, err := s.Token(context.Background())
++ 		if err != nil {
++ 			t.Fatalf("Token: %v", err)
++ 		}
++ 		if tok != "fresh" {
++ 			t.Fatalf("Token = %q, want fresh", tok)
++ 		}
++ 	}
++ 	if hits != 1 {
++ 		t.Errorf("refreshed %d times, want 1 — the result should be cached", hits)
++ 	}
++ }
++ func TestSourceConcurrentTokensRefreshOnce(t *testing.T) {
++ 	var mu sync.Mutex
++ 	var hits int
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		mu.Lock()
++ 		hits++
++ 		mu.Unlock()
++ 		io.WriteString(w, `{"access_token":"fresh","refresh_token":"r1","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	s := NewSource(liveCreds(), srv.Client(), "")
++ 	var wg sync.WaitGroup
++ 	for i := 0; i < 8; i++ {
++ 		wg.Add(1)
++ 		go func() {
++ 			defer wg.Done()
++ 			if _, err := s.Token(context.Background()); err != nil {
++ 				t.Error(err)
++ 			}
++ 		}()
++ 	}
++ 	wg.Wait()
++ 	if hits != 1 {
++ 		t.Errorf("refreshed %d times under concurrency, want 1", hits)
++ 	}
++ }
++ // An expired refresh token cannot be refreshed. Sending the request anyway
++ // spends a round trip to be told what we already knew.
++ func TestSourceExpiredRefreshTokenDoesNotCallOut(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		t.Error("no request should be sent for a dead refresh token")
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	c := liveCreds()
++ 	c.RefreshExpiresAt = time.Now().Add(-time.Hour)
++ 	s := NewSource(c, srv.Client(), "")
++ 	if _, err := s.Token(context.Background()); !errors.Is(err, ErrExpired) {
++ 		t.Fatalf("err = %v, want ErrExpired", err)
++ 	}
++ }
++ func TestSourceMissingRefreshTokenDoesNotCallOut(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		t.Error("no request should be sent without a refresh token")
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	c := liveCreds()
++ 	c.RefreshToken = ""
++ 	s := NewSource(c, srv.Client(), "")
++ 	if _, err := s.Token(context.Background()); !errors.Is(err, ErrExpired) {
++ 		t.Fatalf("err = %v, want ErrExpired", err)
++ 	}
++ }
++ // storeWith writes a credentials file carrying a key this package does not
++ // model, so a round trip through Save can be checked for dropping it.
++ func storeWith(t *testing.T, refresh string) string {
++ 	t.Helper()
++ 	home := t.TempDir()
++ 	if err := os.MkdirAll(filepath.Join(home, ".claude"), 0o700); err != nil {
++ 		t.Fatal(err)
++ 	}
++ 	body := `{"claudeAiOauth":{"accessToken":"stale","refreshToken":"` + refresh + `",
++ 	  "expiresAt":1789668269460,"refreshTokenExpiresAt":1791404074460,
++ 	  "scopes":["user:inference"],"subscriptionType":"team",
++ 	  "rateLimitTier":"default_claude_ai"},"someOtherTool":{"keep":"me"}}`
++ 	if err := os.WriteFile(filepath.Join(home, Filename), []byte(body), 0o600); err != nil {
++ 		t.Fatal(err)
++ 	}
++ 	return home
++ }
++ func readStore(t *testing.T, home string) map[string]any {
++ 	t.Helper()
++ 	raw, err := os.ReadFile(filepath.Join(home, Filename))
++ 	if err != nil {
++ 		t.Fatal(err)
++ 	}
++ 	var doc map[string]any
++ 	if err := json.Unmarshal(raw, &doc); err != nil {
++ 		t.Fatalf("file is no longer valid JSON after Save: %v", err)
++ 	}
++ 	return doc
++ }
++ // Save rewrites a file another program owns, so it must put back everything it
++ // did not come to change — including keys this package has never heard of.
++ func TestSavePreservesUnknownKeys(t *testing.T) {
++ 	home := storeWith(t, "r1")
++ 	c, err := Load(home)
++ 	if err != nil {
++ 		t.Fatal(err)
++ 	}
++ 	c.AccessToken, c.RefreshToken = "new-access", "new-refresh"
++ 	c.ExpiresAt = time.UnixMilli(1999999999000)
++ 	if err := Save(home, c); err != nil {
++ 		t.Fatalf("Save: %v", err)
++ 	}
++ 	doc := readStore(t, home)
++ 	oauth, ok := doc["claudeAiOauth"].(map[string]any)
++ 	if !ok {
++ 		t.Fatal("claudeAiOauth is missing after Save")
++ 	}
++ 	if oauth["rateLimitTier"] != "default_claude_ai" {
++ 		t.Errorf("rateLimitTier = %v, want it preserved — Save dropped a key it does not model", oauth["rateLimitTier"])
++ 	}
++ 	if oauth["subscriptionType"] != "team" {
++ 		t.Errorf("subscriptionType = %v, want it preserved", oauth["subscriptionType"])
++ 	}
++ 	if _, ok := doc["someOtherTool"]; !ok {
++ 		t.Error("Save dropped a whole top-level key it does not model")
++ 	}
++ 	if oauth["accessToken"] != "new-access" || oauth["refreshToken"] != "new-refresh" {
++ 		t.Errorf("Save did not write the new tokens: %v", oauth)
++ 	}
++ 	// The stored form is epoch milliseconds, and it must stay an integer
++ 	// literal rather than turning into 1.999999999e+12.
++ 	if got := string(mustRaw(t, home)); !strings.Contains(got, "1999999999000") {
++ 		t.Errorf("expiresAt was not written as an integer millisecond literal:\n%s", got)
++ 	}
++ }
++ func mustRaw(t *testing.T, home string) []byte {
++ 	t.Helper()
++ 	raw, err := os.ReadFile(filepath.Join(home, Filename))
++ 	if err != nil {
++ 		t.Fatal(err)
++ 	}
++ 	return raw
++ }
++ func TestSaveKeepsTheFileOwnerOnly(t *testing.T) {
++ 	home := storeWith(t, "r1")
++ 	c, err := Load(home)
++ 	if err != nil {
++ 		t.Fatal(err)
++ 	}
++ 	if err := Save(home, c); err != nil {
++ 		t.Fatalf("Save: %v", err)
++ 	}
++ 	info, err := os.Stat(filepath.Join(home, Filename))
++ 	if err != nil {
++ 		t.Fatal(err)
++ 	}
++ 	if perm := info.Mode().Perm(); perm != 0o600 {
++ 		t.Errorf("mode = %o, want 600 — a credential must not become readable", perm)
++ 	}
++ }
++ // The whole rotation policy, in two tests. When the server hands back the same
++ // refresh token, the file is Claude Code's business and we do not touch it.
++ func TestSourceDoesNotWriteBackWhenNotRotated(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		io.WriteString(w, `{"access_token":"fresh","refresh_token":"r1","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	home := storeWith(t, "r1")
++ 	before := mustRaw(t, home)
++ 	c := liveCreds()
++ 	c.RefreshToken = "r1"
++ 	s := NewSource(c, srv.Client(), home)
++ 	if _, err := s.Token(context.Background()); err != nil {
++ 		t.Fatalf("Token: %v", err)
++ 	}
++ 	if got := mustRaw(t, home); string(got) != string(before) {
++ 		t.Errorf("the file was rewritten despite no rotation:\nbefore %s\nafter  %s", before, got)
++ 	}
++ }
++ // When the server rotates, the stored refresh token is already dead. Leaving
++ // it there is what breaks the user's Claude Code login, so this is the one
++ // case where writing is the safe act rather than the risky one.
++ func TestSourceWritesBackWhenRotated(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		io.WriteString(w, `{"access_token":"fresh","refresh_token":"r2-rotated","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	home := storeWith(t, "r1")
++ 	c := liveCreds()
++ 	c.RefreshToken = "r1"
++ 	s := NewSource(c, srv.Client(), home)
++ 	if _, err := s.Token(context.Background()); err != nil {
++ 		t.Fatalf("Token: %v", err)
++ 	}
++ 	oauth := readStore(t, home)["claudeAiOauth"].(map[string]any)
++ 	if oauth["refreshToken"] != "r2-rotated" {
++ 		t.Errorf("refreshToken = %v, want the rotated one written back", oauth["refreshToken"])
++ 	}
++ 	if oauth["accessToken"] != "fresh" {
++ 		t.Errorf("accessToken = %v, want it written back alongside", oauth["accessToken"])
++ 	}
++ 	if oauth["rateLimitTier"] != "default_claude_ai" {
++ 		t.Error("write-back dropped an unmodelled key")
++ 	}
++ }
++ // Write-back is best-effort: a read-only store is a worse session, not a
++ // failed one, and failing the request would be a strictly worse outcome than
++ // running on the token we just successfully obtained.
++ func TestSourceSurvivesAFailedWriteBack(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		io.WriteString(w, `{"access_token":"fresh","refresh_token":"r2-rotated","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	c := liveCreds()
++ 	c.RefreshToken = "r1"
++ 	// A home with no credentials file at all: Save cannot succeed.
++ 	s := NewSource(c, srv.Client(), t.TempDir())
++ 	tok, err := s.Token(context.Background())
++ 	if err != nil {
++ 		t.Fatalf("a failed write-back must not fail the request: %v", err)
++ 	}
++ 	if tok != "fresh" {
++ 		t.Errorf("Token = %q, want the refreshed token", tok)
++ 	}
++ }
++ // With no home, write-back is disabled outright and refresh still works.
++ func TestSourceWithoutAHomeStillRefreshes(t *testing.T) {
++ 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
++ 		io.WriteString(w, `{"access_token":"fresh","refresh_token":"r2","expires_in":28800}`)
++ 	}))
++ 	defer srv.Close()
++ 	t.Setenv(tokenURLEnv, srv.URL)
++ 	s := NewSource(liveCreds(), srv.Client(), "")
++ 	tok, err := s.Token(context.Background())
++ 	if err != nil {
++ 		t.Fatalf("Token: %v", err)
++ 	}
++ 	if tok != "fresh" {
++ 		t.Errorf("Token = %q, want fresh", tok)
++ 	}
++ }