From b2ec4574693bdfcc1c97805c0b95f0cb0afd72cc Mon Sep 17 00:00:00 2001 From: Danathar Date: Tue, 10 Nov 2026 15:10:53 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20[v6]=20claude=20auth:=20never=20?= =?UTF-8?q?re-bridge=20a=20credential=20that=20resolves=20to=20the=20share?= =?UTF-8?q?d=20login=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An agent whose whole ~/.claude is still the legacy directory symlink to /data/home/.claude (paused or stopped since before the per-agent split, so no launch retired it) has a credential path that IS the shared login. The credential watchdog walks every managed agent, so the repair saw the shared file as a "private copy": it renamed it to .stale- every cycle and, when the shared file held no token, linked .credentials.json to itself, logging every Claude agent out. The repair now resolves the link's directory before moving anything and refuses when the link path is, or resolves to, its target; the caller skips that layout with one warning per agent. The dashboard's credential-bridge-broken signal applies the same rule. The launch path already retires the directory link before it runs the repair (#17039), so no new migration is added. Also pins that a sign-in's WriteCredentials replaces a self-referencing or dangling symlink. Refs #17253 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar --- .../fixed-claude-bridge-legacy-dirlink.md | 1 + src/crux/agent/claude_credential_bridge.go | 106 +++++++++- .../claude_credential_bridge_internal_test.go | 197 ++++++++++++++++++ src/crux/claude/oauth_test.go | 42 ++++ src/docs/agent-configuration.md | 2 + 5 files changed, 342 insertions(+), 6 deletions(-) create mode 100644 changelog.d/fixed-claude-bridge-legacy-dirlink.md diff --git a/changelog.d/fixed-claude-bridge-legacy-dirlink.md b/changelog.d/fixed-claude-bridge-legacy-dirlink.md new file mode 100644 index 0000000000..705132817d --- /dev/null +++ b/changelog.d/fixed-claude-bridge-legacy-dirlink.md @@ -0,0 +1 @@ +- Claude credential bridge: the repair no longer acts on an agent whose whole `~/.claude` is still the legacy directory symlink to the shared `/data/home/.claude` (a paused or stopped agent that was never relaunched). Through that link the agent's credential path IS the shared login, so the watchdog renamed the shared file to `.stale-` every cycle and, when the shared file held no token, linked `.credentials.json` to itself, logging every Claude agent out. The repair and the dashboard's "credential bridge broken" signal now resolve the link's directory first and skip that layout with one warning per agent; the agent's next launch already retires the directory link (#17253). diff --git a/src/crux/agent/claude_credential_bridge.go b/src/crux/agent/claude_credential_bridge.go index 7a2c476554..4ca94d05f0 100644 --- a/src/crux/agent/claude_credential_bridge.go +++ b/src/crux/agent/claude_credential_bridge.go @@ -53,6 +53,12 @@ import ( // promoted, the shared file it replaces is preserved the same way beside the // shared credential. Both names fall outside sharedCredentialBases, so the // permissions watcher never opens them up to the group. +// +// The repair never acts on a link path that resolves to the shared credential +// itself (an agent whose whole ~/.claude is still the legacy directory symlink +// to /data/home/.claude): that "private file" is the fleet's login. Such an +// agent is skipped with one warning; its next launch retires the directory +// link (setupPerAgentCLIHome) before the repair runs. // Repair triggers, recorded in the audit detail and the log. const ( @@ -118,15 +124,73 @@ func sharedClaudeBridgeTarget() string { } // claudeCredentialBridgeBroken reports whether a regular file has replaced the -// agent's credential symlink. Read-only (one Lstat), so it is cheap enough for -// the status snapshot. +// agent's credential symlink. Read-only (one Lstat, plus two directory +// resolutions only when that Lstat finds a regular file), so it is cheap +// enough for the status snapshot. It follows the same rule as the repair: the +// legacy layout, where the link path resolves to the shared credential itself, +// is not a broken bridge and is never reported as one. func claudeCredentialBridgeBroken(agentName string, uid int, backend string) bool { - link, _, ok := claudeCredentialBridgePaths(agentName, uid, backend) + link, target, ok := claudeCredentialBridgePaths(agentName, uid, backend) if !ok { return false } info, err := os.Lstat(link) - return err == nil && info.Mode().IsRegular() + if err != nil || !info.Mode().IsRegular() { + return false + } + same, err := claudeBridgeLinkIsTarget(link, target) + return err == nil && !same +} + +// errClaudeBridgeLinkIsTarget: the agent's credential path IS the shared +// credential, so there is no private copy to move aside and no link to +// restore. On a live v6 hive this was an agent whose whole ~/.claude was still +// the legacy directory symlink to the shared /data/home/.claude (the layout +// setupPerAgentCLIHome retires at launch, never reached for an agent that is +// paused or stopped). The repair then renamed the SHARED login aside and, +// for a token-less file, linked .credentials.json to itself, logging every +// agent out. +var errClaudeBridgeLinkIsTarget = errors.New("credential link path resolves to the shared credential it would link to") + +// claudeBridgeLegacyWarned holds the credential links the legacy-layout skip +// has already been logged for, so the watchdog, which walks every managed +// agent each cycle, logs it once per agent instead of every cycle. Keyed by +// the link path, which names the agent. +var claudeBridgeLegacyWarned sync.Map + +// claudeBridgeLinkIsTarget reports whether link names the shared credential +// itself: the same path, or a file of the same name in a directory that +// resolves to the target's directory (a legacy whole-directory ~/.claude +// symlink). An error means a directory could not be resolved (absent, or not +// reachable by this process); callers treat that as nothing to repair. +func claudeBridgeLinkIsTarget(link, target string) (bool, error) { + if filepath.Clean(link) == filepath.Clean(target) { + return true, nil + } + if filepath.Base(link) != filepath.Base(target) { + return false, nil + } + linkDir, err := filepath.EvalSymlinks(filepath.Dir(link)) + if err != nil { + return false, err + } + targetDir, err := filepath.EvalSymlinks(filepath.Dir(target)) + if err != nil { + return false, err + } + if linkDir == targetDir { + return true, nil + } + // Different resolved paths can still be one directory (a bind mount). + li, err := os.Stat(linkDir) + if err != nil { + return false, err + } + ti, err := os.Stat(targetDir) + if err != nil { + return false, err + } + return os.SameFile(li, ti), nil } // preferAgentClaudeCredential decides which credential the shared file keeps. @@ -143,8 +207,10 @@ func preferAgentClaudeCredential(agent, shared *claude.OAuthTokens, now time.Tim // repairClaudeCredentialBridge re-bridges one agent's credential when a regular // file has replaced the symlink. It returns nil, nil when there is nothing to -// repair (a symlink, an absent link, or a directory, which is not this -// failure). +// repair (a symlink, an absent link, a directory, which is not this failure, +// or a link or target directory that cannot be resolved). It returns an error +// wrapping errClaudeBridgeLinkIsTarget, and touches nothing, when the link +// path resolves to the shared credential itself. func (m *Manager) repairClaudeCredentialBridge(agentName, link, target string) (*claudeBridgeRepair, error) { claudeBridgeMu.Lock() defer claudeBridgeMu.Unlock() @@ -153,6 +219,22 @@ func (m *Manager) repairClaudeCredentialBridge(agentName, link, target string) ( if err != nil || !info.Mode().IsRegular() { return nil, nil } + + // Never operate on the shared credential itself. Checked BEFORE anything + // is moved: when the link path resolves to the target, the "private file" + // below IS the shared login, moving it aside strands the fleet, and the + // symlink restored afterwards would point at its own path. + same, err := claudeBridgeLinkIsTarget(link, target) + if err != nil { + // Nothing safe to judge without both directories; never move a file + // aside on a guess. + m.logger.Debug("claude credential bridge: cannot resolve the link or shared directory; not repairing", + "agent", agentName, "link", link, "target", target, "error", err) + return nil, nil + } + if same { + return nil, fmt.Errorf("%w: %s", errClaudeBridgeLinkIsTarget, link) + } now := claudeBridgeNow() // Move the private file aside FIRST. After the rename the CLI can no @@ -292,6 +374,18 @@ func preserveClaudeCredential(path string, now time.Time) (string, error) { // sign-in hook share, so all three log and audit identically. func (m *Manager) rebridgeClaudeCredential(agentName, link, target, trigger string) *claudeBridgeRepair { rep, err := m.repairClaudeCredentialBridge(agentName, link, target) + if errors.Is(err, errClaudeBridgeLinkIsTarget) { + // The legacy layout: skipped, and said once per agent rather than on + // every watchdog cycle. Not audited (nothing changed). + if _, seen := claudeBridgeLegacyWarned.LoadOrStore(link, true); !seen { + m.logger.Warn("claude credential bridge: this agent's .claude directory resolves to the shared login directory (a legacy whole-directory symlink), so its credential path IS the shared login; not re-bridging. The agent's next launch replaces the directory link with a per-agent directory", + "agent", agentName, "trigger", trigger, "dir", filepath.Dir(link), "shared", target) + } + return nil + } + // Any other outcome clears the mark, so a legacy layout that shows up + // again later is logged again. + claudeBridgeLegacyWarned.Delete(link) if err != nil { // Logged, not audited: a repair that keeps failing (an unprivileged // hive that cannot enter the agent's 0700 home) would otherwise add an diff --git a/src/crux/agent/claude_credential_bridge_internal_test.go b/src/crux/agent/claude_credential_bridge_internal_test.go index 746940ce63..9d4d9ce5e3 100644 --- a/src/crux/agent/claude_credential_bridge_internal_test.go +++ b/src/crux/agent/claude_credential_bridge_internal_test.go @@ -1,8 +1,12 @@ package agent import ( + "bytes" + "errors" + "log/slog" "os" "path/filepath" + "strings" "syscall" "testing" "time" @@ -138,3 +142,196 @@ func TestPreferAgentClaudeCredential(t *testing.T) { } } } + +// legacyDirLinkFixture lays out the pre-#17031 layout that the launch path +// retires but the credential watchdog still walks for a paused or stopped +// agent: the agent's whole ~/.claude is a directory symlink to the shared +// .claude, so the path the bridge calls the agent's credential IS the shared +// login. The shared credential holds sharedJSON. Returns the link path exactly +// as production computes it, the target, and the shared file's FileInfo +// captured before any repair runs. +func legacyDirLinkFixture(t *testing.T, shared, agentName string, uid int, sharedJSON string) (string, string, os.FileInfo) { + t.Helper() + sharedClaude := filepath.Join(shared, ".claude") + if err := os.MkdirAll(sharedClaude, 0o755); err != nil { + t.Fatal(err) + } + target := filepath.Join(sharedClaude, ".credentials.json") + if err := os.WriteFile(target, []byte(sharedJSON), 0o660); err != nil { + t.Fatal(err) + } + home := filepath.Join(shared, "agents", agentName) + if err := os.MkdirAll(home, 0o700); err != nil { + t.Fatal(err) + } + if err := os.Symlink(sharedClaude, filepath.Join(home, ".claude")); err != nil { + t.Fatal(err) + } + link, gotTarget, ok := claudeCredentialBridgePaths(agentName, uid, "claude") + if !ok || gotTarget != target { + t.Fatalf("claudeCredentialBridgePaths = (%q, %q, %v), want target %q", link, gotTarget, ok, target) + } + before, err := os.Lstat(target) + if err != nil { + t.Fatal(err) + } + return link, target, before +} + +// assertSharedCredentialUntouched: the shared login is still the very same +// regular file (same inode, not a symlink to anything, let alone itself), +// with the same bytes, and nothing was moved aside beside it. +func assertSharedCredentialUntouched(t *testing.T, target string, before os.FileInfo, wantJSON string) { + t.Helper() + info, err := os.Lstat(target) + if err != nil { + t.Fatalf("shared credential gone: %v", err) + } + if !info.Mode().IsRegular() { + dest, _ := os.Readlink(target) + t.Fatalf("shared credential is no longer a regular file (mode %v, link -> %q)", info.Mode(), dest) + } + if !os.SameFile(before, info) { + t.Errorf("shared credential was replaced (new inode); it must not be renamed or rewritten") + } + if got := readFileString(t, target); got != wantJSON { + t.Errorf("shared credential content changed:\n got %s\nwant %s", got, wantJSON) + } + if got := staleFiles(t, filepath.Dir(target)); len(got) != 0 { + t.Errorf("shared credential was moved aside: %v", got) + } +} + +// TestRepairClaudeCredentialBridge_LegacyDirLinkUsableSharedUntouched: on the +// v6 tip the repair saw the shared file through the directory link as a +// "private copy", renamed it to .stale-, promoted the same bytes back +// (new inode) and then failed the symlink with EEXIST, every watchdog cycle. +// It must leave the shared file alone and say why. +func TestRepairClaudeCredentialBridge_LegacyDirLinkUsableSharedUntouched(t *testing.T) { + shared := withSharedAgentHome(t) + m, sink := testManagerWithSink(t) + sharedJSON := fakeClaudeCredential("fake-shared-access", time.Now().Add(8*time.Hour), "fake-shared-refresh") + link, target, before := legacyDirLinkFixture(t, shared, "reviewer", 2005, sharedJSON) + + rep, err := m.repairClaudeCredentialBridge("reviewer", link, target) + if rep != nil || !errors.Is(err, errClaudeBridgeLinkIsTarget) { + t.Fatalf("repair = (%+v, %v), want (nil, errClaudeBridgeLinkIsTarget)", rep, err) + } + if got := m.rebridgeClaudeCredential("reviewer", link, target, claudeBridgeTriggerWatchdog); got != nil { + t.Fatalf("rebridge = %+v, want nil (skipped)", got) + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) + if ev := sink.find("claude_credential_rebridged"); ev != nil { + t.Errorf("a skipped legacy layout must not be audited as a re-bridge: %+v", ev) + } +} + +// TestRepairClaudeCredentialBridge_LegacyDirLinkTokenlessSharedNotSelfLinked +// is the live incident: a logged-out (token-less) shared file is not +// promoted, so on the v6 tip the repair renamed it away and then created +// .credentials.json -> .credentials.json, a symlink to itself, logging out +// every agent. No symlink may be created and the file must stay in place. +func TestRepairClaudeCredentialBridge_LegacyDirLinkTokenlessSharedNotSelfLinked(t *testing.T) { + shared := withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + const sharedJSON = `{}` + link, target, before := legacyDirLinkFixture(t, shared, "scanner", 2003, sharedJSON) + + if _, err := m.repairClaudeCredentialBridge("scanner", link, target); !errors.Is(err, errClaudeBridgeLinkIsTarget) { + t.Fatalf("repair error = %v, want errClaudeBridgeLinkIsTarget", err) + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) +} + +// TestRepairClaudeCredentialBridges_LegacyDirLinkSurvivesWatchdogCyclesWarnsOnce: +// the watchdog walks every managed agent each cycle, paused ones included. +// Several cycles over the legacy layout leave the shared login untouched, +// re-bridge nothing, and log the skip once rather than every cycle. +func TestRepairClaudeCredentialBridges_LegacyDirLinkSurvivesWatchdogCyclesWarnsOnce(t *testing.T) { + shared := withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + var logs bytes.Buffer + m.logger = slog.New(slog.NewTextHandler(&logs, nil)) + m.mu.Lock() + m.agents["planner"] = &AgentProcess{Name: "planner", UID: 2004, Config: config.AgentConfig{Backend: "claude"}} + m.mu.Unlock() + sharedJSON := fakeClaudeCredential("fake-shared-access", time.Now().Add(8*time.Hour), "fake-shared-refresh") + _, target, before := legacyDirLinkFixture(t, shared, "planner", 2004, sharedJSON) + + for cycle := 0; cycle < 4; cycle++ { + if got := m.RepairClaudeCredentialBridges(claudeBridgeTriggerWatchdog); len(got) != 0 { + t.Fatalf("cycle %d re-bridged %v, want none", cycle, got) + } + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) + if n := strings.Count(logs.String(), "legacy whole-directory symlink"); n != 1 { + t.Errorf("legacy-layout warning logged %d times over 4 cycles, want 1:\n%s", n, logs.String()) + } + if strings.Contains(logs.String(), "repair failed") { + t.Errorf("the legacy layout must be skipped, not reported as a failed repair:\n%s", logs.String()) + } +} + +// TestRepairClaudeCredentialBridge_RefusesLinkEqualToTarget: the last line of +// defence. A link path equal to its own target is refused before anything is +// moved: nothing renamed, nothing created. +func TestRepairClaudeCredentialBridge_RefusesLinkEqualToTarget(t *testing.T) { + withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + target := sharedClaudeBridgeTarget() + if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil { + t.Fatal(err) + } + const sharedJSON = `{}` + if err := os.WriteFile(target, []byte(sharedJSON), 0o660); err != nil { + t.Fatal(err) + } + before, err := os.Lstat(target) + if err != nil { + t.Fatal(err) + } + + rep, err := m.repairClaudeCredentialBridge("coder", target, target) + if rep != nil || !errors.Is(err, errClaudeBridgeLinkIsTarget) { + t.Fatalf("repair = (%+v, %v), want (nil, errClaudeBridgeLinkIsTarget)", rep, err) + } + assertSharedCredentialUntouched(t, target, before, sharedJSON) +} + +// TestClaudeCredentialBridgeBroken_LegacyDirLinkIsNotBroken: the dashboard's +// "bridge broken" signal follows the repair's rule. The legacy layout is not +// a broken bridge (the agent reads the shared login directly), while a real +// per-agent .claude holding a private regular file still is. +func TestClaudeCredentialBridgeBroken_LegacyDirLinkIsNotBroken(t *testing.T) { + shared := withSharedAgentHome(t) + legacyDirLinkFixture(t, shared, "architect", 2001, `{}`) + if claudeCredentialBridgeBroken("architect", 2001, "claude") { + t.Error("the legacy whole-directory layout must not report a broken credential bridge") + } + + brokenBridgeFixture(t, shared, "coder", "", + fakeClaudeCredential("fake-private-access", time.Now().Add(time.Hour), "fake-private-refresh")) + if !claudeCredentialBridgeBroken("coder", 2002, "claude") { + t.Error("a private regular file in a real per-agent .claude must still report a broken bridge") + } +} + +// TestSetupInteractiveHome_LegacyDirLinkLaunchRetiresBeforeRebridge pins the +// launch ordering: setupPerAgentCLIHome retires the directory link and makes +// a real per-agent .claude BEFORE it runs the credential repair, so a launch +// never sees the shared file through the old link. The shared login stays the +// same file and the agent ends up bridged to it. +func TestSetupInteractiveHome_LegacyDirLinkLaunchRetiresBeforeRebridge(t *testing.T) { + shared := withSharedAgentHome(t) + m, _ := testManagerWithSink(t) + sharedJSON := fakeClaudeCredential("fake-shared-access", time.Now().Add(8*time.Hour), "fake-shared-refresh") + link, target, before := legacyDirLinkFixture(t, shared, "coder", 2002, sharedJSON) + + m.setupInteractiveHome(&AgentProcess{Name: "coder", UID: 2002, Config: config.AgentConfig{Backend: "claude"}}, "claude") + + assertSharedCredentialUntouched(t, target, before, sharedJSON) + if info, err := os.Lstat(filepath.Dir(link)); err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() { + t.Fatalf("legacy .claude directory link not retired: info=%v err=%v", info, err) + } + assertBridgeRestored(t, link, target) +} diff --git a/src/crux/claude/oauth_test.go b/src/crux/claude/oauth_test.go index bdbcfbd99d..9a93e6e86d 100644 --- a/src/crux/claude/oauth_test.go +++ b/src/crux/claude/oauth_test.go @@ -352,6 +352,48 @@ func TestWriteCredentialsIsAtomic(t *testing.T) { } } +// A sign-in is how an operator recovers a fleet whose shared credential path +// was turned into a symlink to itself (an older credential-bridge repair did +// this on a live v6 hive) or to a file that no longer exists. WriteCredentials +// renames its temp file over the path, which replaces the symlink itself, so +// the path ends up a regular file holding the new tokens. +func TestWriteCredentialsReplacesSelfAndDanglingSymlinks(t *testing.T) { + cases := []struct { + name string + linkTo func(path string) string + }{ + {"self-referencing", func(path string) string { return path }}, + {"dangling", func(path string) string { return filepath.Join(filepath.Dir(path), "gone", ".credentials.json") }}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + path := filepath.Join(t.TempDir(), ".credentials.json") + if err := os.Symlink(c.linkTo(path), path); err != nil { + t.Fatal(err) + } + tokens := &OAuthTokens{ + AccessToken: "fake-recovered-access", + RefreshToken: "fake-recovered-refresh", + ExpiresAt: time.Now().Add(time.Hour).UnixMilli(), + } + if err := WriteCredentials(tokens, path); err != nil { + t.Fatalf("WriteCredentials over a %s symlink: %v", c.name, err) + } + info, err := os.Lstat(path) + if err != nil { + t.Fatal(err) + } + if !info.Mode().IsRegular() { + t.Fatalf("credentials path is still not a regular file (mode %v)", info.Mode()) + } + got := LoadTokens(path) + if got == nil || got.AccessToken != "fake-recovered-access" || got.RefreshToken != "fake-recovered-refresh" { + t.Fatalf("credentials file does not hold the written tokens: %+v", got) + } + }) + } +} + // An expired token must read as absent: handing an expired token to an agent // produces confusing 401s instead of a clean re-auth prompt. func TestReadAccessTokenRejectsExpiredToken(t *testing.T) { diff --git a/src/docs/agent-configuration.md b/src/docs/agent-configuration.md index d9acd1392a..af61e9df89 100644 --- a/src/docs/agent-configuration.md +++ b/src/docs/agent-configuration.md @@ -703,6 +703,8 @@ The repair never deletes a token: Each repair writes a `claude_credential_rebridged` Audit Log entry naming the agent, the trigger (`launch`, `watchdog` or `sign-in`), which credential was kept (`shared` or `agent`) and where the moved-aside file went. It never records token material. Until the repair runs, the agent card shows **credential bridge broken (private stale file)** instead of a generic "needs login". Moved-aside files are not cleaned up automatically; remove them by hand once you no longer need them. +The repair skips an agent whose whole `~/.claude` is still the old directory symlink to `/data/home/.claude`. That happens to an agent that has been paused or stopped since before the per-agent split, because only a launch replaces the directory link. Through that link the agent's `.credentials.json` is the shared login itself, so there is nothing private to move aside. The hive log says so once per agent (`claude credential bridge: this agent's .claude directory resolves to the shared login directory`), the card does not show a broken bridge, and the agent's next launch replaces the directory link with its own `~/.claude`. + ### CLI auto-memory (`agents.cli_memory`) Subscription CLIs keep their own long-lived "memory" next to the transcripts: Claude Code's auto-memory (`~/.claude/projects/-data-agents-/memory/MEMORY.md`), Codex memories (`$CODEX_HOME/memories/`), Copilot CLI's `memory` setting, and Gemini's `~/.gemini/GEMINI.md`. Hive agents already get their durable context from beads, the knowledge store, and the kick prompt, so a hidden per-CLI notebook mostly accumulates stale one-off inferences ([#17032](https://github.com/hivecommons/hive/issues/17032)). The `agents.cli_memory` block controls it fleet-wide, and each agent may override it with its own `cli_memory:` block: