Shh Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bentools/shh-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Bentools\ShhBundle\ShhBundle::class => ['all' => true],
   ];
   

2. Configuration: Define secrets in config/packages/shh.yaml:

   shh:
       secrets:
           - name: "DB_PASSWORD"
             path: "%kernel.project_dir%/var/secrets/db_password"
             permissions: 0600
   

3. First Use Case: Inject Shh\SecretManager and retrieve a secret:

   use Bentools\ShhBundle\SecretManager;
   
   public function __construct(private SecretManager $secretManager) {}
   
   public function getDbPassword()
   {
       return $this->secretManager->get('DB_PASSWORD');
   }
   

Implementation Patterns

Core Workflows

1. Secret Retrieval:

   • Use dependency injection for SecretManager in services/controllers.
   • Cache secrets in memory (default behavior) for performance:

     $this->secretManager->get('SECRET_KEY', true); // Force refresh
     

2. Environment Integration:

   • Fallback to .env if file-based secret is missing:

     shh:
         fallback_to_env: true
     

3. Dynamic Secrets:

   • Rotate secrets without redeploying:

     # Update secret file (permissions 600)
     echo "new_password" > var/secrets/db_password
     

4. Validation:

   • Validate secrets during retrieval:

     $this->secretManager->get('API_KEY', validate: true);
     

Advanced Patterns

• Secret Generation:

  $this->secretManager->generate('NEW_SECRET', 32); // 32-character random string
  

• Encrypted Secrets: Use Shh\EncryptedSecretManager for encrypted storage (requires defuse/php-encryption):

  shh:
      encryption_key: "%env(ENCRYPTION_KEY)%"
  

• Custom Storage: Implement SecretStorageInterface for databases/cloud storage:

  class MyStorage implements SecretStorageInterface {
      public function read(string $name): string { ... }
      public function write(string $name, string $value): void { ... }
  }
  

Gotchas and Tips

Pitfalls

1. Permissions:

   • Secrets must be stored with 0600 permissions. Use:

     chmod 600 var/secrets/*
     

   • Debugging: Check var/log/shh.log for permission errors.

2. Caching:

   • Secrets are cached by default. Clear cache after updates:

     php bin/console cache:clear
     

3. Environment Fallback:

   • If fallback_to_env: true, ensure .env secrets are not committed to version control.

4. Symfony Debug Toolbar:

   • Secrets will not leak via phpinfo() or logs, but avoid logging them explicitly:

     // ❌ Avoid
     error_log("Secret: " . $this->secretManager->get('DB_PASSWORD'));
     
     // ✅ Safe
     error_log("Database connected.");
     

Debugging Tips

• Verify Secrets:

  php bin/console debug:shh
  

• Log Level: Set shh.log_level: debug in config for detailed logs.

Extension Points

1. Custom Secret Formats: Override Shh\SecretManager to support JSON/YAML secrets:

   class JsonSecretManager extends SecretManager {
       protected function decode(string $content): string {
           return json_decode($content, true)['secret'];
       }
   }
   

2. Secret Events: Listen for secret updates:

   use Bentools\ShhBundle\Event\SecretUpdatedEvent;
   
   public function onSecretUpdated(SecretUpdatedEvent $event) {
       // Log or trigger actions
   }
   

   Register in services.yaml:

   services:
       App\Listener\SecretListener:
           tags:
               - { name: kernel.event_listener, event: shh.secret_updated, method: onSecretUpdated }
   

3. Multi-Environment Secrets: Use %env(default::SECRET_NAME)% in shh.yaml for environment-specific defaults.

Configuration Quirks

• Path Resolution: Use %kernel.project_dir% for relative paths (e.g., var/secrets/). Absolute paths are supported but less portable.

• Secret Naming: Avoid names conflicting with Symfony’s %env() variables (e.g., APP_ENV).