Vapora/docs/adrs/0011-secretumvault.md

# ADR-011: SecretumVault para Secrets Management

**Status**: Accepted | Implemented
**Date**: 2024-11-01
**Deciders**: Security Architecture Team
**Technical Story**: Securing API keys and credentials with post-quantum cryptography

---

## Decision

Usar **SecretumVault** para gestión de secrets con criptografía post-quantum (no HashiCorp Vault, no plain K8s secrets).

---

## Rationale

1. **Post-Quantum Cryptography**: Protege contra ataques futuros con quantum computers
2. **Rust-Native**: Sin dependencias externas, compila a binario standalone
3. **API Key Security**: Encriptación at-rest para LLM API keys
4. **Audit Logging**: Todas las operaciones de secretos registradas
5. **Future-Proof**: Prepara a VAPORA para amenazas de seguridad del futuro

---

## Alternatives Considered

### ❌ HashiCorp Vault
- **Pros**: Maduro, enterprise-grade
- **Cons**: Externa dependencia, operacional overhead, no post-quantum

### ❌ Kubernetes Secrets
- **Pros**: Built-in, simple
- **Cons**: Almacenamiento by default sin encripción, no audit logging

### ✅ SecretumVault (CHOSEN)
- Post-quantum cryptography, Rust-native, audit-friendly

---

## Trade-offs

**Pros**:
- ✅ Post-quantum resistance for future threats
- ✅ Built-in audit logging of secret access
- ✅ Rust-native (no external dependencies)
- ✅ Encryption at-rest for API keys
- ✅ Fine-grained access control

**Cons**:
- ⚠️ Smaller community than HashiCorp Vault
- ⚠️ Fewer integrations with external tools
- ⚠️ Post-quantum crypto adds computational overhead

---

## Implementation

**Secret Storage**:
```rust
// crates/vapora-backend/src/secrets.rs
use secretumvault::SecretStore;

let secret_store = SecretStore::new()?;

// Store API key with encryption
secret_store.store_secret(
    "anthropic_api_key",
    "sk-ant-...",
    SecretMetadata {
        encrypted: true,
        pq_algorithm: "ML-KEM-768",  // Post-quantum algorithm
        owner: "llm-router",
        created_at: Utc::now(),
    }
)?;
```

**Secret Retrieval**:
```rust
// Retrieve and decrypt
let api_key = secret_store
    .get_secret("anthropic_api_key")?
    .decrypt()
    .audit_log("anthropic_api_key_access", &user_id)?;
```

**Audit Log**:
```rust
// All secret operations logged
secret_store.audit_log().query()
    .secret("anthropic_api_key")
    .since(Duration::days(1))
    .await?
    // Returns: Who accessed what secret when
```

**Configuration**:
```toml
# config/secrets.toml
[secretumvault]
store_path = "/etc/vapora/secrets.db"
pq_algorithm = "ML-KEM-768"  # Post-quantum
rotation_days = 90
audit_retention_days = 365

[[secret_categories]]
name = "api_keys"
encryption = true
rotation_required = true

[[secret_categories]]
name = "database_credentials"
encryption = true
rotation_required = true
```

**Key Files**:
- `/crates/vapora-backend/src/secrets.rs` (secret management)
- `/crates/vapora-llm-router/src/providers.rs` (uses secrets to load API keys)
- `/config/secrets.toml` (configuration)

---

## Verification

```bash
# Test secret storage and retrieval
cargo test -p vapora-backend test_secret_storage

# Test encryption/decryption
cargo test -p vapora-backend test_secret_encryption

# Verify audit logging
cargo test -p vapora-backend test_audit_logging

# Test key rotation
cargo test -p vapora-backend test_secret_rotation

# Verify post-quantum algorithms
cargo test -p vapora-backend test_pq_algorithms

# Integration test: load API key from secret store
cargo test -p vapora-llm-router test_provider_auth -- --nocapture
```

**Expected Output**:
- Secrets stored encrypted with post-quantum algorithm
- Decryption works correctly
- All secret access logged with timestamp, user, resource
- Key rotation works automatically
- API keys loaded securely in providers
- No keys leak in logs or error messages

---

## Consequences

### Security Operations
- Secret rotation automated every 90 days
- Audit logs accessible for compliance investigations
- Break-glass procedures for emergency access (logged)
- All secret operations require authentication

### Performance
- Secret retrieval cached (policies don't change)
- Decryption overhead < 1ms per secret
- Audit logging asynchronous (doesn't block requests)

### Maintenance
- Post-quantum algorithms updated as standards evolve
- Audit logs must be retained per compliance policy
- Key rotation scheduled and tracked

### Compliance
- Audit trail for regulatory investigations
- Encryption meets security standards
- Post-quantum protection for long-term security

---

## References

- [SecretumVault Documentation](https://github.com/secretumvault/secretumvault)
- [Post-Quantum Cryptography (ML-KEM)](https://csrc.nist.gov/projects/post-quantum-cryptography)
- `/crates/vapora-backend/src/secrets.rs` (integration code)
- `/config/secrets.toml` (configuration)

---

**Related ADRs**: ADR-009 (Istio), ADR-025 (Multi-Tenancy)