[SPIKE]: Explore design space for Vault support

[araujof]

Summary

Spike to determine how CPEX should integrate with HashiCorp Vault as a SecretProvider backend (see #139), and to decide on a concrete design for the Vault plugin before implementation begins.

Motivation

Vault's official client SDKs are proprietary/BUSL-licensed, which conflicts with deny.toml's strictly permissive allow list (Apache-2.0, MIT, BSD, MPL, ISC, …). Pulling a non-compliant SDK into the dependency graph would create licensing obligations for deployments that don't even use Vault, even if the feature is opt-in.

Vault exposes its own HTTP interface — HashiCorp describes it as "REST like," not a formal REST/JSON:API standard. It's JSON over HTTP with a consistent /v1/-prefixed path scheme and a documented error envelope ({"errors": [...]}), but no fixed success envelope — response shape varies per endpoint. Auth tokens are sent via X-Vault-Token or Authorization: Bearer <token>. Notably, Vault does not promise backward compatibility even on the v1 prefix, which is a real constraint on plugin design, not just a documentation footnote.

If this HTTP interface covers what we need, we can implement the plugin against it directly with a permissively-licensed HTTP client (e.g. reqwest), avoiding the SDK entirely. Vault also publishes a generated OpenAPI document (per-path via ?help=1, or the full spec via /v1/sys/internal/specs/openapi) — worth evaluating as a source for a generated client instead of hand-writing one.

Questions to Answer

1. Does Vault's HTTP interface cover what we need?

   • Secret read (KV v1/v2), authentication (token, AppRole, or other methods relevant to CPEX deployments), and renewal/lease handling.
   • Any gaps that would force us back toward an SDK?

2. How do we manage the no-backward-compatibility risk?

   • Vault reserves the right to change v1 endpoints without notice. Do we pin against a specific Vault version range, hand-write a minimal client against only the endpoints we use, or lean on the OpenAPI spec to detect drift?

3. Is codegen from Vault's OpenAPI spec worth it?

   • Could reduce hand-maintained HTTP glue, but adds a codegen step and a dependency on the spec's stability/quality. Worth prototyping against KV + one auth method before deciding.

4. What does the plugin design look like?

   • How does VaultProvider implement the SecretProvider trait from [FEATURE]: Secret management plugin (Vault / Infisical) #139 using only HTTP calls?
   • Auth method(s) to support initially (token vs. AppRole vs. Kubernetes auth, etc.) and how credentials/tokens are supplied and refreshed.
   • Caching/TTL behavior — how do we respect Vault lease durations when refreshing cached secrets?
   • Error handling/retry behavior for transient Vault unavailability, using Vault's {"errors": [...]} envelope.
   • Cargo feature gating so the HTTP client and Vault-specific code stay out of the default build (mirroring valkey's full-only opt-in).

5. License check

   • Confirm the HTTP client and any supporting crates are on the deny.toml allow list; flag anything that needs a new entry.

Deliverable

A short design writeup (in this issue or a linked doc) covering the API surface used, versioning/compatibility approach, auth flow, caching strategy, and feature-flag structure — enough to hand off to implementation without further discovery. Feeds back into #139's SecretProvider/VaultProvider scope.

[terylt]

Hi folks,

So I think vault would fit well as a Delegation Plugin, acting as a delegator to vault after an identity is verified using the delegate function in APL.

I think there are two scenarios that I have in my mind but there could be others.

1. Agent/Workload SVID -> delegate to Vault -> Vault returns some API Key/credential combination/etc to access agentic entity (tool, LLM, resource, whatever).

This could use the SVID of the agent (caller_workload) or the gateway (this_workload) to access the vault.

It looks like Vault has a feature called dynamic secrets that turns a static, shared legacy credential into a short-lived, per-request, per-agent one — least privilege for the systems OAuth can't reach.

Example might be something like:

# Pattern 1 — workload broker
- tool: legacy_inventory_api
  authorization:
    pre_invocation:
      - "delegate(vault-broker, path: database/creds/inventory-ro, subject: caller_workload)"

2. User using agent requires external token for something like Github. User logs into Github, gets scoped token which is deposited into vault and then accessed during delegation.
   It could work as follows:
   1. Request carries the user's IdP token (subject: user) — the same JWT CPEX already
      validated for identity.
   2. CPEX presents that JWT to Vault's JWT auth (auth/jwt/login). Vault
      independently re-validates it — it does not take CPEX's word for who the user is.
   3. Vault maps sub to an entity and issues a short-TTL token with a templated policy
      scoped to that user's path.
   4. CPEX uses that token to read the one path and inject the third-party token upstream.

Potential APL example:

# --- the route (APL) ---
  - tool: github_search
    authorization:
      pre_invocation:
        - "require(role.employee)"
        - "delegate(vault-user-tokens, subject: user, key: github)"
        - "!delegation.granted: deny"        # not linked → deny (or elicit account-link)

  # --- the plugin (operator config) ---
  plugins:
    - name: vault-user-tokens
      kind: delegator/vault
      hooks: [token.delegate]
      config:
        address: https://vault.internal:8200
        auth:
          method: jwt
          role: user-tokens
          present: user                # CPEX logs in to Vault AS the resolved user
        # path templated from the VERIFIED subject — CPEX fills ${subject.id},
        # never the agent. `${key}` comes from the step (github, jira, …).
        secret_path: "secret/data/user-tokens/${subject.id}/${key}"
        inject: { header: Authorization, format: "Bearer {{token}}" }

I agree we should use an HTTP API to interact with whatever vault to avoid licensing issues.