remctl 0.1.0__py3-none-any.whl

remctl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

remctl/__main__.py

@@ -0,0 +1,4 @@
+from remctl.cli import app
+
+if __name__ == "__main__":
+    app()

remctl/audit.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+import logging
+from logging.handlers import RotatingFileHandler
+
+from remctl.crypto import KEY_DIR
+
+AUDIT_LOG = KEY_DIR / "audit.log"
+
+_logger: logging.Logger | None = None
+
+
+def get_logger(max_bytes: int = 10 * 1024 * 1024, backup_count: int = 5) -> logging.Logger:
+    global _logger
+    if _logger is not None:
+        return _logger
+    KEY_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+    _logger = logging.getLogger("remctl.audit")
+    _logger.setLevel(logging.INFO)
+    handler = RotatingFileHandler(
+        str(AUDIT_LOG),
+        maxBytes=max_bytes,
+        backupCount=backup_count,
+        encoding="utf-8",
+    )
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    _logger.addHandler(handler)
+    _logger.propagate = False
+    return _logger
+
+
+def log_command(
+    source_fingerprint: str,
+    command: str,
+    args: dict,
+    outcome: str,
+    detail: str | None = None,
+) -> None:
+    logger = get_logger()
+    record = {
+        "timestamp": __import__("time").time(),
+        "source": source_fingerprint,
+        "command": command,
+        "args": args,
+        "outcome": outcome,
+    }
+    if detail:
+        record["detail"] = detail
+    logger.info(json.dumps(record, default=str))

remctl/cli.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+
+import typer
+from rich.console import Console
+
+from remctl import __version__
+
+console = Console()
+err_console = Console(stderr=True)
+
+app = typer.Typer(
+    name="remctl",
+    help="Secure LAN-based remote PC control and administration",
+    no_args_is_help=True,
+)
+
+node_app = typer.Typer(help="Node agent commands")
+ctl_app = typer.Typer(help="Client/controller commands")
+app.add_typer(node_app, name="node")
+app.add_typer(ctl_app, name="ctl")
+
+
+def _version_callback(value: bool):
+    if value:
+        console.print(f"remctl v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-V",
+                                callback=_version_callback, help="Show version"),
+    debug: bool = typer.Option(False, "--debug", help="Enable debug logging"),
+):
+    if debug:
+        logging.basicConfig(level=logging.DEBUG, format="%(levelname)s %(name)s: %(message)s")
+    else:
+        logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
+
+
+# ── node subcommands ──────────────────────────────────────────────
+
+
+@node_app.command("start")
+def node_start(
+    bind: str = typer.Option("0.0.0.0", "--bind", "-b", help="Address to bind to"),
+    port: int = typer.Option(8765, "--port", "-p", help="Port to listen on"),
+):
+    """Run the node agent in the foreground"""
+    from remctl.node.daemon import run_daemon
+
+    try:
+        asyncio.run(run_daemon(bind, port))
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Node daemon stopped[/yellow]")
+
+
+@node_app.command("install-service")
+def node_install_service():
+    """Install the node as an OS service"""
+    if sys.platform == "win32":
+        from remctl.node.service_windows import install_service
+        install_service()
+    elif sys.platform == "linux":
+        from remctl.node.service_linux import install_service
+        install_service()
+    else:
+        err_console.print("[red]Service installation not supported on this platform[/red]")
+        raise typer.Exit(1)
+
+
+@node_app.command("uninstall-service")
+def node_uninstall_service():
+    """Uninstall the OS service"""
+    if sys.platform == "win32":
+        from remctl.node.service_windows import uninstall_service
+        uninstall_service()
+    elif sys.platform == "linux":
+        from remctl.node.service_linux import uninstall_service
+        uninstall_service()
+    else:
+        err_console.print("[red]Service uninstallation not supported on this platform[/red]")
+        raise typer.Exit(1)
+
+
+@node_app.command("pair")
+def node_pair(
+    show: bool = typer.Option(False, "--show", help="Show this node's fingerprint"),
+):
+    """Show node identity or manage pairing"""
+    from remctl.crypto import fingerprint, load_or_generate_keypair
+
+    _, pub = load_or_generate_keypair()
+    fp = fingerprint(pub)
+    hostname = __import__("platform").node()
+    console.print(f"Node fingerprint: [yellow]{fp}[/yellow]")
+    console.print(f"Hostname: [cyan]{hostname}[/cyan]")
+    console.print("\nTo pair a controller, run on the controller:")
+    console.print("  remctl ctl pair <node-ip>")
+
+
+@node_app.command("trust-controller")
+def node_trust_controller(
+    pubkey_source: str = typer.Argument(..., help="Public key hex string or path to .pub file"),
+):
+    """Trust a controller's public key"""
+    from remctl.ctl.pairing import trust_controller
+    trust_controller(pubkey_source)
+
+
+@node_app.command("list-controllers")
+def node_list_controllers():
+    """List trusted controllers"""
+    from remctl.ctl.pairing import list_trusted_controllers
+    list_trusted_controllers()
+
+
+# ── ctl subcommands ────────────────────────────────────────────────
+
+
+@ctl_app.command("discover")
+def ctl_discover():
+    """Discover nodes on the LAN"""
+    from remctl.ctl.commands import cmd_discover
+    cmd_discover()
+
+
+@ctl_app.command("pair")
+def ctl_pair(
+    target: str = typer.Argument(..., help="Node hostname or IP address"),
+    port: int = typer.Option(8765, "--port", "-p", help="Node port"),
+):
+    """Pair with a node (manual fingerprint confirmation)"""
+    from remctl.ctl.pairing import pair_with_node
+    asyncio.run(pair_with_node(target, port))
+
+
+@ctl_app.command("pair-show")
+def ctl_pair_show():
+    """Show this controller's fingerprint for pairing"""
+    from remctl.crypto import fingerprint, load_or_generate_keypair
+    _, pub = load_or_generate_keypair()
+    fp = fingerprint(pub)
+    console.print(f"Controller fingerprint: [yellow]{fp}[/yellow]")
+    pub_path = __import__("pathlib").Path.home() / ".remctl" / "identity.pub"
+    if pub_path.exists():
+        console.print(f"Public key file: {pub_path}")
+
+
+@ctl_app.command("lock")
+def ctl_lock(target: str):
+    """Lock the remote machine"""
+    from remctl.ctl.commands import cmd_lock
+    cmd_lock(target)
+
+
+@ctl_app.command("shutdown")
+def ctl_shutdown(
+    target: str = typer.Argument(..., help="Node target (name, IP, or fingerprint)"),
+    delay: int = typer.Option(0, "--delay", "-d", help="Delay in seconds before shutdown"),
+    force: bool = typer.Option(False, "--force", "-f", help="Force shutdown"),
+):
+    """Shut down the remote machine"""
+    from remctl.ctl.commands import cmd_shutdown
+    cmd_shutdown(target, delay, force)
+
+
+@ctl_app.command("restart")
+def ctl_restart(
+    target: str = typer.Argument(..., help="Node target"),
+    delay: int = typer.Option(0, "--delay", "-d", help="Delay in seconds"),
+):
+    """Restart the remote machine"""
+    from remctl.ctl.commands import cmd_restart
+    cmd_restart(target, delay)
+
+
+@ctl_app.command("sleep")
+def ctl_sleep(target: str):
+    """Put the remote machine to sleep"""
+    from remctl.ctl.commands import cmd_sleep
+    cmd_sleep(target)
+
+
+@ctl_app.command("logout")
+def ctl_logout(target: str):
+    """Log out the current user on the remote machine"""
+    from remctl.ctl.commands import cmd_logout
+    cmd_logout(target)
+
+
+@ctl_app.command("closefocused")
+def ctl_closefocused(target: str):
+    """Close the active/focused window on the remote machine"""
+    from remctl.ctl.commands import cmd_closefocused
+    cmd_closefocused(target)
+
+
+@ctl_app.command("cancel")
+def ctl_cancel(target: str):
+    """Cancel a pending shutdown/restart"""
+    from remctl.ctl.commands import cmd_cancel
+    cmd_cancel(target)
+
+
+@ctl_app.command("exec")
+def ctl_exec(
+    target: str = typer.Argument(..., help="Node target"),
+    command: str = typer.Argument(..., help="Shell command to execute"),
+    timeout: int = typer.Option(60, "--timeout", "-t", help="Timeout in seconds"),
+):
+    """Execute a shell command on the remote machine with streamed output"""
+    from remctl.ctl.commands import cmd_exec
+    cmd_exec(target, command, timeout)
+
+
+@ctl_app.command("screenshot")
+def ctl_screenshot(
+    target: str = typer.Argument(..., help="Node target"),
+    output: str = typer.Option("screenshot.png", "--output", "-o", help="Output file path"),
+):
+    """Capture a screenshot of the remote machine"""
+    from remctl.ctl.commands import cmd_screenshot
+    cmd_screenshot(target, output)
+
+
+@ctl_app.command("status")
+def ctl_status(target: str):
+    """Show system status of the remote machine"""
+    from remctl.ctl.commands import cmd_status
+    cmd_status(target)
+
+
+@ctl_app.command("push")
+def ctl_push(
+    target: str = typer.Argument(..., help="Node target"),
+    source: str = typer.Argument(..., help="Local source file path"),
+    dest: str = typer.Argument(..., help="Remote destination path"),
+):
+    """Push a file to the remote machine"""
+    from remctl.ctl.commands import cmd_push
+    cmd_push(target, source, dest)
+
+
+@ctl_app.command("pull")
+def ctl_pull(
+    target: str = typer.Argument(..., help="Node target"),
+    remote_path: str = typer.Argument(..., help="Remote file path"),
+    output: str = typer.Option(None, "--output", "-o", help="Local output path (defaults to filename)"),
+):
+    """Pull a file from the remote machine"""
+    from remctl.ctl.commands import cmd_pull
+    cmd_pull(target, remote_path, output)
+
+
+@ctl_app.command("known-nodes")
+def ctl_known_nodes():
+    """List paired nodes"""
+    from remctl.ctl.commands import cmd_known_nodes
+    cmd_known_nodes()

remctl/config.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+
+from pydantic import BaseModel, Field
+
+from remctl.crypto import KEY_DIR
+
+CONFIG_DIR = KEY_DIR
+NODE_CONFIG_FILE = CONFIG_DIR / "node_config.json"
+KNOWN_NODES_FILE = CONFIG_DIR / "known_nodes.json"
+KNOWN_CONTROLLERS_FILE = CONFIG_DIR / "known_controllers.json"
+
+
+PermissionTier = str | None  # "observe", "standard", "full"
+
+
+class KnownPeer(BaseModel):
+    fingerprint: str
+    pubkey_hex: str
+    hostname: str = ""
+    address: str = ""
+    port: int = 0
+    tier: str = "standard"
+
+
+class NodeConfig(BaseModel):
+    bind_address: str = "0.0.0.0"
+    port: int = 8765
+    discovery_port: int = 8766
+    controllers: list[str] = Field(default_factory=list)
+    controller_tiers: dict[str, str] = Field(default_factory=dict)
+    audit_max_bytes: int = 10 * 1024 * 1024
+    audit_backup_count: int = 5
+
+
+def _ensure_config_dir() -> None:
+    CONFIG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+
+def load_node_config() -> NodeConfig:
+    _ensure_config_dir()
+    if NODE_CONFIG_FILE.exists():
+        data = json.loads(NODE_CONFIG_FILE.read_text())
+        return NodeConfig(**data)
+    cfg = NodeConfig()
+    save_node_config(cfg)
+    return cfg
+
+
+def save_node_config(cfg: NodeConfig) -> None:
+    _ensure_config_dir()
+    NODE_CONFIG_FILE.write_text(cfg.model_dump_json(indent=2))
+
+
+def load_known_nodes() -> dict[str, KnownPeer]:
+    if KNOWN_NODES_FILE.exists():
+        data = json.loads(KNOWN_NODES_FILE.read_text())
+        return {k: KnownPeer(**v) for k, v in data.items()}
+    return {}
+
+
+def save_known_nodes(nodes: dict[str, KnownPeer]) -> None:
+    _ensure_config_dir()
+    data = {k: v.model_dump() for k, v in nodes.items()}
+    KNOWN_NODES_FILE.write_text(json.dumps(data, indent=2))
+
+
+def load_known_controllers() -> dict[str, KnownPeer]:
+    if KNOWN_CONTROLLERS_FILE.exists():
+        data = json.loads(KNOWN_CONTROLLERS_FILE.read_text())
+        return {k: KnownPeer(**v) for k, v in data.items()}
+    return {}
+
+
+def save_known_controllers(controllers: dict[str, KnownPeer]) -> None:
+    _ensure_config_dir()
+    data = {k: v.model_dump() for k, v in controllers.items()}
+    KNOWN_CONTROLLERS_FILE.write_text(json.dumps(data, indent=2))
+
+
+def get_controller_tier(fingerprint: str) -> str:
+    cfg = load_node_config()
+    return cfg.controller_tiers.get(fingerprint, "standard")

remctl/crypto.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import secrets
+from pathlib import Path
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519, x25519
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from typing import Union
+
+KEY_DIR = Path.home() / ".remctl"
+KEY_FILE = KEY_DIR / "identity.key"
+PUB_FILE = KEY_DIR / "identity.pub"
+
+
+def _ensure_key_dir() -> None:
+    KEY_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+
+def _restrict_key_permissions(path: Path) -> None:
+    try:
+        import stat
+        current = os.stat(path)
+        if current.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+            os.chmod(path, current.st_mode & ~(stat.S_IRWXG | stat.S_IRWXO))
+    except (OSError, AttributeError):
+        pass
+
+
+def generate_keypair() -> tuple[ed25519.Ed25519PrivateKey, ed25519.Ed25519PublicKey]:
+    private = ed25519.Ed25519PrivateKey.generate()
+    public = private.public_key()
+    return private, public
+
+
+def load_or_generate_keypair() -> tuple[ed25519.Ed25519PrivateKey, ed25519.Ed25519PublicKey]:
+    _ensure_key_dir()
+    if KEY_FILE.exists() and PUB_FILE.exists():
+        private = load_private_key(KEY_FILE)
+        public = load_public_key(PUB_FILE)
+        return private, public
+    private, public = generate_keypair()
+    save_keypair(private, public)
+    return private, public
+
+
+def save_keypair(private: ed25519.Ed25519PrivateKey, public: ed25519.Ed25519PublicKey) -> None:
+    _ensure_key_dir()
+    private_bytes = private.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    KEY_FILE.write_bytes(private_bytes)
+    _restrict_key_permissions(KEY_FILE)
+    public_bytes = public.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    PUB_FILE.write_bytes(public_bytes)
+
+
+def load_private_key(path: Path = KEY_FILE) -> ed25519.Ed25519PrivateKey:
+    data = path.read_bytes()
+    return ed25519.Ed25519PrivateKey.from_private_bytes(data)
+
+
+def load_public_key(path: Path = PUB_FILE) -> ed25519.Ed25519PublicKey:
+    data = path.read_bytes()
+    return ed25519.Ed25519PublicKey.from_public_bytes(data)
+
+
+def public_key_bytes(pub: Union[ed25519.Ed25519PublicKey, x25519.X25519PublicKey]) -> bytes:
+    return pub.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def fingerprint(pub: ed25519.Ed25519PublicKey) -> str:
+    raw = public_key_bytes(pub)
+    digest = hashlib.sha256(raw).digest()
+    return ":".join(f"{b:02x}" for b in digest)
+
+
+def fingerprint_from_bytes(pub_bytes: bytes) -> str:
+    digest = hashlib.sha256(pub_bytes).digest()
+    return ":".join(f"{b:02x}" for b in digest)
+
+
+def sign(data: bytes, private: ed25519.Ed25519PrivateKey) -> bytes:
+    return private.sign(data)
+
+
+def verify(data: bytes, signature: bytes, public: ed25519.Ed25519PublicKey) -> bool:
+    try:
+        public.verify(signature, data)
+        return True
+    except Exception:
+        return False
+
+
+def generate_ephemeral_keypair() -> tuple[x25519.X25519PrivateKey, x25519.X25519PublicKey]:
+    private = x25519.X25519PrivateKey.generate()
+    public = private.public_key()
+    return private, public
+
+
+def derive_session_key(
+    private_ephemeral: x25519.X25519PrivateKey,
+    peer_ephemeral: x25519.X25519PublicKey,
+    self_long_term_pub: ed25519.Ed25519PublicKey,
+    peer_long_term_pub: ed25519.Ed25519PublicKey,
+) -> bytes:
+    shared_secret = private_ephemeral.exchange(peer_ephemeral)
+    self_bytes = public_key_bytes(self_long_term_pub)
+    peer_bytes = public_key_bytes(peer_long_term_pub)
+    sorted_keys = b"".join(sorted([self_bytes, peer_bytes]))
+    info = b"remctl-session-key-v1"
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=None,
+        info=info,
+    )
+    key = hkdf.derive(shared_secret + sorted_keys)
+    return key
+
+
+class SecureChannel:
+    def __init__(self, session_key: bytes) -> None:
+        self._aesgcm = AESGCM(session_key)
+        self._seq_send = 0
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        nonce = secrets.token_bytes(12)
+        ciphertext = self._aesgcm.encrypt(nonce, plaintext, None)
+        return nonce + ciphertext
+
+    def decrypt(self, data: bytes) -> bytes:
+        if len(data) < 12:
+            raise ValueError("data too short to contain nonce")
+        nonce = data[:12]
+        ciphertext = data[12:]
+        return self._aesgcm.decrypt(nonce, ciphertext, None)

remctl/ctl/client.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric import ed25519, x25519
+
+from remctl.crypto import (
+    SecureChannel,
+    derive_session_key,
+    generate_ephemeral_keypair,
+    load_or_generate_keypair,
+    public_key_bytes,
+    sign,
+    verify,
+)
+from remctl.protocol import Command, CommandType, Frame, Handshake, ResponseChunk
+
+logger = logging.getLogger(__name__)
+
+
+class RemCtlClient:
+    def __init__(self, host: str = "127.0.0.1", port: int = 8765) -> None:
+        self.host = host
+        self.port = port
+        self._private_key, self._public_key = load_or_generate_keypair()
+        self._channel: SecureChannel | None = None
+        self._seq = 0
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+
+    async def connect(self) -> None:
+        r, w = await asyncio.wait_for(
+            asyncio.open_connection(self.host, self.port), timeout=10
+        )
+        self._reader = r
+        self._writer = w
+
+        ephemeral_private, ephemeral_public = generate_ephemeral_keypair()
+
+        hs = Handshake(
+            identity_pubkey=public_key_bytes(self._public_key),
+            ephemeral_pubkey=public_key_bytes(ephemeral_public),
+            signature=sign(public_key_bytes(ephemeral_public), self._private_key),
+        )
+        request_data = hs.model_dump_json().encode("utf-8")
+        w.write(Frame.encode(request_data))
+        await w.drain()
+
+        header = await asyncio.wait_for(
+            r.readexactly(Frame.HEADER_SIZE), timeout=10
+        )
+        length = Frame.decode_header(header)
+        response_data = await asyncio.wait_for(
+            r.readexactly(length), timeout=10
+        )
+
+        response_hs = Handshake.model_validate_json(response_data)
+
+        node_identity = ed25519.Ed25519PublicKey.from_public_bytes(
+            response_hs.identity_pubkey
+        )
+        node_ephemeral = x25519.X25519PublicKey.from_public_bytes(
+            response_hs.ephemeral_pubkey
+        )
+
+        if not verify(
+            response_hs.ephemeral_pubkey, response_hs.signature, node_identity
+        ):
+            raise ValueError("node signature verification failed")
+
+        session_key = derive_session_key(
+            ephemeral_private,
+            node_ephemeral,
+            self._public_key,
+            node_identity,
+        )
+
+        self._channel = SecureChannel(session_key)
+
+    async def send_command(
+        self, cmd: CommandType, args: dict[str, Any] | None = None
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        ch = self._channel
+        w = self._writer
+        r = self._reader
+        if ch is None or w is None or r is None:
+            raise RuntimeError("not connected")
+
+        self._seq += 1
+        command = Command(
+            seq=self._seq,
+            cmd=cmd,
+            args=args or {},
+        )
+        plaintext = command.model_dump_json().encode("utf-8")
+        encrypted = ch.encrypt(plaintext)
+        w.write(Frame.encode(encrypted))
+        await w.drain()
+
+        while True:
+            try:
+                header = await asyncio.wait_for(
+                    r.readexactly(Frame.HEADER_SIZE), timeout=300
+                )
+            except asyncio.IncompleteReadError:
+                break
+
+            length = Frame.decode_header(header)
+            encrypted_resp = await asyncio.wait_for(
+                r.readexactly(length), timeout=300
+            )
+
+            plaintext_resp = ch.decrypt(encrypted_resp)
+            chunk = ResponseChunk.model_validate_json(plaintext_resp)
+
+            result: dict[str, Any] = {
+                "seq": chunk.seq,
+                "type": chunk.type,
+                "data": chunk.data,
+            }
+            yield result
+
+            if chunk.type == "exit" or chunk.type == "error":
+                break
+
+    async def close(self) -> None:
+        if self._writer:
+            try:
+                self._writer.close()
+            except Exception:
+                pass