tunnelmate 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# tunnelme
+
+Reverse-proxies a public domain to a localhost port, for dev/testing — a small
+self-hosted alternative to ngrok, built for your own domain + your own box.
+
+## How it works
+
+Two pieces, both in this one CLI:
+
+- **`tunnelme serve`** — runs on the internet-facing machine (in your case: the
+  machine your router forwards ports 80/443 to). Terminates TLS using
+  automatically-provisioned Let's Encrypt certificates, chosen by SNI per
+  domain, and relays raw bytes to whichever client registered that domain.
+- **`tunnelme`** (a.k.a. `tunnelme run`) — the client. Connects out to the
+  server's control channel, registers a domain, and forwards traffic to
+  `localhost:<port>`.
+
+The server never parses HTTP itself — it just forwards decrypted TLS bytes
+through to the client, which hands them to your local app. That means it
+transparently supports HTTP/1.1 keep-alive, WebSocket upgrades (HMR, etc.),
+anything TCP-based — not just plain request/response.
+
+## Install (global, callable from anywhere)
+
+Once published to npm (package name `tunnelmate`, command stays `tunnelme`):
+
+```powershell
+npm install -g tunnelmate
+```
+
+For local development against this source tree instead:
+
+```powershell
+cd C:\codes\tunnel
+npm install
+npm link
+```
+
+Either way, `tunnelme` ends up on your PATH. Test with `tunnelme --version`
+from any directory.
+
+## One-time setup on your machine
+
+Since your router already forwards TCP 80 and 443 to this machine, and your
+DNS is already pointed at your static IP, you just need to run the server
+component here:
+
+```powershell
+# Run as Administrator (binding ports 80/443 on Windows requires elevation)
+tunnelme serve --tls acme --email you@example.com
+```
+
+Defaults: HTTP on :80, HTTPS on :443, control channel on :7000 (localhost
+only — do **not** forward 7000 through your router; it's for your dev
+machines to reach, not the public internet).
+
+Make sure Windows Firewall allows inbound on 80/443 (and 7000 if your client
+runs on a different LAN machine).
+
+Certificates are cached under `~/.tunnelme/certs` and auto-renew (checked
+whenever a domain is used, renewed once inside 30 days of expiry).
+
+**First run for a new domain**: Let's Encrypt requires your domain's A record
+to already resolve to your static IP, and port 80 to be reachable from the
+internet (used for the HTTP-01 challenge) — both of which you already have.
+If you want to test the flow without hitting Let's Encrypt's rate limits,
+add `--staging` first, then drop it once it's working end-to-end.
+
+## Expose a local dev server
+
+If your app and `serve` run on the **same machine**, skip the second
+terminal entirely by passing `--port`/`--url` straight to `serve` — it starts
+the server and the tunnel together in one process:
+
+```powershell
+tunnelme serve --tls acme --email you@example.com --port 3000 --url app.example.com
+```
+
+(`--config <path>` works here too, for multiple tunnels — see below.)
+
+If your app runs on a **different machine**, run `serve` there once, then run
+the client separately wherever the app lives:
+
+```powershell
+tunnelme --port 3000 --url app.example.com --server ws://192.168.1.50:7000
+```
+
+(`--server` points at whichever machine is running `serve`; use `localhost`
+if they're the same box, or its LAN IP otherwise.)
+
+Visit `https://app.example.com` — it now proxies to `localhost:3000`.
+
+## Multiple routes via config file
+
+`tunnels.yaml`:
+
+```yaml
+server: ws://localhost:7000
+token: some-shared-secret   # optional, must match `serve --token`
+tunnels:
+  - port: 3000
+    url: app.example.com
+  - port: 8080
+    url: api.example.com
+  - port: 5173
+    url: admin.example.com
+```
+
+```powershell
+tunnelme --config .\tunnels.yaml
+```
+
+All tunnels share one control connection and reconnect automatically if it
+drops.
+
+## Securing the control channel
+
+Anyone who can reach the control port (7000) can register a domain and start
+receiving its traffic. If more than just you can reach it on your LAN, set a
+shared secret:
+
+```powershell
+tunnelme serve --token "long-random-string" ...
+tunnelme --port 3000 --url app.example.com --token "long-random-string"
+```
+
+## Diagnostics
+
+**Request logging** — `tunnelme serve` logs every request it sees on both
+:80 and :443 (method, path, remote address, domain), plus connection
+open/close events. Useful for confirming traffic is actually reaching the
+tunnel server at all before worrying about your local app.
+
+**`GET /host/live`** — every registered domain answers this path directly
+from the tunnel server itself, without forwarding to your local app:
+
+```powershell
+curl https://app.example.com/host/live
+# {"live":true,"domain":"app.example.com","checkedAt":"..."}
+```
+
+This proves DNS + port-forwarding + TLS + an actively-connected client are
+all working, independent of whether your local app is up — handy for
+isolating "is the tunnel broken" from "is my app broken".
+
+## Running `serve` continuously
+
+For a long-running setup, run it under a process manager so it survives
+reboots/crashes, e.g. [pm2](https://pm2.keymetrics.io/) or NSSM as a Windows
+service:
+
+```powershell
+npm install -g pm2
+pm2 start tunnelme --name tunnelme-server -- serve --tls acme --email you@example.com
+```
+
+## CLI reference
+
+```
+tunnelme --port <port> --url <domain> [--server <ws-url>] [--token <token>]
+tunnelme --config <path> [--server <ws-url>] [--token <token>]
+tunnelme serve [--http-port 80] [--https-port 443] [--control-port 7000]
+               [--tls acme|self-signed] [--email <email>] [--staging]
+               [--certs-dir <path>] [--token <token>]
+               [--port <port> --url <domain>] [--config <path>]
+```
+
+The last line of `serve`'s options is optional: pass `--port`/`--url` (or
+`--config`) to also run a local tunnel in the same process, against the
+server's own control port — one terminal instead of two, when both run on
+the same machine.

package/bin/tunnelme.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const { Command } = require('commander');
+const { loadConfig } = require('../src/config');
+const { startClient } = require('../src/client');
+const { startServer } = require('../src/server');
+
+const program = new Command();
+
+program
+  .name('tunnelme')
+  .description('Reverse-proxy a public domain to a localhost port, for dev/testing.')
+  .version(require('../package.json').version);
+
+program
+  .command('run', { isDefault: true })
+  .description('Start the client: expose a local port under a public domain')
+  .option('-p, --port <port>', 'local port to expose', (v) => parseInt(v, 10))
+  .option('-u, --url <domain>', 'public domain to route to the local port')
+  .option('-c, --config <path>', 'config file with multiple tunnels (.yaml/.json)')
+  .option('-s, --server <url>', 'tunnelme server control address')
+  .option('-t, --token <token>', 'shared secret expected by the server')
+  .action((opts) => {
+    const DEFAULT_SERVER = 'ws://localhost:7000';
+    let serverUrl;
+    let token = opts.token || null;
+    let tunnels;
+
+    if (opts.config) {
+      const cfg = loadConfig(opts.config);
+      serverUrl = opts.server || cfg.server || DEFAULT_SERVER;
+      token = opts.token || cfg.token || null;
+      tunnels = cfg.tunnels.map((t) => ({ port: t.port, domain: t.url }));
+    } else {
+      serverUrl = opts.server || DEFAULT_SERVER;
+      if (opts.port === undefined || Number.isNaN(opts.port) || !opts.url) {
+        console.error('Error: --port and --url are required (or pass --config)');
+        process.exit(1);
+      }
+      tunnels = [{ port: opts.port, domain: opts.url }];
+    }
+
+    startClient({ serverUrl, token, tunnels });
+  });
+
+program
+  .command('serve')
+  .description('Start the tunnel server (run this on the internet-facing machine)')
+  .option('--http-port <port>', 'plain HTTP port (ACME challenges + redirect)', (v) => parseInt(v, 10), 80)
+  .option('--https-port <port>', 'public HTTPS entrypoint', (v) => parseInt(v, 10), 443)
+  .option('--control-port <port>', 'control channel port for clients to connect to', (v) => parseInt(v, 10), 7000)
+  .option('--certs-dir <path>', 'where to store certificates', path.join(os.homedir(), '.tunnelme', 'certs'))
+  .option('--tls <mode>', 'acme (Let\'s Encrypt) or self-signed', 'acme')
+  .option('--email <email>', 'contact email for Let\'s Encrypt')
+  .option('--staging', 'use Let\'s Encrypt staging directory (for testing)', false)
+  .option('-t, --token <token>', 'require clients to present this shared secret')
+  .option('-p, --port <port>', 'also run a local tunnel: local port to expose', (v) => parseInt(v, 10))
+  .option('-u, --url <domain>', 'also run a local tunnel: public domain for --port')
+  .option('-c, --config <path>', 'also run local tunnel(s) from a config file (.yaml/.json)')
+  .action((opts) => {
+    if (opts.tls === 'acme' && !opts.email) {
+      console.error('Error: --email is required when --tls=acme (Let\'s Encrypt requires a contact email)');
+      process.exit(1);
+    }
+    if ((opts.port !== undefined) !== Boolean(opts.url)) {
+      console.error('Error: --port and --url must be used together');
+      process.exit(1);
+    }
+
+    const { controlHttp } = startServer({
+      httpPort: opts.httpPort,
+      httpsPort: opts.httpsPort,
+      controlPort: opts.controlPort,
+      certsDir: opts.certsDir,
+      tlsMode: opts.tls,
+      acmeEmail: opts.email,
+      staging: opts.staging,
+      token: opts.token || null,
+    });
+
+    // Optionally also run the client in this same process, against the
+    // server's own control port, so `serve` + a tunnel can run from one
+    // terminal instead of two. Wait for the control channel to actually be
+    // listening first, so the client's first connection attempt doesn't race it.
+    if (opts.config || opts.port !== undefined) {
+      controlHttp.once('listening', () => {
+        if (opts.config) {
+          const cfg = loadConfig(opts.config);
+          startClient({
+            serverUrl: `ws://localhost:${opts.controlPort}`,
+            token: opts.token || cfg.token || null,
+            tunnels: cfg.tunnels.map((t) => ({ port: t.port, domain: t.url })),
+          });
+        } else {
+          startClient({
+            serverUrl: `ws://localhost:${opts.controlPort}`,
+            token: opts.token || null,
+            tunnels: [{ port: opts.port, domain: opts.url }],
+          });
+        }
+      });
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "tunnelmate",
+  "version": "0.1.0",
+  "description": "Reverse-proxy a public domain to a localhost port, for dev/testing.",
+  "license": "MIT",
+  "type": "commonjs",
+  "keywords": [
+    "tunnel",
+    "reverse-proxy",
+    "localhost",
+    "ngrok",
+    "dev-server",
+    "self-hosted"
+  ],
+  "bin": {
+    "tunnelme": "bin/tunnelme.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "acme-client": "^5.4.0",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0",
+    "selfsigned": "^2.4.1",
+    "ws": "^8.18.0"
+  }
+}

package/src/certStore.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const tls = require('tls');
+const acme = require('acme-client');
+const selfsigned = require('selfsigned');
+
+const LETS_ENCRYPT_PROD = 'https://acme-v02.api.letsencrypt.org/directory';
+const LETS_ENCRYPT_STAGING = 'https://acme-v02.api.letsencrypt.org/directory'.replace('acme-v02', 'acme-staging-v02');
+
+const RENEW_WITHIN_MS = 30 * 24 * 60 * 60 * 1000; // renew if <30 days left
+
+class CertStore {
+  /**
+   * @param {object} opts
+   * @param {string} opts.certsDir directory to persist certs/account key
+   * @param {'acme'|'self-signed'} opts.mode
+   * @param {string} [opts.acmeEmail] contact email for Let's Encrypt account
+   * @param {boolean} [opts.staging] use LE staging directory (for testing, no rate limits)
+   */
+  constructor(opts) {
+    this.certsDir = opts.certsDir;
+    this.mode = opts.mode;
+    this.acmeEmail = opts.acmeEmail;
+    this.staging = !!opts.staging;
+
+    this.cache = new Map(); // domain -> { ctx, expiresAt }
+    this.pending = new Map(); // domain -> Promise<ctx>
+    this.challenges = new Map(); // token -> keyAuthorization
+    this._acmeClient = null;
+
+    fs.mkdirSync(this.certsDir, { recursive: true });
+  }
+
+  domainDir(domain) {
+    return path.join(this.certsDir, domain);
+  }
+
+  loadFromDisk(domain) {
+    const dir = this.domainDir(domain);
+    const certPath = path.join(dir, 'cert.pem');
+    const keyPath = path.join(dir, 'key.pem');
+    if (!fs.existsSync(certPath) || !fs.existsSync(keyPath)) return null;
+
+    const cert = fs.readFileSync(certPath, 'utf8');
+    const key = fs.readFileSync(keyPath, 'utf8');
+    const expiresAt = this._certExpiry(cert);
+    return { cert, key, expiresAt };
+  }
+
+  saveToDisk(domain, { cert, key }) {
+    const dir = this.domainDir(domain);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'cert.pem'), cert, { mode: 0o644 });
+    fs.writeFileSync(path.join(dir, 'key.pem'), key, { mode: 0o600 });
+  }
+
+  _certExpiry(certPem) {
+    try {
+      const cert = new (require('crypto').X509Certificate)(certPem);
+      return new Date(cert.validTo).getTime();
+    } catch {
+      return 0;
+    }
+  }
+
+  /** Returns a tls.SecureContext for the given domain, provisioning/renewing as needed. */
+  async getSecureContext(domain) {
+    const cached = this.cache.get(domain);
+    if (cached && cached.expiresAt - Date.now() > RENEW_WITHIN_MS) {
+      return cached.ctx;
+    }
+
+    const fromDisk = this.loadFromDisk(domain);
+    if (fromDisk && fromDisk.expiresAt - Date.now() > RENEW_WITHIN_MS) {
+      const ctx = tls.createSecureContext({ cert: fromDisk.cert, key: fromDisk.key });
+      this.cache.set(domain, { ctx, expiresAt: fromDisk.expiresAt });
+      return ctx;
+    }
+
+    if (this.pending.has(domain)) return this.pending.get(domain);
+
+    const provisioning = this._provision(domain)
+      .then(({ cert, key }) => {
+        this.saveToDisk(domain, { cert, key });
+        const ctx = tls.createSecureContext({ cert, key });
+        this.cache.set(domain, { ctx, expiresAt: this._certExpiry(cert) });
+        this.pending.delete(domain);
+        return ctx;
+      })
+      .catch((err) => {
+        this.pending.delete(domain);
+        throw err;
+      });
+
+    this.pending.set(domain, provisioning);
+    return provisioning;
+  }
+
+  async _provision(domain) {
+    if (this.mode === 'self-signed') return this._provisionSelfSigned(domain);
+    return this._provisionAcme(domain);
+  }
+
+  _provisionSelfSigned(domain) {
+    const attrs = [{ name: 'commonName', value: domain }];
+    const pems = selfsigned.generate(attrs, {
+      days: 365,
+      keySize: 2048,
+      extensions: [
+        { name: 'basicConstraints', cA: false },
+        { name: 'subjectAltName', altNames: [{ type: 2, value: domain }] },
+      ],
+    });
+    return { cert: pems.cert, key: pems.private };
+  }
+
+  async _getAcmeClient() {
+    if (this._acmeClient) return this._acmeClient;
+
+    const accountKeyPath = path.join(this.certsDir, 'account-key.pem');
+    let accountKey;
+    if (fs.existsSync(accountKeyPath)) {
+      accountKey = fs.readFileSync(accountKeyPath);
+    } else {
+      accountKey = await acme.forge.createPrivateKey();
+      fs.writeFileSync(accountKeyPath, accountKey, { mode: 0o600 });
+    }
+
+    this._acmeClient = new acme.Client({
+      directoryUrl: this.staging ? LETS_ENCRYPT_STAGING : LETS_ENCRYPT_PROD,
+      accountKey,
+    });
+    return this._acmeClient;
+  }
+
+  async _provisionAcme(domain) {
+    const client = await this._getAcmeClient();
+    const [key, csr] = await acme.forge.createCsr({ commonName: domain });
+
+    let cert;
+    try {
+      cert = await client.auto({
+        csr,
+        email: this.acmeEmail,
+        termsOfServiceAgreed: true,
+        challengePriority: ['http-01'],
+        challengeCreateFn: async (authz, challenge, keyAuthorization) => {
+          if (challenge.type !== 'http-01') return;
+          this.challenges.set(challenge.token, keyAuthorization);
+        },
+        challengeRemoveFn: async (authz, challenge) => {
+          this.challenges.delete(challenge.token);
+        },
+      });
+    } catch (err) {
+      // acme-client's retry logic has a known bug: a pure network failure
+      // (no HTTP response at all) talking to Let's Encrypt, after retries
+      // are exhausted, throws this exact confusing TypeError instead of the
+      // real network error. Surface a clearer, actionable message instead.
+      if (err instanceof TypeError && /reading 'config'/.test(err.message)) {
+        throw new Error(
+          `Failed to reach Let's Encrypt while requesting a certificate for ${domain} ` +
+            "(a network-level failure was hidden by a bug in the acme-client library). " +
+            'Check outbound internet access from this machine to acme-v02.api.letsencrypt.org, ' +
+            'and that inbound port 80 is reachable from the internet for the HTTP-01 challenge ' +
+            '(Let\'s Encrypt must be able to fetch http://' +
+            domain +
+            '/.well-known/acme-challenge/... from outside your network). Then try again.'
+        );
+      }
+      throw err;
+    }
+
+    return { cert: cert.toString(), key: key.toString() };
+  }
+
+  /** Used by the plain :80 server to answer ACME http-01 challenge requests. */
+  getChallengeResponse(token) {
+    return this.challenges.get(token) || null;
+  }
+}
+
+module.exports = { CertStore };

package/src/client.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const net = require('net');
+const WebSocket = require('ws');
+const { createWebSocketStream } = require('ws');
+const { log, pipeBidirectional, describeError } = require('./util');
+
+const RECONNECT_DELAYS_MS = [1000, 2000, 5000, 10000, 15000];
+
+/**
+ * @param {object} opts
+ * @param {string} opts.serverUrl e.g. "ws://localhost:7000"
+ * @param {string|null} opts.token
+ * @param {{port:number, domain:string}[]} opts.tunnels
+ */
+function startClient(opts) {
+  const { serverUrl, token = null, tunnels } = opts;
+  const portByDomain = new Map(tunnels.map((t) => [t.domain, t.port]));
+
+  let attempt = 0;
+  let stopped = false;
+  let currentWs = null;
+
+  function connect() {
+    if (stopped) return;
+    const ws = new WebSocket(`${serverUrl}/_tunnelme/control`);
+    currentWs = ws;
+
+    ws.on('open', () => {
+      attempt = 0;
+      log('connected to tunnel server, registering...');
+      ws.send(
+        JSON.stringify({
+          type: 'register',
+          token,
+          tunnels: tunnels.map((t) => ({ domain: t.domain, port: t.port })),
+        })
+      );
+    });
+
+    ws.on('message', (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+
+      if (msg.type === 'registered') {
+        if (!Array.isArray(msg.domains)) return;
+        for (const domain of msg.domains) {
+          const port = portByDomain.get(domain);
+          log(`tunnel active: https://${domain} -> localhost:${port}`);
+        }
+      } else if (msg.type === 'error') {
+        log('server error:', msg.message);
+      } else if (msg.type === 'conn') {
+        handleConnRequest(msg.id, msg.domain);
+      }
+    });
+
+    ws.on('close', () => {
+      if (stopped) return;
+      log('disconnected from tunnel server, reconnecting...');
+      scheduleReconnect();
+    });
+
+    ws.on('error', (err) => {
+      log('control connection error:', describeError(err));
+    });
+  }
+
+  function scheduleReconnect() {
+    if (stopped) return;
+    const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
+    attempt += 1;
+    setTimeout(connect, delay);
+  }
+
+  function handleConnRequest(id, domain) {
+    const port = portByDomain.get(domain);
+    if (!port) return;
+
+    const dataWs = new WebSocket(`${serverUrl}/_tunnelme/data?id=${encodeURIComponent(id)}`);
+
+    dataWs.on('open', () => {
+      const dataStream = createWebSocketStream(dataWs, { decodeStrings: false });
+      const localSocket = net.connect(port, 'localhost');
+      pipeBidirectional(localSocket, dataStream);
+    });
+
+    dataWs.on('error', (err) => {
+      log(`data connection error for ${domain}:`, describeError(err));
+    });
+  }
+
+  connect();
+
+  return {
+    stop() {
+      stopped = true;
+      if (currentWs) currentWs.close();
+    },
+  };
+}
+
+module.exports = { startClient };

package/src/config.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Loads a tunnelme config file (.yaml/.yml/.json).
+ * Shape:
+ * {
+ *   server: "ws://localhost:7000",   // control-channel address of `tunnelme serve`
+ *   token: "shared-secret",           // optional, must match server --token
+ *   tunnels: [ { port: 3000, url: "app.example.com" }, ... ]
+ * }
+ */
+function loadConfig(configPath) {
+  const resolved = path.resolve(configPath);
+  const raw = fs.readFileSync(resolved, 'utf8');
+  const ext = path.extname(resolved).toLowerCase();
+
+  const data = ext === '.json' ? JSON.parse(raw) : yaml.load(raw);
+
+  if (!data || typeof data !== 'object') {
+    throw new Error(`Config file ${resolved} did not parse to an object`);
+  }
+  if (!Array.isArray(data.tunnels) || data.tunnels.length === 0) {
+    throw new Error(`Config file ${resolved} must define a non-empty "tunnels" array`);
+  }
+  for (const [i, t] of data.tunnels.entries()) {
+    if (t.port === undefined || t.port === null || !t.url) {
+      throw new Error(`tunnels[${i}] must have both "port" and "url"`);
+    }
+  }
+  return data;
+}
+
+module.exports = { loadConfig };

package/src/server.js

@@ -0,0 +1,240 @@
+'use strict';
+
+const http = require('http');
+const tls = require('tls');
+const crypto = require('crypto');
+const { WebSocketServer, WebSocket, createWebSocketStream } = require('ws');
+const { CertStore } = require('./certStore');
+const { log, secureCompare, pipeBidirectional, logRequestLines } = require('./util');
+
+const CONN_WAIT_TIMEOUT_MS = 15000;
+const LIVE_CHECK_PATH = '/host/live';
+const LIVE_CHECK_LINE_RE = /^(GET|HEAD) \/host\/live(\?\S*)? HTTP\/\d\.\d\r?$/;
+
+function liveCheckBody(domain) {
+  return JSON.stringify({ live: true, domain, checkedAt: new Date().toISOString() });
+}
+
+function startServer(opts) {
+  const {
+    httpPort = 80,
+    httpsPort = 443,
+    controlPort = 7000,
+    certsDir,
+    tlsMode = 'acme', // 'acme' | 'self-signed'
+    acmeEmail,
+    staging = false,
+    token = null,
+  } = opts;
+
+  const certStore = new CertStore({ certsDir, mode: tlsMode, acmeEmail, staging });
+
+  /** @type {Map<string, WebSocket>} domain -> control connection */
+  const domainClients = new Map();
+  /** @type {Map<string, {resolve: Function, reject: Function, timer: NodeJS.Timeout}>} */
+  const pendingConns = new Map();
+
+  // ---- Control + data WebSocket server (LAN/localhost only, not internet-exposed) ----
+  const controlHttp = http.createServer((req, res) => {
+    res.writeHead(200, { 'content-type': 'text/plain' });
+    res.end('tunnelme control channel\n');
+  });
+  const wss = new WebSocketServer({ noServer: true });
+
+  controlHttp.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url, 'http://internal');
+    if (url.pathname === '/_tunnelme/control') {
+      wss.handleUpgrade(req, socket, head, (ws) => handleControlConnection(ws));
+    } else if (url.pathname === '/_tunnelme/data') {
+      const id = url.searchParams.get('id');
+      wss.handleUpgrade(req, socket, head, (ws) => handleDataConnection(ws, id));
+    } else {
+      socket.destroy();
+    }
+  });
+
+  function handleControlConnection(ws) {
+    const ownedDomains = new Set();
+
+    ws.on('message', (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+
+      if (msg.type === 'register') {
+        if (token && !secureCompare(msg.token || '', token)) {
+          ws.send(JSON.stringify({ type: 'error', message: 'invalid token' }));
+          ws.close();
+          return;
+        }
+        if (!Array.isArray(msg.tunnels)) {
+          ws.send(JSON.stringify({ type: 'error', message: '"tunnels" must be an array' }));
+          return;
+        }
+        const registered = [];
+        for (const t of msg.tunnels) {
+          if (!t || !t.domain || t.port === undefined || t.port === null) continue;
+          domainClients.set(t.domain, ws);
+          ownedDomains.add(t.domain);
+          registered.push(t.domain);
+          log(`registered ${t.domain} -> client's localhost:${t.port}`);
+        }
+        ws.send(JSON.stringify({ type: 'registered', domains: registered }));
+      }
+    });
+
+    ws.on('close', () => {
+      for (const domain of ownedDomains) {
+        if (domainClients.get(domain) === ws) {
+          domainClients.delete(domain);
+          log(`unregistered ${domain}`);
+        }
+      }
+    });
+
+    ws.on('error', () => {});
+  }
+
+  function handleDataConnection(ws, id) {
+    const pending = pendingConns.get(id);
+    if (!pending) {
+      ws.close();
+      return;
+    }
+    pendingConns.delete(id);
+    clearTimeout(pending.timer);
+    pending.resolve(createWebSocketStream(ws, { decodeStrings: false }));
+  }
+
+  /** Ask the owning client to open a data connection for `domain`; resolves to a duplex stream. */
+  function requestProxyConnection(domain) {
+    const ws = domainClients.get(domain);
+    if (!ws || ws.readyState !== WebSocket.OPEN) return Promise.reject(new Error('no client connected for domain'));
+
+    const id = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingConns.delete(id);
+        reject(new Error('timed out waiting for client data connection'));
+      }, CONN_WAIT_TIMEOUT_MS);
+
+      pendingConns.set(id, { resolve, reject, timer });
+      ws.send(JSON.stringify({ type: 'conn', id, domain }));
+    });
+  }
+
+  // ---- Plain :80 server: ACME http-01 challenges + redirect to https ----
+  const httpServer = http.createServer((req, res) => {
+    const remote = `${req.socket.remoteAddress}:${req.socket.remotePort}`;
+    log(`${remote} -> ${req.headers.host || '(no host)'} ${req.method} ${req.url}`);
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    if (url.pathname.startsWith('/.well-known/acme-challenge/')) {
+      const token_ = url.pathname.split('/').pop();
+      const keyAuth = certStore.getChallengeResponse(token_);
+      if (keyAuth) {
+        res.writeHead(200, { 'content-type': 'text/plain' });
+        res.end(keyAuth);
+        return;
+      }
+      res.writeHead(404);
+      res.end('not found');
+      return;
+    }
+    const host = (req.headers.host || '').split(':')[0];
+    if (!domainClients.has(host)) {
+      res.writeHead(404);
+      res.end('not found');
+      return;
+    }
+    if (url.pathname === LIVE_CHECK_PATH) {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(liveCheckBody(host));
+      return;
+    }
+    const portSuffix = httpsPort === 443 ? '' : `:${httpsPort}`;
+    res.writeHead(301, { location: `https://${host}${portSuffix}${req.url}` });
+    res.end();
+  });
+
+  // ---- TLS :443 server: SNI-routed, only for registered domains. Raw byte
+  // forwarding only -- no HTTP parsing here, so HTTP/1.1, keep-alive and
+  // WebSocket upgrades all pass through transparently to the client's local app. ----
+  const httpsServer = tls.createServer(
+    {
+      SNICallback: (servername, cb) => {
+        if (!domainClients.has(servername)) {
+          cb(new Error(`unknown domain: ${servername}`));
+          return;
+        }
+        certStore
+          .getSecureContext(servername)
+          .then((ctx) => cb(null, ctx))
+          .catch((err) => {
+            log(`cert error for ${servername}:`, err.message);
+            cb(err);
+          });
+      },
+    },
+    (tlsSocket) => {
+      const domain = tlsSocket.servername;
+      if (!domain || !domainClients.has(domain)) {
+        tlsSocket.destroy();
+        return;
+      }
+      proxyRawConnection(tlsSocket, domain);
+    }
+  );
+
+  httpsServer.on('tlsClientError', () => {});
+
+  function proxyRawConnection(socket, domain) {
+    const remote = `${socket.remoteAddress}:${socket.remotePort}`;
+    log(`connection from ${remote} for ${domain}`);
+    socket.on('close', () => log(`connection closed from ${remote} for ${domain}`));
+
+    // Peek at the first chunk to catch the /host/live health check, which the
+    // server answers directly (proves the tunnel is reachable without needing
+    // the local app to be up). Anything else is pushed back with unshift()
+    // and proxied exactly as before. pause()+unshift() happen synchronously
+    // within this handler so no bytes are lost between the peek and the retry.
+    socket.once('data', (chunk) => {
+      const firstLine = chunk.toString('latin1').split('\r\n', 1)[0];
+      if (LIVE_CHECK_LINE_RE.test(firstLine)) {
+        log(`${remote} -> ${domain} GET ${LIVE_CHECK_PATH} (answered by tunnelme server)`);
+        const body = liveCheckBody(domain);
+        socket.end(
+          `HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: ${Buffer.byteLength(body)}\r\nconnection: close\r\n\r\n${body}`
+        );
+        return;
+      }
+      socket.pause();
+      socket.unshift(chunk);
+      forwardToClient(socket, domain, remote);
+    });
+  }
+
+  async function forwardToClient(socket, domain, remote) {
+    try {
+      // Wait for the client's data connection before attaching any 'data'
+      // consumer -- attaching one earlier would switch the socket into
+      // flowing mode and could drop bytes that arrive before pipe() is wired up.
+      const dataStream = await requestProxyConnection(domain);
+      logRequestLines(socket, `${remote} -> ${domain}`);
+      pipeBidirectional(socket, dataStream);
+    } catch (err) {
+      log(`proxy failed for ${domain}:`, err.message);
+      socket.destroy();
+    }
+  }
+
+  controlHttp.listen(controlPort, () => log(`control channel listening on ws://0.0.0.0:${controlPort}`));
+  httpServer.listen(httpPort, () => log(`http (acme + redirect) listening on :${httpPort}`));
+  httpsServer.listen(httpsPort, () => log(`https tunnel entrypoint listening on :${httpsPort}`));
+
+  return { controlHttp, httpServer, httpsServer };
+}
+
+module.exports = { startServer };

package/src/util.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const crypto = require('crypto');
+
+function log(...args) {
+  console.log(new Date().toISOString(), ...args);
+}
+
+/** Formats an Error for logging, unwrapping AggregateError (whose own .message is often empty). */
+function describeError(err) {
+  if (!err) return String(err);
+  if (Array.isArray(err.errors) && err.errors.length > 0) {
+    return err.errors.map((e) => e.message || String(e)).join('; ');
+  }
+  return err.message || err.code || String(err);
+}
+
+/** Constant-time string comparison, safe for comparing against a network-supplied secret. */
+function secureCompare(a, b) {
+  const ha = crypto.createHash('sha256').update(String(a)).digest();
+  const hb = crypto.createHash('sha256').update(String(b)).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
+/** Bidirectionally pipes two duplex streams and destroys both if either errors or closes. */
+function pipeBidirectional(a, b) {
+  a.pipe(b);
+  b.pipe(a);
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    a.destroy();
+    b.destroy();
+  };
+
+  a.on('error', cleanup);
+  b.on('error', cleanup);
+  a.on('close', cleanup);
+  b.on('close', cleanup);
+}
+
+const REQUEST_LINE_RE = /^([A-Z]+) (\S+) HTTP\/\d\.\d$/;
+const MAX_LEFTOVER_BYTES = 8192;
+
+/**
+ * Passively taps a socket carrying raw HTTP bytes and logs each request line
+ * it spots (method + path), without consuming or altering the stream --
+ * safe to use alongside a .pipe() of the same socket. Best-effort: after a
+ * protocol upgrade (e.g. WebSocket) traffic is no longer HTTP and simply
+ * won't match, so logging naturally goes quiet for that connection.
+ */
+function logRequestLines(socket, label) {
+  let leftover = '';
+  socket.on('data', (chunk) => {
+    leftover += chunk.toString('latin1');
+    let idx;
+    while ((idx = leftover.indexOf('\r\n')) !== -1) {
+      const line = leftover.slice(0, idx);
+      leftover = leftover.slice(idx + 2);
+      const match = REQUEST_LINE_RE.exec(line);
+      if (match) log(`${label} ${match[1]} ${match[2]}`);
+    }
+    if (leftover.length > MAX_LEFTOVER_BYTES) {
+      leftover = leftover.slice(-1024);
+    }
+  });
+}
+
+module.exports = { log, secureCompare, pipeBidirectional, describeError, logRequestLines };