local-control 0.1.2__py3-none-any.whl

local_control/__init__.py

@@ -0,0 +1,11 @@
+"""
+Local Control package exposing the web server and CLI helpers.
+"""
+
+from __future__ import annotations
+
+__all__ = ["create_app", "__version__"]
+
+__version__ = "0.1.0"
+
+from .app import create_app  # noqa: E402  (lazy import to avoid side effects)

local_control/app.py

@@ -0,0 +1,291 @@
+"""
+Flask application wiring the authentication manager, control handlers,
+and static frontend.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from flask import (
+    Flask,
+    Response,
+    jsonify,
+    make_response,
+    request,
+    send_from_directory,
+)
+
+from .auth import AuthManager, CredentialError, RateLimitError
+from . import control, clipboard
+from .clipboard import ClipboardData
+
+SESSION_COOKIE = "session_token"
+TRUSTED_COOKIE = "trusted_token"
+SESSION_MAX_AGE = 60 * 60 * 4  # 4 hours
+TRUSTED_MAX_AGE = 60 * 60 * 24 * 30  # 30 days
+
+LOG = logging.getLogger(__name__)
+
+
+def create_app(auth_manager: Optional[AuthManager] = None) -> Flask:
+    static_dir = Path(__file__).parent / "static"
+    app = Flask(
+        __name__,
+        static_folder=str(static_dir),
+        static_url_path="/static",
+    )
+    app.config["JSONIFY_PRETTYPRINT_REGULAR"] = False
+    auth = auth_manager or AuthManager()
+
+    def client_key() -> str:
+        return request.remote_addr or "unknown"
+
+    def ensure_session() -> Tuple[Optional[str], Optional[str]]:
+        token = request.cookies.get(SESSION_COOKIE)
+        user = auth.session_user(token)
+        if user:
+            return user, None
+
+        trusted = request.cookies.get(TRUSTED_COOKIE)
+        user = auth.auto_login(trusted)
+        if user:
+            fresh = auth.create_session(user)
+            return user, fresh
+        return None, None
+
+    def require_auth() -> Tuple[Optional[str], Optional[str]]:
+        user, new_token = ensure_session()
+        if not user:
+            return None, None
+        return user, new_token
+
+    def build_response(
+        payload: Dict[str, Any],
+        session_token: Optional[str] = None,
+        clear_session: bool = False,
+        trusted_token: Optional[str] = None,
+        clear_trusted: bool = False,
+        status: int = 200,
+    ) -> Response:
+        response = make_response(jsonify(payload), status)
+        if session_token:
+            response.set_cookie(
+                SESSION_COOKIE,
+                session_token,
+                httponly=True,
+                secure=False,
+                samesite="Strict",
+                max_age=SESSION_MAX_AGE,
+            )
+        if clear_session:
+            response.delete_cookie(SESSION_COOKIE)
+        if trusted_token:
+            response.set_cookie(
+                TRUSTED_COOKIE,
+                trusted_token,
+                httponly=True,
+                secure=False,
+                samesite="Strict",
+                max_age=TRUSTED_MAX_AGE,
+            )
+        if clear_trusted:
+            response.delete_cookie(TRUSTED_COOKIE)
+        return response
+
+    # Routes -----------------------------------------------------------------
+    @app.get("/")
+    def index() -> Response:
+        return send_from_directory(app.static_folder, "index.html")
+
+    @app.get("/api/session")
+    def session_info() -> Response:
+        user, fresh_token = ensure_session()
+        if user:
+            return build_response(
+                {"authenticated": True, "username": user},
+                session_token=fresh_token,
+            )
+        return build_response({"authenticated": False, "username": None})
+
+    @app.post("/api/login")
+    def login() -> Response:
+        data = request.get_json(silent=True) or {}
+        username = str(data.get("username", "")).strip()
+        password = str(data.get("password", ""))
+        remember = bool(data.get("remember", False))
+        remote = client_key()
+
+        try:
+            auth.check_rate_limit(remote)
+        except RateLimitError as exc:
+            return build_response({"error": str(exc)}, status=429)
+
+        try:
+            verified = auth.verify_credentials(username, password)
+        except CredentialError as exc:
+            LOG.warning("Credential verification error: %s", exc)
+            return build_response({"error": str(exc)}, status=400)
+
+        if not verified:
+            auth.register_failure(remote)
+            return build_response({"error": "Invalid username or password."}, status=401)
+
+        auth.register_success(remote)
+        session_token = auth.create_session(username)
+        trusted_token = auth.create_trusted_token(username) if remember else None
+
+        payload = {"authenticated": True, "username": username}
+        return build_response(
+            payload,
+            session_token=session_token,
+            trusted_token=trusted_token,
+        )
+
+    @app.post("/api/logout")
+    def logout() -> Response:
+        token = request.cookies.get(SESSION_COOKIE)
+        if token:
+            auth.destroy_session(token)
+        return build_response({"authenticated": False}, clear_session=True)
+
+    def auth_endpoint(handler: Callable[[Dict[str, Any]], Dict[str, Any]]) -> Response:
+        user, fresh_token = require_auth()
+        if not user:
+            return build_response({"error": "Authentication required."}, status=401)
+        payload = request.get_json(silent=True) or {}
+        try:
+            response_payload = handler(payload)
+        except ValueError as exc:
+            return build_response({"error": str(exc)}, status=400)
+        except Exception as exc:  # pragma: no cover - defensive
+            LOG.exception("Handler error: %s", exc)
+            return build_response({"error": str(exc)}, status=500)
+        return build_response(response_payload, session_token=fresh_token)
+
+    @app.post("/api/mouse/move")
+    def mouse_move() -> Response:
+        def action(data: Dict[str, Any]) -> Dict[str, Any]:
+            dx = float(data.get("dx", 0.0))
+            dy = float(data.get("dy", 0.0))
+            state = control.move_cursor(dx, dy)
+            return {"status": "ok", "state": state}
+
+        return auth_endpoint(action)
+
+    @app.post("/api/mouse/click")
+    def mouse_click() -> Response:
+        def action(data: Dict[str, Any]) -> Dict[str, Any]:
+            button = str(data.get("button", "left"))
+            double = bool(data.get("double", False))
+            control.click(button=button, double=double)
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.post("/api/mouse/button")
+    def mouse_button() -> Response:
+        def action(data: Dict[str, Any]) -> Dict[str, Any]:
+            button = str(data.get("button", "left"))
+            button_action = str(data.get("action", "down"))
+            control.button_action(button=button, action=button_action)
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.post("/api/mouse/scroll")
+    def mouse_scroll() -> Response:
+        def action(data: Dict[str, Any]) -> Dict[str, Any]:
+            vertical = float(data.get("vertical", 0.0))
+            horizontal = float(data.get("horizontal", 0.0))
+            control.scroll(vertical=vertical, horizontal=horizontal)
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.get("/api/mouse/state")
+    def mouse_state() -> Response:
+        user, fresh_token = require_auth()
+        if not user:
+            return build_response({"error": "Authentication required."}, status=401)
+        state = control.cursor_state()
+        return build_response({"status": "ok", "state": state}, session_token=fresh_token)
+
+    @app.post("/api/keyboard/type")
+    def keyboard_type() -> Response:
+        def action(data: Dict[str, Any]) -> Dict[str, Any]:
+            text = str(data.get("text", ""))
+            control.type_text(text)
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.post("/api/keyboard/key")
+    def keyboard_key() -> Response:
+        def action(data: Dict[str, Any]) -> Dict[str, Any]:
+            key = str(data.get("key", "")).lower()
+            action_name = str(data.get("action", "press")).lower()
+            control.key_action(key, action_name)
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.post("/api/system/lock")
+    def system_lock() -> Response:
+        def action(_: Dict[str, Any]) -> Dict[str, Any]:
+            control.lock_screen()
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.post("/api/system/unlock")
+    def system_unlock() -> Response:
+        def action(_: Dict[str, Any]) -> Dict[str, Any]:
+            control.unlock_screen()
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.post("/api/system/shutdown")
+    def system_shutdown() -> Response:
+        def action(_: Dict[str, Any]) -> Dict[str, Any]:
+            control.shutdown_system()
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    @app.get("/api/clipboard")
+    def clipboard_read() -> Response:
+        user, fresh_token = require_auth()
+        if not user:
+            return build_response({"error": "Authentication required."}, status=401)
+        clip = clipboard.get_clipboard()
+        if clip:
+            content = {"type": clip.kind, "data": clip.data, "mime": clip.mime}
+        else:
+            content = None
+        return build_response(
+            {"status": "ok", "content": content},
+            session_token=fresh_token,
+        )
+
+    @app.post("/api/clipboard")
+    def clipboard_write() -> Response:
+        def action(data: Dict[str, Any]) -> Dict[str, Any]:
+            clip_type = str(data.get("type", "")).lower()
+            if clip_type not in {"text", "image"}:
+                raise ValueError("Clipboard type must be 'text' or 'image'.")
+            payload = data.get("data")
+            if payload is None:
+                raise ValueError("Clipboard payload missing.")
+            mime = data.get("mime")
+            clip = ClipboardData(kind=clip_type, data=str(payload), mime=str(mime) if mime else None)
+            clipboard.set_clipboard(clip)
+            return {"status": "ok"}
+
+        return auth_endpoint(action)
+
+    return app

local_control/auth.py

@@ -0,0 +1,240 @@
+"""
+Authentication manager handling OS credential checks, sessions, device trust,
+and brute-force protections.
+"""
+
+from __future__ import annotations
+
+import getpass
+import hashlib
+import secrets
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .config import data_dir, load_json, save_json
+
+
+class RateLimitError(Exception):
+    """Raised when a client exceeds the allowed login attempts."""
+
+
+class CredentialError(Exception):
+    """Raised when provided credentials cannot be validated."""
+
+
+@dataclass
+class Session:
+    username: str
+    created_at: float
+
+
+@dataclass
+class TrustedDevice:
+    username: str
+    token_hash: str
+    created_at: float
+
+
+class AuthManager:
+    MAX_ATTEMPTS = 5
+    WINDOW_SECONDS = 600
+    LOCKOUT_SECONDS = 600
+
+    def __init__(self) -> None:
+        base = data_dir()
+        self._secret_path = base / "secret.key"
+        self._trusted_path = base / "trusted_devices.json"
+        self._secret = self._load_secret()
+        self._sessions: Dict[str, Session] = {}
+        self._trusted_devices: List[TrustedDevice] = self._load_trusted_devices()
+        self._attempts: Dict[str, Dict[str, float]] = {}
+        self._current_user = getpass.getuser()
+
+    @property
+    def current_user(self) -> str:
+        return self._current_user
+
+    # Secret helpers ---------------------------------------------------------
+    def _load_secret(self) -> bytes:
+        if self._secret_path.exists():
+            return self._secret_path.read_bytes()
+
+        secret = secrets.token_bytes(32)
+        self._secret_path.write_bytes(secret)
+        return secret
+
+    # Trusted device persistence ---------------------------------------------
+    def _load_trusted_devices(self) -> List[TrustedDevice]:
+        data = load_json(
+            self._trusted_path,
+            default={"devices": []},
+        )
+        devices: List[TrustedDevice] = []
+        for entry in data.get("devices", []):
+            try:
+                devices.append(
+                    TrustedDevice(
+                        username=entry["username"],
+                        token_hash=entry["token_hash"],
+                        created_at=float(entry.get("created_at", 0.0)),
+                    )
+                )
+            except KeyError:
+                continue
+        return devices
+
+    def _persist_trusted(self) -> None:
+        payload = {
+            "devices": [
+                {
+                    "username": device.username,
+                    "token_hash": device.token_hash,
+                    "created_at": device.created_at,
+                }
+                for device in self._trusted_devices
+            ]
+        }
+        save_json(self._trusted_path, payload)
+
+    # Rate limiting ----------------------------------------------------------
+    def check_rate_limit(self, key: str) -> None:
+        entry = self._attempts.get(key)
+        now = time.time()
+        if not entry:
+            return
+
+        locked_until = entry.get("locked_until", 0.0)
+        if locked_until and locked_until > now:
+            raise RateLimitError("Too many attempts. Retry later.")
+
+        timestamps = entry.get("timestamps", [])
+        # Drop attempts outside of the time window.
+        timestamps = [ts for ts in timestamps if now - ts < self.WINDOW_SECONDS]
+        entry["timestamps"] = timestamps
+        if len(timestamps) >= self.MAX_ATTEMPTS:
+            entry["locked_until"] = now + self.LOCKOUT_SECONDS
+            raise RateLimitError("Too many attempts. Retry later.")
+
+    def register_failure(self, key: str) -> None:
+        now = time.time()
+        entry = self._attempts.setdefault(
+            key, {"timestamps": [], "locked_until": 0.0}
+        )
+        entry.setdefault("timestamps", []).append(now)
+        # Enforce the window retention.
+        entry["timestamps"] = [
+            ts for ts in entry["timestamps"] if now - ts < self.WINDOW_SECONDS
+        ]
+        if len(entry["timestamps"]) >= self.MAX_ATTEMPTS:
+            entry["locked_until"] = now + self.LOCKOUT_SECONDS
+
+    def register_success(self, key: str) -> None:
+        if key in self._attempts:
+            del self._attempts[key]
+
+    # Token helpers ----------------------------------------------------------
+    def _hash_token(self, token: str) -> str:
+        return hashlib.sha256(self._secret + token.encode("utf-8")).hexdigest()
+
+    def create_session(self, username: str) -> str:
+        token = secrets.token_urlsafe(32)
+        token_hash = self._hash_token(token)
+        self._sessions[token_hash] = Session(username=username, created_at=time.time())
+        return token
+
+    def destroy_session(self, token: str) -> None:
+        token_hash = self._hash_token(token)
+        self._sessions.pop(token_hash, None)
+
+    def session_user(self, token: Optional[str]) -> Optional[str]:
+        if not token:
+            return None
+        token_hash = self._hash_token(token)
+        session = self._sessions.get(token_hash)
+        if session:
+            return session.username
+        return None
+
+    # Trusted devices --------------------------------------------------------
+    def create_trusted_token(self, username: str) -> str:
+        token = secrets.token_urlsafe(32)
+        token_hash = self._hash_token(token)
+        self._trusted_devices.append(
+            TrustedDevice(username=username, token_hash=token_hash, created_at=time.time())
+        )
+        self._persist_trusted()
+        return token
+
+    def auto_login(self, token: Optional[str]) -> Optional[str]:
+        if not token:
+            return None
+        token_hash = self._hash_token(token)
+        for device in self._trusted_devices:
+            if device.token_hash == token_hash and device.username == self._current_user:
+                return device.username
+        return None
+
+    # Credential verification ------------------------------------------------
+    def verify_credentials(self, username: str, password: str) -> bool:
+        if username != self._current_user:
+            return False
+
+        system = sys.platform
+        if system.startswith("win"):
+            return self._verify_windows(username, password)
+        return self._verify_unix(username, password)
+
+    def _verify_unix(self, username: str, password: str) -> bool:
+        # Use sudo in non-interactive mode. Requires the user to be part of sudoers.
+        if not password:
+            return False
+        try:
+            subprocess.run(
+                ["sudo", "-k"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+            )
+            proc = subprocess.run(
+                ["sudo", "-S", "-p", "", "true"],
+                input=f"{password}\n".encode("utf-8"),
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+                check=False,
+                timeout=10,
+            )
+            return proc.returncode == 0
+        except (OSError, subprocess.SubprocessError):
+            raise CredentialError(
+                "Could not verify credentials on this platform. Ensure sudo is available."
+            )
+
+    def _verify_windows(self, username: str, password: str) -> bool:
+        if not password:
+            return False
+        try:
+            import ctypes
+            from ctypes import wintypes
+        except ImportError as exc:  # pragma: no cover
+            raise CredentialError("Windows credential APIs are unavailable.") from exc
+
+        LOGON32_LOGON_INTERACTIVE = 2
+        LOGON32_PROVIDER_DEFAULT = 0
+
+        handle = wintypes.HANDLE()
+        result = ctypes.windll.advapi32.LogonUserW(
+            ctypes.c_wchar_p(username),
+            ctypes.c_wchar_p(None),
+            ctypes.c_wchar_p(password),
+            LOGON32_LOGON_INTERACTIVE,
+            LOGON32_PROVIDER_DEFAULT,
+            ctypes.byref(handle),
+        )
+        if result:
+            ctypes.windll.kernel32.CloseHandle(handle)
+            return True
+        return False

local_control/cli.py

@@ -0,0 +1,143 @@
+"""
+Command-line entry point for launching the local control server.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import socket
+import sys
+from typing import Iterable, List, Optional
+
+from .app import create_app
+from .startup import StartupManager, StartupError
+from .utils.terminal_qr import render_text
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Start the local Control server to steer this machine remotely.",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Host/IP to bind (default: 0.0.0.0 for all interfaces).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=4001,
+        help="Port to listen on (default: 4001).",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable Flask debug mode.",
+    )
+    parser.add_argument(
+        "--startup",
+        action="store_true",
+        help="Register this server to launch automatically for the current user.",
+    )
+    parser.add_argument(
+        "--startup-cancel",
+        action="store_true",
+        help="Remove the auto-start registration created with --startup.",
+    )
+    return parser
+
+
+def main(argv: Optional[Iterable[str]] = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if args.startup and args.startup_cancel:
+        parser.error("Choose only one of --startup or --startup-cancel.")
+
+    if args.startup or args.startup_cancel:
+        manager = StartupManager(args.host, args.port, args.debug)
+        try:
+            if args.startup:
+                manager.enable()
+                print("Startup entry created. Local Control will launch on login.")
+            else:
+                manager.disable()
+                print("Startup entry removed.")
+        except StartupError as exc:
+            print(f"Startup configuration failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+        return
+
+    logging.basicConfig(level=logging.INFO)
+    app = create_app()
+    if not args.debug or os.environ.get("WERKZEUG_RUN_MAIN") == "true":
+        _display_banner(args.host, args.port)
+    app.run(host=args.host, port=args.port, debug=args.debug)
+
+
+def _display_banner(host: str, port: int) -> None:
+    urls = _candidate_urls(host, port)
+    if not urls:
+        return
+    primary = next((url for url in urls if not url.startswith("http://127.")), urls[0])
+
+    print("Local Control server ready. Reach it at:", flush=True)
+    for url in urls:
+        print(f"  • {url}", flush=True)
+
+    try:
+        qr_text = render_text(primary)
+    except Exception as exc:  # pragma: no cover - cosmetic
+        logging.debug("Failed to render QR code: %s", exc)
+        return
+
+    print("\nScan to connect:", flush=True)
+    print(qr_text, flush=True)
+
+
+def _candidate_urls(host: str, port: int) -> List[str]:
+    hosts: List[str] = []
+    if host in {"0.0.0.0", "::", "", "*"}:
+        hosts.extend(_local_ipv4_addresses())
+        hosts.append("127.0.0.1")
+        hosts.append("localhost")
+    else:
+        hosts.append(host)
+        if host not in {"127.0.0.1", "localhost"}:
+            hosts.append("127.0.0.1")
+            hosts.append("localhost")
+
+    normalized = []
+    for h in hosts:
+        if ":" in h and not h.startswith("["):
+            normalized.append(f"http://[{h}]:{port}")
+        else:
+            normalized.append(f"http://{h}:{port}")
+
+    seen = set()
+    unique_urls = []
+    for url in normalized:
+        if url not in seen:
+            seen.add(url)
+            unique_urls.append(url)
+    return unique_urls
+
+
+def _local_ipv4_addresses() -> List[str]:
+    candidates = set()
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+            sock.connect(("8.8.8.8", 80))
+            candidates.add(sock.getsockname()[0])
+    except OSError:
+        pass
+    try:
+        hostname = socket.gethostname()
+        for addr in socket.gethostbyname_ex(hostname)[2]:
+            if addr and addr != "127.0.0.1":
+                candidates.add(addr)
+    except socket.gaierror:
+        pass
+    return sorted(candidates)