fix(mcp): isolate OAuth credentials by authenticated requester

[yu-iskw]

What does this PR do?

Shared Hermes gateways stored MCP OAuth tokens per profile + server ($HERMES_HOME/mcp-tokens/<server>.json). On a multi-user gateway, Alice’s GitHub (or other OAuth) credential could be reused for Bob.

This PR adds an explicit mcp.oauth.identity_mode setting:

• shared (default, absent key): existing layout and behavior. Single-user CLI/TUI/desktop keep working with no config change.
• per_user: tokens and live connections are isolated by a bound requester principal (v1, platform, scope_id, user_id) from session ContextVars only — never os.environ, never tool arguments. Persistence keys are u-v1- + SHA-256 of that tuple, so raw user IDs never appear in paths.

per_user fails closed when no principal is bound (CLI, TUI, desktop, and cron). Invalid values such as per-user are rejected rather than silently falling back to shared. Credential lookups use an exact registry token; they never fall back to “any connection named github.”

This is a native implementation of #78174, not a transplant of #79449. Headless consent UX (#78169) is out of scope.

Related Issue

Fixes NousResearch/hermes-agent#78174

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/mcp_oauth_identity.py — typed principal/scope, fail-closed resolver, opaque persistence keys, exact registry tokens
• gateway/session_context.py — get_bound_session_principal() / apply_bound_session_principal(); never reads os.environ for OAuth identity
• tools/mcp_oauth.py — HermesTokenStorage pins hermes_home + scope; per_user layout under mcp-tokens/by-user/<digest>/; admin all_identities wipe for hermes mcp remove
• tools/mcp_oauth_manager.py — provider cache keyed by (home, server, persistence_key); _key is a pure tuple (no ambient re-resolve)
• tools/mcp_tool.py — fail-closed _oauth_call_target; live maps use exact keys; MCP-loop hops re-bind the caller principal; startup does not pick a shared human credential in per_user; /reload-mcp uses reload_mcp_connections() so a bound per_user requester cannot disconnect another principal’s OAuth session
• tools/mcp_schema_cache.py — private list/schema cache entries are principal-scoped; cacheScope=public stays unscoped; get_startup_cached_entry() republishes tool names from any matching scoped cache without selecting credentials
• hermes_cli/config_defaults.py, cli-config.yaml.example, website/docs/user-guide/features/mcp.md — mcp.oauth.identity_mode
• docs/rfc/requester-scoped-mcp-oauth.md — locked decisions
• Tests: tests/tools/test_mcp_oauth_identity.py, tests/tools/test_mcp_oauth_per_user.py, tests/tools/test_mcp_loop_session_principal.py

Review follow-ups (Codex on #2)

• Unbound per_user startup loads a requester-scoped schema cache so MCP tool names survive a gateway restart (schemas only; never used as a credential selector). Bound /reload-mcp no longer skips a lazy template whose tools were never published.
• _deregister_tools keeps a name registered while another live connection for the same logical server still lists it, or while the cache-backed lazy template still lists it.
• _oauth_protected_servers is add-or-discard per server in the current register batch, and is cleared on shutdown_mcp_servers(), so auth: oauth → header/none on reload does not stay requester-scoped.
• /reload-mcp (gateway, CLI, TUI) calls reload_mcp_connections() instead of a process-wide shutdown_mcp_servers(). In per_user with a bound requester, Alice’s OAuth connections, process-level non-OAuth servers, and every identity of a server removed from config.yaml are recycled; Bob’s live OAuth session stays up. Shared mode and unbound CLI/TUI still take the full wipe path. Process-exit teardown still calls shutdown_mcp_servers().
• Full shutdown (including the no-live-servers fast path) and scoped reload purge cache-backed lazy templates so a server deleted from config cannot remain callable after _deregister_tools started preserving those cache names.
• _refresh_tools (tools/list_changed) no longer globally deregisters a name another principal’s live connection still advertises. Lazy-cache names are not treated as ownership on the live-refresh path, so a truly deleted tool still drops when no sibling holds it.

How to Test

1. Confirm the confused-deputy class is covered: with mcp.oauth.identity_mode: per_user, Alice and Bob bound as different gateway requesters must get distinct token paths and must not share a live MCP connection. A call with no bound principal must fail closed rather than using Alice’s token.
2. Confirm the default is unchanged: omit mcp.oauth.identity_mode (or set shared) and existing $HERMES_HOME/mcp-tokens/<server>.json login/reuse still works.
3. Confirm /reload-mcp in per_user: Alice’s reload must not close Bob’s live OAuth connection; a server removed from config.yaml must drop its lazy template and tool names.
4. Run the canonical suite (not raw pytest; scripts/run_tests.sh is CI-parity):

HERMES_PYTHON=/usr/bin/python3 scripts/run_tests.sh \
  tests/tools/test_mcp_oauth_identity.py \
  tests/tools/test_mcp_oauth_per_user.py \
  tests/tools/test_mcp_loop_session_principal.py \
  tests/tools/test_mcp_oauth.py \
  tests/tools/test_mcp_oauth_manager.py \
  tests/tools/test_mcp_oauth_integration.py \
  tests/tools/test_mcp_schema_cache.py \
  tests/tools/test_mcp_circuit_breaker.py \
  tests/tools/test_mcp_tool_401_handling.py \
  tests/tools/test_mcp_lazy_start.py \
  tests/tools/test_mcp_dynamic_discovery.py \
  tests/tools/test_mcp_tool.py \
  tests/tools/test_mcp_bridge_single_failure.py \
  tests/gateway/test_mcp_reload_refreshes_cached_agents.py \
  tests/tui_gateway/test_mcp_reload_rev.py \
  tests/gateway/test_session_env.py -q

Last run: 313 passed, 0 failed.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux (cloud agent)

The full tree was not run as pytest tests/ -q. The MCP OAuth / session / reload slice above was run with scripts/run_tests.sh (313 passed).

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A (docs/rfc/requester-scoped-mcp-oauth.md instead)
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A (no new core tools; no model-visible credential selector)

Screenshots / Logs

N/A — isolation is covered by unit tests (test_mcp_oauth_per_user.py, test_mcp_oauth_identity.py, test_mcp_loop_session_principal.py).