Vapora/docs/setup/secretumvault-integration.md

# SecretumVault Integration

VAPORA integrates with **SecretumVault**, a post-quantum ready secrets management system, for secure credential and API key management across all microservices.

## Overview

SecretumVault provides:
- **Post-quantum cryptography** ready for future-proof security
- **Multi-backend storage** (filesystem, SurrealDB, PostgreSQL, etcd)
- **Fine-grained access control** with Cedar policy engine
- **Secrets server** for centralized credential management
- **CLI tools** for operations and development

## Integration Points

SecretumVault is integrated into these VAPORA services:

| Service | Purpose | Features |
|---------|---------|----------|
| **vapora-backend** | REST API credentials, database secrets, JWT keys | Central secrets management |
| **vapora-agents** | Agent authentication, service credentials | Secure agent-to-service auth |
| **vapora-llm-router** | LLM provider API keys (Claude, OpenAI, Gemini, Ollama) | Cost tracking + credential rotation |

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    VAPORA Services                          │
├─────────────┬──────────────────┬────────────────────────────┤
│ Backend API │ Agent Orchestration │ LLM Router              │
└──────┬──────┴────────┬─────────┴──────────┬─────────────────┘
       │               │                    │
       └───────────────┼────────────────────┘
                       │
                       ▼
         ┌─────────────────────────────┐
         │   SecretumVault Server      │
         ├─────────────────────────────┤
         │ • Credential storage        │
         │ • Policy enforcement        │
         │ • Audit logging             │
         │ • Key rotation              │
         └──────────┬──────────────────┘
                    │
        ┌───────────┴────────────┐
        ▼                        ▼
    Storage Layer          Policy Engine
    (SurrealDB)            (Cedar)
```

## Configuration

### Environment Variables

```bash
# SecretumVault server connection
SECRETUMVAULT_URL=http://secretumvault:3030
SECRETUMVAULT_TOKEN=<identity-token>

# Storage backend
SECRETUMVAULT_STORAGE=surrealdb
SURREAL_URL=ws://surrealdb:8000
SURREAL_DB=secretumvault

# Crypto backend
SECRETUMVAULT_CRYPTO=openssl  # or aws-lc for post-quantum
```

### Cargo Features

SecretumVault is integrated with these features enabled:

```toml
secretumvault = { workspace = true }
# Automatically uses: "server", "surrealdb-storage"
```

## Usage Examples

### In vapora-backend

```rust
use secretumvault::SecretClient;

// Initialize client
let client = SecretClient::new(
    &env::var("SECRETUMVAULT_URL")?,
    &env::var("SECRETUMVAULT_TOKEN")?,
).await?;

// Retrieve API key
let api_key = client.get_secret("llm/claude-api-key").await?;

// Store credential securely
client.store_secret(
    "database/postgres-password",
    &password,
    Some("postgres-creds"),
).await?;
```

### In vapora-llm-router

```rust
use secretumvault::SecretClient;

// Get LLM provider credentials
let openai_key = client.get_secret("llm/openai-api-key").await?;
let claude_key = client.get_secret("llm/claude-api-key").await?;
let gemini_key = client.get_secret("llm/gemini-api-key").await?;

// Fallback to Ollama (local, no key needed)
```

## Running SecretumVault

### Local Development

```bash
# Terminal 1: Start SecretumVault server
cd /Users/Akasha/Development/secretumvault
cargo run --bin secretumvault-server --features server,surrealdb-storage

# Terminal 2: Initialize with default policies
cargo run --bin secretumvault-cli -- init-policies
```

### Production (Kubernetes)

```bash
# Will be added to kubernetes/
kubectl apply -f kubernetes/secretumvault/
```

## Security Best Practices

1. **Token Management**
   - Use identity-based tokens (not basic auth)
   - Rotate tokens regularly
   - Store token in `.env.local` (not in git)

2. **Secret Storage**
   - Never commit credentials to git
   - Use SecretumVault for all sensitive data
   - Enable audit logging for compliance

3. **Policy Enforcement**
   - Define Cedar policies per role/service
   - Restrict access by principle of least privilege
   - Review policies during security audits

4. **Crypto Backend**
   - Use `aws-lc` for post-quantum readiness
   - Plan migration as quantum threats evolve

## Related Documentation

- [SecretumVault Project](../../../../secretumvault/)
- [VAPORA Architecture](vapora-architecture.md)
- [Security & RBAC](../architecture/roles-permissions-profiles.md)

---

**Integration Status**: ✅ Active
**Services**: Backend, Agents, LLM Router
**Features**: server, surrealdb-storage, cedar-policies