hivemind-admin-panel 0.1.0__py3-none-any.whl

hivemind_admin_panel/__init__.py

@@ -0,0 +1,91 @@
+# hivemind-admin-panel
+# Copyright (C) 2026 Casimiro Ferreira
+# SPDX-License-Identifier: Apache-2.0
+"""HiveMind Admin - Web-based management UI for HiveMind-core.
+
+This module provides a web-based administration interface for HiveMind-core,
+allowing management of clients, permissions, and server configuration via
+a REST API and web UI.
+
+When launched with the in-process hivemind-core (the default), this module gets
+direct access to internal HiveMind-core objects for real-time monitoring.
+"""
+
+from typing import TYPE_CHECKING
+
+from ovos_utils import create_daemon
+from ovos_utils.log import LOG
+
+if TYPE_CHECKING:
+    from hivemind_core.service import HiveMindService
+    from hivemind_core.database import ClientDatabase
+    from hivemind_core.protocol import HiveMindListenerProtocol
+
+__version__ = "0.2.0"
+__all__ = ["start_admin_server", "init_injected_objects", "get_admin_app"]
+
+
+def init_injected_objects(
+    service: "HiveMindService" = None,
+    db: "ClientDatabase" = None,
+    protocol: "HiveMindListenerProtocol" = None,
+    startup_error: Exception = None
+) -> None:
+    """Initialize admin with direct access to core objects.
+
+    Args:
+        service: HiveMindService instance.
+        db: ClientDatabase instance.
+        protocol: HiveMindListenerProtocol instance.
+        startup_error: Exception if core failed to start.
+    """
+    from hivemind_admin_panel.api import init_injected_objects as _init
+    _init(service=service, db=db, protocol=protocol, logger=LOG, startup_error=startup_error)
+
+
+def start_admin_server(
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    reload: bool = False,
+) -> None:
+    """Start the HiveMind Admin web server.
+
+    This function starts a uvicorn server hosting the FastAPI admin interface.
+    It should be called after hivemind-core service is running.
+
+    Args:
+        host: Host to bind the server (default: 127.0.0.1).
+        port: Port to bind the server (default: 8000).
+        reload: Enable auto-reload for development (default: False).
+
+    Note:
+        This function runs the server in a daemon thread and returns
+        immediately. The server will shut down when the main process exits.
+    """
+    import uvicorn
+    from hivemind_admin_panel.__main__ import app
+
+    def _run_server():
+        LOG.info(f"Starting HiveMind Admin UI at http://{host}:{port}")
+        LOG.info("Change admin credentials in ~/.config/hivemind-core/server.json (admin_user, admin_pass)")
+        uvicorn.run(
+            app,
+            host=host,
+            port=port,
+            reload=reload,
+            log_level="info",
+        )
+
+    # Run server in daemon thread
+    create_daemon(_run_server)
+    LOG.info("HiveMind Admin server thread started")
+
+
+def get_admin_app():
+    """Get the FastAPI app instance for admin UI.
+
+    Returns:
+        FastAPI app configured with all admin routes.
+    """
+    from hivemind_admin_panel.api import get_admin_app
+    return get_admin_app()

hivemind_admin_panel/__main__.py

@@ -0,0 +1,267 @@
+# hivemind-admin-panel
+# Copyright (C) 2026 Casimiro Ferreira
+# SPDX-License-Identifier: Apache-2.0
+"""Main entry point for the HiveMind Admin Panel.
+
+This module provides the FastAPI application that serves both the REST API and
+the static web UI, and is the single launcher for a HiveMind deployment: by
+default it starts an in-process ``hivemind-core`` hivemind-core and keeps a live reference
+to it, so operators run ``hivemind-admin-panel`` only — there is no separate
+``hivemind-core`` process to launch.
+
+Example:
+    ```bash
+    # Launch hivemind-core + admin panel together (default)
+    hivemind-admin-panel --host 0.0.0.0 --port 8100
+
+    # Admin panel only, no in-process hivemind-core (manage on-disk state, or attach to a
+    # hivemind-core managed elsewhere on the host)
+    hivemind-admin-panel --no-core
+    ```
+"""
+
+import argparse
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+
+from hivemind_admin_panel.api import app as api_app
+from hivemind_admin_panel.version import __version__
+
+__all__ = ["app", "main"]
+
+#: Directory containing static files (SPA web UI)
+static_dir = Path(__file__).parent / "static"
+
+#: Main FastAPI application instance
+app = FastAPI(title="HiveMind Admin Panel")
+
+# Mount the API app under /api prefix
+app.mount("/api", api_app)
+
+# Mount static files for direct access (CSS, JS, images)
+if static_dir.exists():
+    app.mount("/static", StaticFiles(directory=static_dir), name="static")
+
+
+@app.get("/")
+async def root() -> FileResponse:
+    """Serve the main index.html file for the SPA.
+
+    Returns:
+        FileResponse: The index.html file from static directory.
+
+    Raises:
+        HTTPException: 404 if index.html is not present (e.g. package installed without static assets).
+    """
+    from fastapi import HTTPException
+    index_path = static_dir / "index.html"
+    if not index_path.exists():
+        raise HTTPException(status_code=404, detail="Admin UI static assets not found. "
+                            "Reinstall with: pip install hivemind-admin-panel")
+    return FileResponse(index_path)
+
+
+@app.get("/index.html")
+async def index() -> FileResponse:
+    """Serve the main index.html file for the SPA.
+
+    Returns:
+        FileResponse: The index.html file from static directory.
+
+    Raises:
+        HTTPException: 404 if index.html is not present (e.g. package installed without static assets).
+    """
+    from fastapi import HTTPException
+    index_path = static_dir / "index.html"
+    if not index_path.exists():
+        raise HTTPException(status_code=404, detail="Admin UI static assets not found. "
+                            "Reinstall with: pip install hivemind-admin-panel")
+    return FileResponse(index_path)
+
+
+def _tracked_protocol(base, service):
+    """Subclass hivemind-core's listener protocol to feed the admin panel live state.
+
+    Captures the live protocol instance (so ``/connections``, ``/stats`` and the
+    topology become authoritative) and taps connection + message handlers to feed
+    the metrics event/message buffers — entirely panel-side, with no core change.
+    """
+    from hivemind_admin_panel.api import init_injected_objects
+    from hivemind_admin_panel._metrics import METRICS
+
+    class _Tracked(base):
+        def __init__(self, *a, **kw):
+            super().__init__(*a, **kw)
+            init_injected_objects(service=service, db=service.db, protocol=self)
+            METRICS.event("core.ready", "hivemind-core listener protocol online")
+
+        def handle_new_client(self, client):
+            METRICS.event("client.connected", f"{getattr(client, 'peer', '?')} connected")
+            return super().handle_new_client(client)
+
+        def handle_client_disconnected(self, client):
+            METRICS.event("client.disconnected", f"{getattr(client, 'peer', '?')} disconnected")
+            return super().handle_client_disconnected(client)
+
+        def handle_message(self, message, client):
+            try:
+                METRICS.message(str(getattr(message, "msg_type", "?")),
+                                str(getattr(client, "peer", "?")))
+            except Exception:
+                pass
+            return super().handle_message(message, client)
+
+        def handle_invalid_key_connected(self, client):
+            METRICS.event("auth.rejected", f"invalid key from {getattr(client, 'peer', '?')}")
+            return super().handle_invalid_key_connected(client)
+
+    return _Tracked
+
+
+def launch_core():
+    """Construct an in-process hivemind-core and inject it into the admin API.
+
+    Builds a ``HiveMindService`` and hands its live ``service``/``db`` objects to
+    the admin API via ``init_injected_objects``. It does **not** run hivemind-core —
+    ``HiveMindService.run()`` blocks on signal handlers and must execute on the
+    main thread (see :func:`main`). If construction fails, the error is injected
+    for diagnostics (surfaced at ``GET /api/startup-error``) and ``None`` is
+    returned so the panel can still come up.
+
+    Returns:
+        The ``HiveMindService`` instance, or ``None`` if construction failed.
+    """
+    from ovos_utils.log import LOG
+    from hivemind_admin_panel.api import init_injected_objects
+
+    try:
+        from hivemind_core.service import HiveMindService
+
+        service = HiveMindService()
+        init_injected_objects(service=service, db=service.db, protocol=None)
+        # Wrap the listener protocol so the panel gets the LIVE protocol instance
+        # (authoritative connections) and a tap on every HiveMessage — no core change.
+        service.hm_protocol = _tracked_protocol(service.hm_protocol, service)
+        LOG.info("hivemind-core constructed; will run in-process")
+        return service
+    except Exception as error:
+        LOG.exception("hivemind-core failed to start; admin panel running in diagnostics mode")
+        init_injected_objects(service=None, db=None, protocol=None, startup_error=error)
+        return None
+
+
+def main() -> None:
+    """Launch the hivemind-core (in-process) and the admin panel.
+
+    By default this starts ``hivemind-core`` inside this process and then serves
+    the admin panel. Pass ``--no-core`` to serve the panel only.
+
+    Note:
+        Default credentials are admin/admin. Change them in
+        ~/.config/hivemind-core/server.json (admin_user, admin_pass).
+    """
+    parser = argparse.ArgumentParser(description="HiveMind Admin Panel (launches hivemind-core + admin UI)")
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Admin panel host (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8100,
+        help="Admin panel port (default: 8100)",
+    )
+    parser.add_argument(
+        "--no-core",
+        action="store_true",
+        help="Do not start an in-process hivemind-core; serve the admin panel only.",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload for development (implies --no-core).",
+    )
+    parser.add_argument(
+        "--log-level",
+        type=str,
+        default="INFO",
+        help="Log level for the in-process hivemind-core (e.g. DEBUG, INFO, ERROR).",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Show version and exit",
+    )
+
+    args = parser.parse_args()
+
+    print(f"HiveMind Admin Panel v{__version__}")
+
+    # --reload runs uvicorn in a child process, which would not carry hivemind-core —
+    # so reload (a dev affordance) forces panel-only mode.
+    run_core = not args.no_core and not args.reload
+
+    from hivemind_admin_panel.api import set_runtime_info
+    set_runtime_info(run_mode="in-process" if run_core else "panel-only",
+                     host=args.host)
+
+    if not run_core:
+        import uvicorn
+        print("hivemind-core: not started (--no-core)")
+        print(f"Admin panel: http://{args.host}:{args.port}")
+        print("Change admin credentials in server.json: admin_user, admin_pass")
+        uvicorn.run(
+            "hivemind_admin_panel.__main__:app",
+            host=args.host,
+            port=args.port,
+            reload=args.reload,
+        )
+        return
+
+    # Run-core mode. hivemind-core's run() installs SIGINT/SIGTERM handlers, which only
+    # work on the main thread — so hivemind-core runs on the main thread and the admin
+    # panel (uvicorn, which skips signal handlers off the main thread) runs in a
+    # daemon thread.
+    from ovos_utils import wait_for_exit_signal
+    from ovos_utils.log import init_service_logger, LOG
+    from hivemind_admin_panel import start_admin_server
+
+    init_service_logger("core")
+    LOG.set_level(args.log_level)
+
+    service = launch_core()
+    start_admin_server(host=args.host, port=args.port)  # panel in a daemon thread
+    print("hivemind-core: running in-process")
+    print(f"Admin panel: http://{args.host}:{args.port}")
+    print("Change admin credentials in server.json: admin_user, admin_pass")
+
+    if service is not None:
+        try:
+            service.run()       # main thread; blocks until SIGINT/SIGTERM
+        except KeyboardInterrupt:
+            pass
+        except Exception as error:
+            # The in-process core failed to start — e.g. its agent backend (an OVOS
+            # messagebus) is unreachable and the agent protocol now fails fast
+            # instead of hanging. Keep the admin UI up in diagnostics mode so the
+            # failure is visible at GET /api/startup-error and on the dashboard,
+            # rather than taking the whole panel down with it.
+            from hivemind_admin_panel.api import init_injected_objects
+            LOG.exception("hivemind-core stopped; admin panel staying up in diagnostics mode")
+            init_injected_objects(service=None, db=getattr(service, "db", None),
+                                  protocol=None, startup_error=error)
+            print(f"hivemind-core failed to start: {error}")
+            print("Admin panel staying up in diagnostics mode — see /api/startup-error")
+            wait_for_exit_signal()
+    else:
+        wait_for_exit_signal()  # diagnostics mode: keep the panel up
+
+
+if __name__ == "__main__":
+    main()

hivemind_admin_panel/_auth.py

@@ -0,0 +1,162 @@
+# hivemind-admin-panel
+# Copyright (C) 2026 Casimiro Ferreira
+# SPDX-License-Identifier: Apache-2.0
+"""Authentication, roles and audit log for the admin panel.
+
+Auth model
+----------
+Credentials live in ``server.json``. The legacy ``admin_user`` / ``admin_pass``
+remain the primary full-admin account; an optional ``users`` list adds extra
+accounts with roles:
+
+    "users": [{"username": "ops", "password": "...", "role": "operator"}]
+
+Roles: ``admin`` (full) and ``operator`` (read + non-destructive writes; barred
+from destructive actions guarded by :func:`require_admin` at the API layer).
+
+Sessions are stateless HMAC-signed bearer tokens, so the API accepts either HTTP
+Basic (username/password) or ``Authorization: Bearer <token>``.
+
+Passwords are compared in plaintext for parity with hivemind-core's existing
+``server.json`` model; hashing them is tracked as a hardening follow-up.
+"""
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from ovos_utils.log import LOG
+from ovos_utils.xdg_utils import xdg_data_home
+
+ADMIN = "admin"
+OPERATOR = "operator"
+TOKEN_TTL = 12 * 3600  # 12h
+
+
+# --------------------------------------------------------------------------- users
+
+def _users(config: Dict[str, Any]) -> List[Dict[str, str]]:
+    """All admin accounts: the primary admin_user plus any extra `users`."""
+    users = [{
+        "username": config.get("admin_user", "admin"),
+        "password": config.get("admin_pass", "admin"),
+        "role": ADMIN,
+    }]
+    for u in config.get("users", []) or []:
+        if u.get("username"):
+            users.append({
+                "username": u["username"],
+                "password": u.get("password", ""),
+                "role": u.get("role", OPERATOR),
+            })
+    return users
+
+
+def hash_password(password: str, iterations: int = 200_000) -> str:
+    """Hash a password with PBKDF2-SHA256 (stored format ``pbkdf2_sha256$...``)."""
+    salt = os.urandom(16)
+    dk = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, iterations)
+    return f"pbkdf2_sha256${iterations}${salt.hex()}${dk.hex()}"
+
+
+def verify_password(stored: str, password: str) -> bool:
+    """Verify a password against a stored PBKDF2 hash or legacy plaintext value."""
+    if stored.startswith("pbkdf2_sha256$"):
+        try:
+            _, iters, salt_hex, hash_hex = stored.split("$")
+            dk = hashlib.pbkdf2_hmac("sha256", password.encode(),
+                                     bytes.fromhex(salt_hex), int(iters))
+            return hmac.compare_digest(dk.hex(), hash_hex)
+        except Exception:
+            return False
+    return hmac.compare_digest(stored, password)  # legacy plaintext
+
+
+def authenticate(config: Dict[str, Any], username: str, password: str) -> Optional[str]:
+    """Return the user's role if credentials match, else None.
+
+    Passwords may be PBKDF2 hashes or legacy plaintext (see :func:`verify_password`).
+    """
+    role = None
+    for u in _users(config):
+        if hmac.compare_digest(u["username"], username) and verify_password(u["password"], password):
+            role = u["role"]
+    return role
+
+
+# --------------------------------------------------------------------------- tokens
+
+def _secret(config: Dict[str, Any]) -> bytes:
+    """Persistent signing secret, generated into server.json on first use."""
+    secret = config.get("admin_token_secret")
+    if not secret:
+        secret = os.urandom(32).hex()
+        try:
+            config["admin_token_secret"] = secret
+            config.store()
+        except Exception as e:  # config may be a plain dict in tests
+            LOG.debug(f"could not persist token secret: {e}")
+    return secret.encode()
+
+
+def create_token(config: Dict[str, Any], username: str, role: str, ttl: int = TOKEN_TTL) -> Dict[str, Any]:
+    payload = {"sub": username, "role": role, "exp": int(time.time()) + ttl}
+    raw = base64.urlsafe_b64encode(json.dumps(payload).encode()).decode().rstrip("=")
+    sig = hmac.new(_secret(config), raw.encode(), hashlib.sha256).hexdigest()
+    return {"token": f"{raw}.{sig}", "role": role, "expires": payload["exp"]}
+
+
+def verify_token(config: Dict[str, Any], token: str) -> Optional[Dict[str, Any]]:
+    try:
+        raw, sig = token.split(".", 1)
+    except ValueError:
+        return None
+    expected = hmac.new(_secret(config), raw.encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(sig, expected):
+        return None
+    try:
+        pad = "=" * (-len(raw) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(raw + pad))
+    except Exception:
+        return None
+    if payload.get("exp", 0) < time.time():
+        return None
+    return payload
+
+
+# --------------------------------------------------------------------------- audit
+
+def _audit_path() -> str:
+    base = os.path.join(xdg_data_home(), "hivemind-admin")
+    os.makedirs(base, exist_ok=True)
+    return os.path.join(base, "audit.log")
+
+
+def audit(user: str, action: str, **data: Any) -> None:
+    entry = {"ts": time.time(), "user": user, "action": action, **data}
+    try:
+        with open(_audit_path(), "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    except Exception as e:
+        LOG.debug(f"audit write failed: {e}")
+
+
+def read_audit(limit: int = 200) -> List[Dict[str, Any]]:
+    path = _audit_path()
+    if not os.path.isfile(path):
+        return []
+    try:
+        with open(path, "r", errors="replace") as f:
+            lines = f.readlines()[-limit:]
+    except Exception:
+        return []
+    out = []
+    for ln in lines:
+        try:
+            out.append(json.loads(ln))
+        except Exception:
+            continue
+    return out

hivemind_admin_panel/_chat.py

@@ -0,0 +1,146 @@
+# hivemind-admin-panel
+# Copyright (C) 2026 Casimiro Ferreira
+# SPDX-License-Identifier: Apache-2.0
+"""Server-side client impersonation: chat through the hub *as* a registered client.
+
+The admin picks a client; the panel opens a real ``HiveMessageBusClient`` with that
+client's credentials, connects to the hub like any satellite would, sends typed
+utterances, and collects the agent's ``speak`` replies. This exercises the genuine
+path — ACL enforcement, routing, the agent backend — not a simulation.
+"""
+import threading
+import time
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class ImpersonationSession:
+    """One live impersonated client connection and its chat transcript."""
+
+    def __init__(self, client_id: int, name: str, key: str, password: str,
+                 crypto_key: Optional[str], host: str, port: int):
+        self.id = uuid.uuid4().hex
+        self.client_id = client_id
+        self.name = name
+        self.error: Optional[str] = None
+        self.created = time.time()
+        self.last_used = time.time()
+        self._transcript: List[Dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self.bus = None
+        self._connect(key, password, crypto_key, host, port)
+
+    def _connect(self, key, password, crypto_key, host, port):
+        from ovos_utils.fakebus import FakeBus
+        from hivemind_bus_client import HiveMessageBusClient
+
+        self.bus = HiveMessageBusClient(
+            key=key, password=password, crypto_key=crypto_key,
+            host=host, port=port, self_signed=True, useragent="HiveMindAdminChat",
+        )
+        self.bus.on_mycroft("speak", self._on_speak)
+        self.bus.on_mycroft("hive.complete_intent_failure", self._on_fail)
+
+        def _do():
+            try:
+                self.bus.connect(FakeBus())
+            except Exception as e:   # noqa: BLE001 - surfaced to the caller
+                self.error = str(e)
+
+        threading.Thread(target=_do, daemon=True).start()
+        if not self.bus.handshake_event.wait(15):
+            self.error = self.error or (
+                "handshake timed out — is the hub running and does this client have "
+                "a crypto key?")
+
+    # --- bus callbacks (run on the websocket thread) ---------------------------
+    def _on_speak(self, message):
+        utt = ""
+        try:
+            utt = message.data.get("utterance") or message.data.get("text") or ""
+        except Exception:
+            pass
+        if utt:
+            self._append("assistant", utt)
+
+    def _on_fail(self, message):
+        self._append("system", "the hub reported no skill/agent handled that utterance")
+
+    def _append(self, role: str, text: str):
+        with self._lock:
+            self._transcript.append({"role": role, "text": text, "ts": time.time()})
+
+    # --- public API ------------------------------------------------------------
+    def say(self, utterance: str, lang: str = "en-us"):
+        from hivemind_bus_client.message import HiveMessage, HiveMessageType
+        from ovos_bus_client.message import Message
+
+        self.last_used = time.time()
+        self._append("user", utterance)
+        self.bus.emit(HiveMessage(
+            HiveMessageType.BUS,
+            Message("recognizer_loop:utterance", {"utterances": [utterance], "lang": lang}),
+        ))
+
+    def messages(self, since: int = 0) -> Tuple[List[Dict[str, Any]], int]:
+        with self._lock:
+            self.last_used = time.time()
+            return list(self._transcript[since:]), len(self._transcript)
+
+    def close(self):
+        try:
+            self.bus.close()
+        except Exception:
+            pass
+
+
+class ChatSessions:
+    """Process-wide registry of impersonation sessions (bounded, idle-reaped)."""
+
+    def __init__(self, max_sessions: int = 12, max_idle: float = 900.0):
+        self._sessions: Dict[str, ImpersonationSession] = {}
+        self._lock = threading.Lock()
+        self._max = max_sessions
+        self._max_idle = max_idle
+
+    def _reap(self):
+        now = time.time()
+        for sid, s in list(self._sessions.items()):
+            if now - s.last_used > self._max_idle:
+                s.close()
+                self._sessions.pop(sid, None)
+
+    def create(self, client_id, name, key, password, crypto_key, host, port
+               ) -> ImpersonationSession:
+        with self._lock:
+            self._reap()
+            # one live session per client: replace any existing
+            for sid, s in list(self._sessions.items()):
+                if s.client_id == client_id:
+                    s.close()
+                    self._sessions.pop(sid, None)
+            if len(self._sessions) >= self._max:
+                oldest = min(self._sessions.values(), key=lambda s: s.last_used)
+                oldest.close()
+                self._sessions.pop(oldest.id, None)
+        sess = ImpersonationSession(client_id, name, key, password, crypto_key, host, port)
+        with self._lock:
+            self._sessions[sess.id] = sess
+        return sess
+
+    def get(self, sid: str) -> Optional[ImpersonationSession]:
+        return self._sessions.get(sid)
+
+    def close(self, sid: str):
+        with self._lock:
+            s = self._sessions.pop(sid, None)
+        if s:
+            s.close()
+
+    def list_active(self) -> List[Dict[str, Any]]:
+        return [{"session_id": s.id, "client_id": s.client_id, "name": s.name}
+                for s in self._sessions.values()]
+
+
+# process-wide singleton
+CHAT = ChatSessions()