hermes - 💡(How to fix) Fix Proposal: generic OAuth broker credential source [1 pull requests]

Problem

Some OAuth-backed providers use single-use rotating refresh tokens. When Hermes runs in more than one runtime, copying the same refresh token into multiple auth stores lets more than one process act as a refresh authority. The first refresh rotates the token; the next runtime can then fail with a consumed/invalid refresh token.

Proposal

Add a generic oauth_broker credential-pool source. Hermes would keep only a short-lived access token locally and ask a configured broker endpoint for fresh runtime credentials when the cached token is missing, past refresh_after, near expiry, or after a forced auth retry.

This is intentionally not tied to any specific deployment platform. A broker can be any service that owns OAuth refresh state and returns an access token/API key for a provider + credential id.

Contract

Hermes sends:

{
  "provider": "openai-codex",
  "credential_id": "team-codex",
  "subject": "connection_123",
  "force": false
}

The broker returns access_token or api_key, plus optional fields like base_url, expires_at, expires_at_ms, refresh_after, inference_base_url, or provider-specific runtime keys.

Security model

Hermes never stores the broker-owned refresh token for these entries. Broker auth is supplied through an env var containing JSON headers, so deployments can use their own runtime token, mTLS proxy, local sidecar, or other policy layer.

Draft implementation

I have a draft PR ready that keeps the change scoped to agent/credential_pool.py, adds focused credential-pool tests, and documents the JSON contract.