Crate cellos_broker_vault 

SecretBroker that fetches secrets from HashiCorp Vault using AppRole authentication.

Overview

AppRole is the canonical machine-to-machine authentication method for Vault. The operator pre-stages a role_id and secret_id for the runner; the broker exchanges them for a short-lived Vault token at resolve time, then reads the requested secret from Vault KV v2.

Configuration

Env var	Required	Description
CELLOS_VAULT_ADDR	yes	Vault server address, e.g. https://vault.example.com
CELLOS_VAULT_ROLE_ID	yes	AppRole role_id
CELLOS_VAULT_SECRET_ID	yes	AppRole secret_id
CELLOS_VAULT_KV_MOUNT	no	KV v2 mount name (default: secret)
CELLOS_VAULT_KV_PATH_PREFIX	no	Path prefix prepended to every key (e.g. cellos/prod)
CELLOS_VAULT_NAMESPACE	no	Vault Enterprise namespace (X-Vault-Namespace header)
CELLOS_CA_BUNDLE	no	PEM CA bundle for TLS to private Vault endpoints

Secret path resolution

For resolve("DB_PASSWORD", ...), the broker reads from:

GET {CELLOS_VAULT_ADDR}/v1/{KV_MOUNT}/data/{PATH_PREFIX}/{key}

If CELLOS_VAULT_KV_PATH_PREFIX is not set, no prefix is added and the key is used directly. The data wrapper is Vault KV v2 format.

Auth flow

Classic resolve(...):

1. POST {addr}/v1/auth/approle/login with { "role_id": "...", "secret_id": "..." }
2. GET {addr}/v1/{mount}/data/{path} with X-Vault-Token: {client_token}
3. Extract data.data.{key} from the KV v2 response envelope

A fresh token is obtained for each resolve call. This avoids persistent token state in the supervisor process and ensures each secret fetch is independently authenticated. Use a use_limit=1 or short ttl policy on the AppRole if you want one-shot tokens.

runtimeLeasedBroker:

1. prepare_runtime_secret_lease(...) performs a single AppRole login for the cell
2. fetch_runtime_secret(...) reuses the cached token for on-demand KV reads
3. revoke_for_cell(...) calls /v1/auth/token/revoke-self and drops the cached token

Revocation

For classic env delivery, revocation still depends on short Vault TTLs because a raw secret has already been materialized into the child process. For runtimeLeasedBroker, revoke_for_cell actively revokes the cached Vault token and drops the local runtime channel, so future fetches fail both locally and upstream.

TLS

Honors CELLOS_CA_BUNDLE (PEM file path) for Vault endpoints behind a private CA. HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are respected automatically by reqwest.

Timeout contract (BROKER-VAULT-TIMEOUT)

The reqwest client is built with bounded request and connect timeouts so a hung Vault endpoint cannot stall a cell’s secret-resolve phase indefinitely:

• Request timeout: DEFAULT_REQUEST_TIMEOUT_MS (override via CELLOS_VAULT_TIMEOUT_MS). Default is 15 s — Vault calls are interactive (login + KV read), so a shorter ceiling than artifact upload is appropriate.
• Connect timeout: DEFAULT_CONNECT_TIMEOUT_MS (override via CELLOS_VAULT_CONNECT_TIMEOUT_MS).

Both env vars accept a positive u64 count of milliseconds; unparseable or zero values fall back to the default. The client is never constructed without explicit timeouts.

Correlation propagation (Tranche-1 seam-freeze G1)

Each cell run gets a fresh AppRole login (or a single login when runtimeLeasedBroker is active). The Vault client_token returned by that login is the natural seed for a broker-side correlation ID, but Vault tokens are sensitive material — we do not surface the token itself. SecretBroker::broker_correlation_id therefore returns None today, and the supervisor uses the operator-supplied spec.correlation.correlationId for cross-tool correlation. A future revision may emit urn:vault:lease:<accessor> once the seam-freeze consumer tools (taudit, tencrypt) commit to that shape — accessors are safe to expose because they bind to the lease’s audit log entry rather than the credential.

Structs

VaultAppRoleBroker

Vault AppRole secret broker.

Constants

DEFAULT_CONNECT_TIMEOUT_MS

Default TCP connect timeout (ms) for the underlying reqwest client.

DEFAULT_REQUEST_TIMEOUT_MS

Default total request timeout (ms) applied to every Vault HTTP call.

ENV_CONNECT_TIMEOUT_MS

Env var to override DEFAULT_CONNECT_TIMEOUT_MS.

ENV_REQUEST_TIMEOUT_MS

Env var to override DEFAULT_REQUEST_TIMEOUT_MS.

Functions

resolve_timeout_ms

Resolve a timeout in milliseconds from the named env var.