# HashiCorp Vault Integration

Yemaya integrates with HashiCorp Vault for secure secret management in
production environments.

## Overview

Vault provides:

- Centralized secret storage
- Dynamic credentials
- Automatic secret rotation
- Comprehensive audit logging
- Fine-grained access control

## Quick Start (Development)

Start Vault in development mode:

```bash
# Start Vault with other services
docker compose --profile vault up -d

# Vault is available at http://localhost:8200
# Dev token: yemaya-dev-token
```

Access the Vault UI at http://localhost:8200 and log in with token
`yemaya-dev-token`.

## Architecture

### Secret Paths

Yemaya uses the following secret paths under `secret/yemaya/`:

| Path           | Description                |
| -------------- | -------------------------- |
| `database`     | Database credentials       |
| `redis`        | Redis connection info      |
| `storage`      | MinIO/S3 credentials       |
| `auth/jwt`     | JWT signing keys           |
| `auth/session` | Session secrets            |
| `oauth/*`      | OAuth provider credentials |
| `ai/*`         | AI provider API keys       |
| `email`        | SMTP credentials           |
| `encryption`   | Master encryption key      |

### Access Policies

| Policy            | Description        | Use Case        |
| ----------------- | ------------------ | --------------- |
| `yemaya-api`      | API service access | Web/API servers |
| `yemaya-workers`  | Worker access      | Background jobs |
| `yemaya-admin`    | Full admin access  | Operators       |
| `yemaya-readonly` | Read-only metadata | Monitoring      |

## Authentication Methods

### 1. Token Authentication (Development)

```typescript
import { VaultClient } from '@yemaya/core';

const vault = new VaultClient({
  address: 'http://localhost:8200',
  auth: { method: 'token', token: 'yemaya-dev-token' },
});
```

### 2. AppRole Authentication (Production)

AppRole is recommended for service-to-service authentication.

```typescript
const vault = new VaultClient({
  address: 'https://vault.yemaya.io:8200',
  auth: {
    method: 'approle',
    roleId: process.env.VAULT_ROLE_ID!,
    secretId: process.env.VAULT_SECRET_ID!,
  },
});
```

#### Setting Up AppRole

```bash
# Get Role ID (can be shared)
vault read auth/approle/role/yemaya-api/role-id

# Generate Secret ID (keep secret!)
vault write -f auth/approle/role/yemaya-api/secret-id
```

### 3. Kubernetes Authentication (K8s)

For Kubernetes deployments:

```typescript
const vault = new VaultClient({
  address: 'https://vault.yemaya.io:8200',
  auth: {
    method: 'kubernetes',
    role: 'yemaya-api',
  },
});
```

## Using the Vault Client

### Get Secrets

```typescript
import { createSecretsProvider, CachingSecretsProvider } from '@yemaya/core';

// Create provider (auto-detects Vault or falls back to env vars)
const secrets = createSecretsProvider();

// With caching
const cachedSecrets = new CachingSecretsProvider(secrets, {
  defaultTTL: 300, // 5 minutes
  backgroundRefresh: true,
});

// Get a secret
const dbSecret = await cachedSecrets.getSecret('yemaya/database');
console.log(dbSecret.url);

// Get a specific value
const jwtSecret = await cachedSecrets.getSecretValue(
  'yemaya/auth/jwt',
  'secret'
);
```

### Write Secrets (Admin Only)

```typescript
const vault = new VaultClient({
  address: 'http://localhost:8200',
  auth: { method: 'token', token: adminToken },
});

await vault.putSecret('yemaya/ai/anthropic', {
  api_key: 'sk-ant-...',
  model: 'claude-3-5-sonnet-20241022',
});
```

### List Secrets

```typescript
const keys = await vault.listSecrets('yemaya/');
// ['database', 'redis', 'storage', ...]
```

## Environment Variables

Configure Vault connection via environment:

| Variable          | Description                  |
| ----------------- | ---------------------------- |
| `VAULT_ADDR`      | Vault server address         |
| `VAULT_TOKEN`     | Token for auth               |
| `VAULT_ROLE_ID`   | AppRole role ID              |
| `VAULT_SECRET_ID` | AppRole secret ID            |
| `VAULT_K8S_ROLE`  | Kubernetes auth role         |
| `VAULT_NAMESPACE` | Vault namespace (Enterprise) |

## Production Setup

### 1. Configure Storage Backend

For production, use a highly-available storage backend:

```hcl
# infrastructure/vault/config/vault-prod.hcl

storage "postgresql" {
  connection_url = "postgres://vault:password@postgres:5432/vault"
  ha_enabled     = true
}
```

Or use cloud storage:

- AWS: `storage "s3" { ... }`
- GCP: `storage "gcs" { ... }`
- Azure: `storage "azure" { ... }`

### 2. Enable TLS

```hcl
listener "tcp" {
  address       = "0.0.0.0:8200"
  tls_cert_file = "/vault/tls/vault.crt"
  tls_key_file  = "/vault/tls/vault.key"
}
```

### 3. Configure Auto-Unseal

Use cloud KMS for automatic unsealing:

```hcl
# AWS KMS
seal "awskms" {
  region     = "us-east-1"
  kms_key_id = "alias/vault-unseal-key"
}
```

### 4. Enable Audit Logging

```bash
vault audit enable file file_path=/vault/logs/audit.log
```

### 5. Apply Policies

```bash
# Apply Yemaya policies
vault policy write yemaya-api /vault/policies/yemaya-api.hcl
vault policy write yemaya-workers /vault/policies/yemaya-workers.hcl
vault policy write yemaya-admin /vault/policies/yemaya-admin.hcl
```

### 6. Configure AppRole

```bash
# Enable AppRole auth
vault auth enable approle

# Create roles
vault write auth/approle/role/yemaya-api \
  token_policies="yemaya-api" \
  token_ttl=1h \
  token_max_ttl=24h

vault write auth/approle/role/yemaya-workers \
  token_policies="yemaya-workers" \
  token_ttl=1h \
  token_max_ttl=24h
```

## Dynamic Database Credentials

Vault can generate short-lived database credentials:

### Setup

```bash
# Enable database secrets engine
vault secrets enable database

# Configure PostgreSQL connection
vault write database/config/yemaya-postgres \
  plugin_name=postgresql-database-plugin \
  connection_url="postgresql://{{username}}:{{password}}@postgres:5432/yemaya" \
  allowed_roles="yemaya-api,yemaya-worker" \
  username="vault" \
  password="vault-password"

# Create roles
vault write database/roles/yemaya-api \
  db_name=yemaya-postgres \
  creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
  default_ttl="1h" \
  max_ttl="24h"
```

### Usage

```typescript
// Get dynamic credentials
const creds = await vault.request('GET', '/v1/database/creds/yemaya-api');
// { username: 'v-approle-yemaya-api-...', password: '...', lease_id: '...' }
```

## Secret Rotation

### Manual Rotation

```bash
# Rotate a secret
vault kv put secret/yemaya/auth/jwt \
  secret=$(openssl rand -base64 48)
```

### Automatic Rotation

Configure TTLs on dynamic secrets:

```bash
vault write auth/token/roles/yemaya-api \
  allowed_policies="yemaya-api" \
  period="1h" \
  renewable=true
```

## Monitoring

### Health Check

```typescript
const health = await vault.health();
// { initialized: true, sealed: false, standby: false, version: '1.15.0' }
```

### Metrics

Vault exposes Prometheus metrics at `/v1/sys/metrics`.

## Security Best Practices

1. **Never use dev mode in production** - Use proper storage and unsealing
2. **Enable TLS** - Always use HTTPS for Vault communication
3. **Use AppRole or K8s auth** - Avoid long-lived tokens
4. **Enable audit logging** - Required for compliance
5. **Rotate secrets regularly** - Use short TTLs and dynamic credentials
6. **Limit access** - Apply principle of least privilege
7. **Monitor access** - Alert on unusual patterns
8. **Backup regularly** - Include Vault in disaster recovery

## Troubleshooting

### "Vault is sealed"

```bash
# Check seal status
vault status

# Unseal (manual mode)
vault operator unseal <key1>
vault operator unseal <key2>
vault operator unseal <key3>
```

### "Permission denied"

- Check token has required policy
- Verify policy includes the path
- Check policy syntax

### "Connection refused"

- Verify `VAULT_ADDR` is correct
- Check Vault is running: `vault status`
- Verify network connectivity

## Related Documentation

- [Environment Variables](./ENVIRONMENT_VARIABLES.md)
- [Encryption](./ENCRYPTION.md)
- [Docker Secrets](../docker/secrets/README.md)
