broodlink 0.1.2

package/docs/TLS_DEPLOYMENT.md

@@ -0,0 +1,150 @@
+# TLS Deployment Guide
+
+BroodLink uses plain WebSocket (`ws://`) by default. **For any deployment beyond localhost, you must add TLS encryption** to protect API keys and messages in transit.
+
+---
+
+## Option 1: Reverse Proxy (Recommended)
+
+Use nginx, Caddy, or similar to terminate TLS in front of BroodLink.
+
+### Caddy (Automatic HTTPS)
+
+The simplest option — Caddy auto-provisions certificates via Let's Encrypt.
+
+```
+# /etc/caddy/Caddyfile
+broodlink.example.com {
+    reverse_proxy 127.0.0.1:18800
+}
+```
+
+Agents connect to `wss://broodlink.example.com`.
+
+### nginx
+
+```nginx
+# /etc/nginx/sites-available/broodlink
+upstream broodlink {
+    server 127.0.0.1:18800;
+}
+
+server {
+    listen 443 ssl;
+    server_name broodlink.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/broodlink.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/broodlink.example.com/privkey.pem;
+
+    # Modern TLS configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers off;
+
+    location / {
+        proxy_pass http://broodlink;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+    }
+}
+
+# Redirect HTTP → HTTPS
+server {
+    listen 80;
+    server_name broodlink.example.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
+Generate certificates with [certbot](https://certbot.eff.org/):
+
+```bash
+sudo certbot certonly --nginx -d broodlink.example.com
+```
+
+---
+
+## Option 2: Tailscale (Zero-Config Private Network)
+
+BroodLink has built-in Tailscale support for private networking without certificate management.
+
+```jsonc
+// broodlink.json
+{
+  "host": "127.0.0.1",
+  "port": 18800,
+  "tailscale": {
+    "enabled": true,
+    "interfaceName": "tailscale0"
+  }
+}
+```
+
+Traffic between Tailscale nodes is encrypted with WireGuard. Agents connect using the Tailscale hostname (e.g., `ws://broodlink-server:18800`).
+
+> **Note:** This uses `ws://` (not `wss://`) because WireGuard already encrypts the tunnel. The connection is private to your tailnet.
+
+---
+
+## Configuration for Production
+
+When deploying behind a reverse proxy, bind to localhost only:
+
+```jsonc
+// broodlink.json
+{
+  "host": "127.0.0.1",
+  "port": 18800
+}
+```
+
+This prevents direct access to the unencrypted WebSocket port.
+
+### Checklist
+
+- [ ] BroodLink bound to `127.0.0.1` (not `0.0.0.0`)
+- [ ] TLS proxy configured with valid certificate
+- [ ] HTTP → HTTPS redirect enabled
+- [ ] WebSocket upgrade headers (`Upgrade`, `Connection`) forwarded
+- [ ] Proxy timeouts set high enough for long-lived connections (~24h)
+- [ ] Firewall blocks direct access to BroodLink port (18800)
+- [ ] Agents configured to connect via `wss://` endpoint
+
+---
+
+## Agent Connection
+
+Agents should connect to the TLS endpoint:
+
+```javascript
+// Instead of:
+const ws = new WebSocket("ws://localhost:18800");
+
+// Use:
+const ws = new WebSocket("wss://broodlink.example.com");
+```
+
+No protocol changes — the JSON-RPC API works identically over `ws://` and `wss://`.
+
+---
+
+## Self-Signed Certificates (Development Only)
+
+For development environments where you need TLS but don't have a domain:
+
+```bash
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout broodlink.key -out broodlink.crt \
+  -subj "/CN=localhost"
+```
+
+Use these with your reverse proxy. Agents may need to disable certificate verification (development only — never in production).
+
+---
+
+*For questions or issues, open a GitHub issue or contact the project maintainer.*

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "broodlink",
+    "version": "0.1.2",
+    "description": "Standalone WebSocket chat server for AI agent communication",
+    "type": "module",
+    "main": "dist/index.js",
+    "bin": {
+        "broodlink": "dist/cli.js"
+    },
+    "files": [
+        "dist/",
+        "docs/",
+        "README.md",
+        "INSTALL.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build",
+        "dev": "tsx src/cli.ts",
+        "start": "node dist/cli.js",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "better-sqlite3": "^11.8.1",
+        "commander": "^14.0.3",
+        "ws": "^8.19.0"
+    },
+    "devDependencies": {
+        "@types/better-sqlite3": "^7.6.13",
+        "@types/node": "^22.12.0",
+        "@types/ws": "^8.18.1",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.18"
+    },
+    "engines": {
+        "node": ">=22.0.0"
+    }
+}