io.github.pdaxt/pqvault
Post-quantum secrets manager for AI agents. ML-KEM-768 + X25519 + AES-256-GCM.
Ask AI about io.github.pdaxt/pqvault
Powered by Claude ยท Grounded in docs
I know everything about io.github.pdaxt/pqvault. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
๐ PQVault
Post-Quantum Secrets Management for AI Agents
Your API keys deserve quantum-resistant encryption. Your AI agents deserve controlled access.
Quick Start ยท Architecture ยท MCP Tools ยท Web Dashboard ยท Encryption ยท Providers
AI Agent โ MCP request โ PQVault โ decrypts โ injects key โ proxies API call โ returns response
โ
The agent never sees the key.
The Problem
~/.env โ plaintext, no access control, no audit trail
claude.json env blocks โ keys scattered across MCP configs
shell history โ keys logged forever
1Password / Bitwarden โ designed for humans, not AI agents
HashiCorp Vault โ enterprise complexity for a dev machine
AI agents need API keys. But they don't need to see them. They don't need unlimited access. And nobody's tracking which agent burned through your $200 Anthropic quota at 3am.
The Solution
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ PQVault โ
โ โ
โ โ One encrypted vault for all secrets โ
โ โ AI agents access keys via MCP protocol โ
โ โ Zero-knowledge proxy โ keys never leave โ
โ โ Per-key rate limits (RPM, daily, monthly) โ
โ โ Usage tracking + cost estimation per key โ
โ โ Audit log for every access โ
โ โ Post-quantum encryption (ML-KEM-768) โ
โ โ Web dashboard for humans, MCP for agents โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
PQVault vs Everything Else
| Feature | .env files | 1Password | HashiCorp Vault | PQVault |
|---|---|---|---|---|
| AI agent access (MCP) | โ | โ | โ | โ |
| Zero-knowledge proxy | โ | โ | โ | โ |
| Post-quantum encryption | โ | โ | โ | โ |
| Per-key rate limiting | โ | โ | โ | โ |
| Usage & cost tracking | โ | โ | โ | โ |
| Auto provider detection | โ | โ | โ | โ |
| Key health monitoring | โ | โ | โ | โ |
| No infrastructure needed | โ | โ | โ | โ |
| Free & open source | โ | โ | Partial | โ |
| Single binary | โ | โ | โ | โ |
๐ Quick Start
# Clone and build
git clone https://github.com/pdaxt/pqvault-rs.git
cd pqvault-rs
cargo build --release
# macOS: ad-hoc sign to avoid Gatekeeper
codesign -s - target/release/pqvault
# Initialize vault (generates PQ + classical keypairs, stores master password in Keychain)
./target/release/pqvault init
# Add your first secret
./target/release/pqvault add ANTHROPIC_API_KEY sk-ant-xxxxx
# Check vault status
./target/release/pqvault status
# Start the web dashboard
./target/release/pqvault web
# โ http://localhost:9876
# Start MCP server (for AI agents)
./target/release/pqvault serve
Configure MCP Client
Add to your Claude Code, Cursor, or any MCP-compatible client:
{
"mcpServers": {
"pqvault": {
"command": "/path/to/pqvault-rs/target/release/pqvault",
"args": ["serve"]
}
}
}
PQVault ships as 4 focused MCP servers for modular use:
| Server | Crate | Tools | Purpose |
|---|---|---|---|
pqvault serve | pqvault-mcp | vault_get, vault_add, vault_list, ... | Core vault operations |
pqvault proxy | pqvault-proxy-mcp | vault_proxy | Zero-knowledge API proxy |
pqvault health | pqvault-health-mcp | vault_health, vault_dashboard, vault_usage | Monitoring & analytics |
pqvault env | pqvault-env-mcp | vault_project_env, vault_write_env, vault_rotate | Environment management |
๐ Architecture
HUMAN AI AGENTS
โ โ
โ http://localhost:9876 โ stdio JSON-RPC (MCP)
โผ โผ
โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Web Dashboard โ โ PQVault MCP Server (rmcp 1.1) โ
โ (Axum) โ โ โ
โ โ โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโ โ
โ โข Browse keys โ โ โ 14 Tools โ โ Rate โ โ Usage โ โ
โ โข Verify keys โ โ โ (MCP) โ โ Limiter โ โ Tracker โ โ
โ โข Edit metadata โ โ โโโโโโฌโโโโโโ โโโโโโฌโโโโโโ โโโโโโฌโโโโโ โ
โ โข Search/filter โ โ โโโโโโโโโโโโโโโผโโโโโโโโโโโโ โ
โโโโโโโโโโฌโโโโโโโโโโ โ โ โ
โ โ โโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโ
โ โ โ Vault Engine โโ
โโโโโโโโโโโโโโโโโโโโค โ open โ decrypt โ operate โ encrypt โโ
โ โโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโ
โ โ Hybrid Crypto Layer โโ
โ โ ML-KEM-768 โ X25519 โ HKDF โ โโ
โ โ AES-256-GCM โโ
โ โโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโ
โผ โผ โผ
~/.pqvault/ macOS Keychain ~/.pqvault/
vault.enc (master password) usage.json
*.bin / *.enc audit.log
Workspace Structure
pqvault-rs/
โโโ crates/
โ โโโ pqvault-core/ # Crypto, vault engine, providers, models
โ โโโ pqvault-mcp/ # Core MCP server (14 tools)
โ โโโ pqvault-proxy-mcp/ # Zero-knowledge API proxy
โ โโโ pqvault-health-mcp/ # Health monitoring & dashboards
โ โโโ pqvault-env-mcp/ # .env generation & management
โ โโโ pqvault-cli/ # Terminal interface
โ โโโ pqvault-web/ # Web dashboard (Axum)
โโโ Cargo.toml # Workspace root
๐ก Zero-Knowledge Proxy
The killer feature. AI agents call APIs through PQVault โ the key never leaves the vault process.
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ AI Agent โ vault_proxy() โ PQVault โ
โ โ โโโโโโโโโโโโโโโ>โ โ
โ "Call Stripe โ โ 1. Decrypt key โ
โ /v1/balance" โ โ 2. Inject auth โโโ> Stripe API
โ โ { response } โ 3. Make request โ<โโ Response
โ โ <โโโโโโโโโโโโโโโโ 4. Return data โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
Key stays here โ
# Instead of this (key exposed to agent):
vault_get("STRIPE_SECRET_KEY") โ agent gets key โ agent calls Stripe
# Do this (key never exposed):
vault_proxy(key="STRIPE_SECRET_KEY", method="GET", url="/v1/balance")
โ vault calls Stripe internally โ returns only the response
Security layers:
- HTTPS-only enforcement
- SSRF protection (blocks localhost, metadata endpoints, IP literals)
- Domain allowlisting per provider
- Auto-detected auth injection (Bearer, Basic, header, query param)
- 1MB response limit
๐งฐ MCP Tools (14)
Read Operations
| Tool | Description |
|---|---|
vault_status | Encryption info, key count, health status, active alerts |
vault_get | Retrieve a secret (rate-limited, usage-tracked, audit-logged) |
vault_list | List all secrets with metadata โ no values exposed |
vault_search | Case-insensitive search across names, descriptions, tags |
vault_health | Expired keys, rotation warnings, usage spikes, idle key alerts |
vault_usage | Per-key analytics: requests, rate limit %, cost, callers |
vault_dashboard | Full markdown dashboard with all keys, costs, limits |
vault_project_env | Generate .env content for a registered project |
Write Operations
| Tool | Description |
|---|---|
vault_add | Add secret with auto-detected provider, category, and rate limits |
vault_rotate | Rotate secret value, reset timestamp, clear alerts |
vault_delete | Remove secret and clean up project references |
vault_import_claude | Scan ~/.claude.json and import API keys from MCP env blocks |
Zero-Knowledge Operations
| Tool | Description |
|---|---|
vault_proxy | Proxy API calls โ key auto-injected, never exposed to caller |
vault_write_env | Write .env file to disk โ values never returned to caller |
๐ Web Dashboard
Full-featured web UI at http://localhost:9876 โ embedded in the binary, zero external dependencies.
| Capability | Details |
|---|---|
| Provider-grouped view | Secrets organized by Anthropic, Stripe, Resend, GitHub, etc. |
| One-click verification | Hit provider APIs to check if keys are active, expired, or restricted |
| Masked values | Shows sk-a...8QAA โ click to reveal |
| Sidebar filters | Filter by provider, status (active/error/unknown), category |
| Full-text search | Search across key names, accounts, descriptions, projects |
| Metadata editing | Set account, environment, description per key |
| CRUD operations | Add, rotate, delete secrets via modal dialogs |
| Dark theme | Purple accent, designed for developer use |
API Endpoints
| Method | Path | Description |
|---|---|---|
GET | / | Dashboard HTML |
GET | /api/status | Vault summary |
GET | /api/secrets | All secrets (masked values) |
POST | /api/secrets | Add secret |
DELETE | /api/secrets/{key} | Delete secret |
PUT | /api/secrets/{key}/rotate | Rotate value |
PUT | /api/secrets/{key}/meta | Update metadata |
POST | /api/secrets/{key}/verify | Verify against provider API |
GET | /api/health | Health report |
GET | /api/search?q=... | Search secrets |
๐ Encryption Deep-Dive
Why Hybrid Post-Quantum?
NIST standardized ML-KEM in 2024 (FIPS 203). Harvest-now-decrypt-later attacks mean data encrypted today with classical-only crypto may be readable by quantum computers in 5-15 years. API keys rotate faster than that โ but the vault's master key and private keys protect all secrets. Those deserve quantum-resistant protection now.
Encryption Flow
โโโโโโโโโโโโโโโโโโโโโโโ
โ Plaintext secrets โ
โโโโโโโโโโโโฌโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโ
โผ โผ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ ML-KEM-768 โ โ X25519 ECDH โ
โ (Post-Quantum) โ โ (Classical) โ
โ โ โ โ
โ pq_ss (32B) โ โ x_ss (32B) โ
โโโโโโโโโโฌโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโ
โ HKDF-SHA256 โ
โ ikm = pq_ss โ x_ss โ
โ info = "pqvault- โ
โ hybrid-dek-v1" โ
โโโโโโโโโโโโโฌโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AES-256-GCM โ
โ key = derived DEK โ
โ aad = "pqvault-v1" โ
โโโโโโโโโโโโโฌโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโ
โ Ciphertext โ
โโโโโโโโโโโโโโโโ
An attacker must break both ML-KEM-768 (post-quantum lattice) and X25519 (classical ECDH) simultaneously.
Security Properties
| Property | Mechanism |
|---|---|
| Quantum resistance | ML-KEM-768 (FIPS 203, lattice-based) |
| Classical resistance | X25519 + AES-256-GCM |
| Hybrid binding | Both shared secrets required for DEK derivation |
| Forward secrecy | Ephemeral X25519 keypair per encryption |
| Authentication | AES-GCM AEAD with associated data |
| Key-at-rest protection | scrypt (N=131072, 128MB) + AES-256-GCM |
| Master password | macOS Keychain (Secure Enclave) + file cache |
Binary Payload Format
Bytes 0-3: u32 BE โ pq_ciphertext length (1088 for ML-KEM-768)
Bytes 4-7: u32 BE โ x25519_ephemeral length (32)
Bytes 8-11: u32 BE โ salt length (32)
Bytes 12-15: u32 BE โ nonce length (12)
Bytes 16-19: u32 BE โ ciphertext length (varies)
Byte 20+: pq_ciphertext โ x25519_ephemeral โ salt โ nonce โ ciphertext
๐ Provider System
Auto-Detection
When a key is added, PQVault detects the provider from:
- Key name โ word-boundary matching (
AWS_KEYmatches,AWESOME_VARdoesn't) - Value pattern โ regex on the secret value (e.g.,
^sk-ant-โ Anthropic) - Longest match wins โ avoids false positives
Built-in Providers (10)
| Provider | Detected By | Rate Limit | Cost/req | Rotation |
|---|---|---|---|---|
| Anthropic | ANTHROPIC, ^sk-ant- | 50 RPM / 10k daily | $0.003 | 90d |
| OpenAI | OPENAI, ^sk-[a-z0-9]{20,} | 60 RPM / 10k daily | $0.002 | 90d |
| GitHub | GITHUB, ^ghp_|gho_ | 83 RPM / 5k daily | free | 90d |
| Stripe | STRIPE, ^sk_live_|sk_test_ | 100 RPM / 10k daily | free | 30d |
GOOGLE_API, ^AIza | 100 RPM / 10k daily | $0.001 | 180d | |
| Brave | BRAVE, ^BSA | 10 RPM / 2k monthly | free | 365d |
| Resend | RESEND, ^re_ | 10 RPM / 100 daily | free | 180d |
| Cloudflare | CLOUDFLARE, CF_API | 50 RPM / 10k daily | free | 90d |
| ElevenLabs | ELEVENLABS | 20 RPM / 500 daily | $0.005 | 180d |
| Serper | SERPER | 5 RPM / 100 monthly | free | 365d |
Three-Tier Rate Limiting
Request โ [Token Bucket (per-minute)] โ [Daily Counter] โ [Monthly Counter] โ Allowed
refills at RPM/60 resets at midnight resets monthly
Smart Alerts
| Alert | Trigger | Severity |
|---|---|---|
| Unused key | No access for 30+ days | โ ๏ธ Warning |
| Rotation due | Key age exceeds provider recommendation | โ ๏ธ / ๐ด Critical |
| Usage spike | Today's requests > 3x 7-day average | โ ๏ธ Warning |
๐ File Layout
~/.pqvault/
โโโ vault.enc # Encrypted vault (hybrid PQ + classical)
โโโ vault.meta.json # Algorithm metadata (no secrets)
โโโ pq_public.bin # ML-KEM-768 encapsulation key (1184 bytes)
โโโ pq_private.enc # ML-KEM-768 decapsulation key (encrypted)
โโโ x25519_public.bin # X25519 public key (32 bytes)
โโโ x25519_private.enc # X25519 private key (encrypted)
โโโ usage.json # Per-key usage stats, rate limits, alerts
โโโ .master_cache # Cached master password (0600 permissions)
โโโ audit.log # JSONL access log (rotates at 10k lines)
โโโ audit.log.{1,2,3} # Rotated audit logs (max 3)
โโโ backups/
โโโ vault.YYYY-MM-DD.enc
CLI Reference
pqvault init # Initialize vault + generate keypairs
pqvault serve # Start MCP server (stdio JSON-RPC)
pqvault status # Vault health summary
pqvault list # List secrets (no values)
pqvault get <KEY> # Print secret value
pqvault add <KEY> <VALUE> [-c cat] # Add secret with optional category
pqvault health # Rotation, expiry, orphan warnings
pqvault web [--port 9876] # Start web dashboard
๐ฎ Roadmap: Daemon Mode (v3)
HUMAN (Browser)
โ
localhost:7700
TOTP + password auth
โ
โโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ PQVault Daemon โ
โ โ
โ Web Portal (Axum) โ
โ Token Manager (SQLite) โ
โ Approval Queue (SSE push) โ
โ Vault Engine (existing crypto) โ
โ โ
โ localhost:7700 (HTTP) โ
โ /tmp/pqvault.sock (Unix) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Unix socket + token
โโโโโโโโโโผโโโโโโโโโ
โผ โผ โผ
MCP Proxy CLI Other tools
Planned changes:
- Master password entered via web portal (TOTP-gated), held only in daemon memory
- Encrypted usage.json + audit.log (key names no longer leak)
- Token-scoped access per agent (which keys, TTL, auto-approve vs. human-approve)
- Instant revocation from web portal
Known Limitations
Security (click to expand)
- No authentication on web UI (localhost-only, but still unprotected)
- File cache stores master password in plaintext (0600 perms, same-user readable)
usage.jsonandaudit.lognot encrypted (key names visible)- No TLS on web UI (localhost HTTP only)
Functionality
- No batch key verification (sequential only)
- No push notifications on key failures
- No import from
.envfiles (only~/.claude.json) - Single vault, single master password (no multi-user)
- No backup management in web UI
Architecture
- Web UI HTML embedded in binary (~560 lines of inline HTML/CSS/JS)
- All state in JSON files (works for <1000 secrets)
- Full hybrid re-encrypt on every save
Dependencies
Built on well-audited Rust crates:
| Category | Crates |
|---|---|
| Crypto | ml-kem 0.2, x25519-dalek 2, aes-gcm 0.10, hkdf 0.12, scrypt 0.11 |
| MCP | rmcp 1.1 (stdio JSON-RPC, tool routing, schemars) |
| Web | axum 0.8, tower 0.5, tower-http 0.6 |
| HTTP | reqwest 0.12 (rustls-tls, no OpenSSL) |
| CLI | clap 4 with derive macros |
| Runtime | tokio 1 (multi-threaded async) |
| Keychain | keyring 3 (apple-native) |
| Serialization | serde 1.0, serde_json 1.0, schemars 1.0 |
Built by Pranjal Gupta at DataXLR8
Part of the DataXLR8 AI infrastructure ecosystem.
