# How Your Secrets Are Protected

Your Jetson agent handles sensitive information — API keys, passwords, email credentials. This document explains how we keep them safe, in plain language.

---

## The Short Version

Your passwords and API keys are stored in an **encrypted vault** on your device. The AI agent **never sees your actual passwords**. When it needs to call an API or log into a service, a separate "middleman" program pulls the credential from the vault and injects it — the agent only knows "use my OpenRouter account," not the actual key.

---

## How It Works (Step by Step)

```
You set up credentials once
        ↓
    ┌─────────────┐
    │  Vaultwarden │  ← Your encrypted vault (like a safe)
    │  (on device) │     Only accessible from your device
    └──────┬──────┘
           │ credentials stay here
           ↓
    ┌─────────────┐
    │  Auth Proxy  │  ← The middleman
    │  (on device) │     Pulls credentials from vault
    └──────┬──────┘     Injects them into API calls
           │ request + credentials
           ↓
    ┌─────────────┐
    │  Internet    │  ← OpenRouter, Telegram, Gmail, etc.
    │  (APIs)      │
    └─────────────┘
```

**The AI agent talks to the Auth Proxy, not directly to the internet.** It says "send this message via Telegram" and the proxy handles the authentication. The agent never holds your Telegram bot token in its memory.

---

## What's Protected

| Secret | Where It's Stored | Who Can Access It |
|--------|------------------|-------------------|
| OpenRouter API key | Encrypted vault | Auth Proxy only |
| NVIDIA NIM API key | Encrypted vault | Auth Proxy only |
| Telegram bot token | Encrypted vault | Auth Proxy only |
| Gmail app password | Encrypted vault | Auth Proxy only |
| Backup passphrase | Your records only | You only |

---

## What Happens When the Agent Needs a New Account

1. The agent decides it needs access to a new service
2. It asks the vault to **generate a password** (a random 32-character string)
3. The vault stores the password — the agent never sees it
4. The agent creates the account using the Auth Proxy
5. The Auth Proxy fills in the password during signup
6. Result: account created, password stored, agent never touched the actual secret

---

## Security Layers

### Layer 1: The Vault (Vaultwarden)
- Self-hosted Bitwarden — same technology used by millions of people
- Runs **only on your device** — your passwords never leave your Jetson
- Encrypted at rest — even if someone stole the SSD, they can't read your passwords
- Only accessible from localhost (127.0.0.1) — not reachable from the internet

### Layer 2: The Auth Proxy
- Sits between the agent and the internet
- Injects credentials into API calls so the agent doesn't handle them
- Runs only on localhost — not accessible from the network
- Logs all credential usage (without logging the actual credentials)

### Layer 3: Sentinel (Security Screen)
- Scans every outgoing message from the agent
- If the agent accidentally includes something that looks like an API key or password, Sentinel blocks it
- Catches patterns like `sk-or-`, `nvapi-`, `ghp_`, and other credential formats
- Acts as a safety net even if the other layers somehow fail

### Layer 4: Network Firewall (UFW)
- Only SSH and Tailscale traffic allowed in
- All other incoming connections blocked
- The vault and proxy are on localhost only — invisible to the network

### Layer 5: Tailscale VPN
- All remote access goes through Tailscale (encrypted WireGuard tunnel)
- Only your authorized devices can reach the Jetson
- Even on an untrusted network (coffee shop, hotel), your connection is encrypted

---

## What If Something Goes Wrong?

### "What if someone steals my Jetson?"
- The vault is encrypted — they can't read your passwords without your master password
- Tailscale will show the device as compromised — you can revoke its access
- You should change your API keys (OpenRouter, NIM) from your phone or another device

### "What if the agent gets hacked?"
- The agent can't read credentials directly — it goes through the Auth Proxy
- Sentinel blocks any credential leaks in outgoing messages
- The vault limits what the agent can access (scoped tokens)
- Worst case: revoke the agent's vault token, rotate your API keys

### "What if I forget my passwords?"
- API keys can be regenerated from the provider's website
- The backup passphrase is the one thing you must remember (or write down)
- Your backup is encrypted with that passphrase — no passphrase = no backup recovery

---

## For Technical Users

The full architecture is documented in `docs/architecture/secret-management.md`. Key details:

- **Vault:** Vaultwarden Docker container on localhost:8222
- **Auth Proxy:** Python HTTP server on localhost:8643
- **Sentinel:** Pattern-matching security screen in the agent's tool pipeline
- **Future:** BIP39 mnemonic → HKDF key derivation → LUKS-encrypted vault container
- **Future:** Shamir's Secret Sharing (2-of-3 recovery scheme)

---

*Last updated: 2026-04-04 by Claude Opus 4.6*