commit b66731a004650a23913d256e03c0fd744cf62ad2
Author: Jesús Pérez <jpl@jesusperez.com>
Date:   Mon Dec 22 19:42:49 2025 +0000

    chore: init repo

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7420b9c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,635 @@
+# SecretumVault
+
+**Post-quantum cryptographic secrets management system for modern cloud infrastructure**
+
+SecretumVault is a Rust-native secrets vault combining post-quantum cryptography (ML-KEM-768, ML-DSA-65) with classical crypto, multiple secrets engines, cedar-based policy authorization, and flexible storage backends.
+
+## Features
+
+### 🔐 Post-Quantum Cryptography
+- **ML-KEM-768**: Key encapsulation mechanism for key exchange
+- **ML-DSA-65**: Digital signatures with post-quantum resistance
+- **Hybrid mode**: Classical + PQC algorithms for future-proof security
+- **Multiple backends**: OpenSSL, AWS-LC, RustCrypto (feature-gated)
+
+### 🔑 Secrets Engines
+- **KV Engine**: Versioned key-value storage with encryption at rest
+- **Transit Engine**: Encryption/decryption without storing plaintext
+- **PKI Engine**: Certificate authority with X.509 support
+- **Database Engine**: Dynamic credentials for PostgreSQL, MySQL, others
+- **Extensible**: Add custom engines via trait implementation
+
+### 🛡️ Authorization & Policies
+- **Cedar Integration**: Attribute-based access control (ABAC)
+- **Fine-grained policies**: Context-aware decisions (IP, time, environment)
+- **Token management**: Lease-based credentials with automatic revocation
+- **Audit logging**: Full request/response audit trail
+
+### 💾 Flexible Storage
+- **etcd**: Distributed KV store with high availability
+- **SurrealDB**: Document database with queries
+- **PostgreSQL**: Proven relational database
+- **Filesystem**: Development/testing
+- **Extensible**: Implement `StorageBackend` trait for any backend
+
+### 🚀 Cloud Native
+- **Kubernetes-ready**: Native K8s deployments with RBAC
+- **Helm charts**: Production-ready templated deployments
+- **Docker**: Multi-stage builds for minimal images
+- **Prometheus metrics**: Built-in observability
+- **Structured logging**: JSON or human-readable format
+
+### 🔄 Enterprise Ready
+- **TLS/mTLS**: Encrypted client communication
+- **Shamir Secret Sharing**: Multi-factor unsealing (2-of-3, 3-of-5, etc.)
+- **Auto-unseal**: AWS KMS, GCP Cloud KMS, Azure Key Vault (planned)
+- **High availability**: Multi-node clustering (planned)
+- **Replication**: Active-passive disaster recovery (planned)
+
+---
+
+## Quick Start
+
+### Local Development with Docker Compose
+
+```bash
+# Clone repository
+git clone https://github.com/secretumvault/secretumvault.git
+cd secretumvault
+
+# Build and start
+docker build -t secretumvault:latest .
+docker-compose up -d
+
+# Verify
+curl http://localhost:8200/v1/sys/health
+
+# View logs
+docker-compose logs -f vault
+```
+
+### Kubernetes Deployment
+
+```bash
+# Deploy to cluster
+kubectl apply -f k8s/01-namespace.yaml
+kubectl apply -f k8s/02-configmap.yaml
+kubectl apply -f k8s/03-deployment.yaml
+kubectl apply -f k8s/04-service.yaml
+kubectl apply -f k8s/05-etcd.yaml
+
+# Port-forward and access
+kubectl -n secretumvault port-forward svc/vault 8200:8200
+curl http://localhost:8200/v1/sys/health
+```
+
+### Helm Installation
+
+```bash
+# Install with default configuration
+helm install vault helm/ \
+  --namespace secretumvault \
+  --create-namespace
+
+# Customize backends and engines
+helm install vault helm/ \
+  --namespace secretumvault \
+  --create-namespace \
+  --set vault.config.storageBackend=postgresql \
+  --set postgresql.enabled=true \
+  --set vault.replicas=3
+```
+
+---
+
+## Core Concepts
+
+### Config-Driven Architecture
+
+All components are selected via `svault.toml` configuration:
+
+```toml
+[vault]
+crypto_backend = "openssl"  # or "aws-lc", "rustcrypto"
+
+[storage]
+backend = "etcd"  # or "surrealdb", "postgresql"
+
+[seal]
+seal_type = "shamir"
+threshold = 2
+shares = 3
+
+[engines.kv]
+path = "secret/"
+versioned = true
+
+[engines.transit]
+path = "transit/"
+```
+
+No recompilation needed for backend changes—just update config.
+
+### Registry Pattern
+
+Type-safe backend selection using registry pattern:
+
+```rust
+// CryptoRegistry dispatches config string to backend
+let crypto = CryptoRegistry::create(&config.vault.crypto_backend)?;
+
+// StorageRegistry creates backend from config
+let storage = StorageRegistry::create(&config.storage)?;
+
+// EngineRegistry mounts engines from [engines] section
+let engines = EngineRegistry::mount_engines(&config.engines)?;
+```
+
+### Async/Await
+
+Built on Tokio for high concurrency:
+- Non-blocking I/O for all storage operations
+- Efficient resource utilization
+- Scales to thousands of concurrent connections
+
+### Token-Based Authentication
+
+All API requests require `X-Vault-Token` header:
+
+```bash
+curl -H "X-Vault-Token: $VAULT_TOKEN" \
+  http://localhost:8200/v1/secret/data/myapp
+```
+
+Tokens have:
+- TTL (time-to-live) with automatic expiration
+- Renewable for extended access
+- Revocable for immediate invalidation
+- Audit-logged for compliance
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     API Layer (Axum)                         │
+│  /v1/secret/* | /v1/transit/* | /v1/pki/* | /v1/database/*  │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+        ┌──────────────────┼──────────────────┐
+        │                  │                  │
+    ┌───▼────┐         ┌───▼────┐       ┌────▼────┐
+    │  Auth  │         │ Cedar  │       │ Metrics │
+    │Manager │         │ Policy │       │Collection
+    └─────────         │Engine  │       └─────────┘
+                       └────────┘
+                          │
+    ┌─────────────────────┼──────────────────────┐
+    │                     │                      │
+┌───▼──────┐    ┌─────────▼────────┐   ┌───────▼───────┐
+│ KV Engine│    │ Transit Engine   │   │ PKI Engine    │
+│  (Crypto)│    │  (Encrypt/Desc)  │   │(Certificates) │
+└──────────┘    └──────────────────┘   └───────────────┘
+    │                     │                      │
+    │         ┌───────────▼───────────┐          │
+    │         │  Database Engine      │          │
+    │         │  (Dynamic Secrets)    │          │
+    │         └───────────────────────┘          │
+    │                     │                      │
+    └─────────────────────┼──────────────────────┘
+                          │
+        ┌─────────────────┼────────────────┐
+        │                 │                │
+    ┌───▼──────┐    ┌────▼────┐     ┌─────▼─────┐
+    │  Crypto  │    │ Storage │     │   Seal    │
+    │ Registry │    │ Registry │     │  Manager  │
+    └──────────┘    └─────────┘     └───────────┘
+        │                │                │
+        │        ┌───────┼────────┐       │
+        │        │       │        │       │
+    ┌───▼──┐ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐ ┌─▼─────────┐
+    │OpenSSL
+    │       │ │etcd │ │SurrealDB   │Shamir SSS  │
+    └───────┘ └─────┘ └──────┘ └──────┘ └─────────┘
+                        │
+               ┌────────┼────────┐
+               │        │        │
+           ┌───▼──┐ ┌──▼──┐ ┌──▼──┐
+           │FS    │ │Postgres    │
+           └──────┘ └──────┘ └─────┘
+```
+
+For detailed architecture: `docs/ARCHITECTURE.md`
+
+---
+
+## Configuration
+
+### Minimal Setup
+
+```toml
+[vault]
+crypto_backend = "openssl"
+
+[server]
+address = "0.0.0.0"
+port = 8200
+
+[storage]
+backend = "etcd"
+
+[storage.etcd]
+endpoints = ["http://localhost:2379"]
+
+[seal]
+seal_type = "shamir"
+threshold = 2
+shares = 3
+
+[engines.kv]
+path = "secret/"
+versioned = true
+```
+
+### Production Setup
+
+```toml
+[vault]
+crypto_backend = "aws-lc"  # Post-quantum support
+
+[server]
+address = "0.0.0.0"
+port = 8200
+tls_cert = "/etc/secretumvault/tls.crt"
+tls_key = "/etc/secretumvault/tls.key"
+tls_client_ca = "/etc/secretumvault/client-ca.crt"
+
+[storage]
+backend = "postgresql"
+
+[storage.postgresql]
+connection_string = "postgres://vault:${DB_PASSWORD}@db.example.com:5432/secretumvault"
+
+[seal]
+seal_type = "shamir"
+threshold = 3
+shares = 5
+
+[engines.kv]
+path = "secret/"
+versioned = true
+
+[engines.transit]
+path = "transit/"
+
+[engines.pki]
+path = "pki/"
+
+[engines.database]
+path = "database/"
+
+[logging]
+level = "info"
+format = "json"
+output = "stdout"
+
+[telemetry]
+prometheus_port = 9090
+enable_trace = true
+
+[auth]
+default_ttl = 24
+cedar_policies_dir = "/etc/secretumvault/policies"
+```
+
+Full reference: `docs/CONFIGURATION.md`
+
+---
+
+## API Examples
+
+### Initialize Vault
+
+```bash
+curl -X POST http://localhost:8200/v1/sys/init \
+  -H "Content-Type: application/json" \
+  -d '{
+    "shares": 3,
+    "threshold": 2
+  }'
+```
+
+Response:
+```json
+{
+  "keys": ["key1", "key2", "key3"],
+  "root_token": "root_token_abc123"
+}
+```
+
+### Store Secret (KV Engine)
+
+```bash
+curl -X POST http://localhost:8200/v1/secret/data/myapp \
+  -H "X-Vault-Token: $VAULT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {
+      "username": "admin",
+      "password": "supersecret"
+    }
+  }'
+```
+
+### Read Secret
+
+```bash
+curl http://localhost:8200/v1/secret/data/myapp \
+  -H "X-Vault-Token: $VAULT_TOKEN"
+```
+
+### Encrypt with Transit Engine
+
+```bash
+curl -X POST http://localhost:8200/v1/transit/encrypt/my-key \
+  -H "X-Vault-Token: $VAULT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA=="}'
+```
+
+Full API reference: `docs/API.md`
+
+---
+
+## Deployment
+
+### Docker
+
+```bash
+docker build -t secretumvault:latest .
+docker run -p 8200:8200 \
+  -v /etc/secretumvault:/etc/secretumvault:ro \
+  secretumvault:latest
+```
+
+### Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+Includes: vault, etcd, surrealdb, postgres, prometheus, grafana
+
+### Kubernetes
+
+```bash
+kubectl apply -f k8s/
+# Or: helm install vault helm/
+```
+
+### Complete Deployment Guide
+
+See `DEPLOYMENT.md` for:
+- Docker build and run
+- Docker Compose multi-environment setup
+- Kubernetes manifests and scaling
+- Helm installation and customization
+- TLS/mTLS configuration
+- Prometheus monitoring
+- Troubleshooting
+
+---
+
+## How-To Guides
+
+Quick task guides for common operations:
+
+- **[Getting Started](docs/HOWOTO.md#getting-started)** - Initial setup and first secrets
+- **[Initialize Vault](docs/HOWOTO.md#initialize-vault)** - Create unseal keys and root token
+- **[Unseal Vault](docs/HOWOTO.md#unseal-vault)** - Recover after restart
+- **[Manage Secrets](docs/HOWOTO.md#manage-secrets)** - Create, read, update, delete
+- **[Configure Engines](docs/HOWOTO.md#configure-engines)** - Mount and customize engines
+- **[Setup Authorization](docs/HOWOTO.md#setup-authorization)** - Cedar policies and tokens
+- **[Configure TLS](docs/HOWOTO.md#configure-tls)** - Enable encryption
+- **[Integrate with Kubernetes](docs/HOWOTO.md#integrate-with-kubernetes)** - Pod secret injection
+- **[Backup & Restore](docs/HOWOTO.md#backup--restore)** - Data protection
+- **[Monitor & Troubleshoot](docs/HOWOTO.md#monitor--troubleshoot)** - Observability
+
+Full guide: `docs/HOWOTO.md`
+
+---
+
+## Project Structure
+
+```
+secretumvault/
+├── src/
+│   ├── main.rs                 # Server binary entry point
+│   ├── config.rs               # TOML config parsing and validation
+│   ├── error.rs                # Error types and conversions
+│   ├── api/                    # HTTP API layer (Axum)
+│   │   ├── server.rs           # Server setup and routing
+│   │   ├── handlers/           # Endpoint handlers
+│   │   └── middleware/         # Auth and Cedar middleware
+│   ├── auth/                   # Authentication and authorization
+│   │   ├── token.rs            # Token generation and validation
+│   │   └── cedar.rs            # Cedar policy evaluation
+│   ├── crypto/                 # Cryptographic backends
+│   │   ├── backend.rs          # CryptoBackend trait and registry
+│   │   ├── openssl.rs          # OpenSSL implementation
+│   │   └── aws_lc.rs           # AWS-LC post-quantum backend
+│   ├── storage/                # Storage backends
+│   │   ├── mod.rs              # StorageBackend trait and registry
+│   │   ├── filesystem.rs        # Filesystem implementation
+│   │   ├── etcd.rs             # etcd implementation
+│   │   ├── surrealdb.rs        # SurrealDB implementation
+│   │   └── postgresql.rs        # PostgreSQL implementation
+│   ├── engines/                # Secrets engines
+│   │   ├── mod.rs              # Engine trait and registry
+│   │   ├── kv.rs               # KV versioned store
+│   │   ├── transit.rs          # Encryption as a service
+│   │   ├── pki.rs              # Certificate authority
+│   │   └── database.rs         # Dynamic database credentials
+│   ├── core/                   # Core vault logic
+│   │   ├── vault.rs            # VaultCore and initialization
+│   │   ├── seal.rs             # Shamir SSS seal/unseal
+│   │   └── router.rs           # Request routing to engines
+│   ├── telemetry.rs            # Metrics, logging, audit
+│   └── lib.rs                  # Library exports
+├── Dockerfile                  # Multi-stage container build
+├── docker-compose.yml          # Complete dev environment
+├── docker/config/              # Docker configuration files
+├── k8s/                        # Kubernetes manifests
+│   ├── 01-namespace.yaml
+│   ├── 02-configmap.yaml
+│   ├── 03-deployment.yaml
+│   ├── 04-service.yaml
+│   ├── 05-etcd.yaml
+│   ├── 06-surrealdb.yaml
+│   └── 07-postgresql.yaml
+├── helm/                       # Helm chart
+│   ├── Chart.yaml
+│   ├── values.yaml
+│   └── templates/
+├── docs/                       # Product documentation
+│   ├── README.md               # Documentation index
+│   ├── ARCHITECTURE.md         # System architecture
+│   ├── CONFIGURATION.md        # Configuration reference
+│   ├── API.md                  # API reference
+│   ├── HOWOTO.md               # How-to guides
+│   └── SECURITY.md             # Security guidelines
+├── DEPLOYMENT.md               # Deployment guide
+├── README.md                   # This file
+└── Cargo.toml                  # Rust manifest
+
+```
+
+---
+
+## Development
+
+### Build
+
+```bash
+cargo build --all-features
+```
+
+### Test
+
+```bash
+cargo test --all-features
+```
+
+### Lint
+
+```bash
+cargo clippy -- -D warnings
+```
+
+### Format
+
+```bash
+cargo fmt
+```
+
+### Run
+
+```bash
+cargo run --all-features -- server --config svault.toml
+```
+
+### Documentation
+
+```bash
+cargo doc --all-features --open
+```
+
+---
+
+## Feature Flags
+
+Enable optional features via Cargo:
+
+```bash
+cargo build --features aws-lc,pqc,surrealdb-storage,etcd-storage,postgresql-storage
+```
+
+Available features:
+- `aws-lc` - AWS-LC cryptographic backend with post-quantum support
+- `pqc` - Post-quantum cryptography (ML-KEM-768, ML-DSA-65)
+- `surrealdb-storage` - SurrealDB storage backend
+- `etcd-storage` - etcd storage backend
+- `postgresql-storage` - PostgreSQL storage backend
+- `server` - Server binary
+- `cli` - Command-line tools
+- `cedar` - Cedar policy evaluation
+
+---
+
+## Security
+
+### Design Principles
+
+- **Encryption at rest**: All secrets encrypted with master key
+- **Least privilege**: Cedar policies enforce fine-grained access
+- **Audit logging**: All operations logged and auditable
+- **Secure defaults**: Non-root execution, read-only filesystem, dropped capabilities
+- **Post-quantum ready**: Support for ML-KEM and ML-DSA
+
+### Security Guidelines
+
+See `docs/SECURITY.md` for:
+- Key management best practices
+- Unsealing strategy
+- Token security
+- TLS/mTLS setup
+- Audit log review
+- Vulnerability reporting
+
+---
+
+## Roadmap
+
+### Near-term (Next)
+- [ ] Additional secrets engines (SSH, Kubernetes Auth)
+- [ ] Auto-unseal mechanisms (AWS KMS, GCP Cloud KMS, Azure)
+- [ ] Secret rotation policies
+- [ ] Backup/restore utilities
+- [ ] Client SDKs (Go, Python, Node.js)
+
+### Medium-term
+- [ ] Active-passive replication
+- [ ] Multi-node clustering with Raft consensus
+- [ ] OAuth2/OIDC integration
+- [ ] Cloud IAM integration (AWS, GCP, Azure)
+- [ ] External Secrets Operator for K8s
+
+### Long-term
+- [ ] Active-active multi-region replication
+- [ ] Custom plugin system
+- [ ] FIPS 140-2 certification
+- [ ] HSM/TPM integration
+- [ ] Chaos engineering test suite
+
+---
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork repository
+2. Create feature branch: `git checkout -b feature/name`
+3. Make changes following `CLAUDE.md` guidelines
+4. Test: `cargo test --all-features`
+5. Lint: `cargo clippy -- -D warnings`
+6. Submit pull request
+
+---
+
+## License
+
+[License specification - add appropriate license]
+
+---
+
+## Support
+
+- **Documentation**: Full guides in `docs/`
+- **Issues**: GitHub issue tracker
+- **Security**: Report vulnerabilities via security contact
+- **Community**: Discussions and Q&A
+
+---
+
+## Acknowledgments
+
+SecretumVault combines proven patterns from:
+- HashiCorp Vault (inspiration for API and engine design)
+- NIST PQC standardization (ML-KEM-768, ML-DSA-65)
+- AWS Cedar (policy language and authorization)
+- Kubernetes ecosystem (native cloud deployment)
+
+---
+
+**Built with ❤️ in Rust for modern cryptographic secrets management**