auth_oauth_grants.py 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842
  1. """Single-use OAuth grant hygiene: strip cloned grants from profiles, heal forked grants.
  2. Split out of ``hermes_cli/auth.py`` and re-exported there; origin helpers are imported lazily
  3. inside each function so ``hermes_cli.auth.<name>`` patches still intercept (and no import cycle).
  4. """
  5. from __future__ import annotations
  6. import copy
  7. import json
  8. import logging
  9. import os
  10. from pathlib import Path
  11. from typing import Any, Dict, List, Optional, Tuple
  12. from hermes_cli.auth_constants import _decode_jwt_claims
  13. from utils import file_signature
  14. # Log-record parity with the origin module (caplog tests pin "hermes_cli.auth").
  15. logger = logging.getLogger("hermes_cli.auth")
  16. # Pool providers whose OAuth refresh tokens are SINGLE-USE: redeeming rotates the pair and
  17. # revokes the old one, so a grant forked into two auth.json files is ONE credential with two
  18. # owners — the first to refresh strands the other with ``invalid_grant`` /
  19. # ``refresh_token_reused``.
  20. # Profiles must never receive a copy: ONE grant lives at the global root and named profiles read
  21. # it through the ``read_credential_pool`` root fallback.
  22. SINGLE_USE_REFRESH_POOL_PROVIDERS = frozenset({"anthropic", "openai-codex", "xai-oauth", "nous"})
  23. # Singleton credential files holding the same single-use grants outside ``auth.json``. Copying one
  24. # into a profile re-seeds a forked pool row on the profile's next ``load_pool()``.
  25. SINGLE_USE_OAUTH_SINGLETON_FILES = (".anthropic_oauth.json",)
  26. # Providers whose device-code grants live under ``providers.<id>`` (not only the pool).
  27. # Only a block carrying a refresh token is a forkable grant: an agent_key-only ``nous`` block is
  28. # not single-use and must survive.
  29. _DEVICE_CODE_BLOCK_PROVIDERS = ("openai-codex", "xai-oauth", "nous")
  30. def _block_tokens(block: dict[str, Any]) -> dict[str, Any]:
  31. # Codex/xAI nest the pair under ``tokens``; Nous stores it flat on the block.
  32. tokens = block.get("tokens")
  33. return tokens if isinstance(tokens, dict) else block
  34. def _is_forkable_pool_row(provider_id: str, entry: Any) -> bool:
  35. # An agent_key-only nous row carries no single-use refresh token: it is not a fork, and
  36. # stripping it while its providers block survives lets the profile's next load_pool('nous')
  37. # write that block over root's shared row. Same refresh_token gate the block strip uses.
  38. if not _is_oauth_pool_payload(entry):
  39. return False
  40. # Pool rows are flat (no ``tokens`` nesting), so read refresh_token directly.
  41. return provider_id != "nous" or bool(str(entry.get("refresh_token") or "").strip())
  42. def _is_oauth_pool_payload(entry: Any) -> bool:
  43. if not isinstance(entry, dict):
  44. return False
  45. # Legacy rows predating ``auth_type``: an Anthropic OAuth access token or any row carrying a
  46. # refresh token is an OAuth grant.
  47. return (
  48. str(entry.get("auth_type") or "").strip().lower() == "oauth"
  49. or bool(str(entry.get("refresh_token") or "").strip())
  50. or str(entry.get("access_token") or "").startswith("sk-ant-oat"))
  51. def merge_snapshot_auth_preserving_live_single_use_grants(
  52. snapshot_store: dict[str, Any], live_store: dict[str, Any],
  53. ) -> dict[str, Any]:
  54. """Restore historical auth state without reviving spent single-use OAuth generations.
  55. Snapshot metadata may be restored onto a live grant only when its stable row id proves the
  56. lineage. Historical single-use refresh material with no live counterpart is dropped because
  57. there is no local evidence that it is still redeemable. Current live grants always survive.
  58. """
  59. from hermes_cli.auth import _credential_token_pair, _merge_pool_row_generation
  60. restored = copy.deepcopy(snapshot_store)
  61. snapshot_pool = restored.get("credential_pool")
  62. live_pool = live_store.get("credential_pool")
  63. for provider_id in SINGLE_USE_REFRESH_POOL_PROVIDERS:
  64. live_rows = live_pool.get(provider_id) if isinstance(live_pool, dict) else None
  65. if not isinstance(live_rows, list):
  66. live_rows = []
  67. snapshot_rows = (
  68. snapshot_pool.get(provider_id) if isinstance(snapshot_pool, dict) else None
  69. )
  70. if not isinstance(snapshot_rows, list):
  71. snapshot_rows = []
  72. live_grants = [
  73. row for row in live_rows if _is_forkable_pool_row(provider_id, row)
  74. ]
  75. snapshot_has_grants = any(
  76. _is_forkable_pool_row(provider_id, row) for row in snapshot_rows
  77. )
  78. if not live_grants and not snapshot_has_grants:
  79. continue
  80. if not isinstance(snapshot_pool, dict):
  81. snapshot_pool = restored["credential_pool"] = {}
  82. live_rows_by_id = {
  83. row.get("id"): row
  84. for row in live_rows
  85. if isinstance(row, dict)
  86. and isinstance(row.get("id"), str)
  87. and row.get("id")
  88. }
  89. live_grants_by_id = {
  90. row_id: row
  91. for row_id, row in live_rows_by_id.items()
  92. if _is_forkable_pool_row(provider_id, row)
  93. }
  94. live_without_id = [
  95. copy.deepcopy(row)
  96. for row in live_grants
  97. if not (isinstance(row.get("id"), str) and row.get("id"))
  98. ]
  99. merged_snapshot: list[dict[str, Any]] = []
  100. consumed_ids: set[str] = set()
  101. for snapshot_row in snapshot_rows:
  102. row_id = snapshot_row.get("id") if isinstance(snapshot_row, dict) else None
  103. live_row = (
  104. live_rows_by_id.get(row_id)
  105. if isinstance(row_id, str) and row_id
  106. else None
  107. )
  108. live_is_grant = _is_forkable_pool_row(provider_id, live_row)
  109. snapshot_is_grant = _is_forkable_pool_row(provider_id, snapshot_row)
  110. if snapshot_is_grant:
  111. # A snapshot-only generation may already have spent its refresh token upstream.
  112. # Stable id + a current row is the only local proof of which credential identity
  113. # replaced it. Current non-OAuth state wins as a unit; current OAuth state keeps
  114. # the snapshot metadata while substituting its authoritative token generation.
  115. if live_row is None or row_id in consumed_ids:
  116. continue
  117. consumed_ids.add(row_id)
  118. if live_is_grant:
  119. merged_snapshot.append(
  120. _merge_pool_row_generation(
  121. snapshot_row,
  122. live_row,
  123. provider_id,
  124. base_pair=_credential_token_pair(snapshot_row),
  125. )
  126. )
  127. else:
  128. merged_snapshot.append(copy.deepcopy(live_row))
  129. continue
  130. if live_is_grant:
  131. if row_id in consumed_ids:
  132. continue
  133. consumed_ids.add(row_id)
  134. # The historical row changed auth shape but still claims a live OAuth row's stable
  135. # identity. Keep the live row as a unit rather than manufacturing two credentials.
  136. merged_snapshot.append(copy.deepcopy(live_row))
  137. else:
  138. # Ordinary credentials are historical state: restore the snapshot's version.
  139. merged_snapshot.append(snapshot_row)
  140. live_only = [
  141. copy.deepcopy(row)
  142. for row_id, row in live_grants_by_id.items()
  143. if row_id not in consumed_ids
  144. ]
  145. snapshot_pool[provider_id] = live_without_id + live_only + merged_snapshot
  146. snapshot_providers = restored.get("providers")
  147. live_providers = live_store.get("providers")
  148. for provider_id in _DEVICE_CODE_BLOCK_PROVIDERS:
  149. snapshot_block = (
  150. snapshot_providers.get(provider_id)
  151. if isinstance(snapshot_providers, dict)
  152. else None
  153. )
  154. live_block = (
  155. live_providers.get(provider_id)
  156. if isinstance(live_providers, dict)
  157. else None
  158. )
  159. snapshot_has_refresh = (
  160. isinstance(snapshot_block, dict)
  161. and bool(_block_tokens(snapshot_block).get("refresh_token"))
  162. )
  163. live_has_refresh = (
  164. isinstance(live_block, dict)
  165. and bool(_block_tokens(live_block).get("refresh_token"))
  166. )
  167. if not snapshot_has_refresh and not live_has_refresh:
  168. continue
  169. if not isinstance(snapshot_providers, dict):
  170. snapshot_providers = restored["providers"] = {}
  171. if isinstance(live_block, dict):
  172. snapshot_providers[provider_id] = copy.deepcopy(live_block)
  173. else:
  174. # No current generation exists. Restoring the historical refresh token would
  175. # resurrect a credential whose single-use token may already be spent.
  176. snapshot_providers.pop(provider_id, None)
  177. return restored
  178. def _is_pkce_row(row: dict[str, Any]) -> bool:
  179. return str(row.get("source") or "").endswith("hermes_pkce")
  180. def strip_cloned_single_use_oauth_grants(profile_dir: Path) -> dict[str, Any]:
  181. """Remove forked single-use OAuth grants from a freshly cloned profile.
  182. Called after any path that copies credential files between profiles (``hermes profile create
  183. --clone-all``, the dashboard/TUI ``mirror_credentials`` flow). API-key pool rows are kept — a
  184. static key is safe to duplicate. Returns ``{"pool": [...provider ids], "providers": [...],
  185. "files": [...]}`` of what was stripped. Never raises: a clone must not fail because hygiene
  186. could not run — the caller logs the summary.
  187. """
  188. from hermes_cli.auth import _same_path, _save_auth_store
  189. stripped: dict[str, Any] = {"pool": [], "providers": [], "files": []}
  190. profile_dir = Path(profile_dir)
  191. for name in SINGLE_USE_OAUTH_SINGLETON_FILES:
  192. target = profile_dir / name
  193. try:
  194. if target.is_file() or target.is_symlink():
  195. target.unlink()
  196. stripped["files"].append(name)
  197. except OSError:
  198. logger.debug("Could not remove cloned %s from %s", name, profile_dir, exc_info=True)
  199. auth_path = profile_dir / "auth.json"
  200. if not auth_path.is_file():
  201. return stripped
  202. # A profile auth.json that IS the shared root store (symlink / hardlink) is not a clone;
  203. # stripping it would delete every profile's single-use grants. _is_same_auth_store swallows
  204. # a samefile() OSError as "two stores", which here would fail OPEN — so resolve identity
  205. # positively: same path, or samefile() says so; any error refuses.
  206. try:
  207. from hermes_constants import get_default_hermes_root
  208. root_auth_path = get_default_hermes_root() / "auth.json"
  209. if _same_path(auth_path, root_auth_path) or (
  210. root_auth_path.exists() and auth_path.samefile(root_auth_path)
  211. ):
  212. return stripped
  213. except Exception:
  214. return stripped
  215. try:
  216. store = json.loads(auth_path.read_text(encoding="utf-8-sig"))
  217. except (OSError, json.JSONDecodeError):
  218. store = None
  219. if not isinstance(store, dict):
  220. return stripped
  221. changed = False
  222. pool = store.get("credential_pool")
  223. if isinstance(pool, dict):
  224. for provider_id in list(pool):
  225. entries = pool.get(provider_id)
  226. if (provider_id not in SINGLE_USE_REFRESH_POOL_PROVIDERS
  227. or not isinstance(entries, list)):
  228. continue
  229. kept = [e for e in entries if not _is_forkable_pool_row(provider_id, e)]
  230. if len(kept) != len(entries):
  231. changed = True
  232. stripped["pool"].append(provider_id)
  233. if kept:
  234. pool[provider_id] = kept
  235. else:
  236. # No local rows → read_credential_pool falls back to the root slice.
  237. del pool[provider_id]
  238. providers = store.get("providers")
  239. if isinstance(providers, dict):
  240. # _load_provider_state has the same root fallback, so dropping the copy keeps the
  241. # profile working while removing the fork.
  242. for provider_id in _DEVICE_CODE_BLOCK_PROVIDERS:
  243. block = providers.get(provider_id)
  244. if isinstance(block, dict) and _block_tokens(block).get("refresh_token"):
  245. del providers[provider_id]
  246. stripped["providers"].append(provider_id)
  247. changed = True
  248. if not changed:
  249. return stripped
  250. try:
  251. _save_auth_store(store, target_path=auth_path)
  252. except Exception:
  253. logger.debug(
  254. "Failed to strip cloned single-use OAuth grants from %s", auth_path, exc_info=True)
  255. return stripped
  256. _OAUTH_TOKEN_FIELDS = (
  257. "access_token", "refresh_token", "expires_at", "expires_at_ms", "last_refresh")
  258. _oauth_heal_notices: list[str] = []
  259. # provider -> fingerprint (see ``_heal_forked_single_use_oauth_grants``) of the last store
  260. # verified fork-free; lets load_pool() skip the locked scan.
  261. _oauth_heal_clean_marks: dict[str, tuple[Any, ...]] = {}
  262. # Filename for the ON-DISK twin of ``_oauth_heal_clean_marks``. The in-memory mark only silences
  263. # the heal for the life of ONE process, so every fresh `hermes` invocation and every new worker
  264. # re-pays the heal's two nested EXCLUSIVE auth-store locks just to discover there is nothing to
  265. # consolidate. Behind a sibling holding those locks that costs a full AUTH_LOCK_TIMEOUT_SECONDS
  266. # per provider (measured: 30s for two providers on an otherwise-idle machine) before the process
  267. # can do anything at all.
  268. _OAUTH_HEAL_CLEAN_MARK_FILENAME = "oauth_heal_clean.json"
  269. def _json_shape(fingerprint: tuple) -> list:
  270. """The fingerprint as it reads back from JSON (tuples become lists), so the on-disk compare
  271. is exact."""
  272. return json.loads(json.dumps(fingerprint))
  273. def _oauth_heal_clean_mark_path() -> Optional[Path]:
  274. """Where the persisted clean marks live, or None when unavailable."""
  275. try:
  276. from hermes_cli.auth import _auth_file_path
  277. return _auth_file_path().parent / "cache" / _OAUTH_HEAL_CLEAN_MARK_FILENAME
  278. except Exception:
  279. return None
  280. def _persisted_oauth_heal_fingerprint(provider_id: str) -> Optional[list]:
  281. """The stored clean-mark fingerprint for ``provider_id``, or None.
  282. Pure cache read: any problem at all (absent, unreadable, corrupt, wrong shape) means "no
  283. mark", which falls through to the locked heal — the pre-existing behaviour. It must never
  284. raise into a credential path.
  285. """
  286. path = _oauth_heal_clean_mark_path()
  287. if path is None:
  288. return None
  289. try:
  290. data = json.loads(path.read_text(encoding="utf-8-sig"))
  291. except Exception:
  292. return None
  293. if not isinstance(data, dict):
  294. return None
  295. stored = data.get(provider_id)
  296. return stored if isinstance(stored, list) else None
  297. def _persist_oauth_heal_clean_mark(provider_id: str, fingerprint: tuple) -> None:
  298. """Record ``provider_id`` as clean for this exact fingerprint.
  299. Best-effort by design: a failed write only means the next process re-runs the heal, which is
  300. what it did before this cache existed.
  301. """
  302. path = _oauth_heal_clean_mark_path()
  303. if path is None:
  304. return
  305. try:
  306. from utils import atomic_json_write
  307. try:
  308. existing = json.loads(path.read_text(encoding="utf-8-sig"))
  309. except Exception:
  310. existing = {}
  311. if not isinstance(existing, dict):
  312. existing = {}
  313. marks = {
  314. key: value for key, value in existing.items()
  315. if isinstance(key, str) and isinstance(value, list)
  316. }
  317. new_mark = _json_shape(fingerprint)
  318. if marks.get(provider_id) == new_mark:
  319. return # already recorded; skip the rewrite
  320. marks[provider_id] = new_mark
  321. from hermes_constants import mkdir_under_hermes_home
  322. mkdir_under_hermes_home(path.parent)
  323. # 0o600 like the MCP schema cache: this names credential-store paths.
  324. atomic_json_write(path, marks, mode=0o600)
  325. except Exception:
  326. logger.debug(
  327. "%s: could not persist the forked-OAuth clean mark", provider_id, exc_info=True)
  328. def _mark_oauth_heal_clean(provider_id: str, fingerprint: tuple) -> None:
  329. """Stamp the clean mark both in memory and on disk."""
  330. _oauth_heal_clean_marks[provider_id] = fingerprint
  331. _persist_oauth_heal_clean_mark(provider_id, fingerprint)
  332. def consume_oauth_heal_notices() -> list[str]:
  333. """Return (and clear) human-readable notes about heals run in this process.
  334. ``hermes auth list`` / ``hermes auth status`` print them so the user sees the consolidation.
  335. """
  336. from hermes_cli.auth import _oauth_heal_notices
  337. notes = list(_oauth_heal_notices)
  338. _oauth_heal_notices.clear()
  339. return notes
  340. def _oauth_identity(entry: dict[str, Any]) -> Optional[str]:
  341. """Stable account identity for an OAuth row when the token carries one.
  342. Codex / xAI access tokens are JWTs with ``sub`` / ``email`` / ``chatgpt_account_id`` claims;
  343. Anthropic ``sk-ant-oat`` tokens carry none (None → lineage rests on id / token material).
  344. """
  345. from hermes_cli.auth import _nonempty_str
  346. if not isinstance(entry, dict):
  347. return None
  348. for token in (entry.get("access_token"), entry.get("id_token")):
  349. claims = _decode_jwt_claims(token)
  350. if not claims:
  351. continue
  352. nested = claims.get("https://api.openai.com/auth")
  353. account = nested.get("chatgpt_account_id") if isinstance(nested, dict) else None
  354. for value in (account, claims.get("sub"), claims.get("email")):
  355. if _nonempty_str(value):
  356. return value.strip()
  357. return None
  358. def _oauth_stamps(
  359. entry: dict[str, Any]) -> tuple[Optional[float], Optional[float], Optional[float]]:
  360. """(JWT iat, local issue stamp, expires) epoch seconds of an OAuth pair."""
  361. from agent.credential_pool_timestamps import _parse_absolute_timestamp
  362. claims = _decode_jwt_claims(entry.get("access_token"))
  363. def first(*values: Any) -> Optional[float]:
  364. return next((ts for ts in map(_parse_absolute_timestamp, values) if ts), None)
  365. return (first(claims.get("iat")), first(entry.get("last_refresh"), entry.get("obtained_at")),
  366. first(claims.get("exp"), entry.get("expires_at_ms"), entry.get("expires_at")))
  367. def _sign(x: Optional[float], y: Optional[float]) -> Optional[int]:
  368. """Order of two stamps when both are known, else None."""
  369. return None if x is None or y is None else (x > y) - (x < y)
  370. def oauth_pair_order(a: dict[str, Any], b: dict[str, Any]) -> Optional[int]:
  371. """1 when *a* holds the later-issued OAuth pair than *b*, -1 the earlier, 0 tied, None unstamped.
  372. ISSUE time decides: a rotation always issues later, but not always later-expiring (the Portal
  373. sets access TTLs per client and per issue), so expiry only orders pairs lacking an issue stamp
  374. on either side. Equal whole-second ``iat`` claims (two rotations in one second) fall to the
  375. sub-second local issue stamp, and stay a tie without one. A side with no stamp at all is older.
  376. """
  377. (ia, la, ea), (ib, lb, eb) = _oauth_stamps(a), _oauth_stamps(b)
  378. if ia is not None and ib is not None:
  379. return _sign(ia, ib) or _sign(la, lb) or 0
  380. issued = _sign(ia or la, ib or lb)
  381. if issued is not None:
  382. return issued
  383. if _sign(ea, eb):
  384. return _sign(ea, eb)
  385. sa, sb = (ia, la, ea), (ib, lb, eb)
  386. a_any, b_any = any(v is not None for v in sa), any(v is not None for v in sb)
  387. if not a_any and not b_any:
  388. return None
  389. return 0 if a_any == b_any else (1 if a_any else -1)
  390. def _oauth_fresher(candidate: dict[str, Any], target: dict[str, Any]) -> bool:
  391. return oauth_pair_order(candidate, target) == 1
  392. def _find_root_counterpart(
  393. profile_row: dict[str, Any], root_rows: list[dict[str, Any]]) -> Optional[int]:
  394. """Index of the root OAuth row that shares a grant lineage with *profile_row*.
  395. Only a copied row ID or shared token material establishes lineage. The same
  396. account/client can issue multiple independent grants; identity is not proof.
  397. """
  398. from hermes_cli.auth import _nonempty_str
  399. candidates = [i for i, r in enumerate(root_rows) if _is_oauth_pool_payload(r)]
  400. if not candidates:
  401. return None
  402. pid = profile_row.get("id")
  403. for i in candidates:
  404. if pid and root_rows[i].get("id") == pid:
  405. return i
  406. for key in ("refresh_token", "access_token"):
  407. p_val = profile_row.get(key)
  408. if not _nonempty_str(p_val):
  409. continue
  410. for i in candidates:
  411. if root_rows[i].get(key) == p_val:
  412. return i
  413. return None
  414. def _adopt_oauth_material(target: dict[str, Any], winner: dict[str, Any]) -> dict[str, Any]:
  415. """Return *target* carrying *winner*'s token pair, status markers cleared."""
  416. from hermes_cli.auth import _POOL_STATUS_FIELDS
  417. merged = dict(target)
  418. for key in _OAUTH_TOKEN_FIELDS:
  419. if winner.get(key) is not None:
  420. merged[key] = winner[key]
  421. else:
  422. merged.pop(key, None)
  423. merged.update(dict.fromkeys(_POOL_STATUS_FIELDS))
  424. return merged
  425. def _singleton_as_row(path: Path) -> Optional[dict[str, Any]]:
  426. """Read a ``.anthropic_oauth.json`` as a pool-row-shaped dict, or None."""
  427. try:
  428. data = json.loads(path.read_text(encoding="utf-8-sig"))
  429. except (OSError, ValueError):
  430. return None
  431. if not isinstance(data, dict) or not str(data.get("accessToken") or "").strip():
  432. return None
  433. return {
  434. "access_token": data.get("accessToken"),
  435. "refresh_token": data.get("refreshToken"),
  436. "expires_at_ms": data.get("expiresAt")}
  437. def heal_forked_single_use_oauth_grants(provider_id: str) -> Optional[dict[str, Any]]:
  438. """One-time heal for installs that ALREADY forked a single-use grant into a profile.
  439. Forked copies are one credential with several owners: whichever profile rotated last holds the
  440. only live refresh token and every other copy (root included) is spent. Runs at profile
  441. ``load_pool()`` time for ``SINGLE_USE_REFRESH_POOL_PROVIDERS``: finds profile rows sharing
  442. LINEAGE with a root row (same pool id or shared token material), keeps the
  443. freshest rotation, writes it into ROOT when root's is older, and strips the profile's copy so
  444. the profile borrows root from then on. Idempotent; never touches API-key rows; never deletes a
  445. row with no root counterpart (an independent ``hermes -p <p> auth add`` grant, or the only
  446. surviving copy); reads only the two auth.json files the root fallback already reads. Returns
  447. ``{"adopted", "stripped_ids", "files", "providers_block"}`` when something healed, else None.
  448. Never raises.
  449. """
  450. if provider_id not in SINGLE_USE_REFRESH_POOL_PROVIDERS:
  451. return None
  452. try:
  453. return _heal_forked_single_use_oauth_grants(provider_id)
  454. except Exception:
  455. logger.debug("%s: forked-OAuth heal skipped", provider_id, exc_info=True)
  456. return None
  457. def _heal_forked_provider_block(
  458. profile_store: dict[str, Any], root_store: dict[str, Any], provider_id: str,
  459. lineage_proven: bool = False) -> Optional[bool]:
  460. """Consolidate a forked ``providers.<id>`` device-code block into root.
  461. *lineage_proven* carries the pool-row verdict: a profile row that matched root by copied id
  462. or shared tokens proves the fork even after both sides rotated past token equality. Root's
  463. ``load_pool()`` re-seeds its ``device_code`` row FROM this block, so leaving root's block on
  464. the spent pair would undo the pool-row heal on the next root load.
  465. Returns None when nothing matched, False when the profile copy was dropped (root already
  466. newest), True when the profile copy was fresher and was adopted into root.
  467. """
  468. p_providers, r_providers = profile_store.get("providers"), root_store.get("providers")
  469. if not (isinstance(p_providers, dict) and isinstance(r_providers, dict)):
  470. return None
  471. p_block, r_block = p_providers.get(provider_id), r_providers.get(provider_id)
  472. if not (isinstance(p_block, dict) and _block_tokens(p_block).get("refresh_token")
  473. and isinstance(r_block, dict) and r_block):
  474. return None
  475. def _flat(block: dict[str, Any]) -> dict[str, Any]:
  476. return {**_block_tokens(block), "last_refresh": block.get("last_refresh")}
  477. p_flat, r_flat = _flat(p_block), _flat(r_block)
  478. # Provider blocks have no stable pool-row ID. Without a shared token pair
  479. # component (or lineage proven by the pool rows), a common account is
  480. # insufficient evidence of a copied grant.
  481. if not lineage_proven and not any(
  482. p_flat.get(key) and p_flat.get(key) == r_flat.get(key)
  483. for key in ("access_token", "refresh_token")
  484. ):
  485. return None
  486. adopted = _oauth_fresher(p_flat, r_flat)
  487. if adopted:
  488. r_providers[provider_id] = dict(p_block)
  489. del p_providers[provider_id]
  490. return adopted
  491. def _stat_sig(p: Optional[Path]) -> Optional[tuple[int, int, int, int]]:
  492. """File signature from ONE stat, or None when absent — a torn pair from two stats could
  493. leave a persisted clean mark matching a store rewritten between them."""
  494. try:
  495. st = p.stat() if p is not None else None
  496. except OSError:
  497. return None
  498. return file_signature(st) if st is not None else None
  499. def _pool_rows(store: dict[str, Any], provider_id: str) -> tuple[Any, list[Any]]:
  500. """``(store["credential_pool"], its provider_id rows-or-[])`` — pool may be None/non-dict."""
  501. pool = store.get("credential_pool")
  502. rows = pool.get(provider_id) if isinstance(pool, dict) else None
  503. return pool, rows if isinstance(rows, list) else []
  504. def owned_profile_reads_root_state(
  505. auth_store: dict[str, Any], provider_id: str, source_path: Optional[Path]) -> bool:
  506. """True when a profile that owns its own pool rows would seed ``providers.<id>`` from ROOT.
  507. Seeding that state re-copies root's single-use refresh token into the profile's pool, which
  508. is the fork #100339 forbids; the singleton seeders skip it."""
  509. from hermes_cli.auth import _global_auth_file_path, _same_path
  510. global_root = _global_auth_file_path()
  511. return bool(
  512. source_path is not None and global_root is not None and _same_path(source_path, global_root)
  513. and _pool_rows(auth_store, provider_id)[1])
  514. def _adopt_if_fresher(
  515. target: dict[str, Any], candidate: dict[str, Any]) -> Optional[dict[str, Any]]:
  516. """*target* carrying *candidate*'s pair when the candidate rotated later, else None."""
  517. fresher = _oauth_fresher(candidate, target)
  518. return _adopt_oauth_material(target, candidate) if fresher else None
  519. class _HealPass:
  520. """One heal pass over a profile store vs the root store for *provider_id*."""
  521. def __init__(self, profile_store, root_store, provider_id, root_singleton: Optional[Path]):
  522. self.profile_store, self.root_store = profile_store, root_store
  523. self.provider_id = provider_id
  524. self.summary: dict[str, Any] = {
  525. "adopted": False, "stripped_ids": [], "files": [], "providers_block": False}
  526. self.profile_changed = self.root_changed = False
  527. self.lineage_proven = False # a profile pool row matched root by copied id / shared tokens
  528. self.p_pool, self.p_rows = _pool_rows(profile_store, provider_id)
  529. self.r_pool, self.r_rows = _pool_rows(root_store, provider_id)
  530. self.r_oauth = [r for r in self.r_rows if _is_oauth_pool_payload(r)]
  531. self.root_singleton = root_singleton
  532. self.root_singleton_row = (
  533. _singleton_as_row(root_singleton)
  534. if root_singleton is not None and root_singleton.exists() else None)
  535. def _adopt_root_row(self, idx: int, row: dict[str, Any]) -> None:
  536. merged = _adopt_if_fresher(self.r_rows[idx], row)
  537. if merged is not None:
  538. self.r_rows[idx] = merged
  539. self.root_changed = self.summary["adopted"] = True
  540. def _adopt_root_singleton(self, row: dict[str, Any]) -> None:
  541. merged = _adopt_if_fresher(self.root_singleton_row, row)
  542. if merged is not None:
  543. self.root_singleton_row = merged
  544. self.summary["adopted"] = True
  545. def heal_pool_rows(self) -> None:
  546. kept_rows: list[Any] = []
  547. for row in self.p_rows:
  548. if not _is_forkable_pool_row(self.provider_id, row):
  549. # API keys (and agent_key-only nous rows) are safe to duplicate
  550. kept_rows.append(row)
  551. continue
  552. match_idx = _find_root_counterpart(row, self.r_rows)
  553. if match_idx is not None:
  554. self.lineage_proven = True
  555. self._adopt_root_row(match_idx, row)
  556. # No root pool counterpart. Root's grant may live only in its .anthropic_oauth.json
  557. # (the ``hermes auth`` PKCE shape); a profile ``hermes_pkce`` row is its copy. Not
  558. # ``manual:hermes_pkce``: that is an ``auth add`` login the pool owns, never a copy.
  559. elif row.get("source") == "hermes_pkce" and self.root_singleton_row is not None and not self.r_oauth:
  560. self._adopt_root_singleton(row)
  561. else:
  562. # Root holds no copy of this lineage (independent account, or root never had the
  563. # grant): the profile's row may be the only surviving copy — leave it alone.
  564. kept_rows.append(row)
  565. continue
  566. self.summary["stripped_ids"].append(row.get("id"))
  567. self.profile_changed = True
  568. if self.profile_changed and isinstance(self.p_pool, dict):
  569. if kept_rows:
  570. self.p_pool[self.provider_id] = kept_rows
  571. else:
  572. self.p_pool.pop(self.provider_id, None)
  573. def heal_provider_block(self) -> None:
  574. if self.provider_id not in _DEVICE_CODE_BLOCK_PROVIDERS:
  575. return
  576. block_result = _heal_forked_provider_block(
  577. self.profile_store, self.root_store, self.provider_id, self.lineage_proven)
  578. if block_result is not None:
  579. self.profile_changed = self.summary["providers_block"] = True
  580. if block_result:
  581. self.root_changed = self.summary["adopted"] = True
  582. def heal_profile_singleton(self, profile_singleton: Optional[Path]) -> None:
  583. if profile_singleton is None or not profile_singleton.exists():
  584. return
  585. from hermes_cli.auth import _is_same_auth_store
  586. if self.root_singleton is not None and _is_same_auth_store(profile_singleton, self.root_singleton):
  587. return # an aliased singleton pair is one shared grant, not a fork: never self-compare/unlink
  588. # See #101356.
  589. p_single = _singleton_as_row(profile_singleton)
  590. root_has_grant = bool(self.r_oauth) or self.root_singleton_row is not None
  591. # Otherwise root has NO grant for this provider (or the file is not a grant): the
  592. # profile's singleton may be the only surviving copy — never delete it.
  593. if p_single is None or not root_has_grant:
  594. return
  595. if self.root_singleton_row is not None:
  596. self._adopt_root_singleton(p_single)
  597. else:
  598. # Root only has pool rows: fold the singleton's pair into the freshest-matching
  599. # root pkce row, if any.
  600. idx = next(
  601. (i for i, r in enumerate(self.r_rows)
  602. if _is_oauth_pool_payload(r) and _is_pkce_row(r)), None)
  603. if idx is not None:
  604. self._adopt_root_row(idx, p_single)
  605. try:
  606. profile_singleton.unlink()
  607. self.summary["files"].append(profile_singleton.name)
  608. except OSError:
  609. logger.debug("could not remove %s", profile_singleton, exc_info=True)
  610. def sync_root_singleton_with_pkce_row(self) -> None:
  611. """Keep root's singleton and its ``hermes_pkce``-seeded pool row in step.
  612. Root's next load_pool() re-seeds that row FROM the singleton file, so a stale file would
  613. resurrect the spent pair (and a stale row would be overwritten by a fresh file).
  614. """
  615. if not (
  616. self.summary["adopted"] and self.root_singleton is not None
  617. and self.root_singleton_row is not None):
  618. return
  619. pkce_idx = next(
  620. (i for i, r in enumerate(self.r_rows)
  621. if _is_oauth_pool_payload(r) and r.get("source") == "hermes_pkce"), None)
  622. if pkce_idx is None:
  623. return
  624. pkce_row = self.r_rows[pkce_idx]
  625. order = oauth_pair_order(pkce_row, self.root_singleton_row)
  626. if order == 1:
  627. self.root_singleton_row = _adopt_oauth_material(self.root_singleton_row, pkce_row)
  628. elif order == -1:
  629. self.r_rows[pkce_idx] = _adopt_oauth_material(pkce_row, self.root_singleton_row)
  630. self.root_changed = True
  631. @property
  632. def dirty(self) -> bool:
  633. return bool(self.profile_changed or self.root_changed or self.summary["adopted"])
  634. def notice(self, profile_name: str) -> str:
  635. summary = self.summary
  636. log_bits = [bit for bit, present in (
  637. (f"pool rows {summary['stripped_ids']}", summary["stripped_ids"]),
  638. (f"providers.{self.provider_id} block", summary["providers_block"]),
  639. (", ".join(summary["files"]), summary["files"])) if present]
  640. verdict = (
  641. "profile copy was the live pair; root updated"
  642. if summary["adopted"] else "root copy already newest; profile copy dropped")
  643. return (
  644. f"profile {profile_name}: consolidated forked {self.provider_id} OAuth grant "
  645. f"({'; '.join(log_bits) or 'no-op'}) into the root grant — {verdict}; "
  646. f"this profile now borrows the root grant (#100339)")
  647. def _heal_forked_single_use_oauth_grants(provider_id: str) -> Optional[dict[str, Any]]:
  648. from hermes_cli.auth import (
  649. _auth_file_path, _auth_store_lock, _global_auth_file_path, _load_auth_store,
  650. _is_same_auth_store, _oauth_heal_clean_marks, _oauth_heal_notices, _same_path,
  651. _save_auth_store)
  652. root_path = _global_auth_file_path()
  653. if root_path is None:
  654. return None # classic mode: nothing to consolidate into
  655. if os.environ.get("PYTEST_CURRENT_TEST"):
  656. # Same seat belt as the write-through paths: never touch the real user's
  657. # ~/.hermes/auth.json from a test that forgot to isolate HOME.
  658. real_home_env = os.environ.get("HOME", "")
  659. if real_home_env and _same_path(root_path, Path(real_home_env) / ".hermes" / "auth.json"):
  660. return None
  661. profile_path = _auth_file_path()
  662. profile_home = profile_path.parent
  663. is_anthropic = provider_id == "anthropic"
  664. profile_singleton = profile_home / ".anthropic_oauth.json" if is_anthropic else None
  665. root_singleton = root_path.parent / ".anthropic_oauth.json" if is_anthropic else None
  666. # Hot-path short-circuit: load_pool() runs per model call. Once this profile's store was
  667. # verified clean for *provider_id*, skip the locked read-modify-write until one of the files
  668. # it reads changes.
  669. #
  670. # The ROOT store is part of the fingerprint even though only the profile side is read above:
  671. # this heal consolidates root -> profile, so a new forked grant appearing in ROOT must
  672. # invalidate the mark. The in-memory mark omitted it and got away with it because it died
  673. # with the process; a persisted mark would otherwise keep skipping a heal that has become
  674. # necessary. Sizes, inodes and ctimes ride along with the mtimes for the same reason:
  675. # a metadata-preserving rewrite (``rsync -t``, ``tar -p``, a restore) would otherwise leave
  676. # a stale mark looking current indefinitely rather than for one process.
  677. fingerprint = (
  678. str(profile_path), _stat_sig(profile_path), _stat_sig(profile_singleton),
  679. str(root_path), _stat_sig(root_path), _stat_sig(root_singleton),
  680. )
  681. if _oauth_heal_clean_marks.get(provider_id) == fingerprint:
  682. return None
  683. # Same check against the on-disk mark, BEFORE taking any lock: a fresh process would
  684. # otherwise pay two nested exclusive auth-store locks — a full AUTH_LOCK_TIMEOUT_SECONDS
  685. # each behind a sibling holding them — only to find nothing to consolidate.
  686. if _persisted_oauth_heal_fingerprint(provider_id) == _json_shape(fingerprint):
  687. _oauth_heal_clean_marks[provider_id] = fingerprint
  688. return None
  689. if fingerprint[1] is None and fingerprint[2] is None:
  690. _mark_oauth_heal_clean(provider_id, fingerprint)
  691. return None
  692. if _is_same_auth_store(profile_path, root_path):
  693. # The profile's auth.json IS the root store (symlink/hardlink alias — a deliberate way to
  694. # share one grant). Both "sides" would read the same file, every OAuth row would match
  695. # itself, and the strip would write through the alias and delete the shared credential.
  696. # Nothing to consolidate; the mtime mark keeps this off the per-call hot path.
  697. _mark_oauth_heal_clean(provider_id, fingerprint)
  698. # See #101356.
  699. logger.debug("%s: forked-OAuth heal skipped, %s is the root store", provider_id, profile_path)
  700. return None
  701. # Lock order: active (profile) store first, then the root source store — the same order
  702. # ``_provider_state_transaction`` uses.
  703. with _auth_store_lock():
  704. profile_store = (
  705. _load_auth_store(profile_path) if profile_path.exists() else {"providers": {}})
  706. with _auth_store_lock(target_path=root_path):
  707. root_store = _load_auth_store(root_path) if root_path.exists() else {"providers": {}}
  708. run = _HealPass(profile_store, root_store, provider_id, root_singleton)
  709. run.heal_pool_rows()
  710. run.heal_provider_block()
  711. run.heal_profile_singleton(profile_singleton)
  712. if not run.dirty:
  713. _mark_oauth_heal_clean(provider_id, fingerprint)
  714. return None
  715. run.sync_root_singleton_with_pkce_row()
  716. summary = run.summary
  717. if run.root_changed:
  718. if isinstance(run.r_pool, dict):
  719. run.r_pool[provider_id] = run.r_rows
  720. else:
  721. root_store["credential_pool"] = {provider_id: run.r_rows}
  722. _save_auth_store(root_store, target_path=root_path)
  723. singleton_row = run.root_singleton_row
  724. if summary["adopted"] and root_singleton is not None and singleton_row is not None:
  725. from agent.anthropic_credentials import _write_hermes_oauth_credentials
  726. _write_hermes_oauth_credentials(
  727. singleton_row.get("access_token") or "", singleton_row.get("refresh_token"),
  728. singleton_row.get("expires_at_ms"), target=root_singleton)
  729. if run.profile_changed and profile_path.exists():
  730. _save_auth_store(profile_store, target_path=profile_path)
  731. message = run.notice(profile_home.name)
  732. logger.info(message)
  733. _oauth_heal_notices.append(message)
  734. return summary