local-control 0.1.2__tar.gz

local_control-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DIYer22
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

local_control-0.1.2/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: local_control
+Version: 0.1.2
+Summary: LAN-accessible remote control server for mouse, keyboard, and power management
+Author: DIYer22
+License: MIT License
+Project-URL: Homepage, https://github.com/DIYer22/local_control
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=2.3
+Dynamic: license-file
+
+# 🖱️ Local Control
+
+Let you steer the computer's mouse, keyboard from any device's browser.   
+
+<a href="https://yl-data.github.io/2511.local_control/images/local-send-screenshot.jpeg">
+<img style="height:384px" src=https://yl-data.github.io/2511.local_control/images/local-send-screenshot.jpeg>
+</a>
+
+The server is written in pure Python with minimal dependencies and ships with a mobile-friendly frontend.
+
+## Features
+- Mouse cursor movement and click controls from touch or mouse devices.
+- Realtime input field streams keystrokes (including Backspace/Delete) as you type.
+- OS-level lock, and shutdown shortcuts (best-effort across Windows, macOS, Linux).
+- Authentication that reuses the current OS account credentials, remembers trusted devices, and rate-limits brute-force attempts.
+- Build with GPT-5-Codex, easy to customize and modify with vibe coding.
+
+## Requirements
+- Python 3.9 or newer.
+- Desktop environments capable of receiving simulated input (X11/Wayland, Windows, or macOS).
+- Linux/X11 hosts require the `libX11` and `libXtst` system libraries (commonly present on desktop distributions; Wayland sessions need XWayland support).
+- macOS hosts must grant the Python process accessibility permissions (System Settings → Privacy & Security → Accessibility).
+
+## Installation
+```bash
+pip install local_control
+```
+
+## Usage
+```bash
+local-control --help
+local-control --port 4001
+```
+
+Open `http://<host-ip>:4001` from your phone, tablet, or another computer on the same LAN. Sign in with the current desktop user's username and password. Devices marked as trusted skip future logins under the same secret.
+

local_control-0.1.2/README.md

@@ -0,0 +1,36 @@
+# 🖱️ Local Control
+
+Let you steer the computer's mouse, keyboard from any device's browser.   
+
+<a href="https://yl-data.github.io/2511.local_control/images/local-send-screenshot.jpeg">
+<img style="height:384px" src=https://yl-data.github.io/2511.local_control/images/local-send-screenshot.jpeg>
+</a>
+
+The server is written in pure Python with minimal dependencies and ships with a mobile-friendly frontend.
+
+## Features
+- Mouse cursor movement and click controls from touch or mouse devices.
+- Realtime input field streams keystrokes (including Backspace/Delete) as you type.
+- OS-level lock, and shutdown shortcuts (best-effort across Windows, macOS, Linux).
+- Authentication that reuses the current OS account credentials, remembers trusted devices, and rate-limits brute-force attempts.
+- Build with GPT-5-Codex, easy to customize and modify with vibe coding.
+
+## Requirements
+- Python 3.9 or newer.
+- Desktop environments capable of receiving simulated input (X11/Wayland, Windows, or macOS).
+- Linux/X11 hosts require the `libX11` and `libXtst` system libraries (commonly present on desktop distributions; Wayland sessions need XWayland support).
+- macOS hosts must grant the Python process accessibility permissions (System Settings → Privacy & Security → Accessibility).
+
+## Installation
+```bash
+pip install local_control
+```
+
+## Usage
+```bash
+local-control --help
+local-control --port 4001
+```
+
+Open `http://<host-ip>:4001` from your phone, tablet, or another computer on the same LAN. Sign in with the current desktop user's username and password. Devices marked as trusted skip future logins under the same secret.
+

local_control-0.1.2/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-0.1.2/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-0.1.2/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