feat(rotation): Phase 1 multi-key keyring plumbing (#72)

Foundation for issue #72's rotation work. Adds the data structures and
storage required for N-entry keyrings on both the agent and dashboard
sides, with no operator-visible behaviour change yet — rotation
endpoints and UI follow in Phase 2.

Agent side
----------

- `internal/framework/crypto/keyring.go` — `KeyRing` type with up to
  `MaxKeyRingEntries = 4` accepted keys, atomic tmpfile+rename on disk,
  AES-256-GCM (GBE1) encryption when `GEARBOX_AGENT_ENCRYPTION_KEY` is
  set. Wire token format: `gbx_<6-hex-kid>_<base64url(32 random bytes)>`,
  with legacy 64-hex tokens still accepted for one release cycle.
- `LoadOrCreateKeyRing(keyringPath, legacyAPIKeyPath)` migrates an
  existing `/var/lib/gearbox-agent/api-key` file into a single keyring
  entry tagged `kid="legacy"`, role=primary. Legacy file stays on disk
  as a read-only fallback.
- `KeyRingPointer` wraps `atomic.Pointer[KeyRing]` so Phase 2's
  install/use/remove endpoints can swap the live keyring without
  middleware restart. Verified by the new auth-middleware test
  `TestAPIKeyAuth_HotSwapVisibleImmediately`.
- `internal/framework/middleware/auth.go` rewritten to take a keyring
  pointer instead of a static key. Accepts both prefixed and legacy
  token formats; matched `kid` echoed back as `X-Gearbox-Kid:` header
  on every authenticated response so the dashboard can detect drift
  (consumed in Phase 5). Auth with a secondary key logs at INFO so
  the audit log can later flag "old key still in use after rotation".
- New endpoint `GET /api/v1/system/keyring` (authenticated) returns
  metadata only — kids, roles, created_at, sha256-prefix fingerprint
  for diagnostic equality checks — never the secret bytes themselves.
- `--show-api-key` and `--rotate-api-key` CLI flags work against the
  keyring; the printed key uses the new `gbx_<kid>_<b64>` wire format
  the dashboard can paste verbatim.
- `GEARBOX_AGENT_KEYRING_PATH` env var (default
  `<DataDir>/keyring.json`) is now a config field alongside the legacy
  `HAPROXY_AGENT_API_KEY_PATH`.

Dashboard side
--------------

- Migration `000002_add_box_agent_keys` adds the
  `(box_id, kid)`-keyed `box_agent_keys` table and idempotently
  backfills one `kid='legacy'` row per existing box from
  `boxes.api_key_encrypted`. The legacy column stays for one release.
- `database/box_agent_keys.go` exposes Get/Insert/SetPrimary/Delete/
  TouchLastUsed — the storage primitives Phase 2's rotator service
  composes into the install→use→remove dance.

Tests
-----

- 19 keyring unit tests covering token parsing (prefixed + legacy +
  malformed), keyring mutation, file round-trip with and without
  encryption, legacy api-key migration, and pointer hot-swap.
- 8 auth-middleware integration tests covering bearer parsing, kid
  header echo, secondary-key acceptance, and the live hot-swap path
  Phase 2 depends on.
- 5 storage tests covering primary-key lookup, atomic role flip,
  delete-refuses-last guard, and last_used_at touch.

Carry-overs to Phase 2 (intentional gaps surfaced from this PR)
---------------------------------------------------------------

- `DeleteBox` does not yet cascade to `box_agent_keys` (SQLite
  `PRAGMA foreign_keys` is off in this codebase; enabling it is a
  broader change). Phase 2's box-delete path will clean dependent
  rows explicitly. Documented in box_agent_keys_test.go.
- The dashboard's `agent.Client` does not yet send `X-Gearbox-Kid`
  on outbound requests — there's no kid to send while every box's
  keyring contains only the legacy entry. Phase 2 wires this when
  the rotator starts mutating keyrings.

Refs: research summary and implementation plan posted to #72.

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

Author: sarg3nt

gearbox-agent/cmd/gearbox-agent/main.go

@@ -113,29 +113,63 @@ 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",
+		}
+		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 +278,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 +446,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 +541,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(),

gearbox-agent/internal/api/keyring.go

@@ -0,0 +1,59 @@
+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()
+	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)
+	}
+}

gearbox-agent/internal/api/server.go

@@ -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.

gearbox-agent/internal/framework/config/config.go

@@ -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 != "" {