session_policy_credentials.py 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389
  1. """Borrow frozen config credentials from the existing profile source, not a vault."""
  2. import hashlib
  3. import hmac
  4. import json
  5. import logging
  6. from dataclasses import asdict
  7. from pathlib import Path
  8. from agent.credential_persistence import fingerprint_secret_value
  9. from hermes_state_runtime import RuntimeStoreError
  10. logger = logging.getLogger(__name__)
  11. PREFIX = 'profile-config-v1:'
  12. _ABSENT = object()
  13. def _defined(root, path):
  14. """The value *root* defines at *path*, else ``_ABSENT`` when the key is simply not there."""
  15. value = root
  16. for key in path:
  17. if isinstance(value, list) and type(key) is int:
  18. if not 0 <= key < len(value):
  19. return _ABSENT
  20. elif not isinstance(value, dict) or key not in value:
  21. return _ABSENT
  22. value = value[key]
  23. return value
  24. def _route_paths(policy):
  25. """Secret paths the session's own route authenticates with: its ``model:`` block, a direct alias's
  26. key (``api_key_from``) and the one ``providers:`` / ``custom_providers:`` entry the runtime's own
  27. named-provider selection routes its provider through."""
  28. from hermes_cli.runtime_provider_custom import (custom_provider_config_path_for_url,
  29. named_custom_provider_config_path)
  30. config = json.loads(policy.config_json)
  31. model = config.get('model') if isinstance(config.get('model'), dict) else {}
  32. paths = {('model', key) for key in model}
  33. if isinstance(model.get('api_key_from'), list):
  34. paths.add(tuple(model['api_key_from']))
  35. provider = str(model.get('provider') or '')
  36. if provider.strip().lower() == 'custom':
  37. # A bare custom route authenticates with the entry owning its base_url (the pool's owner).
  38. selected = custom_provider_config_path_for_url(model.get('base_url'), config)
  39. else:
  40. selected = named_custom_provider_config_path(provider, config)
  41. entry = _defined(config, selected) if selected else _ABSENT
  42. if isinstance(entry, dict):
  43. paths |= {selected + (field,) for field in entry}
  44. return paths
  45. class RecoveredSecrets(dict):
  46. """The frozen secrets still valid, plus ``dropped``: the paths whose value changed or was removed
  47. in config.yaml since the session started (never supplied; the policy disables what used them)."""
  48. dropped = ()
  49. session = None
  50. def policy_identity(policy, unhashed=()):
  51. data = asdict(policy)
  52. data.pop('credential_ref')
  53. data.pop('config_secret_ref')
  54. # Fields added after release are hashed only when set, so an older session's reference still matches.
  55. if data.get('editor_mcp_json') is None:
  56. data.pop('editor_mcp_json', None)
  57. if not data.get('coding_posture'):
  58. data.pop('coding_posture', None)
  59. for name in ('client_env_json', 'client_env_rules_json'):
  60. if data.get(name) is None:
  61. data.pop(name, None)
  62. if not data.get('client_env_remote'):
  63. data.pop('client_env_remote', None)
  64. if data.get('edit_approval_policy', 'ask') == 'ask':
  65. data.pop('edit_approval_policy', None)
  66. for name in unhashed: # _legacy_identities: a field the stamping gateway did not have yet
  67. data.pop(name, None)
  68. return hashlib.sha256(json.dumps(data, sort_keys=True).encode()).hexdigest()
  69. # Policy fields a release added after frozen config secrets shipped, hashed unconditionally by the
  70. # gateway that added them. A reference an older gateway stamped never hashed them; at their defaults
  71. # they carry nothing that gateway could have seen, so the same policy without them is its policy.
  72. # The commit that added each, to audit this list against the stamping releases:
  73. _LATER_POLICY_FIELDS = (('skills_prompt', None), # 2ee1cd1ebb02
  74. ('kanban_json', None), # c8f8d9ae6384
  75. ('safe_mode', False), # 53d362e18741
  76. ('ignore_user_config', False)) # 53d362e18741
  77. def _legacy_identities(policy):
  78. """Every whole-policy hash a gateway older than ``bound`` could have stamped for *policy*: the
  79. current hash, plus each subset of the later fields dropped while they are at their defaults."""
  80. from itertools import combinations
  81. unset = [name for name, default in _LATER_POLICY_FIELDS if getattr(policy, name) == default]
  82. return {policy_identity(policy, dropped)
  83. for size in range(len(unset) + 1) for dropped in combinations(unset, size)}
  84. def _fingerprint(value):
  85. return fingerprint_secret_value(value if isinstance(value, str) else json.dumps(value, sort_keys=True))
  86. # What a frozen secret authenticates: the endpoint fields of the block that holds it (``model:``, a
  87. # ``providers:`` entry, an MCP server), plus the endpoint its route RESOLVES to when that lives in another
  88. # block. A secret is bound to these, never to the rest of the policy. ``api`` is an entry's URL field
  89. # (runtime_provider_custom._entry_url reads it before ``url``/``base_url``).
  90. _ENDPOINT_KEYS = ('provider', 'base_url', 'api', 'url', 'command', 'args', 'api_mode')
  91. _ENTRY_SECTIONS = ('providers', 'custom_providers')
  92. # An auxiliary route naming no provider of its own (or ``main``/``auto``) goes where the session's
  93. # ``model:`` route goes, so its key authenticates that endpoint too.
  94. _AUX_FOLLOWS_MAIN = ('', 'auto', 'main')
  95. def _route_owner(config, path):
  96. """The config path of the ROUTE block a secret at *path* rides with, else None. Every route shape a
  97. consumer reads: ``model:`` and its aliases (``model.aliases.<n>``, ``model_aliases.<n>``), both
  98. fallback sections in dictionary (one route) and list form, and each ``auxiliary.<task>`` route with
  99. its ``fallback_chain`` entries. A secret nested deeper in a route (headers, extra_body) rides with it."""
  100. head, rest = path[0], tuple(path[1:])
  101. model = config.get('model') if isinstance(config.get('model'), dict) else {}
  102. if isinstance(model.get('api_key_from'), list) and tuple(model['api_key_from']) == tuple(path):
  103. # ``/model <alias>`` with a literal key: config() projects the alias entry's key into ``model.api_key``,
  104. # so it authenticates the session's ``model:`` route, not the alias entry it is stored under.
  105. return ('model',)
  106. if head == 'model':
  107. if rest[:1] == ('aliases',) and len(rest) > 2:
  108. return ('model', 'aliases', rest[1])
  109. return ('model',)
  110. if head == 'model_aliases' and len(rest) > 1:
  111. return ('model_aliases', rest[0])
  112. if head in ('fallback_model', 'fallback_providers'):
  113. if isinstance(config.get(head), list) and rest and type(rest[0]) is int:
  114. return (head, rest[0])
  115. return (head,)
  116. if head == 'auxiliary' and len(rest) > 1:
  117. task = rest[0]
  118. if rest[1] == 'fallback_chain' and len(rest) > 3 and type(rest[2]) is int:
  119. return ('auxiliary', task, 'fallback_chain', rest[2])
  120. return ('auxiliary', task)
  121. return None
  122. def _owner_block(config, path):
  123. """The config path of the block whose endpoint the secret at *path* authenticates: a route block
  124. (_route_owner) or a provider entry as a whole, else the secret's own parent block."""
  125. route = _route_owner(config, path)
  126. if route is not None:
  127. return route
  128. if path[0] in _ENTRY_SECTIONS:
  129. return tuple(path[:2])
  130. return tuple(path[:-1])
  131. def _resolved(owner, block, config):
  132. """``(provider_identity, url)`` the route *block* at *owner* is actually sent to."""
  133. from gateway.session_route_identity import resolved_route
  134. if owner[0] == 'auxiliary':
  135. provider = str(block.get('provider') or '').strip().lower()
  136. if provider in _AUX_FOLLOWS_MAIN and not str(block.get('base_url') or '').strip():
  137. main = config.get('model') if isinstance(config.get('model'), dict) else {}
  138. return ['main', *resolved_route(main, config)]
  139. return list(resolved_route(block, config))
  140. # Endpoint fields holding a URL: digested in normalize_route_base_url's form, so a re-spelling of the same
  141. # endpoint (host case, a trailing slash, the scheme's default port) is not a moved endpoint.
  142. _URL_KEYS = ('base_url', 'api', 'url')
  143. def _url(value):
  144. from hermes_cli.route_identity import normalize_route_base_url
  145. return normalize_route_base_url(str(value or '').strip())
  146. def _binding(config, path):
  147. """Digest of the endpoint the secret at *path* authenticates in the frozen *config* (a terminal-scope
  148. secret, ``path[0] is None``, authenticates no endpoint)."""
  149. owner = _owner_block(config, path) if path and path[0] is not None else None
  150. block = _defined(config, owner) if owner else _ABSENT
  151. endpoint = {k: block[k] for k in _ENDPOINT_KEYS if k in block} if isinstance(block, dict) else {}
  152. if isinstance(block, dict) and _route_owner(config, path) is not None:
  153. # A route's key authenticates what it resolves to: a named ``providers:`` entry's URL included.
  154. endpoint['resolved'] = _resolved(owner, block, config)
  155. endpoint['resolved'][-1] = _url(endpoint['resolved'][-1])
  156. elif isinstance(block, dict) and path[0] in _ENTRY_SECTIONS:
  157. from hermes_cli.runtime_provider_custom import _entry_url
  158. endpoint['resolved'] = _url(_entry_url(block))
  159. for key in _URL_KEYS:
  160. if isinstance(endpoint.get(key), str):
  161. endpoint[key] = _url(endpoint[key])
  162. return hashlib.sha256(json.dumps([list(path), endpoint], sort_keys=True).encode()).hexdigest()
  163. def config_reference(authority, session_id, policy, secrets):
  164. home = Path(authority.db.db_path).resolve().parent
  165. config = json.loads(policy.config_json)
  166. return PREFIX + json.dumps({'home': str(home), 'profile': authority.profile_id,
  167. # ``policy`` (the whole-policy hash) is still written for an older gateway reading this reference;
  168. # this gateway checks ``bound``: each secret against the endpoint it authenticates (CFG-10).
  169. 'session': session_id, 'policy': policy_identity(policy),
  170. 'bound': [[list(path), _binding(config, path)] for path in secrets],
  171. 'entries': [[list(path), _fingerprint(value)] for path, value in secrets.items()]},
  172. sort_keys=True)
  173. def _field(path):
  174. return '.'.join(str(part) for part in path if part is not None)
  175. def _check_scope(authority, source, policy, home, skip):
  176. """Refuse, by name, a reference from another home or profile, or a secret whose endpoint the policy
  177. moved without re-binding it. A change to anything else in the policy (model name, reasoning, toolsets,
  178. an unrelated provider or MCP server, a policy field a later release added) is not a credential change."""
  179. for name, mine in (('home', str(home)), ('profile', authority.profile_id)):
  180. if source[name] != mine:
  181. raise RuntimeStoreError('launch_credentials_unavailable', field=name,
  182. detail=f'the frozen config credentials belong to another {name}')
  183. if 'bound' not in source:
  184. # Stamped before ``bound``: its whole-policy hash is its only endpoint guard, so it must still
  185. # match -- allowing for the policy fields added since, at their defaults (_legacy_identities).
  186. # The next re-bind writes ``bound``.
  187. if source['policy'] not in _legacy_identities(policy):
  188. raise RuntimeStoreError('launch_credentials_unavailable', field='config_secret_ref',
  189. detail='stamped by an older gateway for another session policy')
  190. return
  191. config = json.loads(policy.config_json)
  192. for path, digest in source['bound']:
  193. if path[0] not in skip and not hmac.compare_digest(_binding(config, path), digest):
  194. raise RuntimeStoreError('launch_credentials_unavailable', field=_field(path),
  195. detail='its endpoint moved in the session policy without a re-bind')
  196. def secrets_moved(ref, secrets, sections):
  197. """Whether *secrets* (the private values of *sections*, as the profile has them now) differ from the ones
  198. the durable reference *ref* froze there, by fingerprint. Unknown for an in-memory reference: False."""
  199. if ref is not None and not ref.startswith(PREFIX):
  200. return False
  201. entries = json.loads(ref[len(PREFIX):])['entries'] if ref else []
  202. frozen = {tuple(path): fingerprint for path, fingerprint in entries if path[0] in sections}
  203. return frozen != {path: _fingerprint(value) for path, value in secrets.items()}
  204. def recover_config_secrets(authority, policy, skip=None):
  205. """The frozen config secrets; entries under a *skip* section are neither re-read nor checked. Every
  206. caller of a following session skips its followed sections: the live profile supplies them, so a key
  207. rotation there is not a revoked launch credential."""
  208. if skip is None:
  209. from gateway.session_policy import FOLLOW_SECTIONS
  210. skip = FOLLOW_SECTIONS if policy.follows_profile else ()
  211. ref = policy.config_secret_ref
  212. if not ref.startswith(PREFIX):
  213. values = getattr(authority, '_local_config_secrets', {}).get(ref)
  214. if values is None:
  215. raise RuntimeStoreError('launch_credentials_unavailable')
  216. return {path: value for path, value in values.items() if path[0] not in skip}
  217. try:
  218. source = json.loads(ref[len(PREFIX):])
  219. home = Path(authority.db.db_path).resolve().parent
  220. _check_scope(authority, source, policy, home, skip)
  221. cached = getattr(authority, '_local_config_secrets', {}).get(ref)
  222. if cached is not None:
  223. return {path: value for path, value in cached.items() if path[0] not in skip}
  224. from gateway.run import _load_gateway_config
  225. entries = [entry for entry in source['entries'] if entry[0][0] not in skip]
  226. config = _load_gateway_config(home / 'config.yaml') if any(path[0] is not None for path, _ in entries) else {}
  227. route = None # computed on the first mismatch only: an unchanged source never needs it
  228. values, dropped = RecoveredSecrets(), []
  229. frozen = None # parsed on the first legacy entry only
  230. for path, fingerprint in entries:
  231. value, lookup = config, path
  232. if path[0] == 'custom_providers' and len(path) > 2 and type(path[1]) is int:
  233. frozen = json.loads(policy.config_json) if frozen is None else frozen
  234. lookup = _current_custom_path(frozen, config, path)
  235. if path[0] is None:
  236. from tools.terminal_scope import build_profile_terminal_scope
  237. value, lookup = build_profile_terminal_scope(home), path[1:]
  238. value = _defined(value, lookup)
  239. actual = None if value is _ABSENT else _fingerprint(value)
  240. if actual is None or not hmac.compare_digest(actual, fingerprint):
  241. if route is None:
  242. route = _route_paths(policy)
  243. if tuple(path) in route:
  244. raise RuntimeStoreError('launch_credentials_unavailable', field=_field(path),
  245. detail=('removed from' if value is _ABSENT else 'changed in')
  246. + ' config.yaml since this session started')
  247. # Any other secret (an MCP env token, an unused provider's key) is simply no longer
  248. # supplied: the frozen tree holds None there, never the profile's new value.
  249. logger.warning('Session %s: frozen config secret %s no longer matches the profile '
  250. 'config; skipping it', source.get('session'), path)
  251. dropped.append(tuple(path))
  252. continue
  253. values[tuple(path)] = value
  254. values.dropped, values.session = tuple(dropped), source.get('session')
  255. return values
  256. except RuntimeStoreError:
  257. raise
  258. except (KeyError, TypeError, ValueError, AttributeError, OSError) as exc:
  259. logger.warning('Frozen config reference unreadable: %s', type(exc).__name__)
  260. raise RuntimeStoreError('launch_credentials_unavailable', field='config_secret_ref',
  261. detail=f'unreadable ({type(exc).__name__})') from exc
  262. def _current_custom_path(frozen, config, path):
  263. """*path* (``custom_providers[i]...``, an index into the frozen list) re-pointed at the profile's
  264. entry of the SAME canonical identity (``custom_provider_slug``), wherever a reorder moved it.
  265. An entry the profile no longer declares maps to no index (absent), never to whatever entry now
  266. sits at ``i``, unless that entry is the same endpoint renamed in place (the fingerprint then decides,
  267. as on main). A frozen entry with no name has no identity: its index is all there is."""
  268. from hermes_cli.providers import custom_provider_slug
  269. def identity(entry):
  270. if not isinstance(entry, dict) or not (entry.get('name') or entry.get('provider_key')):
  271. return None
  272. return custom_provider_slug(str(entry.get('name') or ''), str(entry.get('provider_key') or ''))
  273. held = frozen.get('custom_providers')
  274. mine = identity(held[path[1]]) if isinstance(held, list) and 0 <= path[1] < len(held) else None
  275. current = config.get('custom_providers')
  276. if mine is None or not isinstance(current, list):
  277. return path
  278. if 0 <= path[1] < len(current) and identity(current[path[1]]) == mine:
  279. return path # unmoved (also keeps a duplicate-named later entry on its own index)
  280. for index, entry in enumerate(current):
  281. if identity(entry) == mine: # the first match, as the runtime's own name lookup takes
  282. return (path[0], index, *path[2:])
  283. from hermes_cli.runtime_provider_custom import _entry_url, _normalize_base_url_for_match as url
  284. if 0 <= path[1] < len(current) and isinstance(current[path[1]], dict) \
  285. and url(_entry_url(current[path[1]])) == url(_entry_url(held[path[1]])):
  286. return path # renamed in place: same endpoint at the same index, as main read it (the fingerprint decides)
  287. return (path[0], len(current), *path[2:]) # gone: past the end reads as absent
  288. def _entry_owner_path(entry, config):
  289. """The ``providers:`` / ``custom_providers:`` entry a fallback entry authenticates through."""
  290. from hermes_cli.runtime_provider_custom import (custom_provider_config_path_for_url,
  291. named_custom_provider_config_path)
  292. provider = str(entry.get('provider') or '').strip()
  293. if provider.lower() == 'custom':
  294. return custom_provider_config_path_for_url(entry.get('base_url'), config)
  295. return named_custom_provider_config_path(provider, config) if provider else None
  296. def disable_dropped_secrets(config, dropped, session=None):
  297. """Disable, in the session's effective *config*, whatever authenticated with a *dropped* frozen
  298. secret, instead of leaving it with a null key (null means 'resolve another credential' and would
  299. send another account's key). A fallback using it is removed from the chain; an ``auxiliary.<task>``
  300. override using it is replaced by the session's primary route (``provider: main``). Never substitutes."""
  301. if not dropped:
  302. return config
  303. from agent.auxiliary_task_config import _AUX_ROUTE_KEYS
  304. auxiliary = config.get('auxiliary') if isinstance(config.get('auxiliary'), dict) else {}
  305. for task in sorted({path[1] for path in dropped if path[0] == 'auxiliary' and len(path) > 2}, key=str):
  306. block = auxiliary.get(task)
  307. if isinstance(block, dict):
  308. # The task's own route is gone with its key: the session's primary route, its own credential.
  309. auxiliary[task] = {**{k: v for k, v in block.items() if k not in _AUX_ROUTE_KEYS
  310. and k != 'fallback_chain'}, 'provider': 'main'}
  311. logger.warning('Session %s: auxiliary task %s returned to the primary route: its credential '
  312. 'changed in config.yaml since this session started', session, task)
  313. owners = {path[:2] for path in dropped if path[0] in ('providers', 'custom_providers') and len(path) > 2}
  314. for section in ('fallback_providers', 'fallback_model'):
  315. raw = config.get(section)
  316. if isinstance(raw, dict):
  317. entries, single = [raw], True
  318. elif isinstance(raw, list):
  319. entries, single = list(raw), False
  320. else:
  321. continue
  322. kept = []
  323. for index, entry in enumerate(entries):
  324. prefix = (section,) if single else (section, index)
  325. own = any(path[:len(prefix)] == prefix for path in dropped)
  326. owner = _entry_owner_path(entry, config) if isinstance(entry, dict) and owners else None
  327. if own or (owner is not None and tuple(owner) in owners):
  328. logger.warning('Session %s: fallback %s/%s removed: its credential changed in config.yaml '
  329. 'since this session started', session,
  330. (entry or {}).get('provider') if isinstance(entry, dict) else '?',
  331. (entry or {}).get('model') if isinstance(entry, dict) else '?')
  332. continue
  333. kept.append(entry)
  334. if single:
  335. if kept:
  336. config[section] = kept[0]
  337. else:
  338. config.pop(section, None)
  339. else:
  340. config[section] = kept
  341. return config