Add SOPS age key auto-detection and improved error messages

- Auto-detect SOPS age key path when target is omitted
- Bootstrap now detects source names containing 'sops' and 'age'
- Automatically uses platform-specific default paths
- Added helpful error messages when SOPS fails to decrypt
- Suggests running 'comet bootstrap' or setting SOPS_AGE_KEY
- Updated documentation to reflect optional target path
- File permissions (0600) set correctly on creation

Author: speier

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.6] - 2025-10-23
+
+### Added
+- **Auto-detect SOPS age key path** - Bootstrap `target` is now optional for SOPS age keys. If the source name contains "sops" and "age", it automatically uses the platform-specific default path
+- **Helpful SOPS error messages** - When SOPS fails to decrypt due to missing age keys, provide clear hint suggesting `comet bootstrap` or setting `SOPS_AGE_KEY`
+
+### Changed
+- Improved bootstrap configuration - SOPS age key target path is now optional and auto-detected based on platform
+
 ## [0.6.5] - 2025-10-23
 
 ### Fixed
@@ -153,7 +162,8 @@ bootstrap:
 - Support for Terraform and OpenTofu
 - CLI commands: plan, apply, destroy, list, output, clean
 
-[Unreleased]: https://github.com/moonwalker/comet/compare/v0.6.5...HEAD
+[Unreleased]: https://github.com/moonwalker/comet/compare/v0.6.6...HEAD
+[0.6.6]: https://github.com/moonwalker/comet/releases/tag/v0.6.6
 [0.6.5]: https://github.com/moonwalker/comet/releases/tag/v0.6.5
 [0.6.4]: https://github.com/moonwalker/comet/releases/tag/v0.6.4
 [0.6.3]: https://github.com/moonwalker/comet/releases/tag/v0.6.3

comet.yaml

@@ -16,13 +16,16 @@ generate_backend: false
 #   - name: sops-age-key
 #     type: secret
 #     source: op://vault/infrastructure/sops-age-key  # Your 1Password path
-#     target: ~/.config/sops/age/keys.txt  # Automatically resolves to platform-specific path
+#     # target is optional - automatically uses platform-specific SOPS age key location:
+#     #   macOS (default):    ~/Library/Application Support/sops/age/keys.txt
+#     #   macOS (w/ XDG):     $XDG_CONFIG_HOME/sops/age/keys.txt
+#     #   Linux:              ~/.config/sops/age/keys.txt
+#     # target: ~/.config/sops/age/keys.txt  # Or specify a custom path
 #     mode: "0600"
 #
-#   # Note: For SOPS age keys, bootstrap automatically resolves the target path:
-#   #   - macOS without XDG_CONFIG_HOME: ~/Library/Application Support/sops/age/keys.txt
-#   #   - macOS with XDG_CONFIG_HOME: $XDG_CONFIG_HOME/sops/age/keys.txt
-#   #   - Linux: ~/.config/sops/age/keys.txt (or $XDG_CONFIG_HOME if set)
+#   # Note: For SOPS age keys, if you omit 'target', bootstrap automatically
+#   # detects it's a SOPS age key (based on source name containing 'sops' and 'age')
+#   # and uses the correct platform-specific default path.
 #
 #   # Optional: Check required tools
 #   - name: check-tools

internal/bootstrap/runner.go

@@ -153,8 +153,20 @@ func (r *Runner) runSecretStep(step *schema.BootstrapStep) error {
 
 	log.Debug("Secret fetched", "duration", duration)
 
-	// Expand target path
-	targetPath := expandPath(step.Target)
+	// Determine target path - use default for SOPS age keys if not specified
+	targetPath := step.Target
+	if targetPath == "" {
+		// Auto-detect default path for common secret types
+		if isSopsAgeKeySource(step.Source) {
+			targetPath = getDefaultSopsAgePath()
+			log.Debug("Using default SOPS age key path", "path", targetPath)
+		} else {
+			return fmt.Errorf("target path is required for secret type: %s", step.Source)
+		}
+	}
+
+	// Expand target path (handles ~, env vars, and platform-specific SOPS paths)
+	targetPath = expandPath(targetPath)
 
 	// Create parent directory
 	targetDir := filepath.Dir(targetPath)
@@ -279,6 +291,34 @@ func resolveSopsAgePath(path string) string {
 	return filepath.Join(home, ".config", sopsAgeKeyPath)
 }
 
+// isSopsAgeKeySource checks if the source is likely a SOPS age key
+func isSopsAgeKeySource(source string) bool {
+	// Common patterns for SOPS age keys in secret managers
+	lower := strings.ToLower(source)
+	return strings.Contains(lower, "sops") &&
+		(strings.Contains(lower, "age") || strings.Contains(lower, "key"))
+}
+
+// getDefaultSopsAgePath returns the default SOPS age key path for the current platform
+func getDefaultSopsAgePath() string {
+	// Check if XDG_CONFIG_HOME is set
+	if xdgConfigHome := os.Getenv("XDG_CONFIG_HOME"); xdgConfigHome != "" {
+		return filepath.Join(xdgConfigHome, "sops", "age", "keys.txt")
+	}
+
+	home, err := os.UserHomeDir()
+	if err != nil {
+		// Fallback to a reasonable default
+		return "~/.config/sops/age/keys.txt"
+	}
+
+	if runtime.GOOS == "darwin" {
+		return filepath.Join(home, "Library", "Application Support", "sops", "age", "keys.txt")
+	}
+
+	return filepath.Join(home, ".config", "sops", "age", "keys.txt")
+}
+
 // NeedsBootstrap checks if any bootstrap steps need to be run
 func NeedsBootstrap(config *schema.Config) bool {
 	if len(config.Bootstrap) == 0 {

internal/secrets/sops.go

@@ -32,7 +32,14 @@ func sopsData(ref string) (string, error) {
 	ext := filepath.Ext(u.Path)
 	b, err := decrypt.File(u.Path, ext)
 	if err != nil {
-		return "", err
+		// Detect common SOPS errors and provide helpful messages
+		errMsg := err.Error()
+		if strings.Contains(errMsg, "no age identity") ||
+			strings.Contains(errMsg, "0 successful groups required") ||
+			strings.Contains(errMsg, "failed to get the data key") {
+			return "", fmt.Errorf("failed to decrypt SOPS file: %w\n\nℹ️  Hint: Age key might be missing. Try running:\n  comet bootstrap\n\nOr set the key manually:\n  export SOPS_AGE_KEY=\"...\"", err)
+		}
+		return "", fmt.Errorf("failed to decrypt SOPS file: %w", err)
 	}
 
 	if slices.Contains(yamlExts, ext) {

website/docs/guides/configuration.md

@@ -63,7 +63,9 @@ bootstrap:
   - name: sops-age-key
     type: secret
     source: op://vault/infrastructure/sops-age-key
-    target: ~/.config/sops/age/keys.txt
+    # target is optional - auto-detected for SOPS age keys
+    # macOS: ~/Library/Application Support/sops/age/keys.txt
+    # Linux: ~/.config/sops/age/keys.txt
     mode: "0600"
 ```
 
@@ -109,23 +111,30 @@ Fetch secrets from 1Password or SOPS and save to local files with proper permiss
 
 ```yaml
 bootstrap:
-  # 1Password secret
+  # 1Password secret - SOPS age key (target auto-detected)
   - name: sops-key
     type: secret
-    source: op://vault/item/field        # 1Password reference
-    target: ~/.config/sops/age/keys.txt  # Save location (~ expanded)
-    mode: "0600"                         # File permissions (optional, default: 0600)
+    source: op://vault/sops-age-key/private  # Source contains "sops" and "age"
+    # target is optional - automatically uses platform-specific path
+    mode: "0600"  # File permissions (optional, default: 0600)
   
-  # SOPS secret
+  # Custom secret with explicit target
   - name: api-token
     type: secret
-    source: sops://secrets.enc.yaml#/api/token  # SOPS file reference
-    target: ~/.secrets/api-token
-    mode: "0400"                         # Read-only for extra security
-    optional: true                       # Don't fail if source doesn't exist
+    source: op://vault/api-token/credential
+    target: ~/.secrets/api-token  # Custom path (~ expanded)
+    mode: "0400"                  # Read-only for extra security
+    optional: true                # Don't fail if source doesn't exist
+  
+  # SOPS secret
+  - name: db-password
+    type: secret
+    source: sops://secrets.enc.yaml#/database/password
+    target: ~/.secrets/db-password
 ```
 
 **Features:**
+- **Auto-detect SOPS age key paths** - If source name contains "sops" and "age", target is optional and uses platform defaults
 - Automatically creates parent directories
 - Supports both `op://` (1Password) and `sops://` (SOPS) sources
 - Customizable file permissions (default: `0600`)
@@ -210,11 +219,11 @@ bootstrap:
     type: check
     command: op,sops,tofu
   
-  # 2. Fetch SOPS key from 1Password
+  # 2. Fetch SOPS key from 1Password (target auto-detected)
   - name: sops-key
     type: secret
     source: op://vault/infrastructure/sops-age-key
-    target: ~/.config/sops/age/keys.txt
+    # target is optional for SOPS age keys
     mode: "0600"
   
   # 3. Authenticate with cloud provider (optional)
@@ -287,7 +296,7 @@ bootstrap:
   - name: sops-key
     type: secret
     source: op://vault/sops/key
-    target: ~/.config/sops/age/keys.txt
+    # target is optional - auto-detected for SOPS age keys
   
   - name: github-token
     type: secret
@@ -319,12 +328,12 @@ If you were using `op://` or `sops://` in the `env` section (removed in v0.6.0),
 env:
   SOPS_AGE_KEY: op://vault/key/private
 
-# NEW (v0.6.0) - Fast after bootstrap
+# NEW (v0.6.0+) - Fast after bootstrap
 bootstrap:
   - name: sops-key
     type: secret
     source: op://vault/key/private
-    target: ~/.config/sops/age/keys.txt
+    # target optional for SOPS age keys (auto-detected)
     mode: "0600"
 ```
 
@@ -378,7 +387,7 @@ bootstrap:
   - name: sops-key
     type: secret
     source: op://vault/key/private
-    target: ~/.config/sops/age/keys.txt
+    # target optional (auto-detected for SOPS age keys)
     mode: "0600"
 ```
 

website/docs/guides/secrets-management.md

@@ -72,7 +72,9 @@ bootstrap:
   - name: sops-age-key
     type: secret
     source: op://vault/infrastructure/sops-age-key
-    target: ~/.config/sops/age/keys.txt
+    # target is optional - automatically uses platform-specific path
+    # macOS: ~/Library/Application Support/sops/age/keys.txt
+    # Linux: ~/.config/sops/age/keys.txt
     mode: "0600"
 ```
 
@@ -91,7 +93,9 @@ comet plan dev
 
 :::tip Why Bootstrap?
 
-SOPS needs the `SOPS_AGE_KEY` or `SOPS_AGE_KEY_FILE` environment variable to decrypt files. Instead of fetching this from 1Password on every command (4s overhead), bootstrap caches it to `~/.config/sops/age/keys.txt` once, making all subsequent commands fast.
+SOPS needs the `SOPS_AGE_KEY` or `SOPS_AGE_KEY_FILE` environment variable to decrypt files. Instead of fetching this from 1Password on every command (4s overhead), bootstrap caches it to the platform-specific default location once, making all subsequent commands fast.
+
+The `target` path is optional - Comet automatically detects SOPS age keys (source containing "sops" and "age") and uses the correct platform-specific path where SOPS expects to find them.
 
 :::
     age: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -343,7 +347,7 @@ bootstrap:
   - name: sops-key
     type: secret
     source: op://vault/sops-key/private
-    target: ~/.config/sops/age/keys.txt
+    # target is optional - auto-detected for SOPS age keys
     mode: "0600"
 ```
 
@@ -355,15 +359,28 @@ comet apply production
 
 ## Troubleshooting
 
-### "Failed to get data key" Error
+### "Failed to get data key" / "0 successful groups required" Error
+
+This usually means the age key is missing. Comet will suggest:
+
+```
+ℹ️  Hint: Age key might be missing. Try running:
+  comet bootstrap
+
+Or set the key manually:
+  export SOPS_AGE_KEY="..."
+```
 
-Make sure your encryption key is available:
+Solutions:
 
 ```bash
-# For age
+# Option 1: Use bootstrap
+comet bootstrap
+
+# Option 2: Set environment variable
 export SOPS_AGE_KEY_FILE=/path/to/key.txt
 
-# For GPG
+# Option 3: For GPG
 gpg --list-secret-keys  # Verify key is imported
 ```