[christopher-svensson-stegra]

Motivation

Allow rustguac to consume an already-issued Vault/OpenBao token maintained by an external process, such as Vault Agent or OpenBao Agent. This delegates authentication-method support and token lifecycle to that process rather than adding each auto-auth method to rustguac.

This is backend authentication, not user SSO or target credential forwarding. It does not change KV paths, folder authorization, or credential storage formats.

How it works

1. An external manager authenticates, renews/re-authenticates, and writes an unwrapped token to a protected file.
2. rustguac reopens that file for each Vault request and sends the current token as X-Vault-Token.
3. Atomic file replacement is picked up without restarting rustguac. On a 403 it rereads the file and retries once only if the token changed.

Select token_file instead of role_id or jwt_auth; conflicting configurations are rejected. No SecretID environment variable is required. rustguac does not log in, renew, revoke, or retain a cached fallback token in this mode. Missing/unreadable/empty/malformed files fail closed. Existing AppRole/JWT behavior is unchanged.

Use cases and examples

A VM using certificate-based authentication

Run Vault/OpenBao Agent as a supervised host service. Give the agent a certificate-auth identity and a least-privilege KV policy; configure its file sink at /run/vault-agent/token. rustguac only needs the sink, not the agent's private key:

[vault]
addr = "https://vault.example.com:8200"
mount = "secret"
base_path = "rustguac"
ca_cert = "/run/pki/ca.pem"
token_file = "/run/vault-agent/token"

The integration guide includes a certificate auto-auth HCL example and links to the Vault/OpenBao documentation. Other agent auto-auth methods work without further rustguac changes.

Docker Compose or another container runtime

Run the agent alongside rustguac. Share the sink directory read-write with the agent and read-only with rustguac, using compatible UIDs/GIDs and restrictive permissions. Mount the directory, not the individual file, so an atomic rename is visible. Keep the agent's bootstrap credentials in a separate mount that rustguac cannot read. The same TOML applies; this PR does not prescribe a container image or bundle an agent.

Separate shared/local backends

Each backend can consume a different token, with independently scoped policies and lifecycle managers:

[vault_shared]
addr = "https://shared-vault.example.com:8200"
token_file = "/run/shared-agent/token"

[vault_local]
addr = "https://local-vault.example.com:8200"
token_file = "/run/local-agent/token"

An existing trusted credential manager can also maintain the sink; no agent-specific protocol is required. Write a restricted temporary file in the same directory and rename it over the sink rather than modifying it in place.

Operational boundaries

The token remains a bearer credential readable by rustguac. Use a least-privilege application token, never a root token; protect the directory and consider memory-backed storage, swap and core-dump exposure. The external manager must keep the token valid: a readable file does not establish validity, and expiry/policy are enforced by Vault/OpenBao. If the manager stops, the last valid token may continue working until expiry.

Regression coverage exercises configuration for all three backend sections, conflicting modes, malformed/missing files and the size boundary, atomic replacement, absence of login/renewal requests, namespace forwarding, and bounded 403 retry behavior.