* feat(auth): add same-provider credential pools and rotation UX Add same-provider credential pooling so Hermes can rotate across multiple credentials for a single provider, recover from exhausted credentials without jumping providers immediately, and configure that behavior directly in hermes setup. - agent/credential_pool.py: persisted per-provider credential pools - hermes auth add/list/remove/reset CLI commands - 429/402/401 recovery with pool rotation in run_agent.py - Setup wizard integration for pool strategy configuration - Auto-seeding from env vars and existing OAuth state Co-authored-by: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com> Salvaged from PR #2647 * fix(tests): prevent pool auto-seeding from host env in credential pool tests Tests for non-pool Anthropic paths and auth remove were failing when host env vars (ANTHROPIC_API_KEY) or file-backed OAuth credentials were present. The pool auto-seeding picked these up, causing unexpected pool entries in tests. - Mock _select_pool_entry in auxiliary_client OAuth flag tests - Clear Anthropic env vars and mock _seed_from_singletons in auth remove test * feat(auth): add thread safety, least_used strategy, and request counting - Add threading.Lock to CredentialPool for gateway thread safety (concurrent requests from multiple gateway sessions could race on pool state mutations without this) - Add 'least_used' rotation strategy that selects the credential with the lowest request_count, distributing load more evenly - Add request_count field to PooledCredential for usage tracking - Add mark_used() method to increment per-credential request counts - Wrap select(), mark_exhausted_and_rotate(), and try_refresh_current() with lock acquisition - Add tests: least_used selection, mark_used counting, concurrent thread safety (4 threads × 20 selects with no corruption) * feat(auth): add interactive mode for bare 'hermes auth' command When 'hermes auth' is called without a subcommand, it now launches an interactive wizard that: 1. Shows full credential pool status across all providers 2. Offers a menu: add, remove, reset cooldowns, set strategy 3. For OAuth-capable providers (anthropic, nous, openai-codex), the add flow explicitly asks 'API key or OAuth login?' — making it clear that both auth types are supported for the same provider 4. Strategy picker shows all 4 options (fill_first, round_robin, least_used, random) with the current selection marked 5. Remove flow shows entries with indices for easy selection The subcommand paths (hermes auth add/list/remove/reset) still work exactly as before for scripted/non-interactive use. * fix(tests): update runtime_provider tests for config.yaml source of truth (#4165) Tests were using OPENAI_BASE_URL env var which is no longer consulted after #4165. Updated to use model config (provider, base_url, api_key) which is the new single source of truth for custom endpoint URLs. * feat(auth): support custom endpoint credential pools keyed by provider name Custom OpenAI-compatible endpoints all share provider='custom', making the provider-keyed pool useless. Now pools for custom endpoints are keyed by 'custom:<normalized_name>' where the name comes from the custom_providers config list (auto-generated from URL hostname). - Pool key format: 'custom:together.ai', 'custom:local-(localhost:8080)' - load_pool('custom:name') seeds from custom_providers api_key AND model.api_key when base_url matches - hermes auth add/list now shows custom endpoints alongside registry providers - _resolve_openrouter_runtime and _resolve_named_custom_runtime check pool before falling back to single config key - 6 new tests covering custom pool keying, seeding, and listing * docs: add Excalidraw diagram of full credential pool flow Comprehensive architecture diagram showing: - Credential sources (env vars, auth.json OAuth, config.yaml, CLI) - Pool storage and auto-seeding - Runtime resolution paths (registry, custom, OpenRouter) - Error recovery (429 retry-then-rotate, 402 immediate, 401 refresh) - CLI management commands and strategy configuration Open at: https://excalidraw.com/#json=2Ycqhqpi6f12E_3ITyiwh,c7u9jSt5BwrmiVzHGbm87g * fix(tests): update setup wizard pool tests for unified select_provider_and_model flow The setup wizard now delegates to select_provider_and_model() instead of using its own prompt_choice-based provider picker. Tests needed: - Mock select_provider_and_model as no-op (provider pre-written to config) - Call _stub_tts BEFORE custom prompt_choice mock (it overwrites it) - Pre-write model.provider to config so the pool step is reached * docs: add comprehensive credential pool documentation - New page: website/docs/user-guide/features/credential-pools.md Full guide covering quick start, CLI commands, rotation strategies, error recovery, custom endpoint pools, auto-discovery, thread safety, architecture, and storage format. - Updated fallback-providers.md to reference credential pools as the first layer of resilience (same-provider rotation before cross-provider) - Added hermes auth to CLI commands reference with usage examples - Added credential_pool_strategies to configuration guide * chore: remove excalidraw diagram from repo (external link only) * refactor: simplify credential pool code — extract helpers, collapse extras, dedup patterns - _load_config_safe(): replace 4 identical try/except/import blocks - _iter_custom_providers(): shared generator for custom provider iteration - PooledCredential.extra dict: collapse 11 round-trip-only fields (token_type, scope, client_id, portal_base_url, obtained_at, expires_in, agent_key_id, agent_key_expires_in, agent_key_reused, agent_key_obtained_at, tls) into a single extra dict with __getattr__ for backward-compatible access - _available_entries(): shared exhaustion-check between select and peek - Dedup anthropic OAuth seeding (hermes_pkce + claude_code identical) - SimpleNamespace replaces class _Args boilerplate in auth_commands - _try_resolve_from_custom_pool(): shared pool-check in runtime_provider Net -17 lines. All 383 targeted tests pass. --------- Co-authored-by: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
392 lines
13 KiB
Python
392 lines
13 KiB
Python
"""Tests for auth subcommands backed by the credential pool."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import base64
|
|
import json
|
|
|
|
import pytest
|
|
|
|
|
|
def _write_auth_store(tmp_path, payload: dict) -> None:
|
|
hermes_home = tmp_path / "hermes"
|
|
hermes_home.mkdir(parents=True, exist_ok=True)
|
|
(hermes_home / "auth.json").write_text(json.dumps(payload, indent=2))
|
|
|
|
|
|
def _jwt_with_email(email: str) -> str:
|
|
header = base64.urlsafe_b64encode(b'{"alg":"RS256","typ":"JWT"}').rstrip(b"=").decode()
|
|
payload = base64.urlsafe_b64encode(
|
|
json.dumps({"email": email}).encode()
|
|
).rstrip(b"=").decode()
|
|
return f"{header}.{payload}.signature"
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _clear_provider_env(monkeypatch):
|
|
for key in (
|
|
"OPENROUTER_API_KEY",
|
|
"OPENAI_API_KEY",
|
|
"ANTHROPIC_API_KEY",
|
|
"ANTHROPIC_TOKEN",
|
|
"CLAUDE_CODE_OAUTH_TOKEN",
|
|
):
|
|
monkeypatch.delenv(key, raising=False)
|
|
|
|
|
|
def test_auth_add_api_key_persists_manual_entry(tmp_path, monkeypatch):
|
|
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes"))
|
|
monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
|
|
monkeypatch.delenv("OPENAI_API_KEY", raising=False)
|
|
_write_auth_store(tmp_path, {"version": 1, "providers": {}})
|
|
|
|
from hermes_cli.auth_commands import auth_add_command
|
|
|
|
class _Args:
|
|
provider = "openrouter"
|
|
auth_type = "api-key"
|
|
api_key = "sk-or-manual"
|
|
label = "personal"
|
|
|
|
auth_add_command(_Args())
|
|
|
|
payload = json.loads((tmp_path / "hermes" / "auth.json").read_text())
|
|
entries = payload["credential_pool"]["openrouter"]
|
|
entry = next(item for item in entries if item["source"] == "manual")
|
|
assert entry["label"] == "personal"
|
|
assert entry["auth_type"] == "api_key"
|
|
assert entry["source"] == "manual"
|
|
assert entry["access_token"] == "sk-or-manual"
|
|
|
|
|
|
def test_auth_add_anthropic_oauth_persists_pool_entry(tmp_path, monkeypatch):
|
|
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes"))
|
|
monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
|
|
monkeypatch.delenv("ANTHROPIC_TOKEN", raising=False)
|
|
monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)
|
|
_write_auth_store(tmp_path, {"version": 1, "providers": {}})
|
|
token = _jwt_with_email("claude@example.com")
|
|
monkeypatch.setattr(
|
|
"agent.anthropic_adapter.run_hermes_oauth_login_pure",
|
|
lambda: {
|
|
"access_token": token,
|
|
"refresh_token": "refresh-token",
|
|
"expires_at_ms": 1711234567000,
|
|
},
|
|
)
|
|
|
|
from hermes_cli.auth_commands import auth_add_command
|
|
|
|
class _Args:
|
|
provider = "anthropic"
|
|
auth_type = "oauth"
|
|
api_key = None
|
|
label = None
|
|
|
|
auth_add_command(_Args())
|
|
|
|
payload = json.loads((tmp_path / "hermes" / "auth.json").read_text())
|
|
entries = payload["credential_pool"]["anthropic"]
|
|
entry = next(item for item in entries if item["source"] == "manual:hermes_pkce")
|
|
assert entry["label"] == "claude@example.com"
|
|
assert entry["source"] == "manual:hermes_pkce"
|
|
assert entry["refresh_token"] == "refresh-token"
|
|
assert entry["expires_at_ms"] == 1711234567000
|
|
|
|
|
|
def test_auth_add_nous_oauth_persists_pool_entry(tmp_path, monkeypatch):
|
|
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes"))
|
|
_write_auth_store(tmp_path, {"version": 1, "providers": {}})
|
|
token = _jwt_with_email("nous@example.com")
|
|
monkeypatch.setattr(
|
|
"hermes_cli.auth._nous_device_code_login",
|
|
lambda **kwargs: {
|
|
"portal_base_url": "https://portal.example.com",
|
|
"inference_base_url": "https://inference.example.com/v1",
|
|
"client_id": "hermes-cli",
|
|
"scope": "inference:mint_agent_key",
|
|
"token_type": "Bearer",
|
|
"access_token": token,
|
|
"refresh_token": "refresh-token",
|
|
"obtained_at": "2026-03-23T10:00:00+00:00",
|
|
"expires_at": "2026-03-23T11:00:00+00:00",
|
|
"expires_in": 3600,
|
|
"agent_key": "ak-test",
|
|
"agent_key_id": "ak-id",
|
|
"agent_key_expires_at": "2026-03-23T10:30:00+00:00",
|
|
"agent_key_expires_in": 1800,
|
|
"agent_key_reused": False,
|
|
"agent_key_obtained_at": "2026-03-23T10:00:10+00:00",
|
|
"tls": {"insecure": False, "ca_bundle": None},
|
|
},
|
|
)
|
|
|
|
from hermes_cli.auth_commands import auth_add_command
|
|
|
|
class _Args:
|
|
provider = "nous"
|
|
auth_type = "oauth"
|
|
api_key = None
|
|
label = None
|
|
portal_url = None
|
|
inference_url = None
|
|
client_id = None
|
|
scope = None
|
|
no_browser = False
|
|
timeout = None
|
|
insecure = False
|
|
ca_bundle = None
|
|
|
|
auth_add_command(_Args())
|
|
|
|
payload = json.loads((tmp_path / "hermes" / "auth.json").read_text())
|
|
entries = payload["credential_pool"]["nous"]
|
|
entry = next(item for item in entries if item["source"] == "manual:device_code")
|
|
assert entry["label"] == "nous@example.com"
|
|
assert entry["source"] == "manual:device_code"
|
|
assert entry["agent_key"] == "ak-test"
|
|
assert entry["portal_base_url"] == "https://portal.example.com"
|
|
|
|
|
|
def test_auth_add_codex_oauth_persists_pool_entry(tmp_path, monkeypatch):
|
|
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes"))
|
|
_write_auth_store(tmp_path, {"version": 1, "providers": {}})
|
|
token = _jwt_with_email("codex@example.com")
|
|
monkeypatch.setattr(
|
|
"hermes_cli.auth._codex_device_code_login",
|
|
lambda: {
|
|
"tokens": {
|
|
"access_token": token,
|
|
"refresh_token": "refresh-token",
|
|
},
|
|
"base_url": "https://chatgpt.com/backend-api/codex",
|
|
"last_refresh": "2026-03-23T10:00:00Z",
|
|
},
|
|
)
|
|
|
|
from hermes_cli.auth_commands import auth_add_command
|
|
|
|
class _Args:
|
|
provider = "openai-codex"
|
|
auth_type = "oauth"
|
|
api_key = None
|
|
label = None
|
|
|
|
auth_add_command(_Args())
|
|
|
|
payload = json.loads((tmp_path / "hermes" / "auth.json").read_text())
|
|
entries = payload["credential_pool"]["openai-codex"]
|
|
entry = next(item for item in entries if item["source"] == "manual:device_code")
|
|
assert entry["label"] == "codex@example.com"
|
|
assert entry["source"] == "manual:device_code"
|
|
assert entry["refresh_token"] == "refresh-token"
|
|
assert entry["base_url"] == "https://chatgpt.com/backend-api/codex"
|
|
|
|
|
|
def test_auth_remove_reindexes_priorities(tmp_path, monkeypatch):
|
|
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes"))
|
|
# Prevent pool auto-seeding from host env vars and file-backed sources
|
|
monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
|
|
monkeypatch.delenv("ANTHROPIC_TOKEN", raising=False)
|
|
monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)
|
|
monkeypatch.setattr(
|
|
"agent.credential_pool._seed_from_singletons",
|
|
lambda provider, entries: (False, set()),
|
|
)
|
|
_write_auth_store(
|
|
tmp_path,
|
|
{
|
|
"version": 1,
|
|
"credential_pool": {
|
|
"anthropic": [
|
|
{
|
|
"id": "cred-1",
|
|
"label": "primary",
|
|
"auth_type": "api_key",
|
|
"priority": 0,
|
|
"source": "manual",
|
|
"access_token": "sk-ant-api-primary",
|
|
},
|
|
{
|
|
"id": "cred-2",
|
|
"label": "secondary",
|
|
"auth_type": "api_key",
|
|
"priority": 1,
|
|
"source": "manual",
|
|
"access_token": "sk-ant-api-secondary",
|
|
},
|
|
]
|
|
},
|
|
},
|
|
)
|
|
|
|
from hermes_cli.auth_commands import auth_remove_command
|
|
|
|
class _Args:
|
|
provider = "anthropic"
|
|
index = 1
|
|
|
|
auth_remove_command(_Args())
|
|
|
|
payload = json.loads((tmp_path / "hermes" / "auth.json").read_text())
|
|
entries = payload["credential_pool"]["anthropic"]
|
|
assert len(entries) == 1
|
|
assert entries[0]["label"] == "secondary"
|
|
assert entries[0]["priority"] == 0
|
|
|
|
|
|
def test_auth_reset_clears_provider_statuses(tmp_path, monkeypatch, capsys):
|
|
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes"))
|
|
_write_auth_store(
|
|
tmp_path,
|
|
{
|
|
"version": 1,
|
|
"credential_pool": {
|
|
"anthropic": [
|
|
{
|
|
"id": "cred-1",
|
|
"label": "primary",
|
|
"auth_type": "api_key",
|
|
"priority": 0,
|
|
"source": "manual",
|
|
"access_token": "sk-ant-api-primary",
|
|
"last_status": "exhausted",
|
|
"last_status_at": 1711230000.0,
|
|
"last_error_code": 402,
|
|
}
|
|
]
|
|
},
|
|
},
|
|
)
|
|
|
|
from hermes_cli.auth_commands import auth_reset_command
|
|
|
|
class _Args:
|
|
provider = "anthropic"
|
|
|
|
auth_reset_command(_Args())
|
|
|
|
out = capsys.readouterr().out
|
|
assert "Reset status" in out
|
|
|
|
payload = json.loads((tmp_path / "hermes" / "auth.json").read_text())
|
|
entry = payload["credential_pool"]["anthropic"][0]
|
|
assert entry["last_status"] is None
|
|
assert entry["last_status_at"] is None
|
|
assert entry["last_error_code"] is None
|
|
|
|
|
|
def test_clear_provider_auth_removes_provider_pool_entries(tmp_path, monkeypatch):
|
|
monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes"))
|
|
_write_auth_store(
|
|
tmp_path,
|
|
{
|
|
"version": 1,
|
|
"active_provider": "anthropic",
|
|
"providers": {
|
|
"anthropic": {"access_token": "legacy-token"},
|
|
},
|
|
"credential_pool": {
|
|
"anthropic": [
|
|
{
|
|
"id": "cred-1",
|
|
"label": "primary",
|
|
"auth_type": "oauth",
|
|
"priority": 0,
|
|
"source": "manual:hermes_pkce",
|
|
"access_token": "pool-token",
|
|
}
|
|
],
|
|
"openrouter": [
|
|
{
|
|
"id": "cred-2",
|
|
"label": "other-provider",
|
|
"auth_type": "api_key",
|
|
"priority": 0,
|
|
"source": "manual",
|
|
"access_token": "sk-or-test",
|
|
}
|
|
],
|
|
},
|
|
},
|
|
)
|
|
|
|
from hermes_cli.auth import clear_provider_auth
|
|
|
|
assert clear_provider_auth("anthropic") is True
|
|
|
|
payload = json.loads((tmp_path / "hermes" / "auth.json").read_text())
|
|
assert payload["active_provider"] is None
|
|
assert "anthropic" not in payload.get("providers", {})
|
|
assert "anthropic" not in payload.get("credential_pool", {})
|
|
assert "openrouter" in payload.get("credential_pool", {})
|
|
|
|
|
|
def test_auth_list_does_not_call_mutating_select(monkeypatch, capsys):
|
|
from hermes_cli.auth_commands import auth_list_command
|
|
|
|
class _Entry:
|
|
id = "cred-1"
|
|
label = "primary"
|
|
auth_type="***"
|
|
source = "manual"
|
|
last_status = None
|
|
last_error_code = None
|
|
last_status_at = None
|
|
|
|
class _Pool:
|
|
def entries(self):
|
|
return [_Entry()]
|
|
|
|
def peek(self):
|
|
return _Entry()
|
|
|
|
def select(self):
|
|
raise AssertionError("auth_list_command should not call select()")
|
|
|
|
monkeypatch.setattr(
|
|
"hermes_cli.auth_commands.load_pool",
|
|
lambda provider: _Pool() if provider == "openrouter" else type("_EmptyPool", (), {"entries": lambda self: []})(),
|
|
)
|
|
|
|
class _Args:
|
|
provider = "openrouter"
|
|
|
|
auth_list_command(_Args())
|
|
|
|
out = capsys.readouterr().out
|
|
assert "openrouter (1 credentials):" in out
|
|
assert "primary" in out
|
|
|
|
|
|
def test_auth_list_shows_exhausted_cooldown(monkeypatch, capsys):
|
|
from hermes_cli.auth_commands import auth_list_command
|
|
|
|
class _Entry:
|
|
id = "cred-1"
|
|
label = "primary"
|
|
auth_type = "api_key"
|
|
source = "manual"
|
|
last_status = "exhausted"
|
|
last_error_code = 429
|
|
last_status_at = 1000.0
|
|
|
|
class _Pool:
|
|
def entries(self):
|
|
return [_Entry()]
|
|
|
|
def peek(self):
|
|
return None
|
|
|
|
monkeypatch.setattr("hermes_cli.auth_commands.load_pool", lambda provider: _Pool())
|
|
monkeypatch.setattr("hermes_cli.auth_commands.time.time", lambda: 1030.0)
|
|
|
|
class _Args:
|
|
provider = "openrouter"
|
|
|
|
auth_list_command(_Args())
|
|
|
|
out = capsys.readouterr().out
|
|
assert "exhausted (429)" in out
|
|
assert "59m 30s left" in out
|