> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Hexr Vault Service

> Encrypted at-rest secret storage with per-agent SPIFFE-scoped access control.

## What It Does

Hexr Vault provides encrypted secret storage for AI agents. Secrets are:

* **Encrypted at rest** with AES-256-GCM
* **Scoped per agent** using SPIFFE ID — agents can only access their own secrets
* **Stored in PostgreSQL** (no external vault dependency)
* **Accessible via SDK** through `hexr.vault` module

***

## How Access Works

<Steps>
  <Step title="Agent requests secret">
    Your code calls `vault.get("OPENAI_API_KEY")` via the Hexr SDK.
  </Step>

  <Step title="SDK routes through Envoy">
    The SDK sends `GET /api/v1/secrets/OPENAI_API_KEY` to the Envoy proxy sidecar.
  </Step>

  <Step title="Envoy extracts SPIFFE ID">
    Envoy extracts the SPIFFE ID from the mTLS connection and adds it as the `x-hexr-spiffe-id` header.
  </Step>

  <Step title="Vault verifies scope">
    The Vault Service verifies the SPIFFE ID matches the secret's configured access scope.
  </Step>

  <Step title="Decrypt and return">
    The secret is decrypted (AES-256-GCM) and the plaintext value is returned to the agent.
  </Step>
</Steps>

```
Agent → SDK → Envoy (extract SPIFFE ID) → Vault (verify scope + AES-256 decrypt) → Plaintext value
```

***

## Scoping Model

Secrets are scoped to a SPIFFE ID prefix:

| Scope             | SPIFFE ID Pattern                                            | Who Can Access                  |
| ----------------- | ------------------------------------------------------------ | ------------------------------- |
| **Agent-level**   | `spiffe://hexr.cloud/agent/acme/research-analyst/*`          | All processes in the agent      |
| **Process-level** | `spiffe://hexr.cloud/agent/acme/research-analyst/researcher` | Only the researcher sub-process |
| **Tenant-level**  | `spiffe://hexr.cloud/agent/acme/*`                           | All agents in tenant            |

***

## Storage

| Field          | Description                          |
| -------------- | ------------------------------------ |
| `key`          | Secret name (e.g., `OPENAI_API_KEY`) |
| `value`        | AES-256-GCM encrypted bytes          |
| `nonce`        | Per-secret random nonce              |
| `spiffe_scope` | SPIFFE ID prefix for access control  |
| `created_at`   | Creation timestamp                   |
| `updated_at`   | Last update timestamp                |

Backend: PostgreSQL with the `pgcrypto` extension.

***

## API Endpoints

| Method   | Path                   | Description                   |
| -------- | ---------------------- | ----------------------------- |
| `GET`    | `/api/v1/secrets/:key` | Retrieve a secret             |
| `PUT`    | `/api/v1/secrets/:key` | Create or update a secret     |
| `DELETE` | `/api/v1/secrets/:key` | Delete a secret               |
| `GET`    | `/api/v1/secrets`      | List secret keys (not values) |
| `GET`    | `/health`              | Health check                  |

***

## Configuration

| Environment Variable | Default | Description                   |
| -------------------- | ------- | ----------------------------- |
| `DATABASE_URL`       | —       | PostgreSQL connection string  |
| `ENCRYPTION_KEY`     | —       | AES-256 master encryption key |
| `LISTEN_ADDRESS`     | `:8080` | HTTP listen address           |

***

## Image

```
us-central1-docker.pkg.dev/hexr-cloud-prod/hexr-images/hexr-vault:v0.1.1
```