Metadata-Version: 2.4
Name: remctl
Version: 0.1.0
Summary: Secure LAN-based remote PC control and administration
Author: remctl contributors
License: MIT
License-File: LICENSE
Keywords: administration,lan,remote-control
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Requires-Python: >=3.11
Requires-Dist: cryptography>=42
Requires-Dist: mss>=9.0
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2
Requires-Dist: pywin32>=306; sys_platform == 'win32'
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Requires-Dist: zeroconf>=0.132
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# remctl

**Secure, LAN-based remote PC control and administration.**

`remctl` lets you control machines on your local network from the command line —
lock, shutdown, execute shell commands with streaming output, transfer files,
take screenshots, and check system status. All communication is authenticated
using Ed25519 keys and encrypted with AES-256-GCM.

> ⚠️ **Intended for your own trusted LAN devices only.** `remctl` is not designed
> for Internet-facing use. Do not expose it via port forwarding or NAT.

## Installation

```bash
pip install remctl
```

### From source

```bash
# TODO: user adds PyPI API token via env var / twine config before publishing
git clone <repo-url>
cd remctl
pip install -e ".[dev]"
```

## Quick Start: Pairing Walkthrough

`remctl` requires two-way trust: both the node and the controller must explicitly
authorize each other.

### On the target machine (the node)

```bash
# Show the node's fingerprint
remctl node pair --show

# Start the agent (background via service is recommended)
remctl node start
```

### On the controlling machine

```bash
# Discover nodes on the LAN
remctl ctl discover

# Pair with a node (verify the fingerprint before confirming)
remctl ctl pair <node-ip>

# Show your own fingerprint for the node to trust you
remctl ctl pair-show
```

### Back on the node (trust the controller)

```bash
# Trust the controller's public key (copy from the controller's output)
remctl node trust-controller /path/to/controller_identity.pub
```

### Send commands

```bash
remctl ctl <target> status
remctl ctl <target> lock
remctl ctl <target> exec "whoami"
remctl ctl <target> screenshot -o screenshot.png
remctl ctl <target> push ./file.txt /remote/path/file.txt
remctl ctl <target> pull /remote/log.log ./log.log
```

## Command Reference

| Command | Description |
|---------|-------------|
| `remctl node start` | Start the node agent in foreground |
| `remctl node install-service` | Install as OS service |
| `remctl ctl discover` | Discover nodes on LAN |
| `remctl ctl pair <target>` | Pair with a node |
| `remctl ctl <target> lock` | Lock the remote workstation |
| `remctl ctl <target> shutdown --delay 60` | Shutdown with optional delay |
| `remctl ctl <target> restart` | Restart |
| `remctl ctl <target> sleep` | Sleep/Suspend |
| `remctl ctl <target> logout` | Log out current user |
| `remctl ctl <target> closefocused` | Close active window |
| `remctl ctl <target> exec <command>` | Execute shell command (streamed) |
| `remctl ctl <target> status` | Show system status (CPU/mem/disk/uptime) |
| `remctl ctl <target> screenshot -o out.png` | Capture screenshot |
| `remctl ctl <target> push <local> <remote>` | Push file to node |
| `remctl ctl <target> pull <remote> <local>` | Pull file from node |
| `remctl ctl <target> cancel` | Cancel pending shutdown/restart |

## Security Model (Summary)

- **Identity:** Ed25519 keypairs generated on first run.
- **Authentication:** Two-way explicit pairing — both sides must trust each other.
- **Encryption:** X25519 ECDH key exchange → AES-256-GCM, with forward secrecy.
- **Replay protection:** Per-message sequence numbers + 30-second timestamp window.
- **Permission tiers:** `observe` (status/screenshot), `standard` (commands +
  files), `full` (includes `exec`). Default: `standard`.
- **Audit log:** All commands logged unredacted at `~/.remctl/audit.log`.

See [docs/SECURITY.md](docs/SECURITY.md) for the full threat model.

## Configuration

All config files live in `~/.remctl/`:

| File | Purpose |
|------|---------|
| `identity.key` | Private key (keep secure) |
| `identity.pub` | Public key |
| `known_nodes.json` | Paired nodes (ctl side) |
| `known_controllers.json` | Trusted controllers (node side) |
| `node_config.json` | Node settings (bind address, port, tiers) |
| `audit.log` | Command audit log |

## Platform Support

| Platform | Status |
|----------|--------|
| Windows | First-class |
| Linux | Second-class (best-effort) |
| macOS | Not yet implemented |

## Publishing to PyPI

```bash
python -m build
twine upload dist/*
```

> The user must configure `~/.pypirc` or set `TWINE_USERNAME`/`TWINE_PASSWORD`
> environment variables before running `twine upload`. No credentials are
> included in this repository.
