Secret management: unifying profile-scoped credential hydration across hermes-agent and hermes-webui

[shauneccles]

What this is

A proposal for how profile-scoped secret hydration should work across hermes-agent and hermes-webui. It comes out of a PR I withdrew (#7343) after two review findings turned out to be the same defect in different places — there's no single chokepoint for "resolve this profile's credentials," so every new credential reader is a chance for the next divergence.

The core finding

The agent has a cohesive model — get_secret / build_profile_secret_scope / UnscopedSecretError — but its migration stopped at the agent/ package boundary and never reached hermes_cli/, which is exactly the surface the WebUI consumes:

File	get_secret(	raw os.getenv/os.environ
hermes_cli/models.py (backs /api/models/live)	0	24
hermes_cli/auth.py (registry the WebUI's scrub set derives from)	0	56
hermes_cli/model_switch.py	1	14

So the WebUI cannot converge by adopting get_secret — the code it calls doesn't read through it. The os.environ mirror the WebUI maintains is load-bearing, not NIH. Meanwhile the WebUI runs the agent scope in non-isolating mode (never calls set_multiplex_active), so isolation rests entirely on a hand-maintained 20-name scrub denylist — any name missing from that list leaks root's credential into a named profile. A denylist doing a boundary's job.

Proposed target

Not "one read path" — that's unachievable while hermes_cli/models.py reads raw and the quota probe forks. Instead:

One resolution function. One key-authority table. One publication primitive that fans out to every channel. A shrinking set of read paths.

Four channels are irreducible (contextvar, _thread_ctx.env, os.environ, subprocess env=), so the model is four layers: policy → resolve → publish → read. The key-authority table is a single secret_policy module where scrub and hydrate become the same predicate at two moments — which is what stops them drifting (they're currently two separate, hand-maintained lists that already disagree).

Things the review surfaced that aren't design trivia

• A live leak: api/onboarding.py:1048 and :1113 write os.environ[env_var] = api_key permanently, never restored. Saving a named profile's key writes it into the server process for its lifetime. This exists today, independent of the refactor.
• Five .env parsers exist and disagree (only bootstrap.py handles export , none handle inline comments/escaped quotes/BOM, two drop empty values). Unifying them is the riskiest step because it changes values for real users.
• The quota probe subprocess (api/providers.py:1633) scrubs then re-adds .env only, so a vault-only credential is stripped and never restored.

Migration (each step shippable)

0 land the working tree → 1 one .env parser → 2 one policy table → 3 one resolver → 4 one read path → 5 fail-closed in four sub-steps (warn first, flip to raise last) → 6 migrate hermes_cli/models.py + auth.py in hermes-agent, then delete the mirror.

Step 6 is the highest leverage (it's the only step that makes the architecture actually single) and has no owner — it's an agent-side change, which is why this is a discussion here rather than just a WebUI RFC.

Two decisions already made, flagging for visibility

1. TTS keys → per-profile (currently routes.py:20051 reads raw OPENAI_API_KEY, so profile B's TTS spends profile A's quota).
2. API_SERVER_KEY → process-global (it's the process↔agent channel). Raised as hermes-agent#96920 since the agent classifies it profile-scoped.

What I'm asking

1. Is the direction right — adopt the agent's contract (not its implementation) and push the get_secret migration into hermes_cli/, or should this stay two separate systems?
2. Does the step-6 agent-side migration have a home here, or should it be an issue/RFC on hermes-agent?
3. Would an RFC under docs/rfcs/ be welcome once the direction's agreed, or is a discussion + incremental PRs the preferred path?

Happy to do the implementation work either way.

[shauneccles]

Full design doc for anyone who wants the details before weighing in: https://gist.github.com/shauneccles/b835110a3de49002edabcb57c2b23d45

It covers the get_secret adoption gap in hermes_cli/, the non-isolating-mode finding, the five divergent .env parsers, and the six-step migration with the agent-side step 6 flagged as the unowned highest-leverage piece.