This is the load-bearing claim and it's defensible today against agent
compromise, prompt injection, log theft, and skill exfiltration.
Read [docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/main/docs/THREAT-MODEL.md) for the honest split
between what is covered and what isn't — including the tier where the
stronger "host compromise leaks nothing" claim becomes reachable.

The vault itself (encrypted at rest, passphrase-derived key) is a real
component and the reason the firewall can run on a single machine. The
upcoming [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/main/docs/HOSTED-TIER.md) tier additionally
wraps the proxy in a confidential-compute enclave so even a fully
compromised VPS cannot read the key.

[![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)

## The Problem

Every AI agent framework today stores API keys in environment variables or
`.env` files. A compromised agent, malicious skill, commodity stealer, or
prompt injection exfiltrating `Authorization: Bearer sk-...` from an LLM
log gets full access to your credentials.```
~/.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

## Architettura```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

## Demo

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

## Livelli di Fiducia, Onestamente

| Tier | Dove | Cosa garantisce |
|---|---|---|
| **Self-host (oggi)** | tuo laptop, tuo VPS, CI | Vault crittografato a riposo, protezione firewall contro gli agenti. **Non** difende contro root sull'host. |
| **Hosted (in arrivo)** | gestito da wardn o BYO-cloud | Enclave di calcolo confidenziale (Nitro / SEV-SNP) + attestazione remota + flusso di crittografia verso il proxy. Affermazione reale "il compromesso dell'host non rivela nulla". |

Il livello Self-host è la rivendicazione portante ed è disponibile oggi. Il livello Hosted
è il percorso di aggiornamento rigoroso: costa denaro e complessità operativa, e
il suo design è in [docs/HOSTED-TIER.md](https://github.com/rohansx/wardn/blob/main/docs/HOSTED-TIER.md). Inventario completo e onesto
di cosa è e non è coperto:

👉 **[docs/THREAT-MODEL.md](https://github.com/rohansx/wardn/blob/main/docs/THREAT-MODEL.md)** — tabella copre / non copre,
"nessun vault software elimina il compromesso dell'host" chiamato chiaramente, e
il percorso di aggiornamento.

## Install```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

Ecco fatto. Ora Claude Code utilizza il server MCP di wardn per ottenere token segnaposto invece di leggere le chiavi reali dal tuo ambiente.

### Cosa succede dopo

1. Claude Code chiama `get_credential_ref` → ottiene `wdn_placeholder_a1b2...` (non la chiave reale)
2. L'agente invia la richiesta con il segnaposto attraverso il proxy wardn
3. Il proxy sostituisce il segnaposto con la chiave reale, inoltra all'API
4. Il proxy rimuove la chiave reale dalla risposta prima di restituirla all'agente

La chiave reale non entra mai nella memoria dell'agente, nei log o nella finestra di contesto dell'LLM.

## Dashboard locale

Una volta che il demone è attivo (`wardn serve`, o avviato da `wardn run`), apri
**http://127.0.0.1:7777/ui** in un browser. Una vista in sola lettura, solo locale di:

- **Credenziali** — ogni credenziale memorizzata con le sue ACL (agenti consentiti,
  domini consentiti, limiti di frequenza + badge di budget).
- **Attività recente** — gli ultimi 50 eventi proxy con metodo, dominio,
  percorso, stato, agente, request_id e costo registrato (`request_completed`,
  `credential_injected`, `rate_limit`, `budget_exceeded`, `loop_detected`,
  `request_error`).
- **Budget** — ogni budget configurato della credenziale (massimo, speso,
  rimanente, finestra, modalità) con una barra di avanzamento che diventa warn → bad quando
  supera il 50% / 80%.

Aggiornato automaticamente ogni 2 secondi. Nessun endpoint di mutazione — l'unica via
d'uscita dal dashboard è l'API stessa (`/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

## Riferimento CLI

### Gestione del 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 / Integrazione 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

#### Strumenti MCP disponibili

| Strumento | Cosa restituisce | Sicurezza |
|------|----------------|----------|
| `get_credential_ref` | Token segnaposto (`wdn_placeholder_...`) | Mai il valore reale |
| `list_credentials` | Nomi delle credenziali + metadati | Filtrato dall'accesso dell'agente |
| `check_rate_limit` | Quota rimanente, info sul retry | Sola lettura |

### Migrazione delle credenziali```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

Ogni importatore richiede la passphrase del vault al primo utilizzo (oppure la legge
da `WARDN_PASSPHRASE` / dal portachiavi del sistema operativo). I valori esistenti vengono sovrascritti
silenziosamente — l'importatore è solo valore, i metadati (agenti consentiti /
domini / limite di velocità / budget) vengono preservati.

### Automation

Per CI/script, impostare le variabili d'ambiente `WARDN_PASSPHRASE` e `WARDN_VALUE` per saltare i prompt interattivi:```bash
WARDN_PASSPHRASE=my-pass wardn vault list
WARDN_PASSPHRASE=my-pass WARDN_VALUE=sk-proj-xxx wardn vault set OPENAI_KEY

### Operazioni di 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?;

Imposta `RUST_LOG=wardn=info` (o `debug`/`trace`) per controllare la verbosità. I log vanno su stderr, mai su stdout.

## Configurazione```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"]

## Sviluppo```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 File```
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)