more permissive validation of secret names

jszobody · jszobody · commit a4bce509a6ed · 2025-08-22T11:33:55.000-04:00
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
@@ -32,6 +32,12 @@ Then run Keep commands using:
 ./vendor/bin/keep [command]
 ```
 
+You might enjoy having an alias in your shell profile to make it easier:
+
+```bash
+alias keep="./vendor/bin/keep"
+```
+
 ## Laravel Integration (Optional)
 
 If you're using Keep with a Laravel application, you can publish the configuration and set up the service provider:
diff --git a/docs/index.md b/docs/index.md
@@ -15,20 +15,20 @@ hero:
 
 features:
   - title: Multi-Vault Support
-    details: Support for local files, AWS SSM, and AWS Secrets Manager with consistent interface across all providers.
+    details: Support for local files, AWS SSM, and AWS Secrets Manager with more to come.
     
   - title: Stage Management  
     details: Organize secrets by environment stages (development, staging, production) with easy promotion between stages.
     
   - title: Template System
     details: Generate .env files and configuration from templates with placeholder replacement and validation.
     
-  - title: Laravel Integration
-    details: Seamless integration with Laravel applications including helper functions and service provider.
-    
   - title: CLI First
     details: Powerful command-line interface for all operations with support for CI/CD workflows and automation.
     
+  - title: Laravel Integration
+    details: Seamless integration with Laravel applications including helper functions and service provider.
+    
   - title: Security Focused
     details: Encrypted local storage, secure AWS integration, and careful handling of sensitive data throughout.
 ---
@@ -39,14 +39,26 @@ features:
 # Configure your project
 keep configure
 
-# Add a vault
-keep vault:add local myapp
+# Interactively set up and configure a new vault
+keep vault:add
+
+# Check your vault permissions across all stages
+keep verify
+
+# Set a secret for production stage
+keep set --stage=production DB_PASSWORD "super-secret"
+
+# List all secrets in staging
+keep list --stage=staging --unmask
+
+# Compare stages to see which secrets are defined and differ from each other
+keep diff
 
-# Set a secret
-keep set myapp:development DB_PASSWORD "super-secret"
+# Export all secrets to .env file
+keep export --stage=production > .env
 
-# Export to .env file
-keep export myapp:development --format=env > .env
+# Merge secrets into a template file with placeholders
+keep merge .env.template --stage=production > .env
 ```
 
 ## Why Keep?
diff --git a/src/Commands/ImportCommand.php b/src/Commands/ImportCommand.php
@@ -100,7 +100,14 @@ protected function runImport(SecretCollection $importSecrets, SecretCollection $
 
             if (empty($secret->value())) {
                 $this->warn("Skipping key [{$secret->key()}] with empty value.");
+                continue;
+            }
 
+            // Validate key before importing to ensure it meets Keep's standards
+            try {
+                $this->validateUserKey($secret->key());
+            } catch (\InvalidArgumentException $e) {
+                $this->error("Skipping invalid key [{$secret->key()}]: " . $e->getMessage());
                 continue;
             }
 
@@ -148,4 +155,35 @@ protected function resultsTable(SecretCollection $importSecrets, SecretCollectio
 
         return $rows;
     }
+    
+    /**
+     * Validate a user-provided key for safe vault operations.
+     * More permissive than .env requirements to support various use cases.
+     */
+    protected function validateUserKey(string $key): void
+    {
+        $trimmed = trim($key);
+
+        // Allow letters, digits, underscores, and hyphens (common in cloud services)
+        if (! preg_match('/^[A-Za-z0-9_-]+$/', $trimmed)) {
+            throw new \InvalidArgumentException(
+                "Secret key '{$key}' contains invalid characters. ".
+                'Only letters, numbers, underscores, and hyphens are allowed.'
+            );
+        }
+
+        // Length validation (reasonable limits for secret names)
+        if (strlen($trimmed) < 1 || strlen($trimmed) > 255) {
+            throw new \InvalidArgumentException(
+                "Secret key '{$key}' must be 1-255 characters long."
+            );
+        }
+
+        // Cannot start with hyphen (could be interpreted as command flag)
+        if (str_starts_with($trimmed, '-')) {
+            throw new \InvalidArgumentException(
+                "Secret key '{$key}' cannot start with hyphen."
+            );
+        }
+    }
 }
diff --git a/src/Commands/SetCommand.php b/src/Commands/SetCommand.php
@@ -15,8 +15,12 @@ class SetCommand extends BaseCommand
 
     public function process()
     {
+        // Validate key using strict user input validation
+        $key = $this->key();
+        $this->validateUserKey($key);
+        
         $context = $this->context();
-        $secret = $context->createVault()->set($this->key(), $this->value(), $this->secure());
+        $secret = $context->createVault()->set($key, $this->value(), $this->secure());
 
         $this->info(
             sprintf('Secret [%s] %s in vault [%s].',
@@ -26,4 +30,35 @@ public function process()
             )
         );
     }
+    
+    /**
+     * Validate a user-provided key for safe vault operations.
+     * More permissive than .env requirements to support various use cases.
+     */
+    protected function validateUserKey(string $key): void
+    {
+        $trimmed = trim($key);
+
+        // Allow letters, digits, underscores, and hyphens (common in cloud services)
+        if (! preg_match('/^[A-Za-z0-9_-]+$/', $trimmed)) {
+            throw new \InvalidArgumentException(
+                "Secret key '{$key}' contains invalid characters. ".
+                'Only letters, numbers, underscores, and hyphens are allowed.'
+            );
+        }
+
+        // Length validation (reasonable limits for secret names)
+        if (strlen($trimmed) < 1 || strlen($trimmed) > 255) {
+            throw new \InvalidArgumentException(
+                "Secret key '{$key}' must be 1-255 characters long."
+            );
+        }
+
+        // Cannot start with hyphen (could be interpreted as command flag)
+        if (str_starts_with($trimmed, '-')) {
+            throw new \InvalidArgumentException(
+                "Secret key '{$key}' cannot start with hyphen."
+            );
+        }
+    }
 }
diff --git a/src/Data/Collections/SecretCollection.php b/src/Data/Collections/SecretCollection.php
@@ -18,7 +18,7 @@ public function toKeyValuePair(): static
 
     public function toEnvString()
     {
-        return $this->map(fn (Secret $secret) => $secret->key().'='.$this->formatEnvValue($secret->value())
+        return $this->map(fn (Secret $secret) => $secret->sanitizedKey().'='.$this->formatEnvValue($secret->value())
         )->implode(PHP_EOL);
     }
 
diff --git a/src/Data/Env.php b/src/Data/Env.php
@@ -51,7 +51,7 @@ public function list(): Collection
     public function secrets(): SecretCollection
     {
         $secrets = $this->entries()->map(function ($entry) {
-            return new Secret(
+            return Secret::fromVault(
                 key: $entry->getName(),
                 value: $entry->getValue()->get()->getChars(),
             );
diff --git a/src/Data/Secret.php b/src/Data/Secret.php
@@ -22,13 +22,15 @@ public function __construct(
         protected ?int $revision = 0,
         protected ?string $path = null,
         protected ?AbstractVault $vault = null,
+        protected bool $skipValidation = false,
     ) {
-        $this->key = $this->validateKey($key);
+        $this->key = $skipValidation ? trim($key) : $this->validateKey($key);
     }
 
     /**
-     * Validate a secret key using strict whitelist validation.
-     * Only allows letters, digits, and underscores (standard .env format).
+     * Validate a secret key for safe vault operations.
+     * Allows common naming conventions (letters, digits, underscores, hyphens) 
+     * while preventing characters that could break vault API calls.
      *
      * @param  string  $key  The raw key to validate
      * @return string The validated key
@@ -39,11 +41,11 @@ protected function validateKey(string $key): string
     {
         $trimmed = trim($key);
 
-        // Strict whitelist: Only allow letters, digits, and underscores
-        if (! preg_match('/^[A-Za-z0-9_]+$/', $trimmed)) {
+        // Allow letters, digits, underscores, and hyphens (common in cloud services)
+        if (! preg_match('/^[A-Za-z0-9_-]+$/', $trimmed)) {
             throw new \InvalidArgumentException(
                 "Secret key '{$key}' contains invalid characters. ".
-                'Only letters, numbers, and underscores are allowed.'
+                'Only letters, numbers, underscores, and hyphens are allowed.'
             );
         }
 
@@ -54,28 +56,103 @@ protected function validateKey(string $key): string
             );
         }
 
-        // Cannot start with underscore (poor practice, could conflict with system vars)
-        if (str_starts_with($trimmed, '_')) {
+        // Cannot start with hyphen (could be interpreted as command flag)
+        if (str_starts_with($trimmed, '-')) {
             throw new \InvalidArgumentException(
-                "Secret key '{$key}' cannot start with underscore."
-            );
-        }
-
-        // Cannot start with digit (invalid variable name in most languages)
-        if (preg_match('/^[0-9]/', $trimmed)) {
-            throw new \InvalidArgumentException(
-                "Secret key '{$key}' cannot start with a number."
+                "Secret key '{$key}' cannot start with hyphen."
             );
         }
 
         return $trimmed;
     }
 
+    /**
+     * Create a Secret from vault data (permissive key validation).
+     * Use this when reading existing secrets from external sources.
+     */
+    public static function fromVault(
+        string $key,
+        ?string $value = null,
+        ?string $encryptedValue = null,
+        bool $secure = true,
+        ?string $stage = null,
+        ?int $revision = 0,
+        ?string $path = null,
+        ?AbstractVault $vault = null,
+    ): static {
+        return new static(
+            key: $key,
+            value: $value,
+            encryptedValue: $encryptedValue,
+            secure: $secure,
+            stage: $stage,
+            revision: $revision,
+            path: $path,
+            vault: $vault,
+            skipValidation: true,
+        );
+    }
+
+    /**
+     * Create a Secret from user input (strict key validation).
+     * Use this when accepting user-provided secret names.
+     */
+    public static function fromUser(
+        string $key,
+        ?string $value = null,
+        ?string $encryptedValue = null,
+        bool $secure = true,
+        ?string $stage = null,
+        ?int $revision = 0,
+        ?string $path = null,
+        ?AbstractVault $vault = null,
+    ): static {
+        return new static(
+            key: $key,
+            value: $value,
+            encryptedValue: $encryptedValue,
+            secure: $secure,
+            stage: $stage,
+            revision: $revision,
+            path: $path,
+            vault: $vault,
+            skipValidation: false,
+        );
+    }
+
     public function key()
     {
         return $this->key;
     }
 
+    /**
+     * Get a sanitized version of the key safe for .env files.
+     * Converts non-alphanumeric characters to underscores and ensures valid .env format.
+     */
+    public function sanitizedKey(): string
+    {
+        $sanitized = $this->key;
+        
+        // Replace invalid characters with underscores
+        $sanitized = preg_replace('/[^A-Za-z0-9_]/', '_', $sanitized);
+        
+        // Remove leading underscores
+        $sanitized = ltrim($sanitized, '_');
+        
+        // Remove leading digits by prefixing with 'KEY_'
+        if (preg_match('/^[0-9]/', $sanitized)) {
+            $sanitized = 'KEY_' . $sanitized;
+        }
+        
+        // Handle empty string case
+        if (empty($sanitized)) {
+            $sanitized = 'UNNAMED_KEY';
+        }
+        
+        // Convert to uppercase (common .env convention)
+        return strtoupper($sanitized);
+    }
+
     public function value(): ?string
     {
         return $this->value;
diff --git a/src/Vaults/AwsSecretsManagerVault.php b/src/Vaults/AwsSecretsManagerVault.php
@@ -111,7 +111,7 @@ public function list(): SecretCollection
                         $value = $secretValue->get('SecretString');
                         $isSecure = true; // AWS Secrets Manager always encrypts
 
-                        $secrets->push(new Secret(
+                        $secrets->push(Secret::fromVault(
                             key: $key,
                             value: $value,
                             encryptedValue: null,
@@ -164,7 +164,7 @@ public function get(string $key): Secret
                 throw new SecretNotFoundException("Secret not found [{$this->format($key)}]");
             }
 
-            return new Secret(
+            return Secret::fromVault(
                 key: $key,
                 value: $value,
                 encryptedValue: null,
diff --git a/src/Vaults/AwsSsmVault.php b/src/Vaults/AwsSsmVault.php
@@ -90,7 +90,7 @@ public function list(): SecretCollection
                         ->trim('/')
                         ->toString();
 
-                    $secrets->push(new Secret(
+                    $secrets->push(Secret::fromVault(
                         key: $key,
                         value: $parameter['Value'] ?? null,
                         encryptedValue: null,
@@ -137,7 +137,7 @@ public function get(string $key): Secret
                 throw ExceptionFactory::secretNotFound($key, $this->name());
             }
 
-            return new Secret(
+            return Secret::fromVault(
                 key: $key,
                 value: $parameter['Value'] ?? null,
                 encryptedValue: null,
diff --git a/tests/Support/TestVault.php b/tests/Support/TestVault.php
@@ -72,7 +72,7 @@ public function set(string $key, string $value, bool $secure = true): Secret
         $secrets = $this->getVaultStageSecrets();
         $revision = isset($secrets[$path]) ? $secrets[$path]->revision() + 1 : 1;
 
-        $secret = new Secret($key, $value, null, $secure, $this->stage, $revision, $path, $this);
+        $secret = Secret::fromUser($key, $value, null, $secure, $this->stage, $revision, $path, $this);
         $this->setVaultStageSecret($path, $secret);
 
         // Add to history
diff --git a/tests/Unit/Data/SecretTest.php b/tests/Unit/Data/SecretTest.php
diff --git a/tests/Unit/Data/SecretsCollectionTest.php b/tests/Unit/Data/SecretsCollectionTest.php

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@ public function toKeyValuePair(): static`
`18`	`18`
`19`	`19`	`public function toEnvString()`
`20`	`20`	`{`
`21`		`- return $this->map(fn (Secret $secret) => $secret->key().'='.$this->formatEnvValue($secret->value())`
	`21`	`+ return $this->map(fn (Secret $secret) => $secret->sanitizedKey().'='.$this->formatEnvValue($secret->value())`
`22`	`22`	`)->implode(PHP_EOL);`
`23`	`23`	`}`
`24`	`24`
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@ public function list(): Collection`
`51`	`51`	`public function secrets(): SecretCollection`
`52`	`52`	`{`
`53`	`53`	`$secrets = $this->entries()->map(function ($entry) {`
`54`		`- return new Secret(`
	`54`	`+ return Secret::fromVault(`
`55`	`55`	`key: $entry->getName(),`
`56`	`56`	`value: $entry->getValue()->get()->getChars(),`
`57`	`57`	`);`