pyre-cli 3.0.0 → 3.2.0

package/README.md

@@ -9,7 +9,7 @@ Mac system monitoring CLI: temps, CPU, memory, disk, battery, live dashboard, pa
 
 ## Features
 
-- **P2P live data streaming** — send live system stats to another system over TCP with password authentication
+- **P2P live data streaming** — send live system stats to another system over TCP with password authentication, TLS encryption, rate limiting, IP allow/deny lists, audit logging, and HMAC message signing
 - **Real-time system stats** — CPU brand, cores, frequency, load, and usage
 - **Memory monitoring** — usage, swap, and total/available
 - **Disk space** — mounted volume usage
@@ -87,7 +87,7 @@ pyre live --interval 5 --log   # Custom interval with auto-logging
 
 ## P2P Live Data Streaming
 
-Send live system stats to another system over a TCP connection with password authentication.
+Send live system stats to another system over a TCP connection with password authentication. The server streams `StatsData` snapshots to authenticated peers at the configured interval.
 
 ### Start a P2P server (host)
 
@@ -107,6 +107,75 @@ The server binds to the specified host and port, and streams live system stats t
 | `--interval <seconds>` | Data refresh interval (default: `2`) |
 | `--detailed` | Include detailed sensor readings |
 
+### Server-Side Security Features
+
+#### TLS Encryption
+
+Enable TLS for encrypted connections between the server and clients:
+
+```bash
+pyre p2p server --p2p-cert /path/to/cert.pem --p2p-key /path/to/key.pem --p2p-password mysecret
+```
+
+| Option | Description |
+|---|---|
+| `--p2p-cert <file>` | TLS certificate file (PEM) for the server |
+| `--p2p-key <file>` | TLS private key file (PEM) for the server |
+| `--p2p-ca <file>` | TLS CA certificate file (PEM) — required by clients using `--p2p-tls` |
+
+#### Rate Limiting
+
+Prevent brute-force password attacks by limiting authentication attempts per IP:
+
+```bash
+pyre p2p server --p2p-rate-limit 10 --p2p-password mysecret
+```
+
+| Option | Description |
+|---|---|
+| `--p2p-rate-limit <n>` | Max auth attempts per IP per minute (default: `5`) |
+
+#### IP Allow/Deny Lists
+
+Restrict connections to specific IPs or block known bad actors:
+
+```bash
+# Allow only specific IPs
+pyre p2p server --p2p-allow 192.168.1.100,192.168.1.101 --p2p-password mysecret
+
+# Deny specific IPs (all others allowed)
+pyre p2p server --p2p-deny 10.0.0.99 --p2p-password mysecret
+```
+
+| Option | Description |
+|---|---|
+| `--p2p-allow <ips>` | Comma-separated list of allowed IPs (empty = all) |
+| `--p2p-deny <ips>` | Comma-separated list of denied IPs |
+
+#### Audit Logging
+
+Log all connection events (connects, auth successes/failures, disconnects, rate limit hits, IP blocks) to a directory:
+
+```bash
+pyre p2p server --p2p-audit-log /var/log/pyre --p2p-password mysecret
+```
+
+| Option | Description |
+|---|---|
+| `--p2p-audit-log <dir>` | Directory for P2P audit logs |
+
+#### HMAC Message Signing
+
+All P2P messages are signed with HMAC-SHA256 to ensure integrity and authenticity. The HMAC key is derived from the password by default, but can be overridden for rotation or interoperability:
+
+```bash
+pyre p2p server --p2p-hmac-key my-custom-key --p2p-password mysecret
+```
+
+| Option | Description |
+|---|---|
+| `--p2p-hmac-key <key>` | HMAC key for message signing (default: derived from password) |
+
 ### Connect a P2P client (peer)
 
 On the machine that will receive data:
@@ -122,23 +191,40 @@ The client connects to the server, authenticates with the password, and displays
 | `--p2p-host <host>` | Server address (default: `127.0.0.1`) |
 | `--p2p-port <port>` | Server port (default: `9876`) |
 | `--p2p-password <password>` | Password for authentication (required) |
+| `--p2p-tls` | Enable TLS encryption for the connection |
+| `--p2p-ca <file>` | TLS CA certificate file (PEM) — required when using `--p2p-tls` |
+| `--p2p-insecure` | Skip TLS certificate verification (client only) |
+| `--p2p-audit-log <dir>` | Directory for P2P client audit logs |
+| `--p2p-hmac-key <key>` | HMAC key for message signing (must match server) |
 
 ### P2P Protocol
 
-The P2P connection uses a length-prefixed JSON protocol over TCP:
+The P2P connection uses a length-prefixed JSON protocol over TCP with HMAC-SHA256 message signing:
 
 1. Client connects to the server
-2. Client sends an `auth` message with the password
-3. Server validates the password and responds with `auth-ok` or `auth-fail`
-4. Once authenticated, the server streams `data` messages containing `StatsData` snapshots at the configured interval
-5. Both sides exchange `ping`/`pong` keepalive messages every 15 seconds
-6. Either side can send a `disconnect` message to close gracefully
+2. Server sends a `challenge` message with a random nonce
+3. Client responds with an `auth` message containing the SHA-256 hash of `password:nonce`
+4. Server validates the hash and responds with `auth-ok` or `auth-fail`
+5. Once authenticated, the server streams `data` messages containing `StatsData` snapshots at the configured interval
+6. Both sides exchange `ping`/`pong` keepalive messages every 15 seconds
+7. Either side can send a `disconnect` message to close gracefully
+
+All messages are signed with HMAC-SHA256 using a key derived from the password, ensuring message integrity and authenticity.
+
+### Server Controls
+
+While the P2P server is running, type these commands on the server's stdin:
+
+| Command | Action |
+|---|---|
+| `status` | Print the number of currently connected peers |
+| `q` / `quit` / `exit` | Shut down the server gracefully |
 
-### P2P Controls
+Press `Ctrl+C` to shut down the server as well.
 
-While connected, the client displays live system stats in a formatted table. Press `Ctrl+C` to disconnect.
+### P2P Client Controls
 
-On the server, type `status` to see the number of connected peers, or `q`/`quit`/`exit` to shut down.
+While connected, the client displays live system stats in a formatted table. Press `Ctrl+C` to disconnect. The client will attempt to reconnect automatically after 3 seconds if the connection is lost.
 
 ## Live Dashboard Controls
 
@@ -249,7 +335,7 @@ pyre/
 │   │   ├── index.ts        # Public API: P2PServer, P2PClient
 │   │   ├── types.ts        # P2P protocol type definitions
 │   │   ├── protocol.ts     # Length-prefixed JSON message framing
-│   │   ├── server.ts       # TCP server that authenticates and streams stats
+│   │   ├── server.ts       # TCP server: auth, TLS, rate limiting, IP filtering, audit logging, HMAC signing, data streaming
 │   │   └── client.ts       # TCP client that connects and displays live data
 │   ├── history.ts          # Rolling history buffer for sparkline data
 │   ├── sparkline.ts        # ASCII sparkline rendering