# Trust Vault sidecar

Trust Vault keeps **plaintext secrets out of model context**. The LLM sees `BLW_VAULT_*` placeholders; hydrate runs only inside your cluster with session + tool binding.

## Requirements

| Variable | Purpose |
|----------|---------|
| `BLEKLINE_SIDECAR_AUTH` | Bearer token for sidecar APIs (required) |
| `BLEKLINE_VAULT_MASTER_KEY` | Envelope encryption key (64 hex or passphrase) |
| `BLEKLINE_VAULT_DATA_DIR` | Persistent volume path (default `/app/data/vault`) |

## Kubernetes

Helm chart `blekline-ingress`:

- `trustVault.enabled: true`
- `replicaCount: 1` — single writer
- `strategy.type: Recreate` — prevents dual-pod vault lock during upgrade
- `networkPolicy.enabled: true` — ingress from agent pods only

**Never** expose port 8787 via public Ingress.

## API

- `POST /v1/vault/tokenize` — `{ plaintext, sessionId, toolName, spiffeId? }` → `{ placeholder }`
- `POST /v1/vault/hydrate` — `{ placeholder, sessionId, toolName, spiffeId? }` → `{ plaintext }` or 403  
  Also accepts header `x-spiffe-id`.

## SPIFFE binding (v1)

Optional at tokenize — binds vault entry to a workload SPIFFE ID. Hydrate must present the same ID.

Global policy via env:

- `BLEKLINE_SPIFFE_REQUIRED=true`
- `BLEKLINE_SPIFFE_ALLOWED_IDS=spiffe://domain/ns/default/sa/agent`

SPIRE agent integration — roadmap. See [K8s deployment](/docs/enterprise/k8s-deployment).

## KMS

v1 uses local master key. Enterprise program: external KMS / KEK rotation runbook — contact sales.

## Status

**Shipped v1** in sidecar `0.2.0-nhim`. Source in private runtime engine; sidecar image bundles compiled module only.