cstunnel 1.0.0

package/bin/cs.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * cs — instant localhost tunnel
+ *
+ * Usage:
+ *   cs --port 3000
+ *   cs -p 8080
+ */
+
+const { Command } = require('commander');
+const { createTunnel } = require('../src/tunnel');
+
+const program = new Command();
+
+program
+  .name('cs')
+  .description('Instant localhost tunnel with automatic subdomain assignment')
+  .version('1.0.0')
+  .option('-p, --port <port>', 'local service port', '3000')
+  .option('-H, --host <host>', 'local service host', '127.0.0.1')
+  .option('--no-reconnect', 'disable auto reconnect on disconnect')
+  .parse(process.argv);
+
+const options = program.opts();
+
+// Start tunnel
+createTunnel({
+  localPort: parseInt(options.port, 10),
+  localHost: options.host,
+  reconnect: options.reconnect !== false,
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "cstunnel",
+  "version": "1.0.0",
+  "description": "Instant localhost tunnel with automatic subdomain assignment",
+  "main": "src/index.js",
+  "bin": {
+    "cs": "./bin/cs.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": ["tunnel", "ngrok", "localhost", "proxy", "webhook", "expose", "reverse-proxy"],
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.18.0",
+    "commander": "^12.1.0"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * cstunnel — Programmatic API
+ *
+ * const cstunnel = require('cstunnel');
+ * cstunnel.createTunnel({ localPort: 3000 });
+ */
+
+const { createTunnel } = require('./tunnel');
+
+module.exports = { createTunnel };

package/src/tunnel.js

@@ -0,0 +1,255 @@
+/**
+ * cstunnel core tunnel logic
+ */
+
+const http = require('http');
+const https = require('https');
+const os = require('os');
+const WebSocket = require('ws');
+
+// ANSI color helpers
+const c = {
+  reset: '\x1b[0m',
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+
+/**
+ * Get a unique device fingerprint: hostname + first non-internal MAC address hash.
+ * Cross-platform, no external dependencies.
+ */
+function getDeviceId() {
+  const parts = [os.hostname()];
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const iface of interfaces[name]) {
+      if (!iface.internal && iface.mac !== '00:00:00:00:00:00') {
+        parts.push(iface.mac);
+        break; // grab the first non-internal NIC MAC
+      }
+    }
+  }
+  return parts.join('_').replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 64) || os.hostname();
+}
+
+const SERVER_URL = 'wss://app.cloudstudio.site';
+
+/** Create tunnel connection */
+function createTunnel({ localPort, localHost, reconnect }) {
+  let ws = null;
+  let heartbeatTimer = null;
+  let reconnectTimer = null;
+  let reconnectAttempts = 0;
+  const MAX_RECONNECT_DELAY = 30_000;
+  const deviceId = getDeviceId();
+  const deviceHostname = os.hostname();
+  const devicePlatform = `${os.platform()} ${os.release()} ${os.arch()}`;
+
+  // ---- Pretty output ----
+  function banner(subdomain, publicUrl) {
+    console.log('');
+    console.log(c.green('  Tunnel established!'));
+    console.log('');
+    console.log(
+      `  ${c.dim('Local:')}  ${c.cyan(`http://${localHost}:${localPort}`)}`
+    );
+    console.log(
+      `  ${c.dim('Public:')}  ${c.cyan(publicUrl)}`
+    );
+    console.log('');
+    console.log(c.dim('  Ctrl+C to disconnect'));
+    console.log('');
+  }
+
+  // ---- Connect to server ----
+  function connect() {
+    // URL params: port + mac (device fingerprint)
+    const wsUrl = `${SERVER_URL}?port=${localPort}&mac=${encodeURIComponent(deviceId)}`;
+
+    console.log(c.dim(`  Connecting to ${SERVER_URL} ...`));
+
+    ws = new WebSocket(wsUrl);
+
+    ws.on('open', () => {
+      reconnectAttempts = 0;
+      console.log(c.dim('  WebSocket connected, waiting for tunnel assignment...'));
+    });
+
+    ws.on('message', (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+
+      switch (msg.type) {
+        case 'connected': {
+          const { subdomain, publicUrl } = msg;
+          banner(subdomain, publicUrl);
+
+          // report device info
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({
+              type: 'device_info',
+              mac: deviceId,
+              hostname: deviceHostname,
+              platform: devicePlatform,
+            }));
+          }
+
+          // start heartbeat
+          heartbeatTimer = setInterval(() => {
+            if (ws.readyState === WebSocket.OPEN) {
+              ws.send(JSON.stringify({ type: 'pong' }));
+            }
+          }, 25_000);
+          break;
+        }
+
+        case 'ping': {
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({ type: 'pong' }));
+          }
+          break;
+        }
+
+        case 'rejected': {
+          console.log('');
+          console.log(c.red(`  Connection rejected: ${msg.reason || 'unknown reason'}`));
+          console.log(c.dim(`  Device ID: ${msg.mac || deviceId}`));
+          console.log('');
+          process.exit(1);
+        }
+
+        case 'kicked': {
+          console.log('');
+          console.log(c.yellow(`  Kicked by admin: ${msg.reason || 'no reason given'}`));
+          console.log('');
+          process.exit(1);
+        }
+
+        case 'request': {
+          handleRequest(msg, ws);
+          break;
+        }
+
+        default:
+          break;
+      }
+    });
+
+    ws.on('close', (code) => {
+      clearInterval(heartbeatTimer);
+      console.log(c.yellow(`  Disconnected (code: ${code})`));
+
+      if (reconnect) {
+        scheduleReconnect();
+      } else {
+        console.log(c.red('  Disconnected, not reconnecting'));
+        process.exit(1);
+      }
+    });
+
+    ws.on('error', (err) => {
+      console.error(c.red(`  WebSocket error: ${err.message}`));
+    });
+  }
+
+  // ---- Reconnect logic ----
+  function scheduleReconnect() {
+    const delay = Math.min(1000 * 2 ** reconnectAttempts, MAX_RECONNECT_DELAY);
+    reconnectAttempts++;
+    console.log(c.yellow(`  Reconnecting in ${(delay / 1000).toFixed(1)}s (attempt #${reconnectAttempts})...`));
+    reconnectTimer = setTimeout(connect, delay);
+  }
+
+  // ---- Forward HTTP requests to local ----
+  function handleRequest(msg, wsConn) {
+    const { id, method, path, headers, body, bodyEncoding } = msg;
+
+    const cleanHeaders = { ...headers };
+    delete cleanHeaders['host'];
+    delete cleanHeaders['connection'];
+    delete cleanHeaders['keep-alive'];
+    delete cleanHeaders['transfer-encoding'];
+    delete cleanHeaders['x-forwarded-for'];
+    delete cleanHeaders['x-real-ip'];
+    if (headers['x-forwarded-for'] || headers['x-real-ip']) {
+      cleanHeaders['x-forwarded-for'] = headers['x-forwarded-for'] || headers['x-real-ip'];
+    }
+
+    const options = {
+      hostname: localHost,
+      port: localPort,
+      path: path || '/',
+      method: method || 'GET',
+      headers: cleanHeaders,
+      timeout: 25_000,
+    };
+
+    const connector = localPort === 443 ? https : http;
+    const localReq = connector.request(options, (localRes) => {
+      const chunks = [];
+      localRes.on('data', (chunk) => chunks.push(chunk));
+      localRes.on('end', () => {
+        const responseBody = Buffer.concat(chunks);
+        const isText =
+          (localRes.headers['content-type'] || '').includes('text') ||
+          (localRes.headers['content-type'] || '').includes('json') ||
+          (localRes.headers['content-type'] || '').includes('javascript') ||
+          (localRes.headers['content-type'] || '').includes('xml');
+
+        wsConn.send(
+          JSON.stringify({
+            type: 'response',
+            id,
+            status: localRes.statusCode,
+            headers: localRes.headers,
+            body: responseBody.toString(isText ? 'utf-8' : 'base64'),
+            bodyEncoding: isText ? 'utf-8' : 'base64',
+          })
+        );
+      });
+    });
+
+    localReq.on('timeout', () => {
+      localReq.destroy();
+      wsConn.send(JSON.stringify({ type: 'response', id, status: 504, body: 'Local service timeout' }));
+    });
+
+    localReq.on('error', (err) => {
+      wsConn.send(JSON.stringify({ type: 'response', id, status: 502, body: `Local service error: ${err.message}` }));
+    });
+
+    if (body) {
+      localReq.write(Buffer.from(body, bodyEncoding || 'utf-8'));
+    }
+    localReq.end();
+  }
+
+  // ---- Cleanup ----
+  function cleanup() {
+    clearInterval(heartbeatTimer);
+    clearTimeout(reconnectTimer);
+    if (ws) ws.close();
+  }
+
+  process.on('SIGINT', () => {
+    cleanup();
+    console.log(c.dim('\n  Disconnected'));
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  connect();
+}
+
+module.exports = { createTunnel };