sarg3nt
diff --git a/‎.gitleaks.toml‎
Lines changed: 5 additions & 0 deletions b/‎.gitleaks.toml‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎gearbox-agent/cmd/gearbox-agent/main.go‎
Lines changed: 18 additions & 1 deletion b/‎gearbox-agent/cmd/gearbox-agent/main.go‎
Lines changed: 18 additions & 1 deletion
diff --git a/‎gearbox-agent/internal/framework/crypto/aead.go‎
Lines changed: 138 additions & 0 deletions b/‎gearbox-agent/internal/framework/crypto/aead.go‎
Lines changed: 138 additions & 0 deletions
@@ -73,8 +73,13 @@ regexes = [
 # Allowlist - commits to ignore
 # 2fdb5ba: functional_test.go had an example API key value in a doc comment
 # (test-only, not a real credential — replaced with <YOUR_API_KEY> placeholder in a later commit)
+# 96bd383: aead_test.go added three 64-hex-char fixtures (plainSecret /
+# apiKey) to exercise the encryption-at-rest round-trip. A later commit
+# added inline //gitleaks:allow comments, but the gitleaks-action scans
+# the full PR diff range so the historical commit still trips the rule.
 commits = [
     "2fdb5ba0d2e8da23a6409527cdbf6696d90eb537",
+    "96bd38365b022aa8b9d78886dfd3eb16e644eecf",
 ]
 
 # Stopwords - tokens that if found will stop gitleaks
 
@@ -92,6 +92,14 @@ func main() {
 		Level: logLevel,
 	}))
 
+	// Hard-fail early if GEARBOX_AGENT_ENCRYPTION_KEY is set but malformed,
+	// regardless of which subcommand we're about to run — one-shot CLI
+	// commands like --show-api-key need a usable key too.
+	if _, err := crypto.EncryptionConfigured(); err != nil {
+		fmt.Fprintf(os.Stderr, "Encryption key configuration error: %v\n", err)
+		os.Exit(1)
+	}
+
 	// Handle API key commands
 	if *showAPIKey {
 		key, err := crypto.ReadAPIKey(cfg.APIKeyPath)
@@ -109,7 +117,7 @@ func main() {
 			logger.Error("Failed to generate API key", "error", err)
 			os.Exit(1)
 		}
-		if err := os.WriteFile(cfg.APIKeyPath, []byte(key), crypto.APIKeyFilePerms); err != nil {
+		if err := crypto.WriteAPIKey(cfg.APIKeyPath, key); err != nil {
 			logger.Error("Failed to write API key", "error", err)
 			os.Exit(1)
 		}
@@ -169,6 +177,15 @@ func main() {
 		"built", BuildDate,
 	)
 
+	// Warn once at startup if secret-file encryption is not configured.
+	// Placed after one-shot flag handlers so it doesn't pollute their
+	// stdout output (e.g. --show-api-key piped to a clipboard tool).
+	if ok, _ := crypto.EncryptionConfigured(); !ok {
+		logger.Warn("Secret files are stored in plaintext. " +
+			"Set GEARBOX_AGENT_ENCRYPTION_KEY (64 hex chars, see 'openssl rand -hex 32') " +
+			"to enable AES-256-GCM encryption-at-rest.")
+	}
+
 	// Load or create API key
 	apiKey, isNewKey, err := crypto.LoadOrCreateAPIKey(cfg.APIKeyPath)
 	if err != nil {
 
@@ -0,0 +1,138 @@
+package crypto
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+)
+
+// magic is the 4-byte header written at the start of every encrypted secret file.
+// Its presence tells the loader to decrypt rather than treat the file as plaintext.
+var magic = [4]byte{'G', 'B', 'E', '1'}
+
+// ErrKeyRequired is returned when an encrypted file is found but no encryption key
+// has been configured. Key loss means rotation — there is no recovery path.
+//
+// Recovery: set GEARBOX_AGENT_ENCRYPTION_KEY to the correct value to decrypt;
+// or delete the file and re-generate (--rotate-api-key for the API key,
+// --generate-webhook-secret for the webhook secret — note the latter does
+// NOT overwrite an existing file, so you must rm it first).
+var ErrKeyRequired = errors.New(
+	"secret file is encrypted (GBE1) but GEARBOX_AGENT_ENCRYPTION_KEY is not set; " +
+		"set the key to decrypt, or delete the file and re-generate the secret",
+)
+
+// KeyProvider supplies the 32-byte AES-256 key used to protect on-disk secrets.
+// Implementations include [EnvKeyProvider] (reads from an environment variable) and,
+// in future releases, cloud-KMS backends (see GitHub issue #54).
+type KeyProvider interface {
+	// Key returns the 32-byte AES-256 key, or nil if encryption is not configured.
+	// A nil key means secrets are stored as plaintext; a non-nil key means they are
+	// encrypted with AES-256-GCM.
+	Key() ([]byte, error)
+}
+
+// EnvKeyProvider reads the encryption key from an environment variable.
+// The variable must contain exactly 64 hex characters (32 bytes / 256 bits);
+// both upper- and lower-case hex are accepted.
+// Generate a suitable value with: openssl rand -hex 32
+type EnvKeyProvider struct {
+	EnvVar string // environment variable name; default "GEARBOX_AGENT_ENCRYPTION_KEY"
+}
+
+// DefaultKeyProvider is the KeyProvider used by loadOrCreateSecret and readSecret
+// unless overridden in tests.
+var DefaultKeyProvider KeyProvider = &EnvKeyProvider{EnvVar: "GEARBOX_AGENT_ENCRYPTION_KEY"}
+
+// Key implements [KeyProvider]. Returns nil, nil when the variable is unset.
+func (e *EnvKeyProvider) Key() ([]byte, error) {
+	val := os.Getenv(e.EnvVar)
+	if val == "" {
+		return nil, nil
+	}
+	key, err := hex.DecodeString(val)
+	if err != nil {
+		return nil, fmt.Errorf("%s: invalid hex value: %w", e.EnvVar, err)
+	}
+	if len(key) != 32 {
+		return nil, fmt.Errorf(
+			"%s: must be exactly 64 hex characters (32 bytes); got %d bytes — generate with: openssl rand -hex 32",
+			e.EnvVar, len(key),
+		)
+	}
+	return key, nil
+}
+
+// EncryptionConfigured returns true when the default key provider has a key set.
+// Used at startup to emit a warning when encryption is not configured.
+func EncryptionConfigured() (bool, error) {
+	key, err := DefaultKeyProvider.Key()
+	if err != nil {
+		return false, err
+	}
+	return key != nil, nil
+}
+
+// isEncrypted returns true when data begins with the GBE1 magic header.
+func isEncrypted(data []byte) bool {
+	if len(data) < len(magic) {
+		return false
+	}
+	return data[0] == magic[0] && data[1] == magic[1] &&
+		data[2] == magic[2] && data[3] == magic[3]
+}
+
+// encryptSecret encrypts plaintext using AES-256-GCM and returns the
+// magic-prefixed blob: magic(4) + nonce(12) + GCM-ciphertext-with-tag.
+func encryptSecret(plaintext string, key []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf("aes.NewCipher: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, fmt.Errorf("cipher.NewGCM: %w", err)
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return nil, fmt.Errorf("generate nonce: %w", err)
+	}
+	sealed := gcm.Seal(nil, nonce, []byte(plaintext), nil)
+
+	out := make([]byte, 0, len(magic)+len(nonce)+len(sealed))
+	out = append(out, magic[:]...)
+	out = append(out, nonce...)
+	out = append(out, sealed...)
+	return out, nil
+}
+
+// decryptSecret decrypts a blob produced by [encryptSecret].
+// data must start with the GBE1 magic header.
+func decryptSecret(data []byte, key []byte) (string, error) {
+	if !isEncrypted(data) {
+		return "", errors.New("decryptSecret: data does not start with GBE1 magic")
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", fmt.Errorf("aes.NewCipher: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", fmt.Errorf("cipher.NewGCM: %w", err)
+	}
+	payload := data[len(magic):]
+	nonceSize := gcm.NonceSize()
+	if len(payload) < nonceSize {
+		return "", errors.New("decryptSecret: ciphertext too short")
+	}
+	plaintext, err := gcm.Open(nil, payload[:nonceSize], payload[nonceSize:], nil)
+	if err != nil {
+		return "", fmt.Errorf("gcm.Open: %w (key may be wrong or file corrupted)", err)
+	}
+	return string(plaintext), nil
+}