web_server_dashboard.py 63 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252
  1. """Dashboard UI assets: SPA mount, theme normalisation/bootstrap CSS, dashboard-plugin discovery and the plugins-hub merge.
  2. """
  3. import asyncio
  4. import logging
  5. import importlib.util
  6. import json
  7. import os
  8. import sys
  9. import threading
  10. import time
  11. from contextlib import contextmanager
  12. import hermes_yaml as yaml
  13. from fastapi import Depends, FastAPI, HTTPException, Request, WebSocket, WebSocketException
  14. from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
  15. from fastapi.staticfiles import StaticFiles
  16. from starlette import status
  17. from starlette._utils import get_route_path
  18. from starlette.requests import HTTPConnection
  19. from pathlib import Path
  20. from typing import Any, Dict, List, Optional
  21. from hermes_cli.config import cfg_get, get_process_hermes_home
  22. from utils import env_var_enabled
  23. # Serve assets with explicit MIME types: the host's map (on Windows the
  24. # registry can map .js -> text/plain) must not decide the Content-Type of
  25. # dashboard bundles (#28987). Runs before any StaticFiles/FileResponse below
  26. # serves a request, and is idempotent.
  27. from hermes_cli.web_asset_mime_types import normalize_web_asset_mime_types
  28. normalize_web_asset_mime_types()
  29. # Same logger the code used before extraction (record parity).
  30. _log = logging.getLogger("hermes_cli.web_server")
  31. def _normalise_prefix(raw: Optional[str]) -> str:
  32. """Normalise an X-Forwarded-Prefix header value (single source of truth lives in
  33. ``hermes_cli.dashboard_auth.prefix`` so gate, OAuth, cookies and SPA mount agree)."""
  34. from hermes_cli.dashboard_auth.prefix import normalise_prefix
  35. return normalise_prefix(raw)
  36. def _layer_hex(palette: dict[str, Any], key: str, default: str) -> str:
  37. layer = palette.get(key) or {}
  38. return layer.get("hex", default) if isinstance(layer, dict) else default
  39. def _render_active_theme_bootstrap_css() -> str:
  40. """Critical-CSS ``<style>`` shim for the active *user* theme, so the first paint uses the
  41. target palette instead of flashing the bundle's default Hermes Teal until
  42. ``ThemeProvider.applyTheme()`` runs. Built-in themes return "" (the bundle owns them).
  43. Variable names MUST match what the bundle consumes (``layerVars()`` /
  44. ``typographyVars()`` in ``web/src/themes/context.tsx``). The ``html,body`` rule
  45. references the variables rather than literals so runtime theme switches stay live:
  46. ``applyTheme()`` writes inline styles on ``documentElement`` which outrank this block.
  47. """
  48. from hermes_cli.config import load_config
  49. try:
  50. active = cfg_get(load_config(), "dashboard", "theme", default="default")
  51. if not active or not isinstance(active, str):
  52. return ""
  53. if any(b["name"] == active for b in _BUILTIN_DASHBOARD_THEMES):
  54. return ""
  55. for theme in _discover_user_themes():
  56. if theme.get("name") != active:
  57. continue
  58. palette = theme.get("palette") or {}
  59. typo = theme.get("typography") or {}
  60. font_sans = typo.get("fontSans") or _THEME_DEFAULT_TYPOGRAPHY["fontSans"]
  61. base_size = typo.get("baseSize") or _THEME_DEFAULT_TYPOGRAPHY["baseSize"]
  62. def _esc(s: str) -> str: # defensive ``</style>`` escape
  63. return str(s).replace("</", "<\\/")
  64. return (
  65. '<style id="hermes-theme-bootstrap">'
  66. ":root{"
  67. f"--background-base:{_esc(_layer_hex(palette, 'background', '#0a0a0a'))};"
  68. f"--midground-base:{_esc(_layer_hex(palette, 'midground', '#e5e5e5'))};"
  69. f"--theme-font-sans:{_esc(font_sans)};"
  70. f"--theme-base-size:{_esc(base_size)};"
  71. "}"
  72. "html,body{background-color:var(--background-base);"
  73. "color:var(--midground-base);"
  74. "font-family:var(--theme-font-sans);"
  75. "font-size:var(--theme-base-size);}"
  76. "</style>"
  77. )
  78. return ""
  79. except Exception:
  80. _log.debug("theme bootstrap render failed", exc_info=True)
  81. return ""
  82. # Hashed bundle assets are immutable by construction (content hash in the filename; index.html
  83. # is served ``no-store`` and always references the current hashes).
  84. _IMMUTABLE_ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable"
  85. _NO_STORE = {"Cache-Control": "no-store, no-cache, must-revalidate"}
  86. _HEADLESS_MSG = (
  87. "Headless backend (hermes serve): web UI disabled — use "
  88. "`hermes dashboard` for the browser UI."
  89. )
  90. def mount_spa(application: FastAPI):
  91. """Mount the built SPA; unmatched paths fall back to index.html for client-side routing.
  92. Dashboard injects its session token into index.html; Webapp instead receives
  93. the same credential through an operator-only launch fragment. Behind a path-prefix reverse
  94. proxy (``X-Forwarded-Prefix: /hermes``) the served index.html is rewritten so absolute
  95. asset URLs and the runtime ``__HERMES_BASE_PATH__`` honour that prefix without a rebuild.
  96. A missing WEB_DIST is deliberately NOT a mount-time terminal state: every route copes
  97. with a missing dist per-request (404 JSON / ``check_dir=False``), so a long-lived
  98. ``--skip-build`` process recovers the moment a build appears on disk — no restart.
  99. The dist is also chosen per request: this mount runs at import, and a host that serves
  100. another renderer (the Webapp's ``dist-webapp``) records it on ``application.state.web_dist``
  101. later.
  102. """
  103. from hermes_cli.web_server import WEB_DIST, _DASHBOARD_EMBEDDED_CHAT_ENABLED
  104. from hermes_cli.web_deps import _server
  105. from hermes_cli.web_server_surface import policy
  106. from hermes_cli.web_server_static_assets import is_static_asset_path, public_font_file
  107. # `hermes serve` is the headless backend: it must NEVER serve the browser SPA, even if a
  108. # dist is lying around, so only the JSON-RPC/WS/API surface is reachable.
  109. if os.environ.get("HERMES_SERVE_HEADLESS") == "1":
  110. @application.get("/{full_path:path}")
  111. async def no_frontend(full_path: str):
  112. # Desktop token handshake: the Electron shell boots by fetching `/` and reading
  113. # ``window.__HERMES_SESSION_TOKEN__`` for /api/ws auth. When headless 404'd every
  114. # path, a renderer whose spawn token no longer matched (e.g. after `hermes update`)
  115. # white-screened. Serve a token-only page at the exact root, but ONLY when the auth
  116. # gate is off: on a gated serve the token must never be readable without auth.
  117. # See #94227, #95575.
  118. gated = bool(getattr(application.state, "auth_required", False))
  119. withheld = gated or bool(getattr(_server().app.state, "withhold_session_token", False))
  120. if full_path == "" and not withheld:
  121. return HTMLResponse(
  122. "<!doctype html><html><head><script>"
  123. f"window.__HERMES_SESSION_TOKEN__={json.dumps(_server()._SESSION_TOKEN)};"
  124. "window.__HERMES_AUTH_REQUIRED__=false;"
  125. f"</script></head><body>{_HEADLESS_MSG}</body></html>",
  126. headers=_NO_STORE,
  127. )
  128. return JSONResponse({"error": _HEADLESS_MSG}, status_code=404)
  129. return
  130. # A missing WEB_DIST is deliberately NOT a mount-time terminal state (#82614): a long-lived `hermes
  131. # dashboard --skip-build` process that survives a `git pull` (or starts before the first build) used to
  132. # install a permanent no_frontend catch-all here and could never recover — every route answered 404
  133. # "Frontend not built" until the process was restarted, even after `npm run build` completed. The SPA
  134. # routes below all cope with a missing dist per-request (`_serve_index` returns the same 404 JSON when
  135. # index.html is unreadable; the asset mounts use check_dir=False and 404 on missing files), so mounting
  136. # them unconditionally makes the dashboard recover the moment a build appears on disk — no restart
  137. # needed.
  138. def web_dist() -> Path:
  139. return getattr(application.state, "web_dist", None) or WEB_DIST
  140. def _serve_index(request: Request, prefix: str = ""):
  141. """index.html with the session token + base-path injected.
  142. When the OAuth auth gate is active (``app.state.auth_required``), the legacy
  143. ``_SESSION_TOKEN`` is NOT injected — the SPA reads identity from ``/api/auth/me`` over
  144. cookie auth; ``__HERMES_AUTH_REQUIRED__`` tells it which scheme to use for /api/pty
  145. and /api/ws (ticket vs token).
  146. """
  147. try:
  148. html = (web_dist() / "index.html").read_text(encoding="utf-8-sig")
  149. except OSError:
  150. # Partial build / wiped dist / permissions: same JSON 404 as a fully-missing dist. The
  151. # Webapp's bundle is built by `hermes webapp`, not by the dashboard's web project.
  152. webapp = getattr(application.state, "ui_surface", "dashboard") == "webapp"
  153. missing = ("The Webapp is not built. Run: hermes webapp" if webapp
  154. else "Frontend not built. Run: cd web && npm run build")
  155. return JSONResponse({"error": missing}, status_code=404)
  156. if getattr(application.state, "ui_surface", "dashboard") == "webapp":
  157. # A bundle `hermes update` could not rebuild was built for the code before the update:
  158. # refuse it until `hermes webapp` rebuilds it.
  159. from gateway.webapp_listener import bundle_stale_reason
  160. stale = bundle_stale_reason(web_dist())
  161. if stale:
  162. return JSONResponse({"error": stale}, status_code=503, headers=_NO_STORE)
  163. chat_js = "true" if _DASHBOARD_EMBEDDED_CHAT_ENABLED else "false"
  164. gated = bool(getattr(application.state, "auth_required", False))
  165. # Only a host that records its surface (the gateway's Webapp) names it to the page.
  166. surface = getattr(application.state, "ui_surface", None)
  167. surface_js = "" if surface is None else f"window.__HERMES_UI_SURFACE__={json.dumps(surface)};"
  168. # Webapp grants host files and shell.exec as well as PTYs: its existing
  169. # session token must come from the operator, never anonymous HTML. The
  170. # gateway-hosted listener (gateway/run_api.py) never publishes it either:
  171. # local clients use tickets.
  172. withheld = (gated or bool(getattr(_server().app.state, "withhold_session_token", False))
  173. or not policy(application.state).html_token)
  174. token_js = "" if withheld else f'window.__HERMES_SESSION_TOKEN__="{_server()._SESSION_TOKEN}";'
  175. # Launcher-preselected profile (``--open-profile``): the SPA's fallback scope when the URL
  176. # omits ``?profile=`` (#73085). ``</`` escaped so a hostile name cannot close the script tag.
  177. initial_profile_js = json.dumps(str(getattr(application.state, "initial_profile", "") or "")).replace("</", "<\\/")
  178. # This backend's OWN profile name (empty when it cannot be named unambiguously). The SPA
  179. # falls back to it when neither the URL nor --open-profile names one, so requests carry an
  180. # explicit scope from the first paint: destructive routes 400 on an unnamed profile as soon
  181. # as the host serves more than one, and the switcher shows the same profile it writes. The
  182. # Webapp reads it as the profile its gateway socket and REST answer for when a request names
  183. # none, so a tab on any other profile names that profile on every request.
  184. from hermes_cli.web_server_profiles import serving_profile_name as _serving_profile_name
  185. serving_profile_js = json.dumps(_serving_profile_name()).replace("</", "<\\/")
  186. bootstrap_script = (
  187. f"<script>{token_js}"
  188. f"window.__HERMES_DASHBOARD_EMBEDDED_CHAT__={chat_js};"
  189. f'window.__HERMES_BASE_PATH__="{prefix}";'
  190. f"window.__HERMES_AUTH_REQUIRED__={'true' if gated else 'false'};"
  191. f"window.__HERMES_INITIAL_PROFILE__={initial_profile_js};"
  192. f"{surface_js}"
  193. f"window.__HERMES_DASHBOARD_PROFILE__={serving_profile_js};"
  194. f"</script>"
  195. )
  196. if prefix:
  197. # Rewrite absolute asset URLs baked into the Vite build to go through the proxy.
  198. for attr in ('href="/assets/', 'src="/assets/', 'href="/favicon.ico"', 'href="/fonts/',
  199. 'href="/ds-assets/', 'src="/ds-assets/'):
  200. html = html.replace(attr, attr.replace('"/', f'"{prefix}/', 1))
  201. theme_bootstrap = _render_active_theme_bootstrap_css()
  202. if theme_bootstrap:
  203. html = html.replace("</head>", f"{theme_bootstrap}</head>", 1)
  204. html = html.replace("</head>", f"{bootstrap_script}</head>", 1)
  205. from hermes_cli.webapp_page_policy import page_headers
  206. return HTMLResponse(html, headers=page_headers(request, html, _NO_STORE))
  207. # Built CSS contains absolute ``url(/fonts/...)`` / ``url(/ds-assets/...)`` references that
  208. # browsers resolve against the document origin — wrong under a proxy prefix. Intercept CSS
  209. # BEFORE the StaticFiles mount and rewrite when a prefix is in play.
  210. @application.get("/assets/{filename}.css")
  211. async def serve_css(filename: str, request: Request):
  212. dist = web_dist()
  213. css_path = dist / "assets" / f"{filename}.css"
  214. if not css_path.is_file() or not css_path.resolve().is_relative_to(dist.resolve()):
  215. return JSONResponse({"error": "not found"}, status_code=404)
  216. prefix = _normalise_prefix(request.headers.get("x-forwarded-prefix"))
  217. css = css_path.read_text(encoding="utf-8-sig")
  218. if prefix:
  219. for asset_dir in ("/fonts/", "/fonts-terminal/", "/ds-assets/", "/assets/"):
  220. for quote in ("", '"', "'"):
  221. css = css.replace(f"url({quote}{asset_dir}", f"url({quote}{prefix}{asset_dir}")
  222. return Response(
  223. content=css, media_type="text/css", headers={"Cache-Control": _IMMUTABLE_ASSET_CACHE_CONTROL}
  224. )
  225. class _ImmutableAssetFiles(StaticFiles):
  226. """StaticFiles that marks hashed bundle assets immutable so reloads skip revalidation."""
  227. async def get_response(self, path: str, scope):
  228. response = await super().get_response(path, scope)
  229. if response.status_code == 200:
  230. response.headers["Cache-Control"] = _IMMUTABLE_ASSET_CACHE_CONTROL
  231. return response
  232. asset_files: dict[Path, StaticFiles] = {}
  233. async def serve_assets(scope, receive, send):
  234. # check_dir=False: the dist may not exist yet; StaticFiles 404s per-request until it does.
  235. directory = web_dist() / "assets"
  236. if directory not in asset_files:
  237. asset_files[directory] = _ImmutableAssetFiles(directory=directory, check_dir=False)
  238. await asset_files[directory](scope, receive, send)
  239. from hermes_cli.webapp_previews import mount_preview_assets
  240. mount_preview_assets(application)
  241. application.mount("/assets", serve_assets, name="assets")
  242. @application.get("/{full_path:path}")
  243. async def serve_spa(full_path: str, request: Request):
  244. prefix = _normalise_prefix(request.headers.get("x-forwarded-prefix"))
  245. # An unmatched /api/* path is a missing endpoint, not a client-side route: return a
  246. # real 404 JSON instead of index.html (which breaks JSON clients with a SyntaxError).
  247. if full_path == "api" or full_path.startswith("api/"):
  248. return JSONResponse({"detail": f"No such API endpoint: /{full_path}"}, status_code=404)
  249. dist = web_dist()
  250. file_path = dist / full_path
  251. index = dist / "index.html"
  252. if (not policy(application.state).html_token and file_path.is_file() and index.is_file()
  253. and file_path.samefile(index)):
  254. # No spelling of the entry document may bypass bootstrap or policy.
  255. return _serve_index(request, prefix)
  256. # Prevent path traversal via url-encoded sequences (%2e%2e/)
  257. if (
  258. full_path
  259. and file_path.resolve().is_relative_to(dist.resolve())
  260. and file_path.exists()
  261. and file_path.is_file()
  262. ):
  263. return FileResponse(file_path)
  264. if is_static_asset_path(full_path):
  265. font = public_font_file(dist, WEB_DIST, full_path)
  266. if font is not None:
  267. return FileResponse(font)
  268. return JSONResponse({"error": "not found"}, status_code=404)
  269. return _serve_index(request, prefix)
  270. # ---------------------------------------------------------------------------
  271. # Dashboard themes
  272. # ---------------------------------------------------------------------------
  273. # Built-in themes — label + description only; colors live in web/src/themes/presets.ts.
  274. _BUILTIN_DASHBOARD_THEMES = [
  275. {"name": "default", "label": "Hermes Teal", "description": "Classic dark teal — the canonical Hermes look"},
  276. {"name": "default-large", "label": "Hermes Teal (Large)", "description": "Hermes Teal with bigger fonts and roomier spacing"},
  277. {"name": "nous-blue", "label": "Nous Blue", "description": "Light mode — vivid Nous-blue accents on cream canvas"},
  278. {"name": "midnight", "label": "Midnight", "description": "Deep blue-violet with cool accents"},
  279. {"name": "ember", "label": "Ember", "description": "Warm crimson and bronze — forge vibes"},
  280. {"name": "mono", "label": "Mono", "description": "Clean grayscale — minimal and focused"},
  281. {"name": "cyberpunk", "label": "Cyberpunk", "description": "Neon green on black — matrix terminal"},
  282. {"name": "rose", "label": "Rosé", "description": "Soft pink and warm ivory — easy on the eyes"},
  283. ]
  284. def _parse_theme_layer(value: Any, default_hex: str, default_alpha: float = 1.0) -> Optional[dict[str, Any]]:
  285. """Normalise a theme layer spec (bare hex shorthand or ``{hex, alpha}`` dict); ``None`` on
  286. garbage so the caller falls back to a built-in default."""
  287. if value is None:
  288. return {"hex": default_hex, "alpha": default_alpha}
  289. if isinstance(value, str):
  290. return {"hex": value, "alpha": default_alpha}
  291. if not isinstance(value, dict):
  292. return None
  293. hex_val = value.get("hex", default_hex)
  294. if not isinstance(hex_val, str):
  295. return None
  296. try:
  297. alpha_f = float(value.get("alpha", default_alpha))
  298. except (TypeError, ValueError):
  299. alpha_f = default_alpha
  300. return {"hex": hex_val, "alpha": max(0.0, min(1.0, alpha_f))}
  301. _THEME_DEFAULT_TYPOGRAPHY: dict[str, str] = {
  302. "fontSans": 'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
  303. "fontMono": 'ui-monospace, "SF Mono", "Cascadia Mono", Menlo, Consolas, monospace',
  304. "baseSize": "15px",
  305. "lineHeight": "1.55",
  306. "letterSpacing": "0",
  307. }
  308. _THEME_DEFAULT_LAYOUT: dict[str, str] = {
  309. "radius": "0.5rem", "density": "comfortable"
  310. }
  311. _THEME_OVERRIDE_KEYS = {
  312. "card", "cardForeground", "popover", "popoverForeground",
  313. "primary", "primaryForeground", "secondary", "secondaryForeground",
  314. "muted", "mutedForeground", "accent", "accentForeground",
  315. "destructive", "destructiveForeground", "success", "warning",
  316. "border", "input", "ring",
  317. }
  318. # Named asset slots; other keys under ``assets.custom`` become ``--theme-asset-custom-<key>``.
  319. _THEME_NAMED_ASSET_KEYS = {"bg", "hero", "logo", "crest", "sidebar", "header"}
  320. # Component-style buckets: each camelCase property under a bucket emits
  321. # ``--component-<bucket>-<kebab-property>`` on :root, consumed by shell components.
  322. _THEME_COMPONENT_BUCKETS = {
  323. "card", "header", "footer", "sidebar", "tab", "progress", "badge", "backdrop", "page"
  324. }
  325. _THEME_LAYOUT_VARIANTS = {"standard", "cockpit", "tiled"}
  326. # customCSS cap so an oversized theme YAML can't blow up the payload or <style> tag.
  327. _THEME_CUSTOM_CSS_MAX = 32 * 1024
  328. def _dict_field(data: dict[str, Any], key: str) -> dict[str, Any]:
  329. value = data.get(key)
  330. return value if isinstance(value, dict) else {}
  331. def _nonempty_str(value: Any) -> bool:
  332. return isinstance(value, str) and bool(value.strip())
  333. def _css_ident(key: Any) -> bool:
  334. return isinstance(key, str) and key.replace("-", "").replace("_", "").isalnum()
  335. def _normalise_theme_definition(data: dict[str, Any]) -> Optional[dict[str, Any]]:
  336. """Normalise a user theme YAML into the wire format ``ThemeProvider`` expects; ``None`` if
  337. unusable. Accepts the full schema and a loose form (top-level ``colors``, bare hex).
  338. customCSS is clipped but intentionally NOT sanitised — themes are user-authored YAML in
  339. ~/.hermes/, the same trust level as config.yaml. Empty asset values are dropped so a
  340. theme can explicitly clear a slot.
  341. """
  342. if not isinstance(data, dict):
  343. return None
  344. name = data.get("name")
  345. if not _nonempty_str(name):
  346. return None
  347. palette_src = _dict_field(data, "palette")
  348. colors_src = _dict_field(data, "colors")
  349. def _layer(key: str, default_hex: str, default_alpha: float = 1.0) -> dict[str, Any]:
  350. parsed = _parse_theme_layer(palette_src.get(key, colors_src.get(key)), default_hex, default_alpha)
  351. return parsed if parsed is not None else {"hex": default_hex, "alpha": default_alpha}
  352. raw_noise = palette_src.get("noiseOpacity", data.get("noiseOpacity"))
  353. try:
  354. noise = float(raw_noise) if raw_noise is not None else 1.0
  355. except (TypeError, ValueError):
  356. noise = 1.0
  357. palette = {
  358. "background": _layer("background", "#041c1c", 1.0),
  359. "midground": _layer("midground", "#ffe6cb", 1.0),
  360. "foreground": _layer("foreground", "#ffffff", 0.0),
  361. "warmGlow": palette_src.get("warmGlow") or data.get("warmGlow") or "rgba(255, 189, 56, 0.35)",
  362. "noiseOpacity": noise,
  363. }
  364. typo_src = _dict_field(data, "typography")
  365. typography = dict(_THEME_DEFAULT_TYPOGRAPHY)
  366. for key in ("fontSans", "fontMono", "fontDisplay", "fontUrl", "baseSize", "lineHeight", "letterSpacing"):
  367. if _nonempty_str(typo_src.get(key)):
  368. typography[key] = typo_src[key]
  369. layout_src = _dict_field(data, "layout")
  370. layout = dict(_THEME_DEFAULT_LAYOUT)
  371. if _nonempty_str(layout_src.get("radius")):
  372. layout["radius"] = layout_src["radius"]
  373. density = layout_src.get("density")
  374. if isinstance(density, str) and density in {"compact", "comfortable", "spacious"}:
  375. layout["density"] = density
  376. color_overrides = {
  377. k: v for k, v in _dict_field(data, "colorOverrides").items()
  378. if k in _THEME_OVERRIDE_KEYS and _nonempty_str(v)
  379. }
  380. assets_src = _dict_field(data, "assets")
  381. assets_out: dict[str, Any] = {k: assets_src[k] for k in _THEME_NAMED_ASSET_KEYS if _nonempty_str(assets_src.get(k))}
  382. custom_assets = {k: v for k, v in _dict_field(assets_src, "custom").items() if _css_ident(k) and _nonempty_str(v)}
  383. if custom_assets:
  384. assets_out["custom"] = custom_assets
  385. custom_css_val = data.get("customCSS")
  386. custom_css = custom_css_val[:_THEME_CUSTOM_CSS_MAX] if _nonempty_str(custom_css_val) else None
  387. component_styles: dict[str, dict[str, str]] = {}
  388. for bucket, props in _dict_field(data, "componentStyles").items():
  389. if bucket not in _THEME_COMPONENT_BUCKETS or not isinstance(props, dict):
  390. continue
  391. clean = {
  392. prop: str(value) for prop, value in props.items()
  393. if _css_ident(prop) and isinstance(value, (str, int, float)) and str(value).strip()
  394. }
  395. if clean:
  396. component_styles[bucket] = clean
  397. layout_variant = data.get("layoutVariant")
  398. if not (isinstance(layout_variant, str) and layout_variant in _THEME_LAYOUT_VARIANTS):
  399. layout_variant = "standard"
  400. result: dict[str, Any] = {
  401. "name": name,
  402. "label": data.get("label") or name,
  403. "description": data.get("description", ""),
  404. "palette": palette,
  405. "typography": typography,
  406. "layout": layout,
  407. "layoutVariant": layout_variant,
  408. }
  409. if color_overrides:
  410. result["colorOverrides"] = color_overrides
  411. if assets_out:
  412. result["assets"] = assets_out
  413. if custom_css is not None:
  414. result["customCSS"] = custom_css
  415. if component_styles:
  416. result["componentStyles"] = component_styles
  417. return result
  418. def _discover_user_themes() -> list:
  419. """Fully-normalised user themes from ``<launch home>/dashboard-themes/*.yaml``.
  420. Uses the process launch home, not ``get_hermes_home()``, so a transient profile override
  421. from embedded chat does not hide themes under the server's own ``HERMES_HOME``.
  422. """
  423. themes_dir = get_process_hermes_home() / "dashboard-themes"
  424. if not themes_dir.is_dir():
  425. return []
  426. result = []
  427. for f in sorted(themes_dir.glob("*.yaml")):
  428. try:
  429. data = yaml.safe_load(f.read_text(encoding="utf-8-sig"))
  430. except Exception:
  431. continue
  432. normalised = _normalise_theme_definition(data)
  433. if normalised is not None:
  434. result.append(normalised)
  435. return result
  436. # ---------------------------------------------------------------------------
  437. # Dashboard plugin system
  438. # ---------------------------------------------------------------------------
  439. def _safe_plugin_api_relpath(api_field: Any, *, dashboard_dir: Path) -> Optional[str]:
  440. """Validate the manifest's ``api`` field (later imported as a Python module — arbitrary
  441. code execution by design).
  442. An absolute path would swallow the plugin dir (``Path('safe') / '/tmp/evil.py'`` ->
  443. ``/tmp/evil.py``) and ``../`` could climb out of it (GHSA-5qr3-c538-wm9j). Returns the
  444. original string when the resolved path stays under ``dashboard_dir``, else ``None`` so
  445. the plugin still loads its static JS/CSS but its backend ``api`` is rejected.
  446. The web server later imports this file as a Python module via ``importlib.util.spec_from_file_location``
  447. (arbitrary code execution by design — that's how plugins extend the backend). Pre-#29156 the field was
  448. used as-is, which meant:
  449. """
  450. if not isinstance(api_field, str) or not api_field.strip():
  451. return None
  452. candidate = Path(api_field)
  453. if candidate.is_absolute():
  454. return None
  455. try:
  456. (dashboard_dir / candidate).resolve().relative_to(dashboard_dir.resolve())
  457. except (OSError, RuntimeError, ValueError):
  458. return None
  459. return api_field
  460. def _dashboard_plugin_search_dirs() -> list[tuple]:
  461. """``(root, source)`` pairs to scan, in priority order (first name wins).
  462. User dashboard plugins are a dashboard-owned asset (like theme YAML): resolved from the
  463. process launch home so they don't vanish when a request is scoped to another profile.
  464. When the process itself is profile-scoped (``HERMES_HOME=<root>/profiles/<name>``) the
  465. launch home has no ``plugins/`` — user plugins live in the hermes root — so the default
  466. root is scanned too; profile-local plugins stay authoritative over same-named root ones.
  467. The project source is gated on shared truthy semantics (``1``/``true``/``yes``/``on``):
  468. a bare non-empty check let ``=0``/``=false`` silently enable it (GHSA-5qr3-c538-wm9j).
  469. """
  470. from hermes_cli.plugins import get_bundled_plugins_dir
  471. from hermes_constants import get_default_hermes_root
  472. bundled_root = get_bundled_plugins_dir()
  473. # User dashboard plugins are a dashboard-owned asset (same category as theme YAML): resolve them from
  474. # the process launch home so they don't vanish when a request is scoped to another profile via a
  475. # context-local HERMES_HOME override (e.g. embedded /chat under --open-profile). #87197: when the
  476. # process itself is profile-scoped (``--profile <name>`` sets ``HERMES_HOME=<root>/profiles/<name>``),
  477. # the launch home is the profile directory, which has no ``plugins/`` — user plugins are installed in
  478. # the hermes root (``~/.hermes/plugins``). Scan the default root as well (``get_default_hermes_root()``
  479. # unwraps ``<root>/profiles/<name>`` → ``<root>`` and returns a custom ``HERMES_HOME`` unchanged when it
  480. # *is* the root), mirroring how ``hermes_cli.plugins`` resolves plugin install locations. The
  481. # ``seen_names`` dedupe below keeps profile-local plugins (if any) authoritative over same-named root
  482. # plugins.
  483. user_plugin_roots = [get_process_hermes_home() / "plugins"]
  484. root_plugins = get_default_hermes_root() / "plugins"
  485. if root_plugins.resolve(strict=False) != user_plugin_roots[0].resolve(strict=False):
  486. user_plugin_roots.append(root_plugins)
  487. search_dirs = [(d, "user") for d in user_plugin_roots]
  488. search_dirs += [(bundled_root / "memory", "bundled"), (bundled_root, "bundled")]
  489. # GHSA-5qr3-c538-wm9j (#29156): the previous ``os.environ.get(...)`` check treated *any* non-empty
  490. # string as truthy, so ``=0``, ``=false``, and ``=no`` — all of which the agent loader and operators
  491. # correctly read as "disabled" — silently *enabled* the untrusted project source in the web server.
  492. # Combined with the absolute-path RCE primitive on the manifest's ``api`` field (now patched below),
  493. # this turned the opt-in into a sticky always-on switch. Use the shared truthy semantics (``1`` /
  494. # ``true`` / ``yes`` / ``on``) so the gate matches ``hermes_cli/plugins.py`` and the documented user
  495. # contract.
  496. if env_var_enabled("HERMES_ENABLE_PROJECT_PLUGINS"):
  497. search_dirs.append((Path.cwd() / ".hermes" / "plugins", "project"))
  498. return search_dirs
  499. def _dashboard_plugin_entry(data: dict[str, Any], name: str, dashboard_dir: Path, source: str) -> dict[str, Any]:
  500. # Tab options: ``path`` + ``position`` for a new tab, optional ``override`` to replace a
  501. # built-in route, and ``hidden`` to register component/slots without adding a tab.
  502. raw_tab = data.get("tab", {}) if isinstance(data.get("tab"), dict) else {}
  503. tab_info = {"path": raw_tab.get("path", f"/{name}"), "position": raw_tab.get("position", "end")}
  504. override_path = raw_tab.get("override")
  505. if isinstance(override_path, str) and override_path.startswith("/"):
  506. tab_info["override"] = override_path
  507. if bool(raw_tab.get("hidden")):
  508. tab_info["hidden"] = True
  509. # Slots the plugin populates via ``window.registerSlot(pluginName, slotName, Component)``.
  510. slots_src = data.get("slots")
  511. slots = [s for s in slots_src if isinstance(s, str) and s] if isinstance(slots_src, list) else []
  512. # Validate ``api`` at discovery time so the cached value is already safe for the importer.
  513. raw_api = data.get("api")
  514. safe_api = _safe_plugin_api_relpath(raw_api, dashboard_dir=dashboard_dir)
  515. if raw_api and safe_api is None:
  516. _log.warning(
  517. "Plugin %s: refusing unsafe api path %r (must be a "
  518. "relative file inside the plugin's dashboard/ "
  519. "directory); backend routes from this plugin will "
  520. "not be mounted",
  521. name, raw_api,
  522. )
  523. return {
  524. "name": name,
  525. "label": data.get("label", name),
  526. "description": data.get("description", ""),
  527. "icon": data.get("icon", "Puzzle"),
  528. "version": data.get("version", "0.0.0"),
  529. "tab": tab_info,
  530. "slots": slots,
  531. "entry": data.get("entry", "dist/index.js"),
  532. "css": data.get("css"),
  533. "has_api": bool(safe_api),
  534. "source": source,
  535. "_dir": str(dashboard_dir),
  536. "_api_file": safe_api,
  537. }
  538. def _discover_dashboard_plugins(search_dirs: Optional[list] = None) -> list:
  539. """Scan ``<plugins root>/*/dashboard/manifest.json`` across user, bundled and (opt-in)
  540. project plugin sources — same three sources as ``hermes_cli.plugins`` — or ``search_dirs``."""
  541. plugins = []
  542. seen_names: set = set()
  543. for plugins_root, source in (_dashboard_plugin_search_dirs() if search_dirs is None else search_dirs):
  544. try:
  545. if not plugins_root.is_dir():
  546. continue
  547. with os.scandir(plugins_root) as scan:
  548. children = sorted((Path(e.path) for e in scan), key=lambda p: p.name)
  549. except OSError as exc:
  550. _log.warning("Skipping unreadable dashboard plugin root %s: %s", plugins_root, exc)
  551. continue
  552. for child in children:
  553. manifest_file = child / "dashboard" / "manifest.json"
  554. try:
  555. if not child.is_dir() or not manifest_file.exists():
  556. continue
  557. data = json.loads(manifest_file.read_text(encoding="utf-8-sig"))
  558. name = data.get("name", child.name)
  559. if name in seen_names:
  560. continue
  561. seen_names.add(name)
  562. plugins.append(_dashboard_plugin_entry(data, name, child / "dashboard", source))
  563. except OSError as exc:
  564. _log.warning("Skipping unreadable dashboard plugin %s: %s", manifest_file, exc)
  565. continue
  566. except Exception as exc:
  567. _log.warning("Bad dashboard plugin manifest %s: %s", manifest_file, exc)
  568. continue
  569. return plugins
  570. def _strip_dashboard_manifest(p: dict[str, Any]) -> dict[str, Any]:
  571. return {k: v for k, v in p.items() if not k.startswith("_")}
  572. _PLUGINS_HUB_CACHE_TTL_SECONDS = 5.0
  573. _plugins_hub_cache: dict[str, dict[str, Any]] = {}
  574. _plugins_hub_cache_expires_at: dict[str, float] = {}
  575. _plugins_hub_cache_lock = threading.Lock()
  576. def _invalidate_plugins_hub_cache() -> None:
  577. with _plugins_hub_cache_lock:
  578. _plugins_hub_cache.clear()
  579. _plugins_hub_cache_expires_at.clear()
  580. _plugins_hub_probe_inflight: set = set()
  581. _plugins_hub_probe_lock = threading.Lock()
  582. def _schedule_check_fn_probe(fn) -> Optional[threading.Thread]:
  583. """Warm a cold ``check_fn`` verdict off the request path.
  584. The hub read path only consumes cached availability; the only other warmer is the
  585. tool-schema build, which a dashboard-only session never runs — so a cold cache would
  586. report ``auth_required=False`` forever. Daemon-thread probe, deduplicated per function;
  587. the short hub TTL surfaces the verdict on the next fetch. Returns ``None`` when a probe
  588. for *fn* is already in flight.
  589. """
  590. with _plugins_hub_probe_lock:
  591. if fn in _plugins_hub_probe_inflight:
  592. return None
  593. _plugins_hub_probe_inflight.add(fn)
  594. def _probe():
  595. try:
  596. from tools.registry import _check_fn_cached
  597. _check_fn_cached(fn)
  598. except Exception:
  599. pass
  600. finally:
  601. with _plugins_hub_probe_lock:
  602. _plugins_hub_probe_inflight.discard(fn)
  603. thread = threading.Thread(target=_probe, name="plugins-hub-checkfn-probe", daemon=True)
  604. thread.start()
  605. return thread
  606. def _plugin_login_command(name: str) -> str:
  607. """A plugin that left core with its own login command (``hermes spotify login``), else ``hermes auth <name>``."""
  608. from hermes_cli.left_core_migration import LEFT_CORE
  609. return next((f"hermes {f.cli} login" for f in LEFT_CORE if f.plugin == name and f.cli), f"hermes auth {name}")
  610. def _plugin_auth_hint(name: str, provides_tools: list) -> tuple:
  611. """``(auth_required, auth_command)`` from last-known cached tool availability only.
  612. A missing cache entry is "unknown": schedule a background probe rather than probing
  613. inline (which would starve the root event loop), so the short hub TTL picks it up.
  614. """
  615. try:
  616. from tools.registry import get_cached_check_fn_result, registry
  617. for tname in provides_tools:
  618. entry = registry.get_entry(tname)
  619. if not entry or not entry.check_fn:
  620. continue
  621. cached_result = get_cached_check_fn_result(entry.check_fn)
  622. if cached_result is None:
  623. _schedule_check_fn_probe(entry.check_fn)
  624. elif cached_result is False:
  625. return True, _plugin_login_command(name)
  626. except Exception:
  627. pass
  628. return False, ""
  629. def _plugin_runtime_status(aliases: set, enabled_set: set, disabled_set: set) -> str:
  630. """enabled / disabled / inactive for a plugin's name+key alias set (disabled wins)."""
  631. return "disabled" if aliases & disabled_set else "enabled" if aliases & enabled_set else "inactive"
  632. def _merged_plugins_hub(force_refresh: bool = False) -> dict[str, Any]:
  633. """Agent discovery + dashboard manifests + provider picker metadata.
  634. IMPORTANT: powers a dashboard request path, so it must stay read-only and cheap — never
  635. execute tool ``check_fn`` probes here (imports, auth/network checks would starve the root
  636. event loop). Only cached availability is consumed and the payload is memoized briefly to
  637. collapse the dashboard's bursty duplicate fetches.
  638. """
  639. from hermes_cli.web_server_memory import _discover_memory_provider_statuses, _normalize_memory_provider_name
  640. from hermes_cli.web_server import _get_dashboard_plugins
  641. from hermes_cli.config import get_hermes_home, load_config
  642. from hermes_constants import hermes_home_key
  643. cache_key = hermes_home_key(get_hermes_home())
  644. now = time.monotonic()
  645. if not force_refresh:
  646. with _plugins_hub_cache_lock:
  647. cached = _plugins_hub_cache.get(cache_key)
  648. if cached is not None and now < _plugins_hub_cache_expires_at.get(cache_key, 0.0):
  649. return cached
  650. started_at = time.monotonic()
  651. from hermes_cli.plugins_cmd import (
  652. _category_active_names,
  653. _discover_all_plugins,
  654. _get_current_context_engine,
  655. _get_current_memory_provider,
  656. _discover_context_engines,
  657. _get_disabled_set,
  658. _get_enabled_set,
  659. _plugin_status,
  660. _read_manifest as _read_plugin_manifest_at,
  661. )
  662. from hermes_cli.plugins_cmd_catalog import removed_annotation
  663. from hermes_cli.plugin_catalog import resolved_removed_entries
  664. dashboard_list = _get_dashboard_plugins()
  665. dash_by_name = {str(p["name"]): p for p in dashboard_list}
  666. disabled_set = _get_disabled_set()
  667. enabled_set = _get_enabled_set()
  668. hidden_plugins: list = cfg_get(load_config(), "dashboard", "hidden_plugins", default=[]) or []
  669. plugins_root_resolved = (get_hermes_home() / "plugins").resolve()
  670. rows: list[dict[str, Any]] = []
  671. # One kill-list resolution for the whole rebuild: resolving per row costs a live-catalog
  672. # fetch per installed plugin when the catalog host is slow or unreachable.
  673. removed_entries = resolved_removed_entries()
  674. active = _category_active_names()
  675. for name, version, description, source, dir_str, key in _discover_all_plugins():
  676. # Same verdict as `hermes plugins list` / the TUI hub: name+key aliases for the lists, bundled
  677. # backends/platforms/providers and the live memory provider count as enabled without a list
  678. # entry (#73131, #82898).
  679. runtime_status = _plugin_status(
  680. name, enabled_set, disabled_set, key=key, source=source, dir_path=dir_str, active=active)
  681. if runtime_status == "not enabled":
  682. runtime_status = "inactive"
  683. dir_path = Path(dir_str)
  684. dm = dash_by_name.get(name)
  685. try:
  686. dir_path.resolve().relative_to(plugins_root_resolved)
  687. under_user_tree = True
  688. except ValueError:
  689. under_user_tree = False
  690. can_remove_update = source in {"user", "git"} and under_user_tree and dir_path.is_dir()
  691. provides_tools = _read_plugin_manifest_at(dir_path).get("provides_tools") or []
  692. auth_required, auth_command = _plugin_auth_hint(name, provides_tools) if provides_tools else (False, "")
  693. rows.append({
  694. "name": name,
  695. "version": version or "",
  696. "description": description or "",
  697. "source": source,
  698. "runtime_status": runtime_status,
  699. "has_dashboard_manifest": dm is not None or (dir_path / "dashboard" / "manifest.json").exists(),
  700. "dashboard_manifest": _strip_dashboard_manifest(dm) if dm else None,
  701. "path": dir_str,
  702. "can_remove": can_remove_update,
  703. "can_update_git": can_remove_update and (dir_path / ".git").exists(),
  704. "auth_required": auth_required,
  705. "auth_command": auth_command,
  706. "user_hidden": name in hidden_plugins,
  707. "removed_reason": removed_annotation(name, dir_str, removed_entries),
  708. })
  709. agent_names = {r["name"] for r in rows}
  710. orphan_dashboard = [_strip_dashboard_manifest(p) for p in dashboard_list if str(p["name"]) not in agent_names]
  711. memory_providers = _discover_memory_provider_statuses()
  712. try:
  713. context_engines = [{"name": n, "description": desc} for n, desc in _discover_context_engines()]
  714. except Exception:
  715. context_engines = []
  716. payload = {
  717. "plugins": rows,
  718. "orphan_dashboard_plugins": orphan_dashboard,
  719. "providers": {
  720. "memory_provider": _normalize_memory_provider_name(_get_current_memory_provider()),
  721. "memory_options": memory_providers,
  722. "context_engine": _get_current_context_engine(),
  723. "context_options": context_engines,
  724. },
  725. }
  726. duration = time.monotonic() - started_at
  727. if duration >= 0.25:
  728. _log.info(
  729. "plugins/hub rebuilt in %.3fs (plugins=%d memory_options=%d)", duration, len(rows), len(memory_providers)
  730. )
  731. with _plugins_hub_cache_lock:
  732. _plugins_hub_cache[cache_key] = payload
  733. _plugins_hub_cache_expires_at[cache_key] = time.monotonic() + _PLUGINS_HUB_CACHE_TTL_SECONDS
  734. return payload
  735. def _plugin_api_mount_skip_reason(plugin: dict[str, Any], enabled_set: set, disabled_set: set) -> Optional[str]:
  736. """Why a plugin's backend ``api`` must NOT be imported, or None when it may be.
  737. User plugins must be in ``plugins.enabled`` and not ``plugins.disabled`` before their
  738. Python runs (GHSA-mcfc-hp25-cjv7); bundled plugins are trusted but respect an explicit
  739. disable; project plugins (``./.hermes/plugins/``) ship with the CWD and are
  740. attacker-controlled when opening a malicious repo — never auto-imported (GHSA-5qr3-c538-wm9j).
  741. """
  742. source, plugin_name = plugin.get("source"), plugin.get("name", "")
  743. if source in ("user", "bundled") and plugin_name in disabled_set:
  744. return "explicitly disabled"
  745. if source == "user" and plugin_name not in enabled_set:
  746. return "not in plugins.enabled"
  747. return None
  748. @contextmanager
  749. def _launch_profile_scope():
  750. """Resolve config as the launch profile's, whichever profile the request is scoped to: home and
  751. secrets switch together, so the launch config's ``${VAR}`` refs (and its last-good copy) never
  752. expand through another profile's secrets."""
  753. from hermes_constants import reset_hermes_home_override, set_hermes_home_override
  754. from hermes_cli.web_server_profiles import _config_profile_scope
  755. token = set_hermes_home_override(None)
  756. try:
  757. with _config_profile_scope(None):
  758. yield
  759. finally:
  760. reset_hermes_home_override(token)
  761. def _plugin_enable_sets_here() -> tuple[set, set]:
  762. """``(plugins.enabled, plugins.disabled)`` of the active profile scope from one cached read-only
  763. config read: the gates run on the event loop for every plugin request and upgrade."""
  764. from hermes_cli.config import load_config_readonly
  765. try:
  766. config = load_config_readonly()
  767. except Exception: # health: allow BLE001 -- an unreadable config grants no consent (empty sets), as plugins_cmd reads it
  768. config = {}
  769. enabled, disabled = (cfg_get(config, "plugins", key, default=[]) for key in ("enabled", "disabled"))
  770. return (set(enabled) if isinstance(enabled, list) else set(),
  771. set(disabled) if isinstance(disabled, list) else set())
  772. def _plugin_consent_withheld(plugin: dict[str, Any]) -> bool:
  773. """Whether a request must not reach ``plugin``'s backend or assets (#46435, GHSA-mcfc-hp25-cjv7).
  774. ``plugin`` is the active scope's own copy (a secondary profile's plugins are discovered under
  775. its home and run in its plugin host, :mod:`hermes_cli.web_server_plugin_profiles`), so the
  776. profile the request acts for decides alone: a native ticket's profile, a ``?profile=``
  777. selection, else the launch profile (#134889, PLG-3).
  778. """
  779. return _plugin_api_mount_skip_reason(plugin, *_plugin_enable_sets_here()) is not None
  780. def _plugin_api_name(scope) -> str:
  781. """``<name>`` of an ``/api/plugins/<name>/...`` request (the path the router matches), else ``""``."""
  782. path = get_route_path(scope)
  783. parts = path.split("/") # ['', 'api', 'plugins', '<name>', ...]
  784. return parts[3] if path.startswith("/api/plugins/") and len(parts) >= 4 else ""
  785. async def _plugin_api_request_refused(name: str) -> bool:
  786. """The runtime gate for one ``/api/plugins/<name>/`` request, HTTP and WebSocket alike.
  787. :func:`_mount_plugin_api_routes` gates at import time; a plugin disabled while the server runs
  788. keeps its router mounted until restart, so every request is checked again. An unknown name
  789. counts as a user plugin (safe default: refused).
  790. """
  791. from hermes_cli.web_server import _get_dashboard_plugins
  792. from hermes_cli.web_server_plugin_profiles import rescanned_plugin, secondary_profile_home
  793. plugin = next((p for p in _get_dashboard_plugins() if p.get("name") == name), None)
  794. home = secondary_profile_home()
  795. if plugin is None and home is not None: # installed since the last scan (rate-limited per name)
  796. plugin = await asyncio.to_thread(rescanned_plugin, home, name) # a disk scan: off the event loop
  797. return _plugin_consent_withheld(plugin or {"name": name, "source": "user"})
  798. class PluginApiWebSocketGate:
  799. """:func:`_plugin_api_request_refused` for WebSocket upgrades. ``_plugin_api_runtime_gate`` is
  800. HTTP middleware and never sees one, so a plugin disabled at runtime kept accepting connections
  801. on its websocket routes until restart (#134889).
  802. It refuses before the route's own credential check, which is the disabled plugin's code, so it
  803. cannot wait for auth (a gated-mode ticket is single-use: only the route may redeem it). That is
  804. no plugin-name oracle: a close before accept reaches the client as the same 403 handshake
  805. answer whether the plugin is disabled, unknown, or the credential was refused.
  806. A Desktop's native grant is the exception: it names the profile the socket acts for, so it is
  807. redeemed here, once (:func:`_native_ws_scope`), and consent is checked in that profile. A
  808. secondary profile's socket to a plugin its own host serves is answered here too (PLG-3).
  809. First it runs the core sockets' Host/Origin/peer gate (``_ws_request_is_allowed``, 4403), which
  810. HTTP middleware never applies to an upgrade. Here it covers every plugin socket, whatever form
  811. declares it: a router dependency reaches ``@router.websocket`` routes only.
  812. """
  813. def __init__(self, app) -> None:
  814. self.app = app
  815. async def __call__(self, scope, receive, send) -> None:
  816. from hermes_cli.web_server_chat import _ws_request_is_allowed
  817. from hermes_cli.web_server_plugin_profiles import plugin_request_scope, refuse_secondary_plugin_socket
  818. name = _plugin_api_name(scope) if scope["type"] == "websocket" else ""
  819. if not name:
  820. await self.app(scope, receive, send)
  821. return
  822. if not _ws_request_is_allowed(WebSocket(scope, receive, send)):
  823. await send({"type": "websocket.close", "code": 4403})
  824. return
  825. with _native_ws_scope(scope) as admitted, plugin_request_scope(scope):
  826. if admitted and not await _plugin_api_request_refused(name):
  827. if not await refuse_secondary_plugin_socket(scope, receive, send, name):
  828. await self.app(scope, receive, send)
  829. return
  830. await send({"type": "websocket.close", "code": status.WS_1008_POLICY_VIOLATION})
  831. @contextmanager
  832. def _native_ws_scope(scope):
  833. """Yield whether a plugin socket's native grant (``X-Hermes-Gateway-Ticket``) was admitted,
  834. with that grant's home and secret scope bound for the rest of the connection; without the
  835. header, True and the ambient scope. The grant is redeemed here only: the route's credential
  836. check reads the principal stamped on the connection, and its scope dependency resolves the
  837. same profile, so consent, home and ``get_secret`` all follow the grant, as on HTTP
  838. (``native_profile_scope``).
  839. """
  840. from hermes_cli.dashboard_auth.native_http import HEADER, native_profile_scope, redeem_native_ws
  841. from hermes_cli.web_server_profiles import _config_profile_scope
  842. conn = HTTPConnection(scope)
  843. if HEADER not in conn.headers:
  844. yield True
  845. return
  846. grant = redeem_native_ws(conn)
  847. if grant is None:
  848. yield False
  849. return
  850. conn.state.native_http_principal = grant
  851. with native_profile_scope(conn), _config_profile_scope(None):
  852. yield True
  853. # Serializes plugin API mounts: concurrent first requests for a freshly enabled plugin must import
  854. # and mount it exactly once.
  855. _plugin_api_mount_lock = threading.Lock()
  856. async def _plugin_route_secret_scope(conn: HTTPConnection, profile: Optional[str] = None):
  857. """Home + secret scope for one ``/api/plugins/<name>/`` request: the launch profile's, or the
  858. ``?profile=``-requested one — the same ``_config_profile_scope`` seam the built-in routers use.
  859. Without it plugin handlers ran unscoped, so under multi-profile hosting every ``get_secret``
  860. / ``resolve_runtime_provider`` failed closed with ``UnscopedSecretError`` (#120310; the bundled
  861. kanban plugin's Decompose / Specify / Estimate aux-LLM calls, #123372). ``async`` on purpose:
  862. a sync yield-dependency's setup and teardown run on different threadpool threads, so the
  863. scope token would be reset in a foreign context; sync handlers still see the scope because
  864. ``run_in_threadpool`` copies the request context into the worker."""
  865. from hermes_cli.web_server_plugin_profiles import in_process_router_refused
  866. from hermes_cli.web_server_profiles import _config_profile_scope, _is_current_profile
  867. name = _plugin_api_name(conn.scope)
  868. with _config_profile_scope(profile):
  869. # The plugin must not run on a profile that disabled it (#134889), and this router is the
  870. # launch profile's copy: a secondary profile reaches it only for bundled plugins (PLG-3).
  871. if (not _is_current_profile(profile) and await _plugin_api_request_refused(name)) or in_process_router_refused(name):
  872. if conn.scope["type"] == "websocket":
  873. raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
  874. raise HTTPException(status_code=404, detail="Plugin not found")
  875. yield
  876. def _mount_hosted_plugin_api(app, plugin: dict, api_file_name: str) -> None:
  877. """``plugins.isolation: host``: the plugin's router runs in the requesting profile's plugin host;
  878. this process only forwards each ``/api/plugins/<name>/`` request to it (auth and the profile
  879. scope still apply here first). Responses are buffered: streaming and websockets need in-process."""
  880. name = plugin["name"]
  881. async def forward(request: Request, path: str = "") -> Response:
  882. # Resolve the plugin again in the REQUESTING profile (the route is mounted once, from the
  883. # launch profile): gated by its own plugins.enabled, served by its own host. The copy is
  884. # still the launch profile's (discovery scans only the launch home and the root).
  885. target = await asyncio.to_thread(_hosted_plugin_for_request, name)
  886. if target is None:
  887. return JSONResponse({"detail": f"plugin {name!r} is not enabled in this profile"}, status_code=404)
  888. host, dashboard_dir, api_file = target
  889. from hermes_cli.web_server_plugin_profiles import run_hosted_request
  890. query, headers = request.url.query, [(k, v) for k, v in request.headers.items() if k.lower() != "host"]
  891. body = await request.body()
  892. from hermes_cli.plugin_host_http_auth import admitted_for_sensitive_route
  893. authenticated = admitted_for_sensitive_route(request)
  894. return await run_hosted_request(host.home, name, lambda timeout: host.asgi_request(
  895. name, dashboard_dir, api_file, request.method, "/" + path, query, headers, body,
  896. timeout=timeout, authenticated=authenticated))
  897. app.add_api_route(f"/api/plugins/{name}/{{path:path}}", forward, include_in_schema=False,
  898. methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
  899. dependencies=[Depends(_plugin_route_secret_scope)])
  900. _log.info("Mounted plugin API routes via the plugin host: /api/plugins/%s/", name)
  901. def _hosted_plugin_for_request(name: str) -> Optional[tuple]:
  902. """``(plugin host, dashboard dir, api file)`` for plugin ``name`` in the active profile, or None
  903. when that profile has no enabled user copy of it."""
  904. from hermes_cli.plugins import get_plugin_manager
  905. from hermes_cli.plugins_cmd import _get_disabled_set, _get_enabled_set
  906. for plugin in _discover_dashboard_plugins():
  907. if plugin.get("name") != name or not plugin.get("_api_file") or plugin.get("source") != "user":
  908. continue
  909. if _plugin_api_mount_skip_reason(plugin, _get_enabled_set(), _get_disabled_set()):
  910. return None
  911. return get_plugin_manager()._plugin_host(), str(plugin["_dir"]), str(plugin["_api_file"])
  912. return None
  913. def _mount_plugin_api_routes():
  914. """Import and mount backend API routes from plugins that declare them.
  915. Each plugin's ``api`` file must expose a ``router`` (FastAPI APIRouter), mounted under
  916. ``/api/plugins/<name>/``. See ``_plugin_api_mount_skip_reason`` for the trust gates.
  917. Backend import is restricted to ``bundled`` and ``user`` sources. Project plugins
  918. (``./.hermes/plugins/``) ship with the CWD and are therefore attacker-controlled in any threat model
  919. where the user opens a malicious repo; they can extend the dashboard UI via static JS/CSS but their
  920. Python ``api`` file is never auto-imported by the web server. See GHSA-5qr3-c538-wm9j (#29156).
  921. Additionally, user plugins must be explicitly enabled via the ``plugins.enabled`` allow-list in
  922. config.yaml before their backend code is imported. Without this gate, an installed-but-not-enabled
  923. plugin's Python code would execute at dashboard startup — a code execution vector that bypasses the
  924. user's intent. (#46435, GHSA-mcfc-hp25-cjv7)
  925. """
  926. from hermes_cli.web_server import _get_dashboard_plugins, app
  927. try:
  928. from hermes_cli.plugins_cmd import _get_enabled_set, _get_disabled_set
  929. enabled_set = _get_enabled_set()
  930. disabled_set = _get_disabled_set()
  931. except Exception:
  932. enabled_set = set()
  933. disabled_set = set()
  934. for plugin in _get_dashboard_plugins():
  935. with _plugin_api_mount_lock:
  936. _mount_one_plugin_api(app, plugin, enabled_set, disabled_set)
  937. _register_plugin_api_fallback(app)
  938. def _try_hot_mount_plugin_api(name: str) -> bool:
  939. """Mount plugin ``name``'s backend API on the running app; True when new routes went live.
  940. A plugin installed or enabled after server start had no route until restart: the startup
  941. sweep is the only other caller of ``_mount_one_plugin_api``. Discovery is re-run (the plugin
  942. dir may not have existed at startup) and the decision is the launch profile's, exactly as at
  943. startup (its enable sets and its ``plugins.isolation``), so a plugin the launch profile did not
  944. enable is never imported or forwarded (#134889); a secondary profile's request (its grant or a
  945. ``?profile=`` selection) may mount only its own bundled copy, by its own lists (PLG-3). New
  946. routes are spliced in just ahead of the hot-mount fallback, which sits before the SPA
  947. catch-all: appended at the end they would land behind ``/{full_path:path}`` and every GET
  948. would keep missing them.
  949. """
  950. if not name or any(c in name for c in "/\\{}") or name == "..":
  951. return False
  952. from hermes_cli.plugins_cmd import _get_disabled_set, _get_enabled_set
  953. from hermes_cli.web_server import _get_dashboard_plugins, app
  954. from hermes_cli.web_server_plugin_profiles import plugin_api_path, secondary_plugin, secondary_profile_home
  955. # A secondary profile reaches this router only for its own bundled copy (Hermes code), and its
  956. # own lists decide that one (PLG-3).
  957. secondary, own, requester_sets = secondary_profile_home() is not None, secondary_plugin(name), _plugin_enable_sets_here()
  958. with _launch_profile_scope(), _plugin_api_mount_lock:
  959. enabled_set, disabled_set = _get_enabled_set(), _get_disabled_set()
  960. if _plugin_api_mounted(app, name): # a mounted plugin's unknown subpath: no disk rescan
  961. return False
  962. plugin = next((p for p in _get_dashboard_plugins(force_rescan=True) if p.get("name") == name), None)
  963. if secondary:
  964. if own is None or own.get("source") != "bundled" or plugin_api_path(plugin) != plugin_api_path(own):
  965. return False
  966. enabled_set, disabled_set = requester_sets
  967. routes = app.router.routes
  968. before = len(routes)
  969. if plugin is None or not _mount_one_plugin_api(app, plugin, enabled_set, disabled_set):
  970. return False
  971. fresh, rest = routes[before:], routes[:before]
  972. at = next((i for i, r in enumerate(rest) if getattr(r, "endpoint", None) is _plugin_api_hot_mount), len(rest))
  973. # One slice assignment: a request iterating the list on the loop thread sees routes
  974. # shift right (re-checks one), never skips one.
  975. routes[:] = rest[:at] + fresh + rest[at:]
  976. return True
  977. def _plugin_api_mounted(app, name: str) -> bool:
  978. """Whether ``app`` already serves ``/api/plugins/<name>/`` — read from the route table itself,
  979. so anything that rebuilds the routes (a test restoring its snapshot) cannot leave a stale
  980. "mounted" record that blocks the remount."""
  981. prefix = f"/api/plugins/{name}"
  982. return any(
  983. getattr(r, "endpoint", None) is not _plugin_api_hot_mount
  984. and (getattr(r, "path", "") == prefix or getattr(r, "path", "").startswith(prefix + "/"))
  985. for r in app.router.routes
  986. )
  987. class _PluginApiHotMount:
  988. """ASGI fallback for ``/api/plugins/{name}/{path}`` requests no mounted router matched.
  989. Registered after every startup router, so it only sees plugins that are not mounted yet
  990. (auth and ``_plugin_api_runtime_gate`` already ran). On a successful hot mount the SAME
  991. request is re-routed to the fresh routes in-process — no redirect: Desktop's transport
  992. never follows a 3xx and would fail the first poll. A second miss lands back here, finds the
  993. plugin mounted and gets the plain 404, so re-routing cannot loop. A class instance, not a
  994. function: Starlette wraps plain functions as ``request -> response`` endpoints.
  995. """
  996. async def __call__(self, scope, receive, send) -> None:
  997. from hermes_cli.web_server import app
  998. from hermes_cli.web_server_plugin_profiles import plugin_request_scope
  999. name = str(scope.get("path_params", {}).get("name", ""))
  1000. with plugin_request_scope(scope): # a ``?profile=`` selection decides its own cold mount (PLG-3)
  1001. mounted = await asyncio.to_thread(_try_hot_mount_plugin_api, name)
  1002. if mounted:
  1003. _log.info("Hot-mounted plugin API routes on first request: /api/plugins/%s/", name)
  1004. await app.router(dict(scope, path_params={}), receive, send)
  1005. return
  1006. await JSONResponse({"detail": "Not Found"}, status_code=404)(scope, receive, send)
  1007. _plugin_api_hot_mount = _PluginApiHotMount()
  1008. def _register_plugin_api_fallback(app) -> None:
  1009. """Register the hot-mount fallback once, after the startup plugin routers (so a mounted
  1010. router always matches first) and before the SPA catch-all."""
  1011. if any(getattr(r, "endpoint", None) is _plugin_api_hot_mount for r in app.router.routes):
  1012. return
  1013. app.router.add_route("/api/plugins/{name}/{path:path}", _plugin_api_hot_mount,
  1014. methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
  1015. include_in_schema=False)
  1016. def _mount_one_plugin_api(app, plugin: dict[str, Any], enabled_set: set, disabled_set: set) -> bool:
  1017. """Mount one plugin's backend API routes on ``app`` if its trust gates pass.
  1018. Returns True when routes were added. Callers must hold ``_plugin_api_mount_lock``.
  1019. Shared by the import-time sweep and the hot-mount fallback so both paths
  1020. apply the exact same gates (GHSA-mcfc-hp25-cjv7, GHSA-5qr3-c538-wm9j).
  1021. """
  1022. api_file_name = plugin.get("_api_file")
  1023. if not api_file_name:
  1024. return False
  1025. if _plugin_api_mounted(app, plugin.get("name", "")):
  1026. return False
  1027. skip = _plugin_api_mount_skip_reason(plugin, enabled_set, disabled_set)
  1028. if skip:
  1029. _log.debug("Plugin %s: skipping API mount (%s)", plugin.get("name", ""), skip)
  1030. return False
  1031. if plugin.get("source") not in ("bundled", "project"):
  1032. from hermes_cli.plugin_isolation import ISOLATION_HOST, isolation_mode
  1033. if isolation_mode() == ISOLATION_HOST:
  1034. _mount_hosted_plugin_api(app, plugin, api_file_name)
  1035. return True
  1036. if plugin.get("source") == "project":
  1037. _log.warning(
  1038. "Plugin %s: ignoring backend api=%s (project plugins may "
  1039. "not auto-import Python code; move the plugin to "
  1040. "~/.hermes/plugins/ if you trust it)",
  1041. plugin["name"], api_file_name,
  1042. )
  1043. return False
  1044. dashboard_dir = Path(plugin["_dir"])
  1045. api_path = dashboard_dir / api_file_name
  1046. try:
  1047. api_path.resolve().relative_to(dashboard_dir.resolve())
  1048. except (OSError, RuntimeError, ValueError):
  1049. # Discovery already filters this; defence in depth in case ``_dir`` was tampered
  1050. # with after caching or a future caller bypasses the validator.
  1051. _log.warning(
  1052. "Plugin %s: refusing to import api file outside its "
  1053. "dashboard directory (%s)", plugin["name"], api_path,
  1054. )
  1055. return False
  1056. if not api_path.exists():
  1057. _log.warning("Plugin %s declares api=%s but file not found", plugin["name"], api_file_name)
  1058. return False
  1059. try:
  1060. module_name = f"hermes_dashboard_plugin_{plugin['name']}"
  1061. spec = importlib.util.spec_from_file_location(module_name, api_path)
  1062. if spec is None or spec.loader is None:
  1063. return False
  1064. mod = importlib.util.module_from_spec(spec)
  1065. # Register in sys.modules BEFORE exec_module so pydantic/FastAPI can resolve
  1066. # string annotations (``from __future__ import annotations``) by module name.
  1067. sys.modules[module_name] = mod
  1068. try:
  1069. spec.loader.exec_module(mod)
  1070. except Exception:
  1071. sys.modules.pop(module_name, None)
  1072. raise
  1073. router = getattr(mod, "router", None)
  1074. if router is None:
  1075. _log.warning("Plugin %s api file has no 'router' attribute", plugin["name"])
  1076. return False
  1077. app.include_router(
  1078. router,
  1079. prefix=f"/api/plugins/{plugin['name']}",
  1080. dependencies=[Depends(_plugin_route_secret_scope)],
  1081. )
  1082. _log.info("Mounted plugin API routes: /api/plugins/%s/", plugin["name"])
  1083. return True
  1084. except Exception as exc: # health: allow BLE001 -- executes third-party plugin code; any failure must skip that plugin, not crash the server
  1085. _log.warning("Failed to load plugin %s API routes: %s", plugin["name"], exc, exc_info=True)
  1086. return False