@o-town/expose 1.0.0

package/.vscode/settings.json

@@ -0,0 +1 @@
+{}

package/README.md

@@ -0,0 +1,105 @@
+# expose
+
+> Zero-dependency tunnel — expose `localhost` to `*.site.com` using only Node's built-in `net` module.
+
+```
+http://localhost:3000  →  https://abc1f3.site.com
+```
+
+---
+
+## Install & run (client)
+
+```bash
+# Run directly with npx (no install needed)
+npx expose 3000
+
+# Or install globally
+npm install -g expose
+expose 3000
+
+# With a custom subdomain
+expose 3000 myapp
+# → https://myapp.site.com
+```
+
+### Environment variables
+
+| Variable        | Default          | Description                  |
+|-----------------|------------------|------------------------------|
+| `EXPOSE_SERVER` | `tunnel.site.com`| Tunnel server hostname       |
+| `EXPOSE_PORT`   | `2000`           | Tunnel server TCP port       |
+
+---
+
+## Deploy the server on site.com
+
+```bash
+node server.js --http-port 80 --tunnel-port 2000 --domain site.com
+```
+
+### Flags / env vars
+
+| Flag             | Env var       | Default     |
+|------------------|---------------|-------------|
+| `--http-port`    | `HTTP_PORT`   | `80`        |
+| `--tunnel-port`  | `TUNNEL_PORT` | `2000`      |
+| `--domain`       | `DOMAIN`      | `site.com`  |
+
+### Keep alive with PM2
+
+```bash
+npm i -g pm2
+pm2 start server.js --name expose-server -- --http-port 80 --domain site.com
+pm2 save && pm2 startup
+```
+
+### nginx + TLS (recommended)
+
+Issue a wildcard cert first:
+```bash
+certbot certonly --manual --preferred-challenges dns -d "*.site.com" -d "site.com"
+```
+
+Then add a site config:
+```nginx
+server {
+    listen 443 ssl;
+    server_name *.site.com;
+
+    ssl_certificate     /etc/letsencrypt/live/site.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/site.com/privkey.pem;
+
+    location / {
+        proxy_pass         http://127.0.0.1:80;
+        proxy_set_header   Host $host;
+        proxy_set_header   X-Real-IP $remote_addr;
+    }
+}
+```
+
+---
+
+## How it works
+
+```
+Browser
+  │  HTTPS → nginx → port 80
+  ▼
+server.js  (http.Server — public)
+  │  JSON line over TCP socket (port 2000)
+  ▼
+expose.js  (net.createConnection — your machine)
+  │  http.request
+  ▼
+localhost:3000
+```
+
+1. **Client** opens a raw TCP socket to `site.com:2000` and sends a `register` message.
+2. **Server** assigns a subdomain and replies `ready` with the public URL.
+3. **Browser** hits `https://abc1f3.site.com` → nginx → server's HTTP listener.
+4. **Server** sends a `request` JSON line over the TCP socket.
+5. **Client** forwards it to `localhost:PORT`, gets the response, sends `response` back.
+6. **Server** writes the response to the waiting browser connection.
+
+Zero dependencies. No WebSocket. No npm installs. Pure Node.

package/expose.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * expose — tunnel client
+ * Usage:  node expose.js <port> [subdomain]
+ *         npx expose 3000
+ *         npx expose 3000 myapp
+ */
+
+const net  = require('net');
+const http = require('http');
+
+// ── CLI args ─────────────────────────────────────────────────────────────────
+const [,, rawPort, subdomain] = process.argv;
+
+if (!rawPort || isNaN(Number(rawPort))) {
+  console.error('\n  Usage: expose <port> [subdomain]\n  Example: expose 3000\n');
+  process.exit(1);
+}
+
+const LOCAL_PORT  = Number(rawPort);
+const SERVER_HOST = process.env.EXPOSE_SERVER || 'tunnel.site.com';
+const SERVER_PORT = Number(process.env.EXPOSE_PORT || 2000);
+
+// ── Colours (no deps) ────────────────────────────────────────────────────────
+const c = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  green:  '\x1b[32m',
+  cyan:   '\x1b[36m',
+  yellow: '\x1b[33m',
+  red:    '\x1b[31m',
+};
+
+function log(msg)  { process.stdout.write(msg + '\n'); }
+function dim(msg)  { log(c.dim + msg + c.reset); }
+function ok(msg)   { log(c.green  + '  ✔ ' + c.reset + msg); }
+function warn(msg) { log(c.yellow + '  ⚠ ' + c.reset + msg); }
+function err(msg)  { log(c.red   + '  ✖ ' + c.reset + msg); }
+
+// ── State ────────────────────────────────────────────────────────────────────
+let reconnectDelay = 1000;
+let connected      = false;
+
+// ── Main connection loop ─────────────────────────────────────────────────────
+function connect() {
+  dim(`  Connecting to ${SERVER_HOST}:${SERVER_PORT}…`);
+
+  const sock = net.createConnection({ host: SERVER_HOST, port: SERVER_PORT });
+  let lineBuffer = '';
+
+  // ── Connected ──────────────────────────────────────────────────────────────
+  sock.once('connect', () => {
+    reconnectDelay = 1000;   // reset back-off on success
+    send(sock, {
+      type:      'register',
+      port:      LOCAL_PORT,
+      subdomain: subdomain || null,
+    });
+  });
+
+  // ── Incoming messages ──────────────────────────────────────────────────────
+  sock.on('data', (chunk) => {
+    lineBuffer += chunk.toString();
+    const lines = lineBuffer.split('\n');
+    lineBuffer  = lines.pop();         // keep incomplete tail
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      handleMessage(sock, msg);
+    }
+  });
+
+  // ── Disconnect / error ─────────────────────────────────────────────────────
+  sock.on('close', () => {
+    if (connected) {
+      warn('Tunnel disconnected.');
+      connected = false;
+    }
+    scheduleReconnect();
+  });
+
+  sock.on('error', (e) => {
+    err(`Socket error: ${e.message}`);
+    sock.destroy();
+  });
+}
+
+function scheduleReconnect() {
+  warn(`Reconnecting in ${reconnectDelay / 1000}s…\n`);
+  setTimeout(() => {
+    reconnectDelay = Math.min(reconnectDelay * 2, 30_000);
+    connect();
+  }, reconnectDelay);
+}
+
+// ── Message handler ──────────────────────────────────────────────────────────
+function handleMessage(sock, msg) {
+  switch (msg.type) {
+    case 'ready':
+      connected = true;
+      log('');
+      ok(`Tunnel open!\n`);
+      log(`  ${c.bold}Local  :${c.reset} ${c.cyan}http://localhost:${LOCAL_PORT}${c.reset}`);
+      log(`  ${c.bold}Public :${c.reset} ${c.cyan}${msg.url}${c.reset}`);
+      log(c.dim + '\n  Ctrl+C to stop.\n' + c.reset);
+      break;
+
+    case 'request':
+      forwardRequest(msg, (response) => {
+        send(sock, { type: 'response', id: msg.id, ...response });
+      });
+      break;
+
+    case 'error':
+      err(`Server: ${msg.message}`);
+      break;
+
+    default:
+      break;
+  }
+}
+
+// ── Forward HTTP request to local server ─────────────────────────────────────
+function forwardRequest({ method, path, headers, body }, cb) {
+  // Strip hop-by-hop headers that confuse Node's http module
+  const safeHeaders = Object.fromEntries(
+    Object.entries(headers || {}).filter(([k]) =>
+      !['connection', 'keep-alive', 'transfer-encoding', 'upgrade'].includes(k.toLowerCase())
+    )
+  );
+
+  const options = {
+    hostname: 'localhost',
+    port:     LOCAL_PORT,
+    method:   method || 'GET',
+    path:     path   || '/',
+    headers:  { ...safeHeaders, host: `localhost:${LOCAL_PORT}` },
+  };
+
+  const req = http.request(options, (res) => {
+    const chunks = [];
+    res.on('data',  (c) => chunks.push(c));
+    res.on('end',   ()  => {
+      cb({
+        status:  res.statusCode,
+        headers: res.headers,
+        body:    Buffer.concat(chunks).toString('base64'),
+      });
+    });
+  });
+
+  req.setTimeout(15_000, () => {
+    req.destroy();
+    cb({ status: 504, headers: {}, body: btoa('Gateway Timeout') });
+  });
+
+  req.on('error', (e) => {
+    err(`Local server error: ${e.message}`);
+    cb({
+      status:  502,
+      headers: { 'content-type': 'text/plain' },
+      body:    Buffer.from(`Local error: ${e.message}`).toString('base64'),
+    });
+  });
+
+  if (body) req.write(Buffer.from(body, 'base64'));
+  req.end();
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function send(sock, obj) {
+  if (sock.writable) sock.write(JSON.stringify(obj) + '\n');
+}
+
+function btoa(str) { return Buffer.from(str).toString('base64'); }
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+process.on('SIGINT',  () => { log('\n  Bye!\n'); process.exit(0); });
+process.on('SIGTERM', () => process.exit(0));
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+log('');
+log(`  ${c.bold}expose${c.reset}  v1.0.0  —  localhost:${LOCAL_PORT} → *.site.com`);
+log('');
+connect();

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@o-town/expose",
+  "version": "1.0.0",
+  "description": "Expose localhost to *.site.com — zero dependencies, pure Node net",
+  "bin": { "expose": "./expose.js" },
+  "scripts": {
+    "client": "node expose.js",
+    "server": "node server.js"
+  },
+  "preferGlobal": true,
+  "engines": { "node": ">=14" },
+  "license": "MIT"
+}

package/server.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * expose — tunnel server
+ * Deploy this on your VPS / site.com machine.
+ *
+ * Usage:
+ *   node server.js
+ *   node server.js --http-port 80 --tunnel-port 2000 --domain site.com
+ *
+ * Environment variables (alternative to flags):
+ *   HTTP_PORT    public HTTP port   (default 80)
+ *   TUNNEL_PORT  client TCP port    (default 2000)
+ *   DOMAIN       base domain        (default site.com)
+ */
+
+const net  = require('net');
+const http = require('http');
+const { randomBytes } = require('crypto');
+
+// ── Config ────────────────────────────────────────────────────────────────────
+const args       = parseArgs(process.argv.slice(2));
+const HTTP_PORT  = Number(args['http-port']   || process.env.HTTP_PORT   || 80);
+const TUNNEL_PORT= Number(args['tunnel-port'] || process.env.TUNNEL_PORT || 2000);
+const DOMAIN     =        args['domain']      || process.env.DOMAIN      || 'site.com';
+
+// ── State ─────────────────────────────────────────────────────────────────────
+/**
+ * clients : Map<subdomain, {
+ *   sock     : net.Socket,
+ *   pending  : Map<id, { res: http.ServerResponse, timer: NodeJS.Timeout }>
+ * }>
+ */
+const clients = new Map();
+
+// ── Tunnel server (TCP — clients connect here) ────────────────────────────────
+const tunnelServer = net.createServer((sock) => {
+  let lineBuffer = '';
+  let subdomain  = null;
+
+  sock.on('data', (chunk) => {
+    lineBuffer += chunk.toString();
+    const lines = lineBuffer.split('\n');
+    lineBuffer  = lines.pop();
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      handleClientMessage(sock, msg);
+    }
+  });
+
+  sock.on('close', () => {
+    if (subdomain && clients.get(subdomain)?.sock === sock) {
+      clients.delete(subdomain);
+      log(`[-] Tunnel closed: ${subdomain}.${DOMAIN}`);
+    }
+  });
+
+  sock.on('error', (e) => {
+    if (e.code !== 'ECONNRESET') log(`[!] Client socket error: ${e.message}`);
+    sock.destroy();
+  });
+
+  // ── Handle messages from client ──────────────────────────────────────────────
+  function handleClientMessage(sock, msg) {
+    switch (msg.type) {
+
+      // Client registers a new tunnel
+      case 'register': {
+        const desired = msg.subdomain;
+        subdomain     = (desired && !clients.has(desired))
+          ? desired
+          : randomBytes(4).toString('hex');
+
+        clients.set(subdomain, { sock, pending: new Map() });
+
+        const url = `https://${subdomain}.${DOMAIN}`;
+        log(`[+] Tunnel opened: ${url}  (port=${msg.port})`);
+        send(sock, { type: 'ready', url, subdomain });
+        break;
+      }
+
+      // Client sends back an HTTP response
+      case 'response': {
+        const client = clients.get(subdomain);
+        if (!client) break;
+
+        const pending = client.pending.get(msg.id);
+        if (!pending) break;
+
+        clearTimeout(pending.timer);
+        client.pending.delete(msg.id);
+
+        const body = msg.body
+          ? Buffer.from(msg.body, 'base64')
+          : Buffer.alloc(0);
+
+        // Strip hop-by-hop headers
+        const headers = Object.fromEntries(
+          Object.entries(msg.headers || {}).filter(([k]) =>
+            !['transfer-encoding', 'connection', 'keep-alive'].includes(k.toLowerCase())
+          )
+        );
+
+        pending.res.writeHead(msg.status || 200, headers);
+        pending.res.end(body);
+        break;
+      }
+
+      default:
+        break;
+    }
+  }
+});
+
+tunnelServer.listen(TUNNEL_PORT, () => {
+  log(`[expose-server] Tunnel listener on :${TUNNEL_PORT}`);
+});
+
+// ── HTTP server (public-facing) ───────────────────────────────────────────────
+const httpServer = http.createServer((req, res) => {
+  // Derive subdomain from Host header
+  const host      = (req.headers.host || '').split(':')[0];   // strip port
+  const sub       = host.replace(`.${DOMAIN}`, '').split('.').pop();
+  const client    = clients.get(sub);
+
+  if (!client) {
+    res.writeHead(502, { 'content-type': 'text/html' });
+    res.end(`<h2>No tunnel active for <code>${host}</code></h2>`);
+    return;
+  }
+
+  const id     = randomBytes(8).toString('hex');
+  const chunks = [];
+
+  req.on('data', (c) => chunks.push(c));
+  req.on('end', () => {
+    const body = Buffer.concat(chunks).toString('base64');
+
+    // Forward request to client
+    send(client.sock, {
+      type:    'request',
+      id,
+      method:  req.method,
+      path:    req.url,
+      headers: req.headers,
+      body,
+    });
+
+    // Timeout if client doesn't respond
+    const timer = setTimeout(() => {
+      client.pending.delete(id);
+      if (!res.headersSent) {
+        res.writeHead(504, { 'content-type': 'text/plain' });
+        res.end('Gateway Timeout — local server did not respond.');
+      }
+    }, 30_000);
+
+    client.pending.set(id, { res, timer });
+  });
+
+  req.on('error', () => {
+    res.writeHead(400); res.end();
+  });
+});
+
+httpServer.listen(HTTP_PORT, () => {
+  log(`[expose-server] HTTP listener on :${HTTP_PORT}  (domain: *.${DOMAIN})`);
+});
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function send(sock, obj) {
+  if (sock.writable) sock.write(JSON.stringify(obj) + '\n');
+}
+
+function log(msg) { console.log(`[${new Date().toISOString()}] ${msg}`); }
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) out[argv[i].slice(2)] = argv[i + 1] ?? true;
+  }
+  return out;
+}
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+function shutdown() {
+  log('Shutting down…');
+  tunnelServer.close();
+  httpServer.close();
+  process.exit(0);
+}
+process.on('SIGINT',  shutdown);
+process.on('SIGTERM', shutdown);