secretumvault/docs/README.md

# SecretumVault Documentation

<div align="center">
  <img src="../imgs/secretumvault-logo-h.svg" alt="SecretumVault Logo" width="600" />
</div>

Complete documentation for SecretumVault secrets management system.

## Documentation Index

### Getting Started
- **[Architecture](ARCHITECTURE.md)** - System design, components, and data flow
- **[How-To Guide](HOWOTO.md)** - Step-by-step instructions for common tasks
- **[Configuration](CONFIGURATION.md)** - Complete configuration reference and options
- **[Features Control](FEATURES_CONTROL.md)** - Build features and Justfile recipes

### Operations & Development
- **[Deployment Guide](../DEPLOYMENT.md)** - Docker, Kubernetes, and Helm deployment
- **[API Reference](API.md)** - HTTP API endpoints and request/response formats
- **[Security Guidelines](SECURITY.md)** - Security best practices and hardening

### Build & Features
- **[Build Features](BUILD_FEATURES.md)** - Cargo features, compilation options, dependencies
- **[Post-Quantum Cryptography](PQC_SUPPORT.md)** - PQC algorithms, backend support, configuration
- **[Development Guide](DEVELOPMENT.md)** - Building, testing, and contributing

---

## Quick Navigation

### I want to...

**Deploy SecretumVault**
→ Start with [Deployment Guide](../DEPLOYMENT.md)

**Understand the architecture**
→ Read [Architecture](ARCHITECTURE.md)

**Configure vault for my environment**
→ See [Configuration](CONFIGURATION.md)

**Use the REST API**
→ Check [API Reference](API.md)

**Set up authentication and policies**
→ Follow [How-To: Setup Authorization](HOWOTO.md#setup-authorization)

**Integrate with Kubernetes**
→ See [How-To: Kubernetes Integration](HOWOTO.md#integrate-with-kubernetes)

**Enable post-quantum cryptography**
→ Read [PQC Support Guide](PQC_SUPPORT.md), [Configuration: Crypto Backends](CONFIGURATION.md#crypto-backends), or [Build Features: PQC](BUILD_FEATURES.md#post-quantum-cryptography)

**Rotate secrets automatically**
→ Check [How-To: Secret Rotation](HOWOTO.md#secret-rotation)

**Set up monitoring**
→ See [How-To: Monitoring](HOWOTO.md#monitor--troubleshoot)

**Contribute code**
→ Read [Development Guide](DEVELOPMENT.md)

---

## Documentation Structure

```
docs/
├── README.md                          # This file
├── ARCHITECTURE.md                    # System architecture and design
├── CONFIGURATION.md                   # Configuration reference
├── HOWOTO.md                          # Step-by-step how-to guides
├── API.md                             # REST API reference
├── BUILD_FEATURES.md                  # Cargo features and build options
├── PQC_SUPPORT.md                     # Post-quantum cryptography support
├── DEVELOPMENT.md                     # Development and contribution guide
├── SECURITY.md                        # Security guidelines and best practices
└── ../
    ├── README.md                      # Main overview
    ├── DEPLOYMENT.md                  # Deployment guide (Docker, K8s, Helm)
    └── Cargo.toml                     # Rust manifest with all dependencies
```

---

## Key Concepts

### Config-Driven Architecture

Everything in SecretumVault is configurable via `svault.toml`:

- **Crypto backend**: Choose between OpenSSL, AWS-LC, RustCrypto
- **Storage backend**: etcd, SurrealDB, PostgreSQL, or filesystem
- **Secrets engines**: Mount KV, Transit, PKI, Database dynamically
- **Authorization**: Cedar policies from configuration directory
- **Seal mechanism**: Shamir SSS with configurable thresholds

No recompilation needed—just update the TOML file.

### Registry Pattern

Backend selection uses type-safe registry pattern:

```
Config String → Registry Dispatch → Concrete Backend
    "etcd"   → StorageRegistry  → etcdBackend
    "openssl" → CryptoRegistry  → OpenSSLBackend
    "kv"     → EngineRegistry   → KVEngine
```

### Async/Await Foundation

All I/O is non-blocking using Tokio:

```
HTTP Request → Axum Router → Engine → Storage Backend (async/await)
                                     → Crypto Backend (async/await)
                                     → Policy Engine (sync)
```

### Token-Based Authentication

Every API request requires a token:

```bash
curl -H "X-Vault-Token: $VAULT_TOKEN" \
  http://localhost:8200/v1/secret/data/myapp
```

Tokens include:
- TTL (auto-expiration)
- Renewable (extend access)
- Revocable (immediate invalidation)
- Audited (logged in detail)

---

## Feature Overview

### Cryptography

| Feature | Status | Notes |
|---------|--------|-------|
| OpenSSL backend (RSA, ECDSA) | ✅ Complete | Stable, widely supported |
| AWS-LC backend (RSA, ECDSA) | ✅ Complete | Post-quantum ready |
| ML-KEM-768 (Key encapsulation) | ✅ Feature-gated | Post-quantum, feature: `pqc` |
| ML-DSA-65 (Digital signatures) | ✅ Feature-gated | Post-quantum, feature: `pqc` |
| RustCrypto backend | 🔄 Planned | Pure Rust PQC implementation |
| Hybrid mode (classical + PQC) | ✅ Complete | Use both for future-proof security |

### Secrets Engines

| Engine | Status | Features |
|--------|--------|----------|
| KV (Key-Value) | ✅ Complete | Versioned storage, encryption at rest |
| Transit (Encryption) | ✅ Complete | Encrypt/decrypt without storage |
| PKI (Certificates) | ✅ Complete | CA, certificate issuance, CRL |
| Database (Dynamic) | ✅ Complete | PostgreSQL, MySQL, credential rotation |
| SSH (Future) | 🔄 Planned | SSH certificate issuance |
| AWS (Future) | 🔄 Planned | Dynamic AWS IAM credentials |

### Storage Backends

| Backend | Status | Use Case |
|---------|--------|----------|
| etcd | ✅ Complete | Distributed HA (production) |
| SurrealDB | ✅ Complete | Document queries (testing) |
| PostgreSQL | ✅ Complete | Relational (production) |
| Filesystem | ✅ Complete | Development/testing |
| S3 (Future) | 🔄 Planned | Cloud object storage |
| Consul (Future) | 🔄 Planned | Service mesh integration |

### Authorization

| Feature | Status | Notes |
|---------|--------|-------|
| Cedar policies | ✅ Complete | AWS open-source ABAC language |
| Token management | ✅ Complete | TTL, renewal, revocation |
| Audit logging | ✅ Complete | Full request/response audit |
| IP-based policies | ✅ Complete | Context-aware decisions |
| Time-based policies | ✅ Complete | Schedule-based access |

### Deployment

| Format | Status | Features |
|--------|--------|----------|
| Docker | ✅ Complete | Multi-stage build, minimal image |
| Docker Compose | ✅ Complete | Full dev stack (6 services) |
| Kubernetes | ✅ Complete | Manifests + RBAC + StatefulSet |
| Helm | ✅ Complete | Production-ready chart |
| Terraform (Future) | 🔄 Planned | Infrastructure as code |

### Observability

| Feature | Status | Features |
|---------|--------|----------|
| Prometheus metrics | ✅ Complete | 13+ metrics, text format |
| Structured logging | ✅ Complete | JSON or human-readable |
| Audit logging | ✅ Complete | Encrypted storage + display |
| Tracing (Future) | 🔄 Planned | OpenTelemetry integration |

---

## Common Tasks

### Build from Source

```bash
# Standard build (OpenSSL only)
cargo build --release

# With all features
cargo build --release --all-features

# With specific features
cargo build --release --features aws-lc,pqc,postgresql-storage
```

See [Build Features](BUILD_FEATURES.md) for full feature list.

### Run Locally

```bash
# Start with config file
cargo run --release -- server --config svault.toml

# Or with Docker Compose
docker-compose up -d
```

### Deploy to Kubernetes

```bash
# Apply manifests
kubectl apply -f k8s/

# Or use Helm
helm install vault helm/ --namespace secretumvault --create-namespace
```

### Configure Storage

Edit `svault.toml`:

```toml
[storage]
backend = "postgresql"  # etcd, surrealdb, postgresql, filesystem

[storage.postgresql]
connection_string = "postgres://user:pass@host:5432/vault"
```

### Set Up TLS

```bash
# Generate certificate
openssl req -x509 -newkey rsa:4096 -out tls.crt -keyout tls.key

# Update config
[server]
tls_cert = "/etc/secretumvault/tls.crt"
tls_key = "/etc/secretumvault/tls.key"
```

---

## Support & Troubleshooting

### Check Health

```bash
curl http://localhost:8200/v1/sys/health
```

### View Logs

```bash
# Docker Compose
docker-compose logs -f vault

# Kubernetes
kubectl -n secretumvault logs -f deployment/vault
```

### Common Issues

- **Pod not starting**: Check `kubectl describe pod`
- **Storage connection error**: Verify backend endpoint in ConfigMap
- **TLS errors**: Check certificate paths and permissions
- **High memory**: Increase resource limits in values.yaml

See [How-To: Troubleshooting](HOWOTO.md#monitor--troubleshoot) for detailed guidance.

---

## Next Steps

1. **New to SecretumVault?** → Read [Architecture](ARCHITECTURE.md)
2. **Want to deploy?** → Follow [Deployment Guide](../DEPLOYMENT.md)
3. **Ready to use?** → Start with [How-To Guides](HOWOTO.md)
4. **Need to configure?** → Check [Configuration Reference](CONFIGURATION.md)
5. **Building a feature?** → See [Development Guide](DEVELOPMENT.md)

---

## Documentation Quality

All documentation is:
- ✅ **Accurate**: Reflects current implementation
- ✅ **Complete**: Covers all major features
- ✅ **Practical**: Includes real examples
- ✅ **Actionable**: Step-by-step procedures
- ✅ **Searchable**: Organized with clear structure

---

Last updated: 2025-12-21

For the latest updates, check the repository or create an issue on GitHub.