auth_plugin_providers.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419
  1. """Model-provider plugins as first-class citizens of ``hermes auth`` and the credential pool.
  2. A ``plugins/model-providers/<name>/`` profile (``providers.base.ProviderProfile``) is mirrored into
  3. ``hermes_cli.auth.PROVIDER_REGISTRY`` with the ``auth_type`` it declares, so ``resolve_provider()``
  4. accepts it whatever its auth shape. Non-api-key plugins own their login through two optional profile
  5. callables that core consults BEFORE any built-in, name-keyed path:
  6. - ``auth_handler(action, args) -> bool`` for ``hermes auth add|status|logout|refresh <name>``
  7. (``args`` is the parsed CLI namespace; truthy = the plugin owned the action, falsy = built-in path).
  8. - ``refresh_credential(entry) -> Mapping | None`` for the credential pool: given the pooled
  9. ``PooledCredential`` it returns the rotated fields (``access_token``, ``refresh_token``,
  10. ``expires_at_ms`` …) or raises. A separate hook rather than ``auth_handler("refresh", …)`` because
  11. the pool has a credential row, not an argparse namespace, and needs tokens back, not a bool.
  12. Every function here late-imports ``hermes_cli.auth`` names: this module is imported by the auth facade
  13. right after ``PROVIDER_REGISTRY`` exists, and by ``agent.credential_pool``.
  14. """
  15. from __future__ import annotations
  16. import copy
  17. import logging
  18. import threading
  19. from typing import Any, Callable, Optional
  20. logger = logging.getLogger(__name__)
  21. # Providers handled outside the registry: kimi/zai have bespoke token refresh in auth.py;
  22. # openrouter/custom are aggregator/user-supplied and runtime_provider relies on
  23. # ``openrouter not in PROVIDER_REGISTRY``.
  24. _REGISTRY_PLUGIN_SKIP = frozenset({"kimi-coding", "kimi-coding-cn", "zai", "openrouter", "custom"})
  25. PLUGIN_AUTH_ACTIONS = ("add", "status", "logout", "refresh")
  26. # Names whose PROVIDER_REGISTRY row came from a plugin profile (not the built-in rows). Only these
  27. # can be "OAuth-shaped with nobody to log them in": a bundled OAuth provider (nous, openai-codex …)
  28. # declares the same auth_type but its login lives in core.
  29. PLUGIN_MIRRORED_PROVIDERS: set[str] = set()
  30. _SYNCING = threading.local() # .active: this thread runs the pending mirror
  31. class HomeScopedRegistry(dict):
  32. """``PROVIDER_REGISTRY``: process-wide storage, each row read as the bound profile home sees it.
  33. One process serves many profile homes (multiplex gateway, Desktop ``serve``) and each home
  34. installs its own provider plugins, so no read returns a row another home rewrote: a mirrored row
  35. is hidden from a home without that provider and built from the home's own profile when only the
  36. home declares it; a ``$HERMES_HOME`` plugin's declared fields (:func:`override_registry_row`) land
  37. on a per-home copy; an alias key follows the bound home's plugin that claims it. Built-in rows a
  38. home does not override are returned as stored; writes are plain dict writes.
  39. """
  40. def _view(self, key: str, row: Any, resolve: Callable[[str], tuple]) -> Any:
  41. """*row* (stored under *key*) for the bound home; None = hidden there."""
  42. if key != row.id:
  43. claimant = resolve(key)[0]
  44. if claimant is not None and claimant.name != row.id:
  45. row = dict.get(self, claimant.name)
  46. if row is None or row.id != claimant.name:
  47. return None
  48. user, shared = resolve(row.id)
  49. mirrored = row.id in PLUGIN_MIRRORED_PROVIDERS
  50. if user is None:
  51. return row if shared is not None or not mirrored else None
  52. if row.id in _REGISTRY_PLUGIN_SKIP or not (mirrored or row.id in _builtin_ids()):
  53. return row
  54. return _home_row(row, user, from_profile=mirrored and shared is None)
  55. _sync_pending = False
  56. def sync_before_first_read(self) -> None:
  57. """Mirror plugin profiles (:func:`sync_plugin_provider_registry`) before the first read."""
  58. self._sync_pending = True
  59. def _ready(self) -> None:
  60. """Run the pending mirror on this read. No lock is held across it (it lists providers,
  61. which reads config): concurrent first readers each run the idempotent sync. Never while
  62. ``providers`` is mid-discovery: a partial profile list would mirror a provider that a
  63. later, higher-priority registration replaces (discovery's completion sync runs then)."""
  64. if not self._sync_pending or getattr(_SYNCING, "active", False):
  65. return
  66. import providers
  67. if getattr(providers, "_discovering", False):
  68. return
  69. _SYNCING.active = True # the sync reads the registry
  70. try:
  71. sync_plugin_provider_registry()
  72. finally:
  73. _SYNCING.active = False
  74. self._sync_pending = False
  75. def __getitem__(self, key: str) -> Any:
  76. self._ready()
  77. row = self._view(key, dict.__getitem__(self, key), _resolver())
  78. if row is None:
  79. raise KeyError(key)
  80. return row
  81. def get(self, key: str, default: Any = None) -> Any:
  82. self._ready()
  83. row = dict.get(self, key)
  84. row = None if row is None else self._view(key, row, _resolver())
  85. return default if row is None else row
  86. def __contains__(self, key: object) -> bool:
  87. return self.get(key) is not None
  88. def items(self) -> list[tuple[str, Any]]:
  89. self._ready()
  90. resolve = _resolver()
  91. views = ((key, self._view(key, row, resolve)) for key, row in dict.items(self))
  92. return [(key, row) for key, row in views if row is not None]
  93. def keys(self) -> list[str]:
  94. return [key for key, _ in self.items()]
  95. def values(self) -> list[Any]:
  96. return [row for _, row in self.items()]
  97. def __iter__(self):
  98. return iter(self.keys())
  99. def __len__(self) -> int:
  100. return len(self.items())
  101. def _resolver() -> Callable[[str], tuple]:
  102. from providers import bound_profile_resolver
  103. return bound_profile_resolver()
  104. def _builtin_ids() -> frozenset:
  105. from hermes_cli.auth import BUILTIN_PROVIDER_IDS
  106. return BUILTIN_PROVIDER_IDS
  107. # (id(stored row), id(home profile)) -> (stored row, home profile, that home's row). Holding both
  108. # keeps the ids from being reused; a re-imported plugin is a new profile object, so a new entry.
  109. _HOME_ROWS: dict[tuple[int, int], tuple[Any, Any, Any]] = {}
  110. def _home_row(row: Any, pp: Any, *, from_profile: bool) -> Any:
  111. """The row a home whose own plugin *pp* declares *row*'s provider reads: built from *pp* when no
  112. process-wide profile backs the row (``from_profile``), else a copy carrying *pp*'s declared fields."""
  113. cached = _HOME_ROWS.get((id(row), id(pp)))
  114. if cached is not None:
  115. return cached[2]
  116. home = _profile_row(pp) if from_profile else None
  117. if home is None:
  118. home = copy.copy(row)
  119. override_registry_row(home, pp)
  120. if len(_HOME_ROWS) >= 512:
  121. _HOME_ROWS.clear()
  122. _HOME_ROWS[(id(row), id(pp))] = (row, pp, home)
  123. return home
  124. def _api_key_env_fields(pp: Any) -> tuple[tuple, str]:
  125. """Split a profile's ``env_vars`` into (api-key vars, base-URL var); the URL var may be ""."""
  126. is_url = lambda v: v.endswith("_BASE_URL") or v.endswith("_URL")
  127. return (tuple(v for v in pp.env_vars if not is_url(v)) or pp.env_vars,
  128. next((v for v in pp.env_vars if is_url(v)), None) or "")
  129. def register_plugin_provider(pp: Any) -> None:
  130. """Mirror one profile into ``PROVIDER_REGISTRY`` under the ``auth_type`` it declares.
  131. Registering is what lets an out-of-tree provider pass ``resolve_provider()``'s known-provider
  132. gate ("Unknown provider"); OAuth-shaped plugins carry their own login via ``auth_handler``.
  133. """
  134. from hermes_cli.auth import PROVIDER_REGISTRY
  135. pconfig = _profile_row(pp)
  136. if pconfig is None:
  137. return
  138. _insert_row(PROVIDER_REGISTRY, pconfig, pp.registry_after)
  139. PLUGIN_MIRRORED_PROVIDERS.add(pp.name)
  140. mirror_aliases(pconfig, pp)
  141. def _profile_row(pp: Any) -> Optional[Any]:
  142. """The registry row *pp* declares, or None (a skipped name, an api-key profile without env vars)."""
  143. from hermes_cli.auth import ProviderConfig, _api_key_provider
  144. if pp.name in _REGISTRY_PLUGIN_SKIP:
  145. return None
  146. auth_type = registry_auth_type(pp)
  147. if auth_type == "api_key":
  148. if not pp.env_vars:
  149. return None
  150. key_vars, url_var = _api_key_env_fields(pp)
  151. return _api_key_provider(pp.name, pp.display_name or pp.name, pp.base_url, key_vars,
  152. pp.base_url_env_var or url_var)
  153. return ProviderConfig(pp.name, pp.display_name or pp.name, auth_type, inference_base_url=pp.base_url,
  154. base_url_env_var=pp.base_url_env_var)
  155. def registry_auth_type(pp: Any) -> str:
  156. """The ``auth_type`` *pp*'s registry row carries (``registry_auth_type`` wins over ``auth_type``)."""
  157. return pp.registry_auth_type or pp.auth_type
  158. def _insert_row(registry: dict, pconfig: Any, after: str) -> None:
  159. """Add *pconfig* right after the *after* row (in place: callers hold the dict), else append.
  160. Reads the raw storage: rows hidden from the bound home must survive the rebuild."""
  161. if not dict.__contains__(registry, after):
  162. registry[pconfig.id] = pconfig
  163. return
  164. rows = list(dict.items(registry))
  165. at = [key for key, _ in rows].index(after) + 1
  166. registry.clear()
  167. registry.update(rows[:at] + [(pconfig.id, pconfig)] + rows[at:])
  168. def _user_owns_alias(pp: Any, alias: str) -> bool:
  169. """True when *alias* resolves to the ``$HERMES_HOME`` plugin *pp* in the ``providers`` layer."""
  170. try:
  171. from providers import get_provider_profile, provider_source
  172. except Exception:
  173. return False
  174. owner = get_provider_profile(alias)
  175. return owner is not None and owner.name == pp.name and provider_source(pp.name) == "user"
  176. def mirror_aliases(pconfig: Any, pp: Any) -> None:
  177. """Point ``pp.aliases`` at *pconfig* so ``resolve_provider()`` resolves them too.
  178. A bundled plugin never steals an alias another row already holds; a ``$HERMES_HOME`` plugin
  179. whose alias the ``providers`` layer already resolves to it does — the same ownership rule as
  180. :func:`override_registry_row`, otherwise the alias kept resolving to the built-in row while
  181. ``providers.get_provider_profile`` followed the user's profile (#116668).
  182. """
  183. from hermes_cli.auth import PROVIDER_REGISTRY
  184. for alias in pp.aliases:
  185. if alias not in PROVIDER_REGISTRY or _user_owns_alias(pp, alias):
  186. PROVIDER_REGISTRY[alias] = pconfig
  187. def override_registry_row(pconfig: Any, pp: Any) -> None:
  188. """A ``$HERMES_HOME`` plugin re-registering a name that already has a row wins for the fields
  189. it declares — ``display_name``, ``base_url`` and, on api-key rows, ``env_vars`` (#48450, #116668). ``register_provider()``
  190. is last-writer-wins for the profile; without this the runtime kept reading the built-in
  191. endpoint. A ``$HERMES_HOME`` layer plugin's fields land on that home's own copy of the row
  192. (:class:`HomeScopedRegistry`), so another served home keeps the built-in endpoint; a process-wide
  193. registration (every home reads it) rewrites the stored row in place.
  194. """
  195. if pp.display_name:
  196. pconfig.name = pp.display_name
  197. if pp.base_url:
  198. pconfig.inference_base_url = pp.base_url
  199. if registry_auth_type(pp) == "api_key" == pconfig.auth_type and pp.env_vars:
  200. pconfig.api_key_env_vars, url_var = _api_key_env_fields(pp)
  201. if url_var:
  202. pconfig.base_url_env_var = url_var
  203. def sync_plugin_provider_registry() -> int:
  204. """Mirror provider-plugin profiles into ``PROVIDER_REGISTRY``; return how many were added.
  205. Idempotent (existing entries are never replaced — a user plugin re-registering a bundled name
  206. wins for the fields it declares in its own home only, see :class:`HomeScopedRegistry`), so it is safe from
  207. resolution paths. It runs at
  208. auth import and again whenever a name is missing (:func:`registry_lookup`) or when ``providers``
  209. finishes discovery, because the import-time pass can observe a *partial* profile list: a plugin
  210. whose own imports pull ``hermes_cli.auth`` in mid-``_discover_providers()`` sees only what was
  211. registered so far, and every later plugin would otherwise fail with "Unknown provider" (#102123).
  212. """
  213. from hermes_cli.auth import BUILTIN_PROVIDER_IDS, PROVIDER_REGISTRY
  214. try:
  215. from providers import list_providers, provider_source
  216. profiles = list_providers()
  217. home_profile = lambda name: _resolver()(name)[0]
  218. except Exception:
  219. return 0
  220. added = 0
  221. for pp in profiles:
  222. if pp.name in PROVIDER_REGISTRY:
  223. # Only rows core wrote (built-in or mirrored) — a row the plugin injected itself is its
  224. # own, more specific declaration and stays as written.
  225. core_row = pp.name in BUILTIN_PROVIDER_IDS or pp.name in PLUGIN_MIRRORED_PROVIDERS
  226. if core_row and pp.name not in _REGISTRY_PLUGIN_SKIP and provider_source(pp.name) == "user":
  227. row = dict.__getitem__(PROVIDER_REGISTRY, pp.name)
  228. if home_profile(pp.name) is not pp: # registered process-wide: every home reads it
  229. override_registry_row(row, pp)
  230. mirror_aliases(row, pp)
  231. continue
  232. register_plugin_provider(pp)
  233. added += pp.name in PROVIDER_REGISTRY
  234. return added
  235. def canonical_registry_rows() -> list[tuple[str, Any]]:
  236. """``PROVIDER_REGISTRY`` items in order, minus the alias keys :func:`mirror_aliases` points at a
  237. plugin's row, so a scan or listing sees each provider once, under its own id."""
  238. from hermes_cli.auth import PROVIDER_REGISTRY
  239. return [(pid, pconfig) for pid, pconfig in PROVIDER_REGISTRY.items() if pid == pconfig.id]
  240. def registry_lookup(provider_id: str) -> Optional[Any]:
  241. """``PROVIDER_REGISTRY.get`` that re-syncs plugin profiles on a miss."""
  242. from hermes_cli.auth import PROVIDER_REGISTRY
  243. pconfig = PROVIDER_REGISTRY.get(provider_id)
  244. if pconfig is None:
  245. # Re-read whatever the count says: a home's first plugin scan runs inside the sync's own
  246. # ``list_providers()`` and mirrors its rows in that nested pass.
  247. sync_plugin_provider_registry()
  248. pconfig = PROVIDER_REGISTRY.get(provider_id)
  249. return pconfig
  250. def plugin_profile(provider: str) -> Optional[Any]:
  251. """The registered ``ProviderProfile`` for *provider*, or None (also when the layer is unavailable)."""
  252. try:
  253. from providers import get_provider_profile
  254. except Exception:
  255. return None
  256. return get_provider_profile(provider)
  257. def _profile_hook(provider: str, name: str) -> Optional[Callable[..., Any]]:
  258. hook = getattr(plugin_profile(provider), name, None)
  259. return hook if callable(hook) else None
  260. def plugin_auth_handler(provider: str) -> Optional[Callable[[str, Any], Any]]:
  261. return _profile_hook(provider, "auth_handler")
  262. def plugin_refresh_hook(provider: str) -> Optional[Callable[[Any], Any]]:
  263. """The profile's ``refresh_credential`` hook, i.e. whether its pooled OAuth rows are refreshable."""
  264. return _profile_hook(provider, "refresh_credential")
  265. def is_refreshable_oauth_provider(provider: str) -> bool:
  266. """Built-in refreshable set OR a plugin profile shipping ``refresh_credential``."""
  267. from agent.credential_pool import REFRESHABLE_OAUTH_PROVIDERS
  268. return provider in REFRESHABLE_OAUTH_PROVIDERS or plugin_refresh_hook(provider) is not None
  269. def dispatch_plugin_auth(action: str, args: Any, provider: str) -> bool:
  270. """Offer ``hermes auth <action> <provider>`` to the provider's ``auth_handler``.
  271. True = the plugin owned the action (core prints nothing more). False = run the built-in path. A
  272. handler exception becomes a readable ``SystemExit`` naming provider and action.
  273. ``<plugin>:<id>`` names an OAuth client a plugin declares under ``oauth:`` (:mod:`hermes_cli.plugin_oauth`).
  274. """
  275. from hermes_cli.plugin_oauth import handle_auth_action
  276. owned = handle_auth_action(action, args, provider)
  277. if owned is not None:
  278. return owned
  279. handler = plugin_auth_handler(provider)
  280. if handler is None:
  281. return False
  282. try:
  283. return bool(handler(action, args))
  284. except SystemExit:
  285. raise
  286. except Exception as exc:
  287. raise SystemExit(f"{provider} auth handler failed for `{action}`: {type(exc).__name__}: {exc}") from exc
  288. def plugin_missing_auth_handler_error(provider: str, action: str) -> Optional[SystemExit]:
  289. """Fail loud for a registered non-api-key plugin that ships no ``auth_handler``.
  290. Its login is not something core can perform (there is no token endpoint to call), and silently
  291. running the api-key prompt or reporting "Unknown provider" both hide the plugin bug.
  292. """
  293. if provider not in PLUGIN_MIRRORED_PROVIDERS:
  294. return None
  295. profile = plugin_profile(provider)
  296. if profile is None or registry_auth_type(profile) == "api_key" or plugin_auth_handler(provider) is not None:
  297. return None
  298. return SystemExit(
  299. f"Provider '{provider}' declares auth_type '{profile.auth_type}' but its plugin ships no "
  300. f"auth_handler, so `hermes auth {action} {provider}` cannot be handled. Add "
  301. "`auth_handler=` to its ProviderProfile (see the model-provider plugin guide).")
  302. def _pool_entry_expired(entry: Any) -> bool:
  303. """A pooled OAuth row is expired when its ``expires_at_ms`` / ISO ``expires_at`` is in the past."""
  304. import time
  305. from hermes_cli.auth import _parse_iso_timestamp
  306. if entry.expires_at_ms is not None:
  307. return int(entry.expires_at_ms) <= int(time.time() * 1000)
  308. if entry.expires_at:
  309. epoch = _parse_iso_timestamp(entry.expires_at)
  310. return epoch is not None and epoch <= time.time()
  311. return False
  312. def get_plugin_oauth_auth_status(provider_id: str) -> dict[str, Any]:
  313. """Status for an OAuth-shaped PLUGIN provider, read from the credential pool its ``auth_handler`` fills.
  314. ``configured`` = the profile is registered; ``logged_in`` = a pool row carries a live token;
  315. ``needs_refresh`` = every token is expired but refresh material (and a ``refresh_credential`` hook)
  316. exists. Bundled OAuth providers keep their bespoke builders (``_BESPOKE_STATUS_FUNCTIONS``) — this
  317. one is gated on the plugin-mirrored set so their status bytes never change.
  318. """
  319. if provider_id not in PLUGIN_MIRRORED_PROVIDERS:
  320. return {"logged_in": False}
  321. from agent.credential_pool import load_pool
  322. entries = [e for e in load_pool(provider_id).entries() if (e.access_token or e.agent_key or "").strip()]
  323. live = [e for e in entries if not _pool_entry_expired(e)]
  324. refreshable = [e for e in entries if e.refresh_token] if not live and plugin_refresh_hook(provider_id) else []
  325. return {
  326. "configured": True, "provider": provider_id, "logged_in": bool(live),
  327. "needs_refresh": bool(refreshable), "accounts": len(entries),
  328. "base_url": next((e.base_url for e in live + refreshable if e.base_url), "") or "",
  329. "hint": "" if live else f"Run `hermes auth add {provider_id}` to sign in."}