feat(config): store API keys in OS keychain instead of plaintext

API keys and OAuth tokens are now stored in the operating system's
native keychain (macOS Keychain, Windows Credential Manager, Linux
Secret Service) instead of plaintext in crush.json. Existing plaintext
keys are automatically migrated to the keychain on first load.

A placeholder marker (__keyring__) is written to the JSON config file
so the config system still recognizes that a provider is configured.
When the keychain is unavailable (headless servers, CI, containers),
the system falls back to file-based storage with a warning. Set
CRUSH_DISABLE_KEYRING=1 to force file-based storage.

Closes #2477

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

Author: officialasishkumar

go.mod

@@ -61,6 +61,7 @@ require (
 	github.com/stretchr/testify v1.11.1
 	github.com/tidwall/gjson v1.18.0
 	github.com/tidwall/sjson v1.2.5
+	github.com/zalando/go-keyring v0.2.8
 	github.com/zeebo/xxh3 v1.1.0
 	go.uber.org/goleak v1.3.0
 	golang.org/x/net v0.52.0
@@ -105,6 +106,7 @@ require (
 	github.com/charmbracelet/x/json v0.2.0 // indirect
 	github.com/charmbracelet/x/termios v0.1.1 // indirect
 	github.com/charmbracelet/x/windows v0.2.2 // indirect
+	github.com/danieljoos/wincred v1.2.3 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/dlclark/regexp2 v1.11.5 // indirect
 	github.com/ebitengine/purego v0.10.0 // indirect

go.sum

@@ -141,6 +141,8 @@ github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7X
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
 github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
+github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
+github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
@@ -357,6 +359,8 @@ github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
@@ -392,6 +396,8 @@ github.com/yuin/goldmark v1.7.8 h1:iERMLn0/QJeHFhxSt3p6PeN9mGnvIKSpG9YYorDMnic=
 github.com/yuin/goldmark v1.7.8/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E=
 github.com/yuin/goldmark-emoji v1.0.5 h1:EMVWyCGPlXJfUXBXpuMu+ii3TIaxbVBnEX9uaDC4cIk=
 github.com/yuin/goldmark-emoji v1.0.5/go.mod h1:tTkZEbwu5wkPmgTcitqddVxY9osFZiavD+r4AzQrh1U=
+github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs=
+github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0=
 github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
 github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=

internal/cmd/login.go

@@ -1,12 +1,12 @@
 package cmd
 
 import (
-	"cmp"
 	"context"
 	"fmt"
 	"os"
 	"os/signal"
 
+	"charm.land/catwalk/pkg/catwalk"
 	"charm.land/lipgloss/v2"
 	"github.com/atotto/clipboard"
 	hyperp "github.com/charmbracelet/crush/internal/agent/hyper"
@@ -111,10 +111,7 @@ func loginHyper(cfg *config.ConfigStore) error {
 		return fmt.Errorf("access token is not active")
 	}
 
-	if err := cmp.Or(
-		cfg.SetConfigField(config.ScopeGlobal, "providers.hyper.api_key", token.AccessToken),
-		cfg.SetConfigField(config.ScopeGlobal, "providers.hyper.oauth", token),
-	); err != nil {
+	if err := cfg.SetProviderAPIKey(config.ScopeGlobal, "hyper", token); err != nil {
 		return err
 	}
 
@@ -126,7 +123,8 @@ func loginHyper(cfg *config.ConfigStore) error {
 func loginCopilot(cfg *config.ConfigStore) error {
 	ctx := getLoginContext()
 
-	if cfg.HasConfigField(config.ScopeGlobal, "providers.copilot.oauth") {
+	if cfg.HasConfigField(config.ScopeGlobal, "providers.copilot.oauth") ||
+		cfg.HasConfigField(config.ScopeGlobal, "providers.copilot.api_key") {
 		fmt.Println("You are already logged in to GitHub Copilot.")
 		return nil
 	}
@@ -176,10 +174,7 @@ func loginCopilot(cfg *config.ConfigStore) error {
 		token = t
 	}
 
-	if err := cmp.Or(
-		cfg.SetConfigField(config.ScopeGlobal, "providers.copilot.api_key", token.AccessToken),
-		cfg.SetConfigField(config.ScopeGlobal, "providers.copilot.oauth", token),
-	); err != nil {
+	if err := cfg.SetProviderAPIKey(config.ScopeGlobal, string(catwalk.InferenceProviderCopilot), token); err != nil {
 		return err
 	}
 

internal/config/keyring.go

@@ -0,0 +1,156 @@
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os"
+	"strings"
+
+	"github.com/charmbracelet/crush/internal/oauth"
+	"github.com/zalando/go-keyring"
+)
+
+const (
+	// keyringService is the service name used in the OS keychain.
+	keyringService = "crush"
+
+	// KeyringMarker is the sentinel value stored in the JSON config file to
+	// indicate that the real credential lives in the OS keychain.
+	KeyringMarker = "__keyring__"
+)
+
+// KeyringStore provides secure credential storage via the OS keychain
+// (macOS Keychain, Windows Credential Manager, Linux Secret Service / D-Bus).
+// When the keychain is unavailable (headless servers, CI, etc.) it reports
+// itself as unavailable so callers can fall back to file-based storage.
+type KeyringStore struct {
+	available bool
+}
+
+// NewKeyringStore creates a KeyringStore and probes the system keychain for
+// availability. Set CRUSH_DISABLE_KEYRING=1 to force file-based storage.
+func NewKeyringStore() *KeyringStore {
+	ks := &KeyringStore{}
+
+	if v := os.Getenv("CRUSH_DISABLE_KEYRING"); v == "1" || strings.EqualFold(v, "true") {
+		slog.Debug("OS keychain disabled via CRUSH_DISABLE_KEYRING")
+		return ks
+	}
+
+	// Probe the keyring with a harmless set/delete cycle.
+	const probe = "crush-keyring-probe"
+	if err := keyring.Set(keyringService, probe, "probe"); err != nil {
+		slog.Warn("OS keychain is not available, credentials will be stored in config file", "error", err)
+		return ks
+	}
+	_ = keyring.Delete(keyringService, probe)
+	ks.available = true
+	slog.Debug("OS keychain is available")
+	return ks
+}
+
+// Available reports whether the OS keychain is accessible.
+func (ks *KeyringStore) Available() bool {
+	return ks != nil && ks.available
+}
+
+// --- API key helpers ---
+
+func apiKeyName(providerID string) string {
+	return providerID + "/api_key"
+}
+
+// SetAPIKey stores an API key in the OS keychain.
+func (ks *KeyringStore) SetAPIKey(providerID, apiKey string) error {
+	if !ks.Available() {
+		return fmt.Errorf("keyring not available")
+	}
+	return keyring.Set(keyringService, apiKeyName(providerID), apiKey)
+}
+
+// GetAPIKey retrieves an API key from the OS keychain.
+func (ks *KeyringStore) GetAPIKey(providerID string) (string, error) {
+	if !ks.Available() {
+		return "", fmt.Errorf("keyring not available")
+	}
+	return keyring.Get(keyringService, apiKeyName(providerID))
+}
+
+// DeleteAPIKey removes an API key from the OS keychain.
+func (ks *KeyringStore) DeleteAPIKey(providerID string) error {
+	if !ks.Available() {
+		return fmt.Errorf("keyring not available")
+	}
+	return keyring.Delete(keyringService, apiKeyName(providerID))
+}
+
+// --- OAuth token helpers ---
+
+func oauthKeyName(providerID string) string {
+	return providerID + "/oauth"
+}
+
+// SetOAuthToken stores a serialized OAuth token in the OS keychain.
+func (ks *KeyringStore) SetOAuthToken(providerID string, token *oauth.Token) error {
+	if !ks.Available() {
+		return fmt.Errorf("keyring not available")
+	}
+	data, err := json.Marshal(token)
+	if err != nil {
+		return fmt.Errorf("failed to marshal OAuth token: %w", err)
+	}
+	return keyring.Set(keyringService, oauthKeyName(providerID), string(data))
+}
+
+// GetOAuthToken retrieves an OAuth token from the OS keychain.
+func (ks *KeyringStore) GetOAuthToken(providerID string) (*oauth.Token, error) {
+	if !ks.Available() {
+		return nil, fmt.Errorf("keyring not available")
+	}
+	data, err := keyring.Get(keyringService, oauthKeyName(providerID))
+	if err != nil {
+		return nil, err
+	}
+	var token oauth.Token
+	if err := json.Unmarshal([]byte(data), &token); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal OAuth token from keyring: %w", err)
+	}
+	return &token, nil
+}
+
+// DeleteOAuthToken removes an OAuth token from the OS keychain.
+func (ks *KeyringStore) DeleteOAuthToken(providerID string) error {
+	if !ks.Available() {
+		return fmt.Errorf("keyring not available")
+	}
+	return keyring.Delete(keyringService, oauthKeyName(providerID))
+}
+
+// --- Helpers ---
+
+// IsKeyringMarker reports whether a config value is the keyring placeholder.
+func IsKeyringMarker(value string) bool {
+	return value == KeyringMarker
+}
+
+// isEnvVarReference reports whether a value looks like an environment variable
+// reference (e.g. $OPENAI_API_KEY or ${OPENAI_API_KEY}).
+func isEnvVarReference(value string) bool {
+	return strings.HasPrefix(value, "$")
+}
+
+// isCommandSubstitution reports whether a value looks like a command
+// substitution (e.g. $(some-command)).
+func isCommandSubstitution(value string) bool {
+	return strings.HasPrefix(value, "$(") && strings.HasSuffix(value, ")")
+}
+
+// isLiteralSecret reports whether a value is a plaintext literal secret
+// (not a marker, not an env-var reference, not a command substitution, and not empty).
+func isLiteralSecret(value string) bool {
+	return value != "" &&
+		!IsKeyringMarker(value) &&
+		!isEnvVarReference(value) &&
+		!isCommandSubstitution(value)
+}

internal/config/load.go

@@ -46,6 +46,7 @@ func Load(workingDir, dataDir string, debug bool) (*ConfigStore, error) {
 		workingDir:     workingDir,
 		globalDataPath: GlobalConfigData(),
 		workspacePath:  filepath.Join(cfg.Options.DataDirectory, fmt.Sprintf("%s.json", appName)),
+		keyring:        NewKeyringStore(),
 	}
 
 	if debug {
@@ -168,6 +169,29 @@ func (c *Config) configureProviders(store *ConfigStore, env env.Env, resolver Va
 		config, configExists := c.Providers.Get(string(p.ID))
 		// if the user configured a known provider we need to allow it to override a couple of parameters
 		if configExists {
+			// Resolve credentials from keyring when the marker is present.
+			if IsKeyringMarker(config.APIKey) {
+				if store.keyring.Available() {
+					if realKey, err := store.keyring.GetAPIKey(string(p.ID)); err == nil {
+						config.APIKey = realKey
+					} else {
+						slog.Warn("Failed to read API key from OS keychain", "provider", p.ID, "error", err)
+						config.APIKey = "" // Clear marker so provider is properly skipped
+					}
+					if token, err := store.keyring.GetOAuthToken(string(p.ID)); err == nil {
+						config.OAuthToken = token
+					}
+				} else {
+					slog.Warn("Config has keyring marker but OS keychain is unavailable", "provider", p.ID)
+					config.APIKey = "" // Clear marker — can't resolve without keychain
+				}
+			}
+
+			// Migrate plaintext literal keys to keyring on first load.
+			if isLiteralSecret(config.APIKey) && store.keyring.Available() {
+				migrateProviderToKeyring(store, string(p.ID), &config)
+			}
+
 			if config.BaseURL != "" {
 				p.APIEndpoint = config.BaseURL
 			}
@@ -308,6 +332,29 @@ func (c *Config) configureProviders(store *ConfigStore, env env.Env, resolver Va
 			continue
 		}
 
+		// Resolve credentials from keyring when the marker is present.
+		if IsKeyringMarker(providerConfig.APIKey) {
+			if store.keyring.Available() {
+				if realKey, err := store.keyring.GetAPIKey(id); err == nil {
+					providerConfig.APIKey = realKey
+				} else {
+					slog.Warn("Failed to read API key from OS keychain", "provider", id, "error", err)
+					providerConfig.APIKey = "" // Clear marker so provider is properly skipped
+				}
+				if token, err := store.keyring.GetOAuthToken(id); err == nil {
+					providerConfig.OAuthToken = token
+				}
+			} else {
+				slog.Warn("Config has keyring marker but OS keychain is unavailable", "provider", id)
+				providerConfig.APIKey = "" // Clear marker — can't resolve without keychain
+			}
+		}
+
+		// Migrate plaintext literal keys to keyring on first load.
+		if isLiteralSecret(providerConfig.APIKey) && store.keyring.Available() {
+			migrateProviderToKeyring(store, id, &providerConfig)
+		}
+
 		// Make sure the provider ID is set
 		providerConfig.ID = id
 		providerConfig.Name = cmp.Or(providerConfig.Name, id) // Use ID as name if not set
@@ -816,3 +863,37 @@ func GlobalSkillsDirs() []string {
 }
 
 func isAppleTerminal() bool { return os.Getenv("TERM_PROGRAM") == "Apple_Terminal" }
+
+// migrateProviderToKeyring moves a plaintext API key (and optional OAuth token)
+// from the JSON config file into the OS keychain, replacing the values in the
+// file with markers. The in-memory config retains the real values.
+func migrateProviderToKeyring(store *ConfigStore, providerID string, pc *ProviderConfig) {
+	if !store.keyring.Available() {
+		return
+	}
+
+	if err := store.keyring.SetAPIKey(providerID, pc.APIKey); err != nil {
+		slog.Warn("Migration: failed to store API key in keychain", "provider", providerID, "error", err)
+		return
+	}
+
+	// Replace plaintext in JSON with marker.
+	if err := store.SetConfigField(ScopeGlobal, fmt.Sprintf("providers.%s.api_key", providerID), KeyringMarker); err != nil {
+		slog.Warn("Migration: failed to write keyring marker", "provider", providerID, "error", err)
+		return
+	}
+
+	// Migrate OAuth token too if present.
+	if pc.OAuthToken != nil {
+		if err := store.keyring.SetOAuthToken(providerID, pc.OAuthToken); err != nil {
+			slog.Warn("Migration: failed to store OAuth token in keychain", "provider", providerID, "error", err)
+			return
+		}
+		if err := store.SetConfigField(ScopeGlobal, fmt.Sprintf("providers.%s.oauth", providerID), KeyringMarker); err != nil {
+			slog.Warn("Migration: failed to write OAuth keyring marker", "provider", providerID, "error", err)
+			return
+		}
+	}
+
+	slog.Info("Migrated credentials from config file to OS keychain", "provider", providerID)
+}