Esta es la afirmación fundamental y es defendible hoy contra el compromiso del agente, la inyección de indicaciones, el robo de registros y la exfiltración de habilidades.
Lea [docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/HEAD/docs/THREAT-MODEL.md) para conocer la división honesta entre lo que está cubierto y lo que no, incluido el nivel donde la afirmación más fuerte de "el compromiso del anfitrión no filtra nada" se vuelve alcanzable.

La bóveda en sí (cifrada en reposo, clave derivada de una frase de contraseña) es un componente real y la razón por la que el cortafuegos puede ejecutarse en una sola máquina. El próximo nivel [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/HEAD/docs/HOSTED-TIER.md) además envuelve el proxy en un enclave de cómputo confidencial para que incluso un VPS completamente comprometido no pueda leer la clave.

[![Crates.io](https://img.shields.io/crates/v/wardn.svg)](https://crates.io/crates/wardn)
[![License](https://img.shields.io/crates/l/wardn.svg)](LICENSE)

## El Problema

Cada framework de agente de IA hoy almacena claves API en variables de entorno o archivos `.env`. Un agente comprometido, una habilidad maliciosa, un ladrón de credenciales común o una inyección de indicaciones que exfiltre `Authorization: Bearer sk-...` de un registro de LLM obtiene acceso completo a sus credenciales.```
~/.env              → OPENAI_KEY=sk-proj-real-key      # plaintext, readable by anyone
agent context       → "Use OPENAI_KEY=sk-proj-real-key" # leaked into LLM context window
agent logs          → Authorization: Bearer sk-proj-... # sitting in log files

## Arquitectura```mermaid
flowchart TB
    subgraph Agent["AI Agent Process"]
        A1["Agent Code"]
        A2["ENV: OPENAI_KEY=wdn_placeholder_a1b2..."]
    end

    subgraph Wardn["wardn daemon · localhost:7777"]
        direction TB
        P["HTTP Proxy"]
        MCP["MCP Server\n(stdio)"]

        subgraph Pipeline["Request Pipeline"]
            direction LR
            S1["Identify\nAgent"] --> S2["Resolve\nPlaceholder"] --> S3["Check\nAuth"] --> S4["Rate\nLimit"] --> S5["Inject\nReal Key"]
        end

        subgraph ResponsePipeline["Response Pipeline"]
            direction RL
            R1["Strip Real\nKeys"] --> R2["Replace with\nPlaceholders"]
        end

        subgraph Vault["Encrypted Vault"]
            V1["AES-256-GCM"]
            V2["Argon2id KDF"]
            V3["Placeholder Map\nper agent × credential"]
        end
    end

    subgraph External["External APIs"]
        E1["api.openai.com"]
        E2["api.anthropic.com"]
        E3["..."]
    end

    A1 -- "placeholder token\nin headers/body" --> P
    A1 -. "MCP: get_credential_ref\nlist_credentials\ncheck_rate_limit" .-> MCP
    MCP -. "placeholder token\n(never real keys)" .-> A1
    P --> Pipeline
    Pipeline --> External
    External --> ResponsePipeline
    ResponsePipeline -- "response with\nplaceholders only" --> A1
    Pipeline <--> Vault
    ResponsePipeline <--> Vault

    style Agent fill:#1a1a2e,stroke:#e94560,color:#fff
    style Wardn fill:#0f3460,stroke:#16213e,color:#fff
    style Pipeline fill:#16213e,stroke:#e94560,color:#fff
    style ResponsePipeline fill:#16213e,stroke:#e94560,color:#fff
    style Vault fill:#1a1a2e,stroke:#00d2ff,color:#fff
    style External fill:#0a0a0a,stroke:#533483,color:#fff

## Demostración

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/12823/1fa6109ffd855ec98c173c5edd2d7ee77f6b0c918a3cdecb1ea5fbfe8326161d.gif" alt="demostración de wardn" width="800">
</p>

## Niveles de Confianza, Honestamente

| Nivel | Dónde | Qué ofrece |
|---|---|---|
| **Autoalojado (hoy)** | tu portátil, tu VPS, CI | Bóveda cifrada en reposo, reclamo de firewall contra agentes. **No** defiende contra root en el anfitrión. |
| **Alojado (próximamente)** | gestionado por wardn o BYO-cloud | Entorno de computación confidencial (Nitro / SEV-SNP) + atestación remota + flujo de cifrado hacia el proxy. Afirmación real de "una compromiso del anfitrión no filtra nada". |

El nivel autoalojado es la afirmación principal y se envía hoy. El nivel alojado
es la ruta de actualización estricta: cuesta dinero y complejidad operativa, y
su diseño está en [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/HEAD/docs/HOSTED-TIER.md). Inventario completo
y honesto de lo que está y no está cubierto:

👉 **[docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/HEAD/docs/THREAT-MODEL.md)** — tabla de cubre / no cubre,
"ninguna bóveda de software elimina la compromiso del anfitrión" indicado claramente, y
la ruta de actualización.

## Instalación```bash
# Prebuilt binary (Linux/macOS, amd64/arm64), checksum-verified
curl -sSf https://raw.githubusercontent.com/rohansx/wardn/main/install.sh | sh

# or from crates.io
cargo install wardn

# or Homebrew, once the tap is published (see Formula/wardn.rb)
brew install rohansx/wardn/wardn

Eso es todo. Claude Code ahora usa el servidor MCP de wardn para obtener tokens de marcador de posición en lugar de leer claves reales de tu entorno.

### Qué sucede a continuación

1. Claude Code llama a `get_credential_ref` → obtiene `wdn_placeholder_a1b2...` (no la clave real)
2. El agente envía la solicitud con el marcador a través del proxy de wardn
3. El proxy intercambia el marcador por la clave real y la reenvía a la API
4. El proxy elimina la clave real de la respuesta antes de devolverla al agente

La clave real nunca entra en la memoria, los registros o la ventana de contexto del LLM del agente.

## Panel de control local

Una vez que el daemon esté activo (`wardn serve`, o iniciado por `wardn run`), abre
**http://127.0.0.1:7777/ui** en un navegador. Una vista de solo lectura y solo local de:

- **Credenciales** — cada credencial almacenada con sus ACL (agentes permitidos, dominios permitidos, límite de tasa + insignias de presupuesto).
- **Actividad reciente** — los últimos 50 eventos del proxy con método, dominio, ruta, estado, agente, request_id y costo registrado (`request_completed`, `credential_injected`, `rate_limit`, `budget_exceeded`, `loop_detected`, `request_error`).
- **Presupuestos** — el presupuesto configurado de cada credencial (máx., gastado, restante, ventana, modo) con una barra de progreso que cambia de advertencia a malo al cruzar el 50% / 80%.

Se sondea automáticamente cada 2 s. Sin puntos finales de mutación: la única forma
de salir del panel de control es la propia API (`/api/summary`, `/api/credentials`,
`/api/audit?limit=N`, `/api/budgets`).```bash
# Static, anonymous, never sees real keys
curl http://127.0.0.1:7777/api/summary | jq

## Referencia de CLI

### Gestión de Vault```bash
wardn vault create                        # create encrypted vault
wardn vault set OPENAI_KEY                # store credential (prompts for value, no echo)
wardn vault get OPENAI_KEY                # get placeholder token (never the real value)
wardn vault get OPENAI_KEY --agent bot    # get placeholder for specific agent
wardn vault list                          # list all credentials
wardn vault rotate OPENAI_KEY             # rotate value, placeholders unchanged
wardn vault remove OPENAI_KEY             # remove credential

# Custom vault path
wardn --vault /path/to/vault.enc vault list

### Claude Code / Integración con Cursor```bash
wardn setup claude-code                   # register wardn as MCP server in Claude Code
wardn setup cursor                        # register wardn as MCP server in Cursor

# Or manually:
claude mcp add --transport stdio --scope user wardn -- wardn serve --mcp --agent claude-code

#### Herramientas MCP disponibles

| Herramienta | Qué devuelve | Seguridad |
|-------------|--------------|-----------|
| `get_credential_ref` | Token de marcador de posición (`wdn_placeholder_...`) | Nunca el valor real |
| `list_credentials` | Nombres de credenciales + metadatos | Filtrado por acceso del agente |
| `check_rate_limit` | Cuota restante, info de reintento | Solo lectura |

### Migración de Credenciales```bash
wardn migrate --dry-run                             # audit Claude Code dir for exposed keys
wardn migrate --source claude-code                  # scan + migrate to vault
wardn migrate --source open-claw                    # scan OpenClaw config
wardn migrate --source directory --path ./my-proj   # scan any directory

Cada importador solicita la frase de contraseña de la bóveda en el primer uso (o la lee
de `WARDN_PASSPHRASE` / el llavero del SO). Los valores existentes se sobrescriben
silenciosamente — el importador es solo de valores, los metadatos (agentes permitidos /
dominios / límite de tasa / presupuesto) se conservan.

### Automatización

Para CI/scripts, configure las variables de entorno `WARDN_PASSPHRASE` y `WARDN_VALUE` para omitir los mensajes interactivos:```bash
WARDN_PASSPHRASE=my-pass wardn vault list
WARDN_PASSPHRASE=my-pass WARDN_VALUE=sk-proj-xxx wardn vault set OPENAI_KEY

### Operaciones de Vault```rust
use wardn::{Vault, config::CredentialConfig};

// Create an encrypted vault
let vault = Vault::create("vault.enc", "my-passphrase")?;

// Store a credential
vault.set_with_config("OPENAI_KEY", "sk-proj-real-key-123", &CredentialConfig {
    allowed_agents: vec!["researcher".into(), "writer".into()],
    allowed_domains: vec!["api.openai.com".into()],
    rate_limit: Some(RateLimitConfig { max_calls: 200, per: TimePeriod::Hour }),
})?;

// Agent gets a placeholder (not the real key)
let placeholder = vault.get_placeholder("OPENAI_KEY", "researcher")?;
// → "wdn_placeholder_a1b2c3d4e5f6g7h8"

// Rotate the real key — all placeholders keep working
vault.rotate("OPENAI_KEY", "sk-proj-new-key-456")?;

### MCP Server```rust
use wardn::mcp::WardenMcpServer;

// Serve over stdio (for Claude Code, Cursor, etc.)
WardenMcpServer::serve_stdio(vault, rate_limiter, "agent-id".into()).await?;

Set `RUST_LOG=wardn=info` (o `debug`/`trace`) para controlar la verbosidad. Los registros van a stderr, nunca a stdout.

## Configuración```toml
[warden]
vault_path = "~/.vibeguard/vault.enc"

[warden.credentials.OPENAI_KEY]
rate_limit = { max_calls = 200, per = "hour" }
allowed_agents = ["researcher", "writer"]
allowed_domains = ["api.openai.com"]

[warden.credentials.ANTHROPIC_KEY]
rate_limit = { max_calls = 100, per = "hour" }
allowed_agents = ["researcher"]
allowed_domains = ["api.anthropic.com"]

## Desarrollo```bash
# Integration tests use a fast (insecure) KDF so the suite runs in
# milliseconds instead of paying the real Argon2id cost per test —
# always pass this feature flag when running tests locally or in CI:
cargo test --features test-fast-kdf

cargo build
cargo clippy --all-targets --features test-fast-kdf

subgraph KDF["Key Derivation"]
    Argon["Argon2id\nm=19456 t=2 p=1"]
end

subgraph Encrypt["Encryption"]
    AES["AES-256-GCM"]
    Nonce["Random Nonce\n(12 bytes)"]
end

subgraph Output["WDNV File"]
    direction TB
    Magic["WDNV (4B)"]
    Ver["Version (2B)"]
    SaltOut["Salt (16B)"]
    Payload["Nonce ‖ Ciphertext ‖ Tag"]
end

Pass --> Argon
Salt --> Argon
Argon -- "256-bit key" --> AES
Creds --> AES
Nonce --> AES
AES --> Payload

style Input fill:#1a1a2e,stroke:#e94560,color:#fff
style KDF fill:#16213e,stroke:#00d2ff,color:#fff
style Encrypt fill:#16213e,stroke:#00d2ff,color:#fff
style Output fill:#0f3460,stroke:#533483,color:#fff

### Formato de archivo```
Bytes 0-3:   Magic "WDNV"
Bytes 4-5:   Version (u16 LE)
Bytes 6-21:  Argon2id salt (16 bytes)
Bytes 22+:   AES-256-GCM encrypted payload (nonce ‖ ciphertext ‖ tag)