@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/api/dashboard_probe.py

@@ -0,0 +1,255 @@
+"""Safe server-side probe for the official Hermes Agent dashboard.
+
+The official `hermes dashboard` binds to 127.0.0.1:9119 by default and exposes
+GET /api/status as a public, read-only identity/status endpoint.  Keep all
+probing server-side to avoid browser CORS/mixed-content failures, and only allow
+loopback targets so a user-controlled setting cannot become an SSRF primitive.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.request
+from urllib.parse import urlparse, urlunparse
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_DASHBOARD_PORT = 9119
+DEFAULT_DASHBOARD_TIMEOUT = 0.5
+DEFAULT_DASHBOARD_TARGETS = (("127.0.0.1", DEFAULT_DASHBOARD_PORT), ("localhost", DEFAULT_DASHBOARD_PORT))
+_DASHBOARD_ENABLED_VALUES = {"auto", "always", "never"}
+_LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+
+def _base_url(host: str, port: int, scheme: str = "http") -> str:
+    display_host = f"[{host}]" if ":" in host and not host.startswith("[") else host
+    return f"{scheme}://{display_host}:{port}"
+
+
+def normalize_dashboard_url(raw_url: str | None) -> tuple[str, int, str, str] | None:
+    """Return (host, port, scheme, base_url) for a safe loopback dashboard URL.
+
+    Overrides intentionally accept only scheme + loopback host + explicit port.
+    Paths, query strings, fragments, and credentials are rejected: the probe
+    appends the official `/api/status` fingerprint itself and must not become an
+    arbitrary local URL fetcher.
+    """
+    raw = str(raw_url or "").strip()
+    if not raw:
+        return None
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("invalid dashboard URL scheme")
+    if parsed.username or parsed.password:
+        raise ValueError("invalid dashboard URL credentials")
+    host = parsed.hostname or ""
+    normalized_host = host.strip().lower()
+    if normalized_host not in _LOOPBACK_HOSTS:
+        raise ValueError("invalid dashboard URL host")
+    try:
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError("invalid dashboard URL port") from exc
+    if not isinstance(port, int) or not (1 <= port <= 65535):
+        raise ValueError("invalid dashboard URL port")
+    path = parsed.path or ""
+    if path not in ("", "/") or parsed.params or parsed.query or parsed.fragment:
+        raise ValueError("invalid dashboard URL path")
+    base = _base_url(normalized_host, port, parsed.scheme)
+    return normalized_host, port, parsed.scheme, base
+
+
+def normalize_dashboard_browser_url(raw_url: str | None) -> str:
+    """Return a safe browser-only dashboard link URL.
+
+    Unlike the server-side probe target, this value is only returned to the
+    browser for navigation.  It may point at a public reverse-proxy hostname, but
+    it still rejects credentials, paths, query strings, fragments, and non-HTTP
+    schemes so it cannot hide secrets or script URLs in config.
+    """
+    raw = str(raw_url or "").strip()
+    if not raw:
+        return ""
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("invalid dashboard URL scheme")
+    if parsed.username or parsed.password:
+        raise ValueError("invalid dashboard URL credentials")
+    if not parsed.hostname:
+        raise ValueError("invalid dashboard URL host")
+    if parsed.params or parsed.query or parsed.fragment:
+        raise ValueError("invalid dashboard URL path")
+    path = parsed.path or ""
+    if path not in ("", "/"):
+        raise ValueError("invalid dashboard URL path")
+    try:
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError("invalid dashboard URL port") from exc
+    host = parsed.hostname.lower()
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    netloc = host
+    if port is not None:
+        if not (1 <= port <= 65535):
+            raise ValueError("invalid dashboard URL port")
+        netloc = f"{netloc}:{port}"
+    return urlunparse((parsed.scheme, netloc, "", "", "", ""))
+
+
+def _looks_like_official_dashboard(payload: object) -> bool:
+    if not isinstance(payload, dict):
+        return False
+    version = payload.get("version")
+    if not isinstance(version, str) or not version.strip():
+        return False
+    # Verified against current Hermes Agent `hermes_cli.web_server.get_status()`:
+    # /api/status returns version plus these Hermes-specific fields. Requiring at
+    # least one avoids treating any generic {version: ...} local service as the
+    # official dashboard.
+    return any(key in payload for key in ("release_date", "hermes_home", "config_path", "gateway_running"))
+
+
+def probe_official_dashboard(
+    host: str,
+    port: int,
+    timeout: float = DEFAULT_DASHBOARD_TIMEOUT,
+    scheme: str = "http",
+) -> dict:
+    """Best-effort check that `hermes dashboard` is running on host:port."""
+    try:
+        normalized_host = str(host or "").strip().lower()
+        if normalized_host not in _LOOPBACK_HOSTS:
+            raise ValueError("dashboard probe host must be loopback")
+        port = int(port)
+        if not (1 <= port <= 65535):
+            raise ValueError("dashboard probe port out of range")
+        if scheme not in {"http", "https"}:
+            raise ValueError("dashboard probe scheme must be http or https")
+        base = _base_url(normalized_host, port, scheme)
+        request = urllib.request.Request(
+            f"{base}/api/status",
+            headers={"Accept": "application/json", "User-Agent": "hermes-webui-dashboard-probe"},
+        )
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            if getattr(response, "status", None) != 200:
+                return {"running": False}
+            payload = json.loads(response.read().decode("utf-8"))
+        if not _looks_like_official_dashboard(payload):
+            return {"running": False}
+        result = {"running": True, "host": normalized_host, "port": port, "url": base}
+        version = payload.get("version")
+        if isinstance(version, str) and version.strip():
+            result["version"] = version.strip()
+        return result
+    except Exception:
+        logger.debug("official Hermes dashboard probe failed", exc_info=True)
+        return {"running": False}
+
+
+def _dashboard_config(config_data: dict | None = None) -> dict:
+    if config_data is None:
+        try:
+            from api.config import get_config
+
+            config_data = get_config()
+        except Exception:
+            config_data = {}
+    webui_cfg = config_data.get("webui", {}) if isinstance(config_data, dict) else {}
+    dashboard_cfg = webui_cfg.get("dashboard", {}) if isinstance(webui_cfg, dict) else {}
+    return dashboard_cfg if isinstance(dashboard_cfg, dict) else {}
+
+
+def get_dashboard_config(config_data: dict | None = None) -> dict:
+    """Return normalized profile config for the Settings → System controls."""
+    dashboard_cfg = _dashboard_config(config_data)
+    enabled = str(dashboard_cfg.get("enabled", "auto") or "auto").strip().lower()
+    if enabled not in _DASHBOARD_ENABLED_VALUES:
+        enabled = "auto"
+    raw_url = str(dashboard_cfg.get("url") or "").strip()
+    if raw_url:
+        raw_url = normalize_dashboard_browser_url(raw_url)
+    return {"enabled": enabled, "url": raw_url}
+
+
+def save_dashboard_config(payload: dict) -> dict:
+    """Persist dashboard link settings under webui.dashboard in config.yaml."""
+    enabled = str((payload or {}).get("enabled", "auto") or "auto").strip().lower()
+    if enabled not in _DASHBOARD_ENABLED_VALUES:
+        raise ValueError("invalid dashboard enabled mode")
+    raw_url = str((payload or {}).get("url", "") or "").strip()
+    normalized_url = normalize_dashboard_browser_url(raw_url) if raw_url else ""
+
+    from api import config as webui_config
+
+    config_path = webui_config._get_config_path()
+    config_data = webui_config._load_yaml_config_file(config_path)
+    webui_section = config_data.get("webui")
+    if not isinstance(webui_section, dict):
+        webui_section = {}
+        config_data["webui"] = webui_section
+    dashboard_section = webui_section.get("dashboard")
+    if not isinstance(dashboard_section, dict):
+        dashboard_section = {}
+        webui_section["dashboard"] = dashboard_section
+    dashboard_section["enabled"] = enabled
+    if normalized_url:
+        dashboard_section["url"] = normalized_url
+    else:
+        dashboard_section.pop("url", None)
+    webui_config._save_yaml_config_file(config_path, config_data)
+    webui_config.reload_config()
+    return {"enabled": enabled, "url": normalized_url}
+
+
+def _webui_bind_host_allows_auto_probe() -> bool:
+    raw_host = str(os.environ.get("HERMES_WEBUI_HOST") or "127.0.0.1").strip().lower()
+    host = raw_host.replace("[", "").replace("]", "")
+    return host in _LOOPBACK_HOSTS
+
+
+def get_dashboard_status(config_data: dict | None = None) -> dict:
+    """Return the safe status payload consumed by GET /api/dashboard/status."""
+    dashboard_cfg = _dashboard_config(config_data)
+    enabled = str(dashboard_cfg.get("enabled", "auto") or "auto").strip().lower()
+    if enabled not in _DASHBOARD_ENABLED_VALUES:
+        enabled = "auto"
+    if enabled == "never":
+        return {"running": False, "enabled": "never"}
+
+    raw_url = dashboard_cfg.get("url") or dashboard_cfg.get("target") or ""
+    try:
+        browser_url = normalize_dashboard_browser_url(raw_url) if raw_url else ""
+    except ValueError:
+        return {"running": False, "enabled": enabled, "error": "invalid dashboard url"}
+    try:
+        override = normalize_dashboard_url(raw_url)
+    except ValueError:
+        override = None
+
+    targets: list[tuple[str, int, str, str]]
+    if override:
+        targets = [override]
+    else:
+        targets = [(host, port, "http", _base_url(host, port)) for host, port in DEFAULT_DASHBOARD_TARGETS]
+
+    if enabled == "always":
+        if browser_url and not override:
+            return {"running": True, "enabled": enabled, "url": browser_url, "browser_url": browser_url}
+        host, port, scheme, base = targets[0]
+        return {"running": True, "enabled": enabled, "host": host, "port": port, "url": browser_url or base, "browser_url": browser_url or base}
+
+    if not _webui_bind_host_allows_auto_probe():
+        return {"running": False, "enabled": enabled}
+
+    for host, port, scheme, _base in targets:
+        result = probe_official_dashboard(host, port, timeout=DEFAULT_DASHBOARD_TIMEOUT, scheme=scheme)
+        if result.get("running"):
+            result["enabled"] = enabled
+            if browser_url:
+                result["browser_url"] = browser_url
+                result["url"] = browser_url
+            return result
+    return {"running": False, "enabled": enabled}

package/vendor/agent-frontend-shell/api/extensions.py

@@ -0,0 +1,253 @@
+"""Opt-in WebUI extension hooks.
+
+This module intentionally provides a small, self-hosted extension surface:
+configured same-origin script/style injection plus sandboxed static file serving.
+It is disabled by default and never executes or fetches third-party URLs.
+"""
+
+import html
+import logging
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+from urllib.parse import unquote, urlsplit
+
+from api.config import REPO_ROOT
+from api.helpers import _security_headers, j
+
+_log = logging.getLogger(__name__)
+
+# Sane bound on configured URLs — real extensions ship 1-3 files. Higher values
+# typically indicate a misconfiguration (one giant unsplit string, or a runaway
+# generator script that wrote an env-var template without filtering). Capping
+# avoids rendering tens of thousands of <script> tags into every page load.
+_MAX_URL_LIST = 32
+
+# Tracks rejected URL strings we've already warned about so a misconfigured env
+# var doesn't spam the log on every request that re-reads it.
+_warned_urls: set = set()
+
+EXTENSION_ROUTE_PREFIX = "/extensions/"
+_EXTENSION_DIR_ENV = "HERMES_WEBUI_EXTENSION_DIR"
+_EXTENSION_SCRIPT_URLS_ENV = "HERMES_WEBUI_EXTENSION_SCRIPT_URLS"
+_EXTENSION_STYLESHEET_URLS_ENV = "HERMES_WEBUI_EXTENSION_STYLESHEET_URLS"
+_ALLOWED_ASSET_PREFIXES = ("/extensions/", "/static/")
+
+_EXTENSION_MIME = {
+    "css": "text/css",
+    "js": "application/javascript",
+    "html": "text/html",
+    "svg": "image/svg+xml",
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "ico": "image/x-icon",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "woff": "font/woff",
+    "woff2": "font/woff2",
+    "ttf": "font/ttf",
+    "otf": "font/otf",
+    "wasm": "application/wasm",
+}
+_TEXT_MIME_TYPES = {"text/css", "application/javascript", "text/html", "image/svg+xml", "text/plain"}
+
+
+def _extension_root() -> Optional[Path]:
+    """Return the configured extension directory, or None when disabled.
+
+    A missing or non-directory path disables extensions instead of failing open.
+    The startup docs encourage users to point this at a directory they control.
+
+    Relative paths are resolved against REPO_ROOT so they work regardless of
+    the process working directory (ctl.sh start, bootstrap.py, etc.).
+    """
+    raw = os.getenv(_EXTENSION_DIR_ENV, "").strip()
+    if not raw:
+        return None
+    path = Path(raw).expanduser()
+    if not path.is_absolute():
+        path = REPO_ROOT / path
+    root = path.resolve()
+    if not root.exists() or not root.is_dir():
+        return None
+    return root
+
+
+def _fully_unquote_path(path: str) -> str:
+    """Decode percent-encoding until stable so encoded dot-segments cannot hide.
+
+    Iterates up to 10 times so even quadruple-encoded inputs like
+    ``%2525252e%2525252e`` collapse to literal ``..`` and are rejected by
+    the segment-level safety check downstream. URL strings stabilize in
+    fewer than 5 iterations in practice; the cap is defensive.
+    """
+    previous = path
+    for _ in range(10):
+        current = unquote(previous)
+        if current == previous:
+            return current
+        previous = current
+    return previous
+
+
+def _is_safe_asset_url(value: str) -> bool:
+    """Allow only same-origin extension/static asset URLs.
+
+    External schemes, protocol-relative URLs, fragments, arbitrary API paths, and
+    encoded traversal are rejected so enabling extensions does not require
+    loosening the CSP.
+    """
+    if not value or any(ch in value for ch in ('\x00', '\r', '\n', '"', "'", "<", ">", "\\")):
+        return False
+    parsed = urlsplit(value)
+    if parsed.scheme or parsed.netloc or parsed.fragment:
+        return False
+
+    decoded_path = _fully_unquote_path(parsed.path)
+    if not any(decoded_path.startswith(prefix) for prefix in _ALLOWED_ASSET_PREFIXES):
+        return False
+
+    for prefix in _ALLOWED_ASSET_PREFIXES:
+        if decoded_path.startswith(prefix):
+            return _is_safe_relative_path(decoded_path[len(prefix) :])
+    return False
+
+
+def _read_url_list(env_name: str) -> List[str]:
+    raw = os.getenv(env_name, "")
+    urls = []
+    for item in raw.split(","):
+        value = item.strip()
+        if not value:
+            continue
+        if _is_safe_asset_url(value):
+            urls.append(value)
+            if len(urls) >= _MAX_URL_LIST:
+                # Stop accumulating after the cap. Anything past this point
+                # would be silently dropped anyway; logging once makes the
+                # truncation visible to a confused operator.
+                if env_name not in _warned_urls:
+                    _warned_urls.add(env_name)
+                    _log.warning(
+                        "Extension URL list %s truncated at %d entries",
+                        env_name, _MAX_URL_LIST,
+                    )
+                break
+        elif value not in _warned_urls:
+            # First-time-seen invalid URL: log once per process so a typo
+            # in HERMES_WEBUI_EXTENSION_*_URLS doesn't disappear silently.
+            _warned_urls.add(value)
+            _log.warning(
+                "Rejected extension URL %r from %s (not a same-origin "
+                "/extensions/ or /static/ path, or contains unsafe chars)",
+                value, env_name,
+            )
+    return urls
+
+
+def get_extension_config() -> Dict[str, object]:
+    """Return public extension config without exposing filesystem paths."""
+    enabled = _extension_root() is not None
+    if not enabled:
+        return {"enabled": False, "script_urls": [], "stylesheet_urls": []}
+    return {
+        "enabled": True,
+        "script_urls": _read_url_list(_EXTENSION_SCRIPT_URLS_ENV),
+        "stylesheet_urls": _read_url_list(_EXTENSION_STYLESHEET_URLS_ENV),
+    }
+
+
+def inject_extension_tags(index_html: str) -> str:
+    """Inject configured extension tags into the app shell.
+
+    Tags are inserted only when the extension directory is enabled. URLs are
+    escaped even though they are already validated, keeping the renderer robust
+    if validation rules evolve later.
+    """
+    config = get_extension_config()
+    if not config["enabled"]:
+        return index_html
+
+    result = index_html
+    stylesheet_tags = [
+        '<link rel="stylesheet" href="{}">'.format(html.escape(url, quote=True))
+        for url in config["stylesheet_urls"]
+    ]
+    script_tags = [
+        '<script src="{}" defer></script>'.format(html.escape(url, quote=True))
+        for url in config["script_urls"]
+    ]
+
+    if stylesheet_tags:
+        head_marker = "</head>"
+        block = "\n".join(stylesheet_tags) + "\n"
+        if head_marker in result:
+            result = result.replace(head_marker, block + head_marker, 1)
+        else:
+            result = block + result
+
+    if script_tags:
+        body_marker = "</body>"
+        block = "\n".join(script_tags) + "\n"
+        if body_marker in result:
+            result = result.replace(body_marker, block + body_marker, 1)
+        else:
+            result = result + "\n" + block
+
+    return result
+
+
+def _is_safe_relative_path(rel: str) -> bool:
+    if not rel or "\x00" in rel or "\\" in rel:
+        return False
+    for segment in rel.split("/"):
+        if not segment or segment in (".", "..") or segment.startswith("."):
+            return False
+    return True
+
+
+def _not_found(handler) -> bool:
+    j(handler, {"error": "not found"}, status=404)
+    return True
+
+
+def serve_extension_static(handler, parsed) -> bool:
+    """Serve a file from the configured extension directory.
+
+    The function always returns True for /extensions/* requests: either a file
+    response or a 404. It never reveals why a request failed, which avoids
+    leaking local paths or extension configuration details.
+    """
+    root = _extension_root()
+    if root is None:
+        return _not_found(handler)
+
+    rel = unquote(parsed.path[len(EXTENSION_ROUTE_PREFIX) :])
+    if not _is_safe_relative_path(rel):
+        return _not_found(handler)
+
+    static_file = (root / rel).resolve()
+    try:
+        static_file.relative_to(root)
+    except ValueError:
+        return _not_found(handler)
+
+    if not static_file.exists() or not static_file.is_file():
+        return _not_found(handler)
+
+    ct = _EXTENSION_MIME.get(static_file.suffix.lower().lstrip("."), "text/plain")
+    ct_header = "{}; charset=utf-8".format(ct) if ct in _TEXT_MIME_TYPES else ct
+    try:
+        raw = static_file.read_bytes()
+    except OSError:
+        return _not_found(handler)
+
+    handler.send_response(200)
+    handler.send_header("Content-Type", ct_header)
+    handler.send_header("Cache-Control", "no-store")
+    handler.send_header("Content-Length", str(len(raw)))
+    _security_headers(handler)
+    handler.end_headers()
+    handler.wfile.write(raw)
+    return True