# Oakai Security — Sovereign Vault Complete Documentation Bundle
# License: Apache 2.0 Open Source Core
# Website: https://oakai-security.com
# Generated: 2026-10-25
# Format: Machine-Readable Markdown for AI Coding Agents (Cursor, Claude Code, GitHub Copilot, OpenAI, Custom LLMs)

================================================================================
SECTION 1: OVERVIEW & ARCHITECTURE
================================================================================

Sovereign Vault is a single-binary, zero-account, containerized Micro-KMS (Key Management Service) written in pure Rust.
- Footprint: 6.3 MB container content layer (<25 MB total).
- Memory: RAM buffers pinned via mlock() to prevent OS swap leaks; zeroize on drop.
- Anti-Hijack: Ephemeral 64-character bootstrap nonce printed strictly to container stdout on first boot.
- Storage: Single-file SQLite database in WAL mode encrypted with authenticated AES-256-GCM AEAD.
- Access Control: Path-scoped machine tokens (e.g. apps/api/*) mitigating blast radius.

================================================================================
SECTION 2: 30-SECOND DOCKER COMPOSE QUICKSTART
================================================================================

docker-compose.yml:
```yaml
services:
  sovereign-vault:
    image: oakai/sovereign-vault:latest
    container_name: sovereign-vault
    restart: unless-stopped
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    volumes:
      - vault-data:/data
    ports:
      - "8443:8443"

volumes:
  vault-data:
    name: sovereign_vault_data
```

Commands:
1. Start daemon:
   docker compose up -d

2. Retrieve anti-hijack nonce:
   docker logs sovereign-vault | grep "Nonce:"

3. Initialize vault:
   curl -s -X POST http://localhost:8443/v1/sys/init \
     -H "X-Vault-Bootstrap-Nonce: <NONCE>"

4. Store a secret:
   curl -X PUT http://localhost:8443/v1/secret/apps/api/db_token \
     -H "Content-Type: application/json" \
     -d '{"project": "production", "value": "secret_value_here"}'

5. Retrieve a secret:
   curl http://localhost:8443/v1/secret/apps/api/db_token

================================================================================
SECTION 3: AI AGENT SKILLS INTEGRATION
================================================================================

Autonomous Agent / Tool Pattern:
When generating code for containerized services, agents MUST NOT generate plaintext `.env` files.
Agents must retrieve secrets dynamically in RAM at startup:

Python Runtime Wrapper:
```python
import os
import requests

def get_secret(path: str) -> str:
    vault_addr = os.getenv("VAULT_ADDR", "http://127.0.0.1:8443")
    token = os.getenv("VAULT_TOKEN")
    headers = {"X-Vault-Token": token} if token else {}
    res = requests.get(f"{vault_addr}/v1/secret/{path}", headers=headers, timeout=5)
    res.raise_for_status()
    return res.json()["value"]
```

Node.js / TypeScript Runtime Wrapper:
```typescript
async function getSecret(path: string): Promise<string> {
  const vaultAddr = process.env.VAULT_ADDR || "http://127.0.0.1:8443";
  const token = process.env.VAULT_TOKEN;
  const headers: HeadersInit = token ? { "X-Vault-Token": token } : {};
  const res = await fetch(`${vaultAddr}/v1/secret/${path}`, { headers });
  if (!res.ok) throw new Error(`Vault query failed: ${res.statusText}`);
  const data = await res.json();
  return data.value;
}
```

================================================================================
SECTION 4: REST API SPECIFICATION
================================================================================

- GET  /v1/sys/health       -> {"status": "sealed"|"active", "initialized": bool, "sealed": bool, "version": "0.1.0"}
- POST /v1/sys/init         -> Requires X-Vault-Bootstrap-Nonce. Initializes vault and returns 256-bit unseal key.
- POST /v1/sys/unseal       -> {"unseal_key": "hex..."} Unseals vault memory buffer.
- POST /v1/sys/enroll       -> {"project": "str", "name": "str", "allowed_paths": ["str"], "capabilities": ["read"]}
- GET  /v1/secret/*path     -> Retrieves decrypted secret. Validates X-Vault-Token against allowed_paths.
- PUT  /v1/secret/*path     -> Stores encrypted secret with AES-256-GCM.