embedded-lab-control 0.2.0__py3-none-any.whl

labctl/web/app.py

@@ -0,0 +1,202 @@
+"""
+Flask application factory for lab controller web interface.
+"""
+
+import secrets
+from datetime import timedelta
+from pathlib import Path
+
+from flask import Flask, g, jsonify, redirect, request, session, url_for
+
+from labctl import __version__
+from labctl.core import audit
+from labctl.core.config import Config, load_config
+from labctl.core.manager import ResourceManager, get_manager
+from labctl.web.auth import (
+    generate_csrf_token,
+    get_user_by_api_key,
+    get_user_by_username,
+    validate_csrf_token,
+)
+
+
+def create_app(config: Config | None = None) -> Flask:
+    """
+    Create and configure Flask application.
+
+    Args:
+        config: Optional Config instance. If None, loads from default location.
+
+    Returns:
+        Configured Flask application
+    """
+    app = Flask(
+        __name__,
+        template_folder=str(Path(__file__).parent / "templates"),
+        static_folder=str(Path(__file__).parent / "static"),
+    )
+
+    # Load configuration
+    if config is None:
+        config = load_config()
+    if config.load_errors:
+        # Fail closed: serving on another file's or built-in settings could
+        # mean no login (auth.enabled off). `labctl web` checks this too;
+        # this covers WSGI servers and other callers of create_app().
+        raise RuntimeError(
+            "Refusing to create the web app: config not loaded ("
+            + "; ".join(config.load_errors)
+            + ")"
+        )
+
+    app.config["LABCTL_CONFIG"] = config
+    app.jinja_env.globals["labctl_version"] = __version__
+
+    # SECRET_KEY signs the session cookie, which carries the CSRF token even
+    # when auth is disabled, so it must never be a known constant. Without a
+    # configured key, use a random per-process key (the web server is a single
+    # process); sessions then reset on restart.
+    if config.auth.secret_key:
+        app.config["SECRET_KEY"] = config.auth.secret_key
+    else:
+        app.config["SECRET_KEY"] = secrets.token_hex(32)
+
+    # Set session lifetime
+    app.config["PERMANENT_SESSION_LIFETIME"] = timedelta(
+        minutes=config.auth.session_lifetime_minutes
+    )
+
+    # Register blueprints
+    from labctl.web.activity_broadcaster import ActivityBroadcaster
+    from labctl.web.api import api_bp
+    from labctl.web.auth import auth_bp
+    from labctl.web.views import views_bp
+
+    app.register_blueprint(auth_bp)
+    app.register_blueprint(api_bp, url_prefix="/api")
+    app.register_blueprint(views_bp)
+
+    # Start the activity-stream broadcaster thread. Polls audit_log and
+    # fans new rows out to SSE subscribers on /activity/stream.
+    mgr_for_broadcast = get_manager(
+        config.database_path,
+        timeout_seconds=config.database.timeout_seconds,
+    )
+    app.config["ACTIVITY_BROADCASTER"] = ActivityBroadcaster(mgr_for_broadcast.db)
+    app.config["ACTIVITY_BROADCASTER"].start()
+
+    # Register csrf_token as Jinja2 template global
+    app.jinja_env.globals["csrf_token"] = generate_csrf_token
+
+    def _request_activity_identity() -> tuple[str, str]:
+        """Derive audit actor/source for the current Flask request."""
+        source = (
+            "api" if request.endpoint and request.endpoint.startswith("api.") else "web"
+        )
+
+        user = getattr(g, "audit_user", None)
+        if not user:
+            user = session.get("user")
+        if not user:
+            user = "anonymous"
+
+        return f"{source}:{user}", source
+
+    @app.before_request
+    def before_request():
+        """Set up manager and enforce auth for each request."""
+        config = app.config["LABCTL_CONFIG"]
+        g.manager = get_manager(
+            config.database_path,
+            timeout_seconds=config.database.timeout_seconds,
+            base_tcp_port=config.serial.base_tcp_port,
+        )
+        g.config = config
+
+        api_request = bool(request.endpoint and request.endpoint.startswith("api."))
+        api_user = None
+        # The authenticated user (UserConfig), for claim checks: their
+        # role decides who may override a claim (D013).
+        g.auth_user = None
+
+        if api_request and config.auth.enabled:
+            api_key = request.headers.get("X-API-Key", "")
+            if api_key:
+                api_user = get_user_by_api_key(config.auth, api_key)
+                if api_user:
+                    g.audit_user = api_user.username
+                    g.auth_user = api_user
+        elif "user" in session:
+            g.audit_user = session["user"]
+            if config.auth.enabled:
+                g.auth_user = get_user_by_username(config.auth, session["user"])
+
+        actor, source = _request_activity_identity()
+        ctx = audit.activity_context(actor, source)
+        ctx.__enter__()
+        g._activity_context = ctx
+
+        # Skip auth enforcement if auth is disabled
+        if not config.auth.enabled:
+            return
+
+        # Whitelist: login page, static files, health check
+        if request.endpoint in (
+            "auth.login",
+            "auth.logout",
+            "static",
+            "api.health_check",
+        ):
+            return
+
+        # API requests: check X-API-Key header
+        if api_request:
+            api_key = request.headers.get("X-API-Key", "")
+            if not api_key:
+                return jsonify({"error": "API key required"}), 401
+            if not api_user:
+                return jsonify({"error": "Invalid API key"}), 401
+
+        # Web requests: check session
+        if "user" not in session:
+            if not api_request:
+                if request.endpoint not in ("auth.login", "auth.logout", "static"):
+                    return redirect(url_for("auth.login", next=request.path))
+
+    @app.teardown_request
+    def teardown_request(exc):
+        """Reset per-request audit attribution context."""
+        ctx = getattr(g, "_activity_context", None)
+        if ctx is not None:
+            ctx.__exit__(
+                type(exc) if exc else None, exc, exc.__traceback__ if exc else None
+            )
+
+    @app.before_request
+    def enforce_csrf():
+        """Enforce CSRF token on state-changing web requests."""
+        config = app.config["LABCTL_CONFIG"]
+        if not config.auth.enabled:
+            return
+
+        # Only enforce on state-changing methods
+        if request.method not in ("POST", "PUT", "DELETE"):
+            return
+
+        # Skip for API endpoints (they use API keys, not CSRF)
+        if request.endpoint and request.endpoint.startswith("api."):
+            return
+
+        # Skip for login (uses its own CSRF)
+        if request.endpoint == "auth.login":
+            return
+
+        if not validate_csrf_token():
+            return redirect(request.referrer or url_for("views.index"))
+
+    return app
+
+
+def get_manager_from_app() -> ResourceManager:
+    """Get resource manager from Flask g object."""
+    return g.manager

labctl/web/auth.py

@@ -0,0 +1,97 @@
+"""
+Authentication module for lab controller web interface.
+
+Provides session-based login for web UI and API key auth for REST API.
+"""
+
+import hmac
+import secrets
+from typing import Optional
+
+from flask import (
+    Blueprint,
+    current_app,
+    flash,
+    redirect,
+    render_template,
+    request,
+    session,
+    url_for,
+)
+from werkzeug.security import check_password_hash
+
+from labctl.core.config import AuthConfig, UserConfig
+
+auth_bp = Blueprint("auth", __name__)
+
+
+def get_user_by_username(
+    auth_config: AuthConfig, username: str
+) -> Optional[UserConfig]:
+    """Look up a user by username."""
+    for user in auth_config.users:
+        if user.username == username:
+            return user
+    return None
+
+
+def get_user_by_api_key(auth_config: AuthConfig, api_key: str) -> Optional[UserConfig]:
+    """Look up a user by API key using constant-time comparison."""
+    return auth_config.user_for_api_key(api_key)
+
+
+def verify_password(user: UserConfig, password: str) -> bool:
+    """Verify a password against a user's stored hash."""
+    if not user.password_hash:
+        return False
+    return check_password_hash(user.password_hash, password)
+
+
+def generate_csrf_token() -> str:
+    """Generate or retrieve a CSRF token for the current session."""
+    if "_csrf_token" not in session:
+        session["_csrf_token"] = secrets.token_hex(32)
+    return session["_csrf_token"]
+
+
+def validate_csrf_token() -> bool:
+    """Validate CSRF token from form data against session."""
+    token = request.form.get("_csrf_token", "")
+    session_token = session.get("_csrf_token", "")
+    if not token or not session_token:
+        return False
+    return hmac.compare_digest(token, session_token)
+
+
+@auth_bp.route("/login", methods=["GET", "POST"])
+def login():
+    """Handle login page and form submission."""
+    if request.method == "POST":
+        username = request.form.get("username", "")
+        password = request.form.get("password", "")
+
+        config = current_app.config["LABCTL_CONFIG"]
+        user = get_user_by_username(config.auth, username)
+
+        if user and verify_password(user, password):
+            session["user"] = username
+            session.permanent = True
+            flash("Logged in successfully.", "success")
+            next_url = request.args.get("next", "")
+            # Prevent open redirect: only allow relative paths
+            if not next_url or next_url.startswith("//") or "://" in next_url:
+                next_url = url_for("views.index")
+            return redirect(next_url)
+        else:
+            flash("Invalid username or password.", "error")
+
+    return render_template("login.html")
+
+
+@auth_bp.route("/logout", methods=["POST"])
+def logout():
+    """Log out the current user."""
+    session.pop("user", None)
+    session.pop("_csrf_token", None)
+    flash("Logged out.", "success")
+    return redirect(url_for("auth.login"))

labctl/web/claims.py

@@ -0,0 +1,232 @@
+"""
+Claim checks for the web UI and REST API (D013).
+
+A change to a board that another user has claimed is refused: REST with
+409 ``sbc_claimed``, the web UI with a page naming the holder. Operators
+may override explicitly (``"override_claim": true`` in a REST body, or the
+button on that page); the override is recorded in the activity log.
+"""
+
+from typing import Optional
+
+from flask import g, render_template, request, session, url_for
+
+from labctl.core.models import (
+    ClaimActor,
+    ClaimConflict,
+    ClaimRequiredError,
+    NotOperatorError,
+    UnknownSBCError,
+)
+
+# A refusal: the JSON error body and its HTTP status.
+Refusal = tuple[dict, int]
+
+_TRUE_VALUES = ("1", "true", "yes", "on")
+
+
+def port_number(value) -> Optional[int]:
+    """``value`` (an int, or text of decimal digits) when it is a whole
+    number from 1 to 65535, else None. Text is length-checked before
+    ``int()``, which refuses very long digit strings."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, str):
+        value = value.strip()
+        if not value.isdecimal() or len(value) > 5:
+            return None
+        value = int(value)
+    if isinstance(value, int) and 1 <= value <= 65535:
+        return value
+    return None
+
+
+def is_api_request() -> bool:
+    return bool(request.endpoint and request.endpoint.startswith("api."))
+
+
+def web_actor() -> ClaimActor:
+    """Who is acting, for claim checks.
+
+    With auth, the logged-in or API-key user: their claims from any
+    session (REST, the web UI, MCP over HTTP) count as theirs, and their
+    role decides whether they may override. Without auth there is one
+    shared identity, which is an operator (as unauthenticated MCP is).
+    """
+    if not g.config.auth.enabled:
+        return ClaimActor(session_id="web:anonymous", operator=True)
+    user = getattr(g, "auth_user", None)
+    if user is not None:
+        return ClaimActor(
+            session_id=f"web:{user.username}",
+            owner=user.username,
+            operator=user.is_operator,
+        )
+    # A login whose user has since left the config: theirs, but no
+    # operator rights.
+    name = session.get("user") or "unknown"
+    return ClaimActor(session_id=f"web:{name}", owner=name, operator=False)
+
+
+def web_user_name() -> str:
+    """The name recorded for this caller's claims, releases and requests."""
+    actor = web_actor()
+    return actor.owner or "web-operator"
+
+
+def override_requested() -> bool:
+    """``override_claim`` in the JSON body (must be ``true``), the form or
+    the query string (``1``, ``true``, ``yes`` or ``on``)."""
+    data = request.get_json(silent=True) if request.is_json else None
+    if isinstance(data, dict) and "override_claim" in data:
+        return data["override_claim"] is True
+    value = request.values.get("override_claim", "")
+    return str(value).strip().lower() in _TRUE_VALUES
+
+
+def claimed_error(sbc_name: str, claim, *, override_hint: bool = True) -> dict:
+    """``sbc_claimed`` for a change to ``sbc_name``; ``claim`` may be on
+    another board that shares its hardware."""
+    holder_board = claim.sbc_name or sbc_name
+    holder = claim.agent_name or "unknown"
+    shared = (
+        f" (it shares hardware with '{sbc_name}')" if holder_board != sbc_name else ""
+    )
+    if claim.is_active:
+        until = f"until {claim.expires_at.isoformat()}" if claim.expires_at else ""
+        hints = [
+            "Wait for the claim to expire or be released",
+            f"Ask for it: POST /api/claims/{holder_board}/request-release",
+        ]
+        if web_actor().operator:
+            if override_hint:
+                hints.append(
+                    'Operator override: repeat with "override_claim": true '
+                    "(recorded in the activity log)"
+                )
+            else:
+                hints.append(
+                    f"Operator override: POST /api/claims/{holder_board}"
+                    "/force-release"
+                )
+    else:
+        # Past its deadline, inside the grace period: only its holder may
+        # re-claim it, and release requests only act on active claims.
+        until = "(expired, in its grace period)"
+        hints = ["Retry once the grace period ends"]
+    return {
+        "error": "sbc_claimed",
+        "sbc_name": holder_board,
+        "message": f"SBC '{holder_board}' is claimed by '{holder}' {until}{shared}",
+        "claim": claim.to_dict(),
+        "hints": hints,
+    }
+
+
+def _refusal(exc: Exception, sbc_name: str, for_sbc: Optional[str]) -> Refusal:
+    if isinstance(exc, ClaimConflict):
+        return claimed_error(for_sbc or sbc_name, exc.claim), 409
+    if isinstance(exc, NotOperatorError):
+        return (
+            {
+                "error": "not_operator",
+                "sbc_name": sbc_name,
+                "message": f"{exc}; your user has role 'agent'",
+                "hints": [f"Ask for it: POST /api/claims/{sbc_name}/request-release"],
+            },
+            403,
+        )
+    assert isinstance(exc, ClaimRequiredError)
+    return (
+        {
+            "error": "claim_required",
+            "sbc_name": sbc_name,
+            "message": str(exc),
+            "hints": [f"Claim it first: POST /api/claims/{sbc_name}"],
+        },
+        409,
+    )
+
+
+def check(
+    sbc_name: str,
+    *,
+    shared: bool = True,
+    sharers: Optional[dict] = None,
+) -> Optional[Refusal]:
+    """Refusal for a change to ``sbc_name`` by this caller, or None to go
+    ahead (the caller's own claim is heartbeated; an override is logged).
+
+    ``shared`` also checks boards sharing ``sbc_name``'s hardware; pass
+    False for changes to the board's own records. ``sharers`` is hardware
+    about to be wired to ``sbc_name`` (keyword arguments for
+    ResourceManager.sbcs_sharing_hardware): the boards that already have
+    it are checked first, so a claimed board's plug, SDWire or console
+    can't be driven through another board. ``claims.require_claim``
+    applies to REST calls, not to the web UI. An override is what the
+    request asks for (see override_requested).
+    """
+    config = g.config
+    if not config.claims.enabled:
+        return None
+    override = override_requested()
+    manager = g.manager
+    actor = web_actor()
+    if sharers:
+        others = set(manager.sbcs_sharing_hardware(**sharers)) - {sbc_name}
+        try:
+            manager.check_claims_of(others, actor, override=override)
+        except (ClaimConflict, NotOperatorError) as exc:
+            return _refusal(exc, sbc_name, sbc_name)
+    try:
+        manager.check_claim(
+            sbc_name,
+            actor,
+            override=override,
+            require_claim=is_api_request() and config.claims.require_claim,
+            include_shared=shared,
+        )
+    except UnknownSBCError:
+        # Callers load the board first, so it was renamed or deleted
+        # meanwhile: don't act on what they loaded unchecked.
+        return (
+            {
+                "error": "sbc_changed",
+                "sbc_name": sbc_name,
+                "message": f"SBC '{sbc_name}' was renamed or removed; retry",
+            },
+            404,
+        )
+    except (ClaimConflict, NotOperatorError, ClaimRequiredError) as exc:
+        return _refusal(exc, sbc_name, None)
+    return None
+
+
+def refusal_page(refusal: Refusal, sbc_name: str):
+    """The web UI's answer to a refused change: the holder, how to ask for
+    the board, and (for operators, on an active claim) a button that
+    repeats the change with ``override_claim``."""
+    body, status = refusal
+    claim = body.get("claim") or {}
+    fields = [
+        (key, value)
+        for key, value in request.form.items(multi=True)
+        if key not in ("_csrf_token", "override_claim")
+    ]
+    can_override = (
+        body["error"] == "sbc_claimed"
+        and web_actor().operator
+        and bool(claim.get("is_active", True))
+    )
+    return (
+        render_template(
+            "claim_refused.html",
+            body=body,
+            sbc_name=sbc_name,
+            fields=fields,
+            action=request.path,
+            can_override=can_override,
+            back=url_for("views.sbc_detail", name=sbc_name),
+        ),
+        status,
+    )