claude-code: never write a lease over a login the manager was not handed

A login made on a node (while the tool runner was stopped, or before the
manager asked claude_code_grant for it) was overwritten by the next apply
of the binding's older grant: Apply took any refresh token in the file as
one already handed, and forced the write. The person's login was lost and
the session asked for a login again.

The node side now keeps the fingerprint of the login claude_code_grant last
sealed (state login-handed, never the token). Apply leaves a file whose
login is not that one untouched (applied false, reason login-not-adopted);
its report makes it the manager's candidate, and the successor the manager
hands back replaces it, as before without a refresh token.

Builds: ADR 0206, ADR 0209; design 39 §6 (the latest login wins, a login
moves its node); design 14 (a node never holds a refresh token).
This commit is contained in:
2026-11-20 14:02:37 +01:00
parent 8b91552f59
commit a7459c6e4f
3 changed files with 103 additions and 12 deletions
@@ -358,18 +358,77 @@ func TestAnAppliedBindingSaysWhyAndWho(t *testing.T) {
} }
} }
func TestTheTokenANodeIsHandedReplacesALoginsGrantAndLeavesNoRefreshToken(t *testing.T) { // ADR 0206, ADR 0209, design 39 §6 "the latest login wins": a login in the file that was never handed to the manager
// is newer than every lease, made while the tool runner was stopped (the start's first view) or while it runs (a
// binding or the vault's change heard before the manager asked claude_code_grant). No path writes over it; once
// claude_code_grant handed it, its successor replaces it and leaves no refresh token, and a file holding no login is
// restored as before.
func TestALoginNotHandedIsNeverWrittenOverAndItsSuccessorReplacesIt(t *testing.T) {
login := `{"claudeAiOauth":{"accessToken":"at-login","refreshToken":"rt-login","expiresAt":` +
strings.TrimSpace(string(mustJSON(now+7_200_000))) + `,"refreshTokenExpiresAt":9000},"other":1}`
lease := `{"claudeAiOauth":{"accessToken":"at-lease","expiresAt":1},"other":1}`
for _, c := range []struct {
name, file string
handed bool
heard func(p Paths, ask Ask, w WriteManaged) (string, error)
want string // the access token the file holds after
}{
{"the start's first view, a login made while stopped", login, false, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return FirstBinding(p, ask, w)
}, "at-login"},
{"binding.changed heard while it runs, before the grant was asked", login, false, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-login"},
{"the vault's change heard while it runs, before the grant was asked", login, false, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnSecretChanged(p, []byte(`{"name":"licence.personal.access","generation":5}`), ask, w)
}, "at-login"},
{"the successor of a login handed", login, true, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return OnBindingChanged(p, []byte(`{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}`), ask, w)
}, "at-new"},
{"a file holding the lease, older than the one handed", lease, false, func(p Paths, ask Ask, w WriteManaged) (string, error) {
return FirstBinding(p, ask, w)
}, "at-new"},
} {
t.Run(c.name, func(t *testing.T) {
p, w := node(t, "laptop") p, w := node(t, "laptop")
writeFile(t, p.credentials(), `{"claudeAiOauth":{"accessToken":"at-old","refreshToken":"rt-spent","expiresAt":`+ writeFile(t, p.binding(), `{"licence":"personal","key":"personal","kind":"subscription","generation":2}`+"\n")
strings.TrimSpace(string(mustJSON(now+7_200_000)))+`}}`) writeFile(t, p.credentials(), c.file)
var asked []string if c.handed {
out, err := Pull(p, seat(t, "personal", "at-new", 1, &asked), writer(w)) manager, _ := GenerateKeyPair()
if err != nil || out["applied"] != true { if a, err := GrantFor(p, manager.PublicKey); err != nil || a.Sealed == nil {
t.Fatalf("%v %v", out, err) t.Fatalf("the grant: %+v %v", a, err)
} }
c := creds(t, p) }
if c["accessToken"] != "at-new" || c["refreshToken"] != nil || HoldingsOf(p).Refresh.Present { var asked []string
t.Fatalf("%v", c) current := seat(t, "personal", "at-new", 9, &asked)
ask := func(address string, args any) (json.RawMessage, error) {
if address == SeatVerb("bindings") {
return json.RawMessage(`[{"consumer":"laptop","licence":"personal","key":"personal","kind":"subscription","generation":9}]`), nil
}
return current(address, args)
}
before, _ := os.ReadFile(p.credentials())
if _, err := c.heard(p, ask, writer(w)); err != nil {
t.Fatal(err)
}
got := creds(t, p)
if got["accessToken"] != c.want {
t.Fatalf("the file holds %v, want %s", got["accessToken"], c.want)
}
after, _ := os.ReadFile(p.credentials())
if c.want == "at-login" {
if string(after) != string(before) || !HoldingsOf(p).Refresh.Present {
t.Fatalf("a login not handed was changed: %s", after)
}
return
}
// Restored: no refresh token survives (design 14, design 36 §5), the CLI's other keys stay.
var whole map[string]any
_ = json.Unmarshal(after, &whole)
if got["refreshToken"] != nil || HoldingsOf(p).Refresh.Present || whole["other"] == nil {
t.Fatalf("restored %s", after)
}
})
} }
} }
@@ -122,6 +122,14 @@ func HoldsLogin(c Credentials) bool {
return rt != "" return rt != ""
} }
// LoginNotHanded says the file holds a login that was never handed to the manager: handed is the fingerprint
// of the refresh token claude_code_grant last sealed, "" when none was. Such a login is newer than anything the
// manager holds, so no grant may overwrite it before the manager adopts it (ADR 0206, ADR 0209).
func LoginNotHanded(c Credentials, handed string) bool {
rt := RefreshTokenOf(c)
return rt != "" && Fingerprint(rt) != handed
}
// RefreshTokenOf is the refresh token a login left, or "". // RefreshTokenOf is the refresh token a login left, or "".
func RefreshTokenOf(c Credentials) string { func RefreshTokenOf(c Credentials) string {
rt, _ := c.oauth()["refreshToken"].(string) rt, _ := c.oauth()["refreshToken"].(string)
@@ -143,6 +143,7 @@ func HomeScopeRefused(p Paths, target string) string {
func (p Paths) credentials() string { return filepath.Join(p.Home, ".claude", ".credentials.json") } func (p Paths) credentials() string { return filepath.Join(p.Home, ".claude", ".credentials.json") }
func (p Paths) account() string { return filepath.Join(p.Home, ".claude.json") } func (p Paths) account() string { return filepath.Join(p.Home, ".claude.json") }
func (p Paths) binding() string { return filepath.Join(p.State, "licence.json") } func (p Paths) binding() string { return filepath.Join(p.State, "licence.json") }
func (p Paths) handed() string { return filepath.Join(p.State, "login-handed") }
func (p Paths) apiKey() string { return filepath.Join(p.keyDir(), "api-key") } func (p Paths) apiKey() string { return filepath.Join(p.keyDir(), "api-key") }
func (p Paths) helper() string { return filepath.Join(p.keyDir(), "api-key-helper") } func (p Paths) helper() string { return filepath.Join(p.keyDir(), "api-key-helper") }
@@ -418,9 +419,26 @@ func GrantFor(p Paths, managerPublicKey string) (GrantAnswer, error) {
if err != nil { if err != nil {
return GrantAnswer{}, err return GrantAnswer{}, err
} }
// Which login was handed: only its successor may replace it (ADR 0206, ADR 0209). The fingerprint, never
// the token.
if err := fsys.MkdirAll(p.State, 0o700); err != nil {
return GrantAnswer{}, err
}
if err := fsys.WriteFile(p.handed(), []byte(Fingerprint(rt)+"\n"), 0o600); err != nil {
return GrantAnswer{}, err
}
return GrantAnswer{Sealed: &box, Identity: ReadIdentity(p.account()), Fingerprint: Fingerprint(rt)}, nil return GrantAnswer{Sealed: &box, Identity: ReadIdentity(p.account()), Fingerprint: Fingerprint(rt)}, nil
} }
// readHanded is the fingerprint of the login last handed to the manager, or "".
func readHanded(p Paths) string {
raw, err := fsys.ReadFile(p.handed())
if err != nil {
return ""
}
return strings.TrimSpace(string(raw))
}
// Pull asks the seat which licence this node holds, then the vault for that licence's access secret, sealed to this // Pull asks the seat which licence this node holds, then the vault for that licence's access secret, sealed to this
// module's key, and applies it (§19). // module's key, and applies it (§19).
func Pull(p Paths, ask Ask, write WriteManaged) (map[string]any, error) { func Pull(p Paths, ask Ask, write WriteManaged) (map[string]any, error) {
@@ -609,6 +627,12 @@ func Apply(p Paths, c Current, sealed SealedBox, write WriteManaged) (map[string
return nil, err return nil, err
} }
local := ReadCredentials(p.credentials()) local := ReadCredentials(p.credentials())
// A login made here that the manager has not adopted yet stays whole: the grant handed is the old
// lineage's, and writing it would spend the person's login unseen (ADR 0206, ADR 0209). The manager
// asks claude_code_grant for it on this node's report; its successor then comes as a newer generation.
if LoginNotHanded(local, readHanded(p)) {
return map[string]any{"applied": false, "licence": c.Licence, "reason": "login-not-adopted"}, nil
}
// A login waiting here was handed to the manager first (ADR 0206): what comes back is its successor, // A login waiting here was handed to the manager first (ADR 0206): what comes back is its successor,
// and the refresh token in the file is the one the manager just spent. // and the refresh token in the file is the one the manager just spent.
d := DecideApply(GrantOf(local), g, switched || HoldsLogin(local)) d := DecideApply(GrantOf(local), g, switched || HoldsLogin(local))