sarg3nt
diff --git a/‎gearbox-agent/cmd/gearbox-agent/main.go‎
Lines changed: 70 additions & 19 deletions b/‎gearbox-agent/cmd/gearbox-agent/main.go‎
Lines changed: 70 additions & 19 deletions
diff --git a/‎gearbox-agent/internal/api/keyring.go‎
Lines changed: 68 additions & 0 deletions b/‎gearbox-agent/internal/api/keyring.go‎
Lines changed: 68 additions & 0 deletions
diff --git a/‎gearbox-agent/internal/api/server.go‎
Lines changed: 9 additions & 7 deletions b/‎gearbox-agent/internal/api/server.go‎
Lines changed: 9 additions & 7 deletions
diff --git a/‎gearbox-agent/internal/api/server_test.go‎
Lines changed: 17 additions & 2 deletions b/‎gearbox-agent/internal/api/server_test.go‎
Lines changed: 17 additions & 2 deletions
diff --git a/‎gearbox-agent/internal/framework/config/config.go‎
Lines changed: 13 additions & 2 deletions b/‎gearbox-agent/internal/framework/config/config.go‎
Lines changed: 13 additions & 2 deletions
@@ -113,29 +113,64 @@ func main() {
 		os.Exit(1)
 	}
 
-	// Handle API key commands
+	// Handle API key commands.
+	//
+	// Both flags read/write the agent's keyring (issue #72), falling back
+	// to the legacy api-key file when no keyring is present yet. The
+	// printed key is the keyring's primary entry, in the
+	// `gbx_<kid>_<base64url>` wire format the dashboard accepts.
 	if *showAPIKey {
-		key, err := crypto.ReadAPIKey(cfg.APIKeyPath)
+		kr, _, err := crypto.LoadOrCreateKeyRing(cfg.KeyRingPath, cfg.APIKeyPath)
 		if err != nil {
-			logger.Error("Failed to read API key", "error", err)
+			logger.Error("Failed to read keyring", "error", err)
 			os.Exit(1)
 		}
-		fmt.Println(key)
+		primary := kr.Primary()
+		if primary == nil {
+			fmt.Fprintln(os.Stderr, "no primary key found in keyring")
+			os.Exit(1)
+		}
+		fmt.Println(crypto.FormatToken(primary.KID, primary.Secret))
 		os.Exit(0)
 	}
 
 	if *rotateAPIKey {
-		key, err := crypto.GenerateAPIKey()
+		// Generates a fresh primary key and writes it to the keyring,
+		// replacing whatever was primary before. The agent reads the
+		// keyring on startup so the new key takes effect after restart.
+		// (Phase 2 will add a hot-reload endpoint that avoids restart.)
+		kr, _, err := crypto.LoadOrCreateKeyRing(cfg.KeyRingPath, cfg.APIKeyPath)
 		if err != nil {
-			logger.Error("Failed to generate API key", "error", err)
+			logger.Error("Failed to load keyring", "error", err)
+			os.Exit(1)
+		}
+		// Replace all entries with a single fresh primary. CLI rotate is
+		// the operator escape hatch — it's intentionally not the same as
+		// the controller-driven three-phase rotation; rather, it wipes
+		// the slate so a fresh dashboard pairing can take over.
+		kid, kerr := crypto.NewKID()
+		if kerr != nil {
+			logger.Error("Failed to generate key id", "error", kerr)
+			os.Exit(1)
+		}
+		secret, serr := crypto.NewSecret()
+		if serr != nil {
+			logger.Error("Failed to generate secret", "error", serr)
 			os.Exit(1)
 		}
-		if err := crypto.WriteAPIKey(cfg.APIKeyPath, key); err != nil {
-			logger.Error("Failed to write API key", "error", err)
+		fresh := crypto.KeyRingEntry{
+			KID:       kid,
+			Secret:    secret,
+			Role:      "primary",
+			CreatedAt: time.Now().UTC(),
+		}
+		kr.Entries = []crypto.KeyRingEntry{fresh}
+		if err := crypto.SaveKeyRing(cfg.KeyRingPath, kr); err != nil {
+			logger.Error("Failed to write keyring", "error", err)
 			os.Exit(1)
 		}
 		fmt.Println("New API key generated:")
-		fmt.Println(key)
+		fmt.Println(crypto.FormatToken(fresh.KID, fresh.Secret))
 		fmt.Println("\nRestart the service for the new key to take effect.")
 		os.Exit(0)
 	}
@@ -244,19 +279,33 @@ func main() {
 			"to enable AES-256-GCM encryption-at-rest.")
 	}
 
-	// Load or create API key
-	apiKey, isNewKey, err := crypto.LoadOrCreateAPIKey(cfg.APIKeyPath)
+	// Load or create the keyring. Issue #72 replaced the single-key model
+	// with an N-entry keyring to support zero-downtime rotation. Existing
+	// installs that still have an api-key file (no keyring.json yet) are
+	// migrated transparently: the on-disk hex key becomes the keyring's
+	// primary entry with kid="legacy", and the file is left in place as
+	// a read-only fallback for one release cycle.
+	keyring, isNewKey, err := crypto.LoadOrCreateKeyRing(cfg.KeyRingPath, cfg.APIKeyPath)
 	if err != nil {
-		logger.Error("Failed to initialize API key", "error", err)
+		logger.Error("Failed to initialize keyring", "error", err)
 		os.Exit(1)
 	}
+	keyringPtr := crypto.NewKeyRingPointer(keyring)
 	if isNewKey {
-		logger.Warn("NEW API KEY GENERATED - Save this key, it will not be shown again!")
-		// Print to stdout (not logger) so it doesn't appear in system logs
-		fmt.Printf("API Key: %s\n", apiKey)
-		logger.Info("API key saved", "path", cfg.APIKeyPath)
+		primary := keyring.Primary()
+		if primary != nil {
+			logger.Warn("NEW API KEY GENERATED - Save this key, it will not be shown again!")
+			// Print to stdout (not logger) so it doesn't appear in system logs
+			fmt.Printf("API Key: %s\n", crypto.FormatToken(primary.KID, primary.Secret))
+			logger.Info("Keyring saved", "path", cfg.KeyRingPath, "kid", primary.KID)
+		}
 	} else {
-		logger.Info("API key loaded from file")
+		primary := keyring.Primary()
+		kid := "<none>"
+		if primary != nil {
+			kid = primary.KID
+		}
+		logger.Info("Keyring loaded", "path", cfg.KeyRingPath, "entries", len(keyring.Entries), "primary_kid", kid)
 	}
 
 	// Load or create TLS certificates
@@ -398,7 +447,7 @@ func main() {
 	// Create and start API server
 	serverCfg := api.ServerConfig{
 		ListenAddr:     cfg.ListenAddr,
-		APIKey:         apiKey,
+		KeyRing:        keyringPtr,
 		CertFile:       tlsCfg.CertPath,
 		KeyFile:        tlsCfg.KeyPath,
 		Version:        Version,
@@ -493,12 +542,14 @@ func main() {
 	// backoff layered on top — see 2026-05 audit P1-7).
 	rateLimiter := middleware.DefaultRateLimiter(logger)
 	authBackoff := middleware.DefaultBackoffTracker(logger)
+	keyRingHandler := api.NewKeyRingHandler(server.KeyRing(), logger)
 	pluginRouter := server.Router().Group(func(r chi.Router) {
 		r.Use(middleware.RateLimitMiddleware(rateLimiter))
-		r.Use(middleware.APIKeyAuth(server.APIKey(), logger, authBackoff))
+		r.Use(middleware.APIKeyAuth(server.KeyRing(), logger, authBackoff))
 	})
 	gearManager.RegisterRoutes(pluginRouter)
 	gearManager.RegisterSystemRoutes(pluginRouter)
+	keyRingHandler.RegisterRoutes(pluginRouter)
 
 	logger.Info("Plugin system initialized",
 		"plugins", gear.Names(),
 
@@ -0,0 +1,68 @@
+package api
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/sarg3nt/gearbox-agent/internal/framework/crypto"
+)
+
+// KeyRingHandler exposes the agent's keyring metadata over the HTTP API.
+// Phase 1 ships only the read endpoint; Phase 2 adds install/use/remove
+// for the controller-driven three-phase rotation flow (issue #72).
+type KeyRingHandler struct {
+	keyring *crypto.KeyRingPointer
+	logger  *slog.Logger
+}
+
+// NewKeyRingHandler wires a handler around the agent's keyring pointer.
+func NewKeyRingHandler(keyring *crypto.KeyRingPointer, logger *slog.Logger) *KeyRingHandler {
+	return &KeyRingHandler{keyring: keyring, logger: logger}
+}
+
+// RegisterRoutes mounts the keyring endpoints on r. The caller is
+// responsible for putting r behind the API-key auth middleware.
+func (h *KeyRingHandler) RegisterRoutes(r chi.Router) {
+	r.Get("/api/v1/system/keyring", h.handleGet)
+}
+
+// keyRingResponse is what the API returns. Never includes secret bytes.
+type keyRingResponse struct {
+	Version int                       `json:"version"`
+	Entries []crypto.KeyRingMetadata  `json:"entries"`
+}
+
+// handleGet returns the keyring metadata — kids, roles, creation times,
+// and short fingerprints — but never the actual secrets.
+//
+//	@Summary		Get agent keyring metadata
+//	@Description	Returns the currently-installed API keys' metadata. Secrets are NEVER exposed. The fingerprint is the first 8 hex chars of sha256(secret); useful to verify the dashboard has the same secret without round-tripping the secret itself.
+//	@Tags			system
+//	@Security		BearerAuth
+//	@Produce		json
+//	@Success		200	{object}	keyRingResponse
+//	@Failure		401	{string}	string	"Unauthorized"
+//	@Router			/api/v1/system/keyring [get]
+func (h *KeyRingHandler) handleGet(w http.ResponseWriter, _ *http.Request) {
+	kr := h.keyring.Load()
+	if kr == nil {
+		// Should be unreachable — main.go calls NewKeyRingPointer(kr)
+		// with a non-nil value before mounting the handler. Defensive
+		// 500 + log so a future wiring bug fails loud rather than
+		// panicking the agent on every keyring request.
+		h.logger.Error("keyring pointer empty when serving /system/keyring")
+		http.Error(w, "keyring unavailable", http.StatusInternalServerError)
+		return
+	}
+	resp := keyRingResponse{
+		Version: kr.Version,
+		Entries: kr.Snapshot(),
+	}
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(resp); err != nil {
+		h.logger.Error("encode keyring response failed", "error", err)
+	}
+}
@@ -17,6 +17,7 @@ import (
 
 	_ "github.com/sarg3nt/gearbox-agent/docs" // Swagger docs
 	"github.com/sarg3nt/gearbox-agent/internal/api/console"
+	"github.com/sarg3nt/gearbox-agent/internal/framework/crypto"
 	"github.com/sarg3nt/gearbox-agent/internal/framework/events"
 	frameworkmiddleware "github.com/sarg3nt/gearbox-agent/internal/framework/middleware"
 )
@@ -26,15 +27,15 @@ type Server struct {
 	httpServer *http.Server
 	router     chi.Router
 	logger     *slog.Logger
-	apiKey     string
+	keyring    *crypto.KeyRingPointer
 	certFile   string
 	keyFile    string
 }
 
 // ServerConfig holds configuration for the API server.
 type ServerConfig struct {
 	ListenAddr       string
-	APIKey           string
+	KeyRing          *crypto.KeyRingPointer
 	CertFile         string
 	KeyFile          string
 	Version          string
@@ -147,7 +148,7 @@ func NewServer(cfg ServerConfig) *Server {
 	// Protected API routes (require API key auth)
 	r.Group(func(r chi.Router) {
 		r.Use(frameworkmiddleware.RateLimitMiddleware(rateLimiter))
-		r.Use(frameworkmiddleware.APIKeyAuth(cfg.APIKey, cfg.Logger, authBackoff))
+		r.Use(frameworkmiddleware.APIKeyAuth(cfg.KeyRing, cfg.Logger, authBackoff))
 
 		// Core endpoints (not handled by plugins)
 		r.Get("/api/v1/metadata", handlers.Metadata)
@@ -193,7 +194,7 @@ func NewServer(cfg ServerConfig) *Server {
 		},
 		router:   r,
 		logger:   cfg.Logger,
-		apiKey:   cfg.APIKey,
+		keyring:  cfg.KeyRing,
 		certFile: cfg.CertFile,
 		keyFile:  cfg.KeyFile,
 	}
@@ -204,9 +205,10 @@ func (s *Server) Router() chi.Router {
 	return s.router
 }
 
-// APIKey returns the server's API key for middleware configuration.
-func (s *Server) APIKey() string {
-	return s.apiKey
+// KeyRing returns the server's keyring pointer for middleware
+// configuration on plugin routes registered after server construction.
+func (s *Server) KeyRing() *crypto.KeyRingPointer {
+	return s.keyring
 }
 
 // Logger returns the server's logger.
 
@@ -1,12 +1,15 @@
 package api
 
 import (
+	"encoding/hex"
 	"io"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 
+	"github.com/sarg3nt/gearbox-agent/internal/framework/crypto"
 	"github.com/sarg3nt/gearbox-agent/internal/framework/events"
 )
 
@@ -29,9 +32,21 @@ func TestNewServer_ConsoleRoutesAlwaysMounted(t *testing.T) {
 	bus := events.NewBus()
 	defer bus.Close()
 
+	// Build a one-entry keyring whose legacy bare-hex token the test
+	// then sends in the Authorization header. The keyring replaced the
+	// single-string APIKey field on ServerConfig (issue #72).
+	testSecret := strings.Repeat("ab", 32) // 64 hex chars / 32 bytes
+	secretBytes, _ := hex.DecodeString(testSecret)
+	kr := &crypto.KeyRing{
+		Version: 1,
+		Entries: []crypto.KeyRingEntry{{
+			KID: "legacy", Secret: secretBytes, SecretHex: testSecret, Role: "primary",
+		}},
+	}
+
 	srv := NewServer(ServerConfig{
 		ListenAddr: "127.0.0.1:0",
-		APIKey:     "test-key",
+		KeyRing:    crypto.NewKeyRingPointer(kr),
 		Logger:     newSilentLogger(),
 		EventBus:   bus,
 	})
@@ -42,7 +57,7 @@ func TestNewServer_ConsoleRoutesAlwaysMounted(t *testing.T) {
 	// Capabilities — auth-gated, no token required, deterministic
 	// response.
 	req, _ := http.NewRequest(http.MethodGet, ts.URL+"/api/v1/console/capabilities", nil)
-	req.Header.Set("Authorization", "Bearer test-key")
+	req.Header.Set("Authorization", "Bearer "+testSecret)
 	resp, err := http.DefaultClient.Do(req)
 	if err != nil {
 		t.Fatalf("capabilities request: %v", err)
 
@@ -35,8 +35,18 @@ type Config struct {
 	// whitespace around each entry is trimmed, empty entries are dropped.
 	TLSHosts []string
 
-	// API key settings
-	APIKeyPath string
+	// API key settings.
+	//
+	// APIKeyPath is the legacy single-key file; retained for backwards
+	// compatibility with installs that pre-date the keyring. On startup
+	// the agent migrates its contents into a single keyring entry
+	// (kid="legacy", role=primary) and the file is left in place as a
+	// read-only fallback for one release cycle.
+	//
+	// KeyRingPath is the new N-entry rotating keyring (issue #72).
+	// Defaults to <DataDir>/keyring.json.
+	APIKeyPath  string
+	KeyRingPath string
 
 	// Data directory for state, certs, etc.
 	DataDir string
@@ -174,6 +184,7 @@ func Load() (*Config, error) {
 	}
 	cfg.TLSHosts = parseCommaList(os.Getenv("HAPROXY_AGENT_TLS_HOSTS"))
 	cfg.APIKeyPath = getEnvOrDefault("HAPROXY_AGENT_API_KEY_PATH", cfg.DataDir+"/api-key")
+	cfg.KeyRingPath = getEnvOrDefault("GEARBOX_AGENT_KEYRING_PATH", cfg.DataDir+"/keyring.json")
 
 	// Logging
 	if v := os.Getenv("HAPROXY_AGENT_LOG_LEVEL"); v != "" {