How the proxy works.
What it protects against. What it doesn't.

Architecture

The proxy is a CONNECT-based HTTPS MITM proxy that runs on 127.0.0.1. An AI agent sets HTTPS_PROXY to point at it. When the agent makes an HTTPS request, the proxy intercepts the TLS connection, inspects request headers for credential references, resolves them against the Clavitor vault, and forwards the request with injected credentials to the upstream API.

Agent                    Proxy (127.0.0.1:1983)              Upstream API
  |                            |                                 |
  |--- CONNECT host:443 ----> |                                 |
  |<-- 200 OK --------------- |                                 |
  |                            |                                 |
  |== TLS (MITM cert) ======= |                                 |
  |                            |                                 |
  |--- GET /v1/models ------> |                                 |
  |    Authorization:          |                                 |
  |    Bearer clavitor://X/key |                                 |
  |                            |--- GET /v1/models ------------>|
  |                            |    Authorization:               |
  |                            |    Bearer sk-proj-abc123...     |
  |                            |                                 |
  |                            |<-- 200 OK --------------------|
  |<-- 200 OK --------------- |                                 |

The proxy is a standalone Go binary. No CGO. All Clavitor protocol cryptography routes through a canonical Rust implementation compiled to WebAssembly and loaded via wazero at startup.

TLS handling

The proxy generates a self-signed ECDSA P-256 root CA on first run, persisted at the binary's directory with mode 0600. For each upstream host, a leaf certificate is minted on-demand, signed by this CA, and cached in memory with bounded eviction (1,000 hosts). Leaf certificates are valid for 24 hours and regenerated transparently at the 23-hour mark to prevent mid-session expiry.

The agent must trust the proxy's CA certificate. Export it with clavitor-proxy ca.

Upstream connections use TLS 1.3 minimum with ALPN negotiation for HTTP/2 and HTTP/1.1. The system certificate pool is used for upstream verification. No certificate pinning — the proxy trusts whatever the OS trusts.

Credential lifecycle

Credentials are never cached, never written to disk, and never held longer than one HTTP request.

The proxy holds the agent's L2 key (16 bytes) in memory for its entire runtime. L2 is the decryption key for tier-2 vault fields. It is loaded from the encrypted sidecar config (CLV1 format) at startup and cleared on graceful shutdown. L2 never leaves the process.

The sidecar config is encrypted with AES-128-GCM and HMAC-SHA256 using deterministic keys derived from a static seed. This is obfuscation, not confidentiality — the security boundary is file permissions (0600) and possession of the file. The CLV1 format is shared between the proxy, the CLI, and the browser extension.

Resolution modes

The decision tree is deterministic: placeholder present → resolve or fail. No placeholder → URL match or passthrough. There is no silent fallback path where a failed resolution results in a request going upstream without credentials.

Agent identity

By default, the vault sees the proxy's own agent ID on every request. Rate limits, scope checks, and audit entries are attributed to the proxy.

When multiple agents share one proxy instance, the placeholder can include an agent ID: clavitor://agentid@Entry/field. The proxy sends this agent ID to the vault, which applies that agent's scopes and rate limits and logs the access against it. The agent ID is the 32-char hex value shown on the agent detail page in the vault UI.

The agent ID in the URL is not an authentication mechanism — the proxy's CVT token authenticates the connection. The agent ID determines attribution: whose scopes apply, whose rate limits count, whose audit trail records the access. The vault rejects unknown agent IDs with a loud failure.

Network security

Header handling

Hop-by-hop headers are stripped from both requests and responses per RFC 7230 §6.1: Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, TE, Trailers, Transfer-Encoding, Upgrade.

Set-Cookie is stripped from upstream responses to prevent upstreams from planting cookies in the agent's HTTP client.

Request and response bodies stream through without buffering. Request bodies are capped at 64 MB by default (CLAVITOR_PROXY_MAX_BODY_MB). Response bodies stream without a hard cap; a log warning is emitted when Content-Length exceeds 100 MB.

Field-to-header mapping

In URL-match mode, the proxy maps vault field labels to HTTP headers:

In placeholder mode, the agent controls which field is resolved and where it goes. The mapping above only applies to URL-match mode.

Error codes

Every failure produces a stable ERR-PROXY-NNN code. These codes are part of the proxy's public interface — agents and operators can match on them for alerting and debugging.

Tier-3 fields are unreachable

Vault entries support three encryption tiers. Tier-1 fields are plaintext metadata. Tier-2 fields are encrypted with L2 (the agent's key). Tier-3 fields (identity fields) are encrypted with L3 — a key the server and the proxy have never seen. Only the vault owner, via their hardware security key, can decrypt tier-3 fields.

If a placeholder references a tier-3 field, the proxy returns ERR-PROXY-035. No fallback, no partial result. The field is architecturally unreachable from the proxy.

What the proxy does not protect against

The proxy's threat model is a compromised skill or prompt injection that makes an authenticated agent harvest credentials. The vault's per-agent rate limits, unique-entries quotas, and two-strike lockdown are the primary defenses. The proxy adds a network-layer enforcement point where credentials are resolved per-request and never held by the agent.

Logging

The proxy logs one line per accepted CONNECT and emits error lines for failures. It never logs:

• Decrypted credential values
• Full request URLs (query strings may carry secrets — only scheme + host + path are logged)
• Request or response bodies
• The L2 key or sidecar config contents

When the proxy detects that a 400 response from upstream contains auth-related keywords (unauthorized, invalid token, etc.), it logs a diagnostic hint suggesting the injected credential may be stale. The response is forwarded unchanged.

Cryptography

All Clavitor protocol cryptography — AES-GCM field decryption, HKDF key derivation, base62 encoding, CVT token minting, CLV1 config pack/unpack — executes inside a single WebAssembly module (clavis_crypto.wasm) loaded via wazero, a pure-Go WASM runtime. No CGO. No Go reimplementation of Clavitor primitives.

The WASM module is compiled from the same Rust crate (clavis-crypto) used by the browser, the CLI, and the browser extensions. One source of truth, one binary, one audit surface.

The proxy uses Go's crypto/tls for the TLS wire and crypto/ecdsa for MITM certificate generation. These are transport concerns, not Clavitor protocol operations.

Configuration

Secrets (L2 key, agent ID, device ID, vault URL) live in the encrypted CLV1 sidecar config, written once during clavitor-proxy init. Operational knobs live in environment variables:

Operational knobs are not secrets. They don't belong in the encrypted config. They belong where deployment tools already manage them — the environment.

Review this yourself.

The cryptography is a single auditable WASM artifact. The threat model is documented. If you find something we missed, we want to hear about it.