vectra-client 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a0a1971b5aaa4e71cce684542a9baa8b5c43a47b5e9faa8231bb3dbf5ebe2d1
-  data.tar.gz: d80c394c3cfbc4b94e42e649c26333238feb0e946570e6cb918c13c73d491d37
+  metadata.gz: 2d3586fe349f6746ba939c2596bf5b1110551a8e7ed16a8dc6581eaa2f91af81
+  data.tar.gz: 11d141983fba57e97fc0d96792f75e8e2e50eac453671ddb25ce8456002acac2
 SHA512:
-  metadata.gz: e422697e86cd942b25d49b88a15254789754dea5646fe5407989c4915f4bb4fc3f36a84f19d38a2409bf684c7ce67bde02d012590e909cb980777e35beabf1c1
-  data.tar.gz: 5ef94bacfffe1ce6f67faeaa92febf739b498a14675661612058104dc7d1119e59dc0284a1c32338b08cd73c8cc4aac63e0be249c8250e9d78699dd45eb93b3d
+  metadata.gz: 6396f52e61633d9b2eed5502edbc80f8c001d85aea638afad4ff5c377e7d141ca80dd6198ace23808324411355924b2e653aa661e157fa4ae33c0b905bf31e4d
+  data.tar.gz: 1581ca62c63111caaf6fc26ced7503a101ceb30c8a0531b3fa454a0ac10376446f5a358dfbb29f045de9ba799114803af02b6a021828debc8df14cab129a5147

data/CHANGELOG.md

@@ -43,7 +43,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Thread-safe implementation
   - Configurable failure/success thresholds
 
-## [0.3.0] - 2025-01-08
+- **Credential Rotation** (`Vectra::CredentialRotator`)
+  - Zero-downtime API key rotation
+  - Pre-rotation validation
+  - Rollback support
+  - Multi-provider rotation manager
+  - Per-provider rotation tracking
+
+- **Audit Logging** (`Vectra::AuditLog`)
+  - Structured audit events for compliance
+  - Access, authentication, authorization logging
+  - Configuration change tracking
+  - Credential rotation audit trail
+  - Automatic API key sanitization
+  - Global audit logging support
+
+## [v0.3.2](https://github.com/stokry/vectra/tree/v0.3.2) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.3.1...v0.3.2)
+
+### Fixed
+
+- Audit log keyword parameter ordering and optional fields now align with linting and usage expectations.
+- Credential rotation utilities use symbol procs and string interpolation while keeping the existing `switch_to_secondary` API.
+
+## [v0.3.1](https://github.com/stokry/vectra/tree/v0.3.1) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.3.0...v0.3.1)
+
+## [v0.3.0](https://github.com/stokry/vectra/tree/v0.3.0) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.2.2...v0.3.0)
 
 ### Added
 
@@ -88,7 +118,13 @@ New configuration options:
 
 - Added `concurrent-ruby ~> 1.2` for thread-safe operations
 
-## [0.2.1] - 2025-01-08
+## [v0.2.2](https://github.com/stokry/vectra/tree/v0.2.2) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.2.1...v0.2.2)
+
+## [v0.2.1](https://github.com/stokry/vectra/tree/v0.2.1) (2026-01-08)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.2.0...v0.2.1)
 
 ### Added
 
@@ -113,9 +149,11 @@ New configuration options:
 - ✅ Pinecone - Fully implemented
 - ✅ pgvector (PostgreSQL) - Fully implemented
 - ✅ Qdrant - Fully implemented
-- 🚧 Weaviate - Stub implementation (planned for v0.3.0)
+- 🚧 Weaviate - Stub implementation (planned for v0.4.0)
+
+## [v0.2.0](https://github.com/stokry/vectra/tree/v0.2.0) (2026-01-08)
 
-## [0.2.0] - 2025-01-08
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.1.3...v0.2.0)
 
 ### Added
 
@@ -138,7 +176,13 @@ New configuration options:
 - Added IMPLEMENTATION_GUIDE.md for developers implementing new features
 - Added NEW_FEATURES_v0.2.0.md with migration guide
 
-## [0.1.1] - 2025-01-07
+## [v0.1.3](https://github.com/stokry/vectra/tree/v0.1.3) (2026-01-07)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/v0.1.1...v0.1.3)
+
+## [v0.1.1](https://github.com/stokry/vectra/tree/v0.1.1) (2026-01-07)
+
+[Full Changelog](https://github.com/stokry/vectra/compare/0ab2ea7b42d7fbf0b540b24889cc2b24254fef2e...v0.1.1)
 
 ### Added
 
@@ -157,37 +201,6 @@ New configuration options:
 - Updated gemspec description to include pgvector
 - Added `pg` gem as development dependency
 
-## [0.1.0] - 2024-XX-XX
-
-### Added
-
-- Initial release
-- Pinecone provider with full support for:
-  - Vector upsert, query, fetch, update, delete operations
-  - Index management (list, describe, create, delete)
-  - Namespace support
-  - Metadata filtering
-- Configuration system with global and per-client options
-- Automatic retry logic with exponential backoff
-- Comprehensive error handling with specific error classes:
-  - `AuthenticationError` - API key issues
-  - `RateLimitError` - Rate limiting with retry-after
-  - `NotFoundError` - Resource not found
-  - `ValidationError` - Invalid request parameters
-  - `ServerError` - Server-side errors
-  - `ConnectionError` - Network issues
-  - `TimeoutError` - Request timeouts
-- `Vector` class for vector representation with:
-  - Cosine similarity calculation
-  - Euclidean distance calculation
-  - Metadata support
-- `QueryResult` class with Enumerable support:
-  - Score filtering
-  - Easy iteration
-  - Result statistics
-- Full RSpec test suite
-- YARD documentation
-
 ## Planned
 
 ### [0.4.0]
@@ -200,4 +213,4 @@ New configuration options:
 
 - Background job integration (Sidekiq, GoodJob)
 - Production-ready with full documentation
-- Performance monitoring dashboard
+- Performance monitoring dashboard

data/SECURITY.md

@@ -46,30 +46,100 @@ We will:
 
 ### API Key Management
 
+**CRITICAL: Always use environment variables or secure vaults for API keys.**
+
 - **Never commit API keys** to version control
-- Store API keys in environment variables or secure vaults
+- Store API keys in environment variables or secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.)
 - Use different API keys for development, staging, and production
-- Rotate API keys regularly
+- Rotate API keys regularly (every 90 days recommended)
 - Limit API key permissions to minimum required access
+- Monitor API key usage for anomalies
 
 ```ruby
 # ✅ Good - Use environment variables
 Vectra.configure do |config|
-  config.api_key = ENV['PINECONE_API_KEY']
+  config.provider = :pinecone
+  config.api_key = ENV['PINECONE_API_KEY']  # Set in environment
+  config.environment = ENV['PINECONE_ENVIRONMENT'] || 'us-east-1'
+end
+
+# ✅ Good - Use Rails credentials (encrypted)
+Vectra.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:pinecone, :api_key)
+end
+
+# ✅ Good - Use AWS Secrets Manager
+require 'aws-sdk-secretsmanager'
+secrets = Aws::SecretsManager::Client.new
+secret = JSON.parse(secrets.get_secret_value(secret_id: 'vectra/pinecone').secret_string)
+
+Vectra.configure do |config|
+  config.api_key = secret['api_key']
 end
 
 # ❌ Bad - Hardcoded API key
 Vectra.configure do |config|
-  config.api_key = "pk-123456789"  # Never do this!
+  config.api_key = "pk-123456789"  # NEVER DO THIS!
 end
+
+# ❌ Bad - API key in config file
+# config/vectra.yml
+# api_key: "pk-123456789"  # This will be committed to git!
+```
+
+### Credential Rotation
+
+Use built-in credential rotation helpers for zero-downtime key rotation:
+
+```ruby
+require 'vectra/credential_rotation'
+
+# Setup rotation
+rotator = Vectra::CredentialRotator.new(
+  primary_key: ENV['PINECONE_API_KEY'],
+  secondary_key: ENV['PINECONE_API_KEY_NEW'],
+  provider: :pinecone
+)
+
+# Test new key before switching
+if rotator.test_secondary
+  rotator.switch_to_secondary
+  puts "Rotation complete!"
+else
+  puts "New key validation failed - keeping primary"
+end
+
+# Rollback if needed
+rotator.rollback
 ```
 
+**Rotation Best Practices:**
+
+1. **Test new credentials** before switching
+2. **Monitor for errors** after rotation
+3. **Keep old key active** for 24-48 hours after rotation
+4. **Rotate during low-traffic periods** when possible
+5. **Use gradual migration** for high-traffic systems
+
 ### Network Security
 
 - Always use HTTPS for API connections (enforced by default)
 - Verify SSL certificates (enabled by default)
 - Use VPN or private networks when possible
 - Monitor API usage for unusual patterns
+- **mTLS Support**: For providers that support mutual TLS, configure client certificates
+
+```ruby
+# mTLS configuration (provider-specific)
+# Note: mTLS support depends on provider capabilities
+# For pgvector, use SSL connection parameters:
+Vectra.configure do |config|
+  config.provider = :pgvector
+  config.host = "postgresql://user:pass@host/db?sslmode=verify-full&sslcert=/path/to/client.crt&sslkey=/path/to/client.key"
+end
+
+# For cloud providers, check provider documentation for mTLS setup
+```
 
 ### Data Security
 
@@ -137,6 +207,7 @@ end
 - Monitor for authentication failures
 - Track unusual query patterns
 - Set up alerts for rate limit violations
+- **Enable audit logging** for compliance requirements
 
 ```ruby
 # ❌ Bad - Logs API key
@@ -144,8 +215,67 @@ logger.info("Using API key: #{config.api_key}")
 
 # ✅ Good - Logs without sensitive data
 logger.info("Initializing Vectra client for #{config.provider}")
+
+# ✅ Good - Use audit logging for security events
+require 'vectra/audit_log'
+
+audit = Vectra::AuditLog.new(output: "log/audit.json.log")
+
+# Log access events
+audit.log_access(
+  user_id: current_user.id,
+  operation: "query",
+  index: "sensitive-data",
+  result_count: 10
+)
+
+# Log authentication events
+audit.log_authentication(
+  user_id: user.id,
+  success: true,
+  provider: "pinecone"
+)
+
+# Log credential rotations
+audit.log_credential_rotation(
+  provider: "pinecone",
+  success: true,
+  rotated_by: admin_user.id
+)
+```
+
+### Audit Logging
+
+For compliance and security auditing:
+
+```ruby
+# Setup global audit logging
+Vectra::AuditLogging.setup!(
+  output: "log/audit.json.log",
+  app: "my-service",
+  env: Rails.env
+)
+
+# Automatic audit logging for operations
+Vectra::Instrumentation.on_operation do |event|
+  Vectra::AuditLogging.log(:access,
+    user_id: current_user&.id,
+    operation: event.operation,
+    index: event.index,
+    success: event.success?
+  )
+end
 ```
 
+**Audit Log Events:**
+- `access` - Data access operations
+- `authentication` - Auth success/failure
+- `authorization` - Permission checks
+- `configuration_change` - Config modifications
+- `credential_rotation` - Key rotations
+- `data_modification` - Upsert/delete/update
+- `error` - Security-relevant errors
+
 ## Known Security Considerations
 
 ### API Key Exposure

data/docs/_layouts/page.html

@@ -36,6 +36,7 @@
           <li><a href="{{ site.baseurl }}/guides/getting-started" class="tma-sidebar__link {% if page.url == '/guides/getting-started/' %}tma-sidebar__link--active{% endif %}">Quick Start</a></li>
           <li><a href="{{ site.baseurl }}/guides/performance" class="tma-sidebar__link {% if page.url == '/guides/performance/' %}tma-sidebar__link--active{% endif %}">Performance</a></li>
           <li><a href="{{ site.baseurl }}/guides/monitoring" class="tma-sidebar__link {% if page.url == '/guides/monitoring/' %}tma-sidebar__link--active{% endif %}">Monitoring</a></li>
+          <li><a href="{{ site.baseurl }}/guides/security" class="tma-sidebar__link {% if page.url == '/guides/security/' %}tma-sidebar__link--active{% endif %}">Security</a></li>
         </ul>
       </div>
 

data/docs/guides/security.md

@@ -0,0 +1,348 @@
+---
+layout: page
+title: Security Best Practices
+permalink: /guides/security/
+---
+
+# Security Best Practices
+
+Complete guide for securing Vectra in production environments.
+
+## API Key Management
+
+### Environment Variables (Recommended)
+
+**Always use environment variables for API keys:**
+
+```ruby
+# ✅ Good
+Vectra.configure do |config|
+  config.provider = :pinecone
+  config.api_key = ENV['PINECONE_API_KEY']  # Set in .env or system env
+  config.environment = ENV['PINECONE_ENVIRONMENT'] || 'us-east-1'
+end
+```
+
+```bash
+# Set in environment
+export PINECONE_API_KEY="your-key-here"
+export PINECONE_ENVIRONMENT="us-east-1"
+```
+
+### Rails Credentials (Encrypted)
+
+```ruby
+# ✅ Good - Rails encrypted credentials
+Vectra.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:pinecone, :api_key)
+end
+```
+
+```bash
+# Edit credentials
+rails credentials:edit
+
+# Add to credentials.yml.enc:
+# pinecone:
+#   api_key: your-key-here
+```
+
+### Secret Management Services
+
+```ruby
+# ✅ Good - AWS Secrets Manager
+require 'aws-sdk-secretsmanager'
+
+secrets = Aws::SecretsManager::Client.new
+secret = JSON.parse(
+  secrets.get_secret_value(secret_id: 'vectra/pinecone').secret_string
+)
+
+Vectra.configure do |config|
+  config.api_key = secret['api_key']
+end
+```
+
+```ruby
+# ✅ Good - HashiCorp Vault
+require 'vault'
+
+Vault.auth.aws
+secret = Vault.logical.read("secret/vectra/pinecone")
+
+Vectra.configure do |config|
+  config.api_key = secret.data[:api_key]
+end
+```
+
+### What NOT to Do
+
+```ruby
+# ❌ NEVER hardcode API keys
+Vectra.configure do |config|
+  config.api_key = "pk-123456789"  # This will be committed to git!
+end
+
+# ❌ NEVER store in config files
+# config/vectra.yml
+# api_key: "pk-123456789"  # This will be committed!
+
+# ❌ NEVER log API keys
+logger.info("API key: #{config.api_key}")  # Will appear in logs!
+```
+
+## Credential Rotation
+
+Use built-in credential rotation for zero-downtime key updates:
+
+```ruby
+require 'vectra/credential_rotation'
+
+# Setup rotation
+rotator = Vectra::CredentialRotator.new(
+  primary_key: ENV['PINECONE_API_KEY'],
+  secondary_key: ENV['PINECONE_API_KEY_NEW'],
+  provider: :pinecone
+)
+
+# Test new key before switching
+if rotator.test_secondary
+  rotator.switch_to_secondary
+  puts "✅ Rotation complete"
+else
+  puts "❌ New key validation failed - keeping primary"
+end
+
+# Rollback if issues occur
+rotator.rollback
+```
+
+### Multi-Provider Rotation
+
+```ruby
+# Register multiple providers
+Vectra::CredentialRotationManager.register(:pinecone,
+  primary: ENV['PINECONE_API_KEY'],
+  secondary: ENV['PINECONE_API_KEY_NEW']
+)
+
+Vectra::CredentialRotationManager.register(:qdrant,
+  primary: ENV['QDRANT_API_KEY'],
+  secondary: ENV['QDRANT_API_KEY_NEW']
+)
+
+# Test all new keys
+results = Vectra::CredentialRotationManager.test_all_secondary
+# => { pinecone: true, qdrant: false }
+
+# Rotate all if tests pass
+if results.values.all?
+  Vectra::CredentialRotationManager.rotate_all
+end
+
+# Check rotation status
+Vectra::CredentialRotationManager.status
+```
+
+### Rotation Best Practices
+
+1. **Test before switching** - Always validate new credentials
+2. **Monitor after rotation** - Watch for errors for 24-48 hours
+3. **Keep old key active** - Don't revoke immediately
+4. **Rotate during low traffic** - Minimize impact
+5. **Use gradual migration** - For high-traffic systems
+
+## Audit Logging
+
+Enable audit logging for compliance and security monitoring:
+
+```ruby
+require 'vectra/audit_log'
+
+# Setup audit logging
+audit = Vectra::AuditLog.new(
+  output: "log/audit.json.log",
+  app: "my-service",
+  env: Rails.env
+)
+
+# Log access events
+audit.log_access(
+  user_id: current_user.id,
+  operation: "query",
+  index: "sensitive-data",
+  result_count: 10
+)
+
+# Log authentication
+audit.log_authentication(
+  user_id: user.id,
+  success: true,
+  provider: "pinecone"
+)
+
+# Log credential rotations
+audit.log_credential_rotation(
+  provider: "pinecone",
+  success: true,
+  rotated_by: admin_user.id
+)
+
+# Log data modifications
+audit.log_data_modification(
+  user_id: user.id,
+  operation: "upsert",
+  index: "vectors",
+  record_count: 100
+)
+```
+
+### Global Audit Logging
+
+```ruby
+# Setup once in initializer
+Vectra::AuditLogging.setup!(
+  output: "log/audit.json.log",
+  app: "my-service"
+)
+
+# Use anywhere
+Vectra::AuditLogging.log(:access,
+  user_id: current_user.id,
+  operation: "query",
+  index: "data"
+)
+```
+
+### Audit Log Format
+
+```json
+{
+  "timestamp": "2025-01-08T12:00:00.123Z",
+  "level": "info",
+  "logger": "vectra",
+  "message": "audit.access",
+  "event_type": "access",
+  "user_id": "user123",
+  "operation": "query",
+  "resource": "my-index",
+  "result_count": 10
+}
+```
+
+## Network Security
+
+### HTTPS/TLS
+
+- **Always use HTTPS** - Enforced by default
+- **Verify certificates** - Enabled by default
+- **Use VPN/private networks** when possible
+
+### mTLS (Mutual TLS)
+
+For providers supporting mutual TLS authentication:
+
+```ruby
+# pgvector with client certificates
+Vectra.configure do |config|
+  config.provider = :pgvector
+  config.host = "postgresql://user:pass@host/db?" \
+                 "sslmode=verify-full&" \
+                 "sslcert=/path/to/client.crt&" \
+                 "sslkey=/path/to/client.key&" \
+                 "sslrootcert=/path/to/ca.crt"
+end
+```
+
+**Note:** mTLS support depends on provider capabilities. Check provider documentation.
+
+## Data Security
+
+### Input Sanitization
+
+```ruby
+# Sanitize metadata before upsert
+def sanitize_metadata(metadata)
+  metadata.reject { |k, _| k.to_s.match?(/password|secret|token|ssn|credit_card/i) }
+end
+
+vectors = [{
+  id: "vec1",
+  values: embedding,
+  metadata: sanitize_metadata(user_data)
+}]
+
+client.upsert(index: "my-index", vectors: vectors)
+```
+
+### Access Control
+
+```ruby
+# Implement application-level access control
+class VectorService
+  def query(user:, index:, vector:, top_k:)
+    # Check permissions
+    unless user.can_access?(index)
+      audit.log_authorization(
+        user_id: user.id,
+        resource: index,
+        allowed: false,
+        reason: "Insufficient permissions"
+      )
+      raise ForbiddenError, "Access denied"
+    end
+
+    # Log access
+    audit.log_access(
+      user_id: user.id,
+      operation: "query",
+      index: index,
+      result_count: top_k
+    )
+
+    client.query(index: index, vector: vector, top_k: top_k)
+  end
+end
+```
+
+## Compliance
+
+### GDPR/Privacy
+
+- **Data retention policies** - Implement automatic deletion
+- **Right to deletion** - Support user data removal
+- **Data encryption** - Encrypt sensitive metadata
+- **Access logs** - Maintain audit trails
+
+### HIPAA/Healthcare
+
+- **Encryption at rest** - Provider responsibility
+- **Encryption in transit** - HTTPS enforced
+- **Access controls** - Application-level
+- **Audit logging** - Required for compliance
+
+### PCI-DSS
+
+- **No card data in vectors** - Never store card numbers
+- **Tokenization** - Use tokens instead of raw data
+- **Access monitoring** - Audit all access
+
+## Security Checklist
+
+- [ ] API keys stored in environment variables or vaults
+- [ ] No API keys in version control
+- [ ] Different keys for dev/staging/production
+- [ ] Credential rotation implemented
+- [ ] Audit logging enabled
+- [ ] HTTPS/TLS enforced
+- [ ] Input sanitization implemented
+- [ ] Access controls in place
+- [ ] Rate limiting configured
+- [ ] Error monitoring setup
+- [ ] Security alerts configured
+
+## Related
+
+- [SECURITY.md](https://github.com/stokry/vectra/blob/main/SECURITY.md) - Security policy
+- [Monitoring Guide]({{ site.baseurl }}/guides/monitoring) - Security monitoring
+- [Performance Guide]({{ site.baseurl }}/guides/performance) - Rate limiting

data/lib/vectra/audit_log.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Audit logging for security and compliance
+  #
+  # Provides structured audit logs for security-sensitive operations,
+  # including authentication, authorization, and data access.
+  #
+  # @example Basic usage
+  #   audit = Vectra::AuditLog.new(output: "log/audit.json.log")
+  #
+  #   audit.log_access(
+  #     user_id: "user123",
+  #     operation: "query",
+  #     index: "sensitive-data",
+  #     result_count: 10
+  #   )
+  #
+  class AuditLog
+    # Audit event types
+    EVENT_TYPES = %i[
+      access
+      authentication
+      authorization
+      configuration_change
+      credential_rotation
+      data_modification
+      error
+    ].freeze
+
+    attr_reader :logger, :enabled
+
+    # Initialize audit logger
+    #
+    # @param output [IO, String] Log output destination
+    # @param enabled [Boolean] Enable/disable audit logging
+    # @param metadata [Hash] Default metadata for all events
+    def initialize(output: $stdout, enabled: true, **metadata)
+      @enabled = enabled
+      @logger = enabled ? Vectra::JsonLogger.new(output, **metadata) : nil
+    end
+
+    # Log access event
+    #
+    # @param user_id [String, nil] User identifier
+    # @param operation [Symbol, String] Operation type
+    # @param index [String] Index accessed
+    # @param result_count [Integer, nil] Number of results
+    # @param metadata [Hash] Additional metadata
+    def log_access(operation:, index: nil, result_count: nil, user_id: nil, **metadata)
+      log_event(
+        type: :access,
+        user_id: user_id,
+        operation: operation.to_s,
+        resource: index,
+        result_count: result_count,
+        **metadata
+      )
+    end
+
+    # Log authentication event
+    #
+    # @param user_id [String, nil] User identifier
+    # @param success [Boolean] Authentication success
+    # @param provider [String, nil] Provider name
+    # @param metadata [Hash] Additional metadata
+    def log_authentication(success:, provider: nil, user_id: nil, **metadata)
+      log_event(
+        type: :authentication,
+        user_id: user_id,
+        success: success,
+        provider: provider,
+        **metadata
+      )
+    end
+
+    # Log authorization event
+    #
+    # @param user_id [String] User identifier
+    # @param resource [String] Resource accessed
+    # @param allowed [Boolean] Authorization result
+    # @param reason [String, nil] Reason if denied
+    def log_authorization(user_id:, resource:, allowed:, reason: nil)
+      log_event(
+        type: :authorization,
+        user_id: user_id,
+        resource: resource,
+        allowed: allowed,
+        reason: reason
+      )
+    end
+
+    # Log configuration change
+    #
+    # @param user_id [String] User who made change
+    # @param change_type [String] Type of change
+    # @param old_value [Object, nil] Previous value
+    # @param new_value [Object, nil] New value
+    def log_configuration_change(user_id:, change_type:, old_value: nil, new_value: nil)
+      log_event(
+        type: :configuration_change,
+        user_id: user_id,
+        change_type: change_type,
+        old_value: sanitize_value(old_value),
+        new_value: sanitize_value(new_value)
+      )
+    end
+
+    # Log credential rotation
+    #
+    # @param provider [String] Provider name
+    # @param success [Boolean] Rotation success
+    # @param rotated_by [String, nil] User who initiated rotation
+    def log_credential_rotation(provider:, success:, rotated_by: nil)
+      log_event(
+        type: :credential_rotation,
+        provider: provider,
+        success: success,
+        rotated_by: rotated_by
+      )
+    end
+
+    # Log data modification
+    #
+    # @param user_id [String, nil] User identifier
+    # @param operation [String] Operation (upsert, delete, update)
+    # @param index [String] Index modified
+    # @param record_count [Integer] Number of records affected
+    def log_data_modification(operation:, index:, record_count:, user_id: nil)
+      log_event(
+        type: :data_modification,
+        user_id: user_id,
+        operation: operation.to_s,
+        resource: index,
+        record_count: record_count
+      )
+    end
+
+    # Log error event
+    #
+    # @param error [Exception] Error that occurred
+    # @param context [Hash] Error context
+    def log_error(error:, **context)
+      log_event(
+        type: :error,
+        error_class: error.class.name,
+        error_message: error.message,
+        severity: error_severity(error),
+        **context
+      )
+    end
+
+    private
+
+    def log_event(type:, **data)
+      return unless @enabled && @logger
+
+      @logger.info(
+        "audit.#{type}",
+        event_type: type.to_s,
+        timestamp: Time.now.utc.iso8601(3),
+        **data
+      )
+    end
+
+    def sanitize_value(value)
+      case value
+      when String
+        # Mask sensitive values: keep a short prefix and suffix, hide the middle
+        return value unless value.length >= 10
+
+        prefix = value[0, 9]
+        suffix = value[-4, 4]
+        "#{prefix}...#{suffix}"
+      when Hash
+        value.transform_values { |v| sanitize_value(v) }
+      else
+        value
+      end
+    end
+
+    def error_severity(error)
+      case error
+      when Vectra::AuthenticationError
+        "critical"
+      when Vectra::ServerError, Vectra::ConnectionError
+        "high"
+      when Vectra::RateLimitError
+        "medium"
+      else
+        "low"
+      end
+    end
+  end
+
+  # Global audit log instance
+  module AuditLogging
+    class << self
+      attr_accessor :audit_log
+
+      # Setup global audit logging
+      #
+      # @param output [IO, String] Log output
+      # @param enabled [Boolean] Enable audit logging
+      # @param metadata [Hash] Default metadata
+      # @return [AuditLog]
+      def setup!(output: "log/audit.json.log", enabled: true, **metadata)
+        @audit_log = AuditLog.new(output: output, enabled: enabled, **metadata)
+      end
+
+      # Log audit event
+      #
+      # @param type [Symbol] Event type
+      # @param data [Hash] Event data
+      def log(type, **data)
+        return unless @audit_log
+
+        @audit_log.public_send("log_#{type}", **data)
+      rescue NoMethodError
+        # Event type not supported
+        @audit_log.instance_variable_get(:@logger)&.info("audit.#{type}", **data)
+      end
+    end
+  end
+end

data/lib/vectra/credential_rotation.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Credential rotation helper for seamless API key updates
+  #
+  # Provides utilities for rotating API keys without downtime by supporting
+  # multiple credentials and gradual migration.
+  #
+  # @example Basic rotation
+  #   rotator = Vectra::CredentialRotator.new(
+  #     primary_key: ENV['PINECONE_API_KEY'],
+  #     secondary_key: ENV['PINECONE_API_KEY_NEW']
+  #   )
+  #
+  #   # Test new key before switching
+  #   if rotator.test_secondary
+  #     rotator.switch_to_secondary
+  #   end
+  #
+  class CredentialRotator
+    attr_reader :primary_key, :secondary_key, :current_key
+
+    # Initialize credential rotator
+    #
+    # @param primary_key [String] Current active API key
+    # @param secondary_key [String, nil] New API key to rotate to
+    # @param provider [Symbol] Provider name
+    # @param test_client [Client, nil] Client instance for testing
+    def initialize(primary_key:, secondary_key: nil, provider: nil, test_client: nil)
+      @primary_key = primary_key
+      @secondary_key = secondary_key
+      @provider = provider
+      @test_client = test_client
+      @current_key = primary_key
+      @rotation_complete = false
+    end
+
+    # Test if secondary key is valid
+    #
+    # @param timeout [Float] Test timeout in seconds
+    # @return [Boolean] true if secondary key works
+    def test_secondary(timeout: 5)
+      return false if secondary_key.nil? || secondary_key.empty?
+
+      client = build_test_client(secondary_key)
+      client.healthy?(timeout: timeout)
+    rescue StandardError
+      false
+    end
+
+    # Switch to secondary key
+    #
+    # @param validate [Boolean] Validate key before switching
+    # @return [Boolean] true if switched successfully
+    # rubocop:disable Naming/PredicateMethod
+    def switch_to_secondary(validate: true)
+      return false if secondary_key.nil? || secondary_key.empty?
+
+      if validate && !test_secondary
+        raise CredentialRotationError, "Secondary key validation failed"
+      end
+
+      @current_key = secondary_key
+      @rotation_complete = true
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
+    # Rollback to primary key
+    #
+    # @return [void]
+    def rollback
+      @current_key = primary_key
+      @rotation_complete = false
+    end
+
+    # Check if rotation is complete
+    #
+    # @return [Boolean]
+    def rotation_complete?
+      @rotation_complete
+    end
+
+    # Get current active key
+    #
+    # @return [String]
+    def active_key
+      @current_key
+    end
+
+    private
+
+    def build_test_client(key)
+      return @test_client if @test_client
+
+      config = Vectra::Configuration.new
+      config.provider = @provider || Vectra.configuration.provider
+      config.api_key = key
+      config.host = Vectra.configuration.host
+      config.environment = Vectra.configuration.environment
+
+      Vectra::Client.new(
+        provider: config.provider,
+        api_key: key,
+        host: config.host,
+        environment: config.environment
+      )
+    end
+  end
+
+  # Error raised during credential rotation
+  class CredentialRotationError < Vectra::Error; end
+
+  # Credential rotation manager for multiple providers
+  #
+  # @example
+  #   manager = Vectra::CredentialRotationManager.new
+  #
+  #   manager.register(:pinecone,
+  #     primary: ENV['PINECONE_API_KEY'],
+  #     secondary: ENV['PINECONE_API_KEY_NEW']
+  #   )
+  #
+  #   manager.rotate_all
+  #
+  module CredentialRotationManager
+    class << self
+      # Register a credential rotator
+      #
+      # @param provider [Symbol] Provider name
+      # @param primary [String] Primary API key
+      # @param secondary [String, nil] Secondary API key
+      # @return [CredentialRotator]
+      def register(provider, primary:, secondary: nil)
+        rotators[provider] = CredentialRotator.new(
+          primary_key: primary,
+          secondary_key: secondary,
+          provider: provider
+        )
+      end
+
+      # Get rotator for provider
+      #
+      # @param provider [Symbol] Provider name
+      # @return [CredentialRotator, nil]
+      def [](provider)
+        rotators[provider.to_sym]
+      end
+
+      # Test all secondary keys
+      #
+      # @return [Hash<Symbol, Boolean>] Test results
+      def test_all_secondary
+        rotators.transform_values(&:test_secondary)
+      end
+
+      # Rotate all providers
+      #
+      # @param validate [Boolean] Validate before rotating
+      # @return [Hash<Symbol, Boolean>] Rotation results
+      def rotate_all(validate: true)
+        rotators.transform_values { |r| r.switch_to_secondary(validate: validate) }
+      end
+
+      # Rollback all rotations
+      #
+      # @return [void]
+      def rollback_all
+        rotators.each_value(&:rollback)
+      end
+
+      # Get rotation status
+      #
+      # @return [Hash<Symbol, Hash>]
+      def status
+        rotators.transform_values do |r|
+          {
+            rotation_complete: r.rotation_complete?,
+            has_secondary: !r.secondary_key.nil?,
+            active_key: "#{r.active_key[0, 8]}..." # First 8 chars only
+          }
+        end
+      end
+
+      # Clear all rotators
+      #
+      # @return [void]
+      def clear!
+        @rotators = {}
+      end
+
+      private
+
+      def rotators
+        @rotators ||= {}
+      end
+    end
+  end
+end

data/lib/vectra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectra
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/lib/vectra.rb

@@ -15,6 +15,8 @@ require_relative "vectra/circuit_breaker"
 require_relative "vectra/rate_limiter"
 require_relative "vectra/logging"
 require_relative "vectra/health_check"
+require_relative "vectra/credential_rotation"
+require_relative "vectra/audit_log"
 require_relative "vectra/active_record"
 require_relative "vectra/providers/base"
 require_relative "vectra/providers/pinecone"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Mijo Kristo
@@ -264,6 +264,7 @@ files:
 - docs/guides/runbooks/high-error-rate.md
 - docs/guides/runbooks/high-latency.md
 - docs/guides/runbooks/pool-exhausted.md
+- docs/guides/security.md
 - docs/index.md
 - docs/providers/index.md
 - docs/providers/pgvector.md
@@ -277,11 +278,13 @@ files:
 - lib/generators/vectra/templates/vectra.rb
 - lib/vectra.rb
 - lib/vectra/active_record.rb
+- lib/vectra/audit_log.rb
 - lib/vectra/batch.rb
 - lib/vectra/cache.rb
 - lib/vectra/circuit_breaker.rb
 - lib/vectra/client.rb
 - lib/vectra/configuration.rb
+- lib/vectra/credential_rotation.rb
 - lib/vectra/errors.rb
 - lib/vectra/health_check.rb
 - lib/vectra/instrumentation.rb