​

Secret Vault

​

How It Works

# ❌ Old way — dangerous
OPENAI_API_KEY=sk-proj-abc123...
ANTHROPIC_API_KEY=sk-ant-def456...

// 1. Store an encrypted credential
await fetch("http://localhost:3200/secrets", {
  method: "POST",
  headers: {
    "X-Steward-Key": "your-tenant-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "openai-prod",
    value: "sk-proj-abc123...",
    description: "Production OpenAI API key",
  }),
});

// 2. Create a route: when an agent calls api.openai.com, inject this key
await fetch("http://localhost:3200/secrets/routes", {
  method: "POST",
  headers: {
    "X-Steward-Key": "your-tenant-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    secretId: "secret-uuid",
    hostPattern: "api.openai.com",
    pathPattern: "/*",
    injectAs: "header",
    injectKey: "Authorization",
    injectFormat: "Bearer {value}",
  }),
});

​

Encryption

STEWARD_MASTER_PASSWORD + STEWARD_KDF_SALT
    └── scrypt with the "secret-vault" domain label
          └── deployment/domain root (not stored in the database)
                └── scrypt with a fresh random salt for each record
                      └── AES-256-GCM record key
                            └── AAD: tenantId + name + version

• Secrets written before KDF domain separation may require the old undomained root. Production enables that temporary path only with STEWARD_SECRET_VAULT_LEGACY_ROOT_FALLBACK=true; migrate the full secret inventory and remove the flag as described in the rotation runbook.
• Ciphertext written before context AAD may require a no-AAD decrypt retry. STEWARD_ALLOW_LEGACY_KEYSTORE_DECRYPT_FALLBACK=true enables that retry only outside production; production ignores the flag and fails closed. Re-encrypt legacy records with context rather than treating this as a tenant-key mechanism.

​

Secret Lifecycle

curl -X POST http://localhost:3200/secrets \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "anthropic-prod",
    "value": "sk-ant-def456...",
    "description": "Anthropic production key",
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

{
  "ok": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "anthropic-prod",
    "description": "Anthropic production key",
    "version": 1,
    "expiresAt": "2027-01-01T00:00:00Z",
    "createdAt": "2026-03-26T12:00:00Z"
  }
}

curl -X POST http://localhost:3200/secrets/{id}/rotate \
  -H "X-Steward-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk-ant-new-key..." }'

curl -X DELETE http://localhost:3200/secrets/{id} \
  -H "X-Steward-Key: your-key"

​

Credential Injection

1. Decrypts the credential for the bounded outbound operation
2. Injects it according to the route config (header, query param, or body)
3. Forwards the request to the real API
4. Drops the plaintext reference after the outbound operation (JavaScript strings cannot be reliably zeroed in place)

​

Security Properties

• Secrets never leave the vault in API responses — list/get endpoints return metadata only
• Plaintext lifetime is bounded to the use callback or pinned injection path — references are dropped afterward, but JavaScript strings cannot be reliably zeroed in place
• Auditing is enforced by governed callers, not by the cipher primitive — new consumers use the pre-decrypt audit chokepoint, and the remaining direct-decrypt caller inventory is CI-pinned
• Tenant isolation — secrets are scoped to tenants; agents can only trigger decryption of their tenant’s secrets

​

Related

• Proxy Gateway — How the proxy routes and injects credentials
• Secrets API Reference — Full CRUD API
• Routes API Reference — Route configuration API
• Managing Secrets Guide — Step-by-step guide
• Root Secret Key Rotation — Offline full-inventory root and legacy migration procedure