Vault Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require csharpru/vault-php
   

   Add to config/services.php:

   'vault' => [
       'url' => env('VAULT_ADDR', 'http://127.0.0.1:8200'),
       'token' => env('VAULT_TOKEN'),
       'timeout' => 5.0,
   ],
   

2. First Use Case: Reading a Secret

   use Csharpru\Vault\Client;
   
   $client = new Client(config('services.vault'));
   $secret = $client->read('secret/data/myapp/config');
   echo $secret['data']['data']['api_key'];
   

3. Key Files

   • README.md – Official docs, API reference.
   • src/Client.php – Core class for methods.
   • tests/ – Real-world usage examples.

Implementation Patterns

Common Workflows

1. Dynamic Secret Rotation

   // Fetch and auto-rotate DB credentials
   $client->read('secret/data/db/creds');
   // Later, trigger rotation via KV v2 API
   $client->write('transit/rotate/db-key', ['key' => 'db-key']);
   

2. Policy-Based Access

   // Assign a policy to a token
   $client->write('auth/token/create', [
       'policies' => ['app-policy'],
       'ttl' => '1h',
   ]);
   

3. Environment-Specific Config

   // Load config per environment (dev/staging/prod)
   $env = app()->environment();
   $config = $client->read("secret/data/app/config/{$env}");
   

Integration Tips

• Laravel Service Provider Bind the client to the container for dependency injection:

  $this->app->singleton(Client::class, function ($app) {
      return new Client($app['config']['services.vault']);
  });
  

• Caching Secrets Use Laravel’s cache to avoid repeated Vault calls:

  $secret = Cache::remember('vault_db_creds', now()->addHours(1), function () {
      return $client->read('secret/data/db/creds');
  });
  

• Error Handling Wrap Vault calls in a try-catch for HTTP/token errors:

  try {
      $client->read('secret/nonexistent');
  } catch (\Csharpru\Vault\Exception\VaultException $e) {
      Log::error("Vault error: " . $e->getMessage());
      abort(500);
  }
  

Gotchas and Tips

Pitfalls

1. Token Management

   • Issue: Hardcoded tokens in code violate security best practices.
   • Fix: Use VAULT_TOKEN env vars or dynamic token generation via auth/token/create.

2. KV v1 vs. v2

   • Issue: KV v1 is deprecated; v2 requires explicit path formatting (secret/data/...).
   • Fix: Update paths and enable v2 in Vault:

     vault secrets enable -path=secret -version=2 kv
     

3. Rate Limiting

   • Issue: High-frequency calls may hit Vault’s default rate limits.
   • Fix: Implement exponential backoff or local caching.

4. TLS/HTTPS

   • Issue: Self-signed certs may cause connection failures.
   • Fix: Configure CA certs in the client:

     $client = new Client([
         'url' => 'https://vault.example.com',
         'ca_cert' => file_get_contents('/path/to/ca.crt'),
     ]);
     

Debugging

• Enable Debugging Set the debug option to log HTTP requests:

  $client = new Client([
      'url' => env('VAULT_ADDR'),
      'debug' => true, // Logs requests to storage/logs/vault.log
  ]);
  

• Common Errors

  Error	Cause	Solution
  InvalidResponseException	Malformed Vault response	Check Vault server logs
  ConnectionException	Network issues	Verify VAULT_ADDR and firewall rules
  PermissionDeniedException	Insufficient token permissions	Reassign policies via auth/token/roles

Extension Points

1. Custom Middleware Add request/response filters:

   $client->setMiddleware(function ($request) {
       $request->setHeader('X-Custom-Header', 'value');
   });
   

2. Mocking for Tests Use the MockClient for unit tests:

   $mock = new \Csharpru\Vault\MockClient();
   $mock->setResponse('secret/data/test', ['data' => ['key' => 'value']]);
   

3. Async Operations For long-running jobs (e.g., key rotation), use Laravel Queues:

   dispatch(new RotateVaultKey($client, 'transit/keys/db-key'));