docs/
├── README.md                          # This file
├── index.md                           # mdBook introduction
├── user-guide/
│   ├── README.md
│   ├── configuration.md               # Configuration reference
│   └── howto.md                       # Step-by-step how-to guides
├── architecture/
│   ├── README.md
│   ├── overview.md                    # System architecture and design
│   └── complete-architecture.md       # Detailed architecture reference
├── operations/
│   ├── README.md
│   └── deployment.md                  # Deployment guide
└── development/
    ├── README.md
    ├── build-features.md             # Cargo features and build options
    ├── features-control.md           # Feature control and Justfile recipes
    └── pqc-support.md                # Post-quantum cryptography support
└── ../
    ├── README.md                      # Main overview
    └── 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:

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

# 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 for full feature list.

Run Locally

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

# Or with Docker Compose
docker-compose up -d

Deploy to Kubernetes

# Apply manifests
kubectl apply -f k8s/

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

Configure Storage

Edit svault.toml:

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

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

Set Up TLS

# 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

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

View Logs

# 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 for detailed guidance.

Next Steps

New to SecretumVault? → Read Architecture
Want to deploy? → Follow Deployment Guide
Ready to use? → Start with How-To Guides
Need to configure? → Check Configuration Reference
Building a feature? → See Development Guide

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.

README.md

SecretumVault Documentation

Documentation Index

Getting Started

Operations & Development

Build & Features

Quick Navigation

I want to...

Documentation Structure