bhole 0.1.0-alpha.0

package/src/commands/http.tsx

@@ -0,0 +1,117 @@
+import net from "net";
+import { Command } from "commander";
+import { loadConfig } from "../config.js";
+import { runTunnelPlain } from "../lib/tunnelPlain.js";
+import { randomMnemonicId } from "../lib/words.js";
+
+const authToken = process.env.BHOLE_AUTH_TOKEN;
+
+function isPortListening(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, 500);
+    socket.on("connect", () => {
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on("error", () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+    socket.connect(port, "127.0.0.1");
+  });
+}
+
+async function runTunnel(
+  serverUrl: string,
+  endpoint: string,
+  localPort: number,
+  publicUrl: string,
+  tunnelDomain?: string
+) {
+  if (process.stdin.isTTY) {
+    const { render } = await import("ink");
+    const { TunnelApp } = await import("../ui/TunnelApp.js");
+
+    const { waitUntilExit } = render(
+      <TunnelApp
+        serverUrl={serverUrl}
+        endpoint={endpoint}
+        localPort={localPort}
+        publicUrl={publicUrl}
+        tunnelDomain={tunnelDomain}
+        authToken={authToken}
+        onExit={(code) => process.exit(code)}
+      />
+    );
+
+    await waitUntilExit();
+  } else {
+    await runTunnelPlain(serverUrl, endpoint, localPort, publicUrl, authToken);
+  }
+}
+
+export const httpCommand = new Command("http")
+  .description("Expose a local HTTP server to the internet")
+  .argument("<port>", "Local port to expose")
+  .option("-s, --server <url>", "Tunnel server URL (default: ws://localhost:8080)", "ws://localhost:8080")
+  .option("-d, --domain <domain>", "Static subdomain (e.g. --domain=myapp)")
+  .option("--subdomain <name>", "Custom subdomain (alias for --domain)")
+  .action(async (portStr: string, options: { server: string; domain?: string; subdomain?: string }) => {
+    const port = parseInt(portStr, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      console.error("Error: port must be a valid number between 1 and 65535");
+      process.exit(1);
+    }
+
+    const config = loadConfig();
+    const tunnelDomain = config.tunnelDomain ?? process.env.BHOLE_TUNNEL_DOMAIN;
+
+    let serverUrl = (options.server || process.env.BHOLE_SERVER_URL || "ws://localhost:8080").replace(/^http/, "ws");
+    if (!serverUrl.startsWith("ws")) serverUrl = "ws://" + serverUrl;
+
+    if (!tunnelDomain && !serverUrl.includes("localhost")) {
+      console.error("Error: Set tunnel domain with 'bhole config set-tunnel-domain <domain>' or BHOLE_TUNNEL_DOMAIN");
+      process.exit(1);
+    }
+    const effectiveDomain = tunnelDomain ?? "localhost";
+
+    const domainOrSub = options.domain ?? options.subdomain;
+    let endpoint: string;
+    let publicUrl: string;
+    if (domainOrSub) {
+      let hostname = domainOrSub.trim();
+      if (hostname.startsWith("http://") || hostname.startsWith("https://")) {
+        try {
+          hostname = new URL(hostname).hostname;
+        } catch {
+          hostname = domainOrSub;
+        }
+      }
+      if (hostname.includes(".")) {
+        endpoint = hostname.split(".")[0] ?? hostname;
+        publicUrl = domainOrSub.startsWith("http") ? domainOrSub : `https://${hostname}`;
+      } else {
+        endpoint = hostname;
+        publicUrl = `https://${endpoint}.${effectiveDomain}`;
+      }
+      if (!endpoint || endpoint.length > 63) {
+        console.error("Error: endpoint must be 1–63 characters");
+        process.exit(1);
+      }
+    } else {
+      endpoint = randomMnemonicId();
+      publicUrl = `https://${endpoint}.${effectiveDomain}`;
+    }
+
+    const portOk = await isPortListening(port);
+    if (!portOk) {
+      console.warn(`Note: Nothing appears to be listening on localhost:${port}. Requests will return 502 until your server is running.`);
+    }
+
+    await runTunnel(serverUrl, endpoint, port, publicUrl, effectiveDomain);
+  });

package/src/commands/tcp.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+
+export const tcpCommand = new Command("tcp")
+  .description("Expose a local TCP port to the internet (coming soon)")
+  .argument("<port>", "Local port to expose")
+  .option("-s, --server <url>", "Blackhole server URL", "ws://localhost:8081")
+  .option("--subdomain <name>", "Custom subdomain for the tunnel")
+  .action((_portStr: string) => {
+    console.log("TCP tunneling is not yet implemented. Use 'bhole http <port>' for HTTP.");
+    process.exit(1);
+  });

package/src/config.ts

@@ -0,0 +1,41 @@
+import fs from "fs";
+import path from "path";
+import { homedir } from "os";
+
+const CONFIG_DIR = path.join(homedir(), ".blackhole");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+export interface Config {
+  /** Public domain for tunnel URLs. Tunnels are reachable at https://{endpoint}.{tunnelDomain} */
+  tunnelDomain?: string;
+}
+
+export function getConfigDir(): string {
+  return CONFIG_DIR;
+}
+
+export function loadConfig(): Config {
+  try {
+    const data = fs.readFileSync(CONFIG_FILE, "utf-8");
+    return JSON.parse(data) as Config;
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config: Config): void {
+  try {
+    if (!fs.existsSync(CONFIG_DIR)) {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+    try {
+      fs.chmodSync(CONFIG_DIR, 0o700);
+      fs.chmodSync(CONFIG_FILE, 0o600);
+    } catch {
+      // chmod may no-op on some platforms (e.g. Windows); ignore
+    }
+  } catch (err) {
+    throw new Error(`Failed to save config: ${err}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { configCommand } from "./commands/config.js";
+import { httpCommand } from "./commands/http.js";
+import { tcpCommand } from "./commands/tcp.js";
+import { CLI_VERSION } from "./lib/version.js";
+
+const program = new Command();
+
+program
+  .name("bhole")
+  .description("Expose local services to the internet - tunnel localhost with one command")
+  .version(CLI_VERSION);
+
+program.addCommand(configCommand);
+program.addCommand(httpCommand);
+program.addCommand(tcpCommand);
+
+program.parse();

package/src/lib/tunnelPlain.ts

@@ -0,0 +1,45 @@
+import { createHttpTunnel } from "../tunnel/http.js";
+
+const MAX_RETRIES = 2;
+const BASE_DELAY_MS = 2000;
+
+export async function runTunnelPlain(
+  serverUrl: string,
+  endpoint: string,
+  localPort: number,
+  publicUrl: string,
+  authToken?: string
+): Promise<void> {
+  const wsUrl = serverUrl.replace(/^http/, "ws");
+
+  console.log(`Connecting to ${wsUrl}...`);
+  console.log(`Exposing localhost:${localPort} at ${publicUrl}`);
+
+  const tryConnect = (attempt: number): Promise<void> =>
+    new Promise((resolve, reject) => {
+      createHttpTunnel(
+        { serverUrl: wsUrl, endpoint, localPort, authToken },
+        {
+          onReady: () => {
+            console.log("Tunnel established. Forwarding traffic to localhost:" + localPort);
+            console.log(`URL: ${publicUrl}`);
+            console.log(`(or use X-Blackhole-Endpoint: ${endpoint})`);
+            resolve();
+          },
+          onError: (err) => {
+            console.error("Tunnel error:", err.message);
+          },
+        }
+      ).catch((err) => {
+        if (attempt < MAX_RETRIES) {
+          const delayMs = BASE_DELAY_MS * Math.pow(2, attempt);
+          console.error(`Connection failed. Retrying in ${delayMs / 1000}s...`);
+          setTimeout(() => tryConnect(attempt + 1).then(resolve, reject), delayMs);
+        } else {
+          reject(err);
+        }
+      });
+    });
+
+  tryConnect(0).catch(() => process.exit(1));
+}

package/src/lib/version.ts

@@ -0,0 +1,45 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const pkg = require(path.join(__dirname, "../../package.json")) as { version: string };
+
+export const CLI_VERSION = pkg.version;
+
+/** Compare semver strings. Returns true if a > b. */
+function isNewer(a: string, b: string): boolean {
+  const parse = (s: string) =>
+    s
+      .replace(/[-].*$/, "")
+      .split(".")
+      .map((n) => parseInt(n, 10) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va > vb) return true;
+    if (va < vb) return false;
+  }
+  return false;
+}
+
+export async function getLatestVersion(): Promise<string | null> {
+  try {
+    const res = await fetch("https://registry.npmjs.org/bhole/latest", {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { version?: string };
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function shouldSuggestUpdate(latest: string | null): boolean {
+  if (!latest) return false;
+  return isNewer(latest, CLI_VERSION);
+}

package/src/lib/words.ts

@@ -0,0 +1,25 @@
+/**
+ * Mnemonic word list for ngrok-style random subdomains (e.g. happy-blue-frog).
+ * Short, memorable, URL-safe words.
+ */
+const WORDS = [
+  "angel", "apple", "arrow", "beach", "bear", "bird", "blue", "boat", "bold",
+  "bone", "book", "boss", "bush", "cake", "cash", "cat", "cave", "cold",
+  "cord", "crab", "cube", "dark", "demo", "dice", "dock", "door", "dove",
+  "dusk", "edge", "echo", "elm", "fall", "fern", "fire", "fish", "flag",
+  "flat", "fog", "fork", "frog", "gold", "gray", "grey", "grid", "gulf",
+  "harp", "hill", "hope", "iris", "iron", "java", "jazz", "key", "kite",
+  "lake", "lamp", "lane", "leaf", "lime", "lion", "log", "map", "mask",
+  "mint", "mist", "moon", "nova", "oak", "ocean", "olive", "opal", "pine",
+  "pink", "pool", "port", "rain", "reed", "rock", "rose", "rust", "sand",
+  "seed", "sky", "snow", "star", "sun", "surf", "swan", "tide", "tree",
+  "vine", "wave", "wolf", "wood", "zen",
+];
+
+export function randomMnemonicId(): string {
+  const picks: string[] = [];
+  for (let i = 0; i < 3; i++) {
+    picks.push(WORDS[Math.floor(Math.random() * WORDS.length)]!);
+  }
+  return picks.join("-");
+}

package/src/tunnel/http.ts

@@ -0,0 +1,315 @@
+import http from "http";
+import WebSocket from "ws";
+
+export interface HttpTunnelOptions {
+  serverUrl: string;
+  endpoint: string;
+  localPort: number;
+  /** Shared secret for auth (from BHOLE_AUTH_TOKEN) */
+  authToken?: string;
+}
+
+export interface TunnelRequestInfo {
+  method: string;
+  path: string;
+  bytesIn: number;
+  bytesOut: number;
+  statusCode?: number;
+  timestamp: Date;
+}
+
+export interface HttpTunnelCallbacks {
+  onOpen?: () => void;
+  onReady?: () => void;
+  onRequest?: (info: TunnelRequestInfo) => void;
+  onError?: (err: Error) => void;
+}
+
+const REGISTER_TIMEOUT_MS = 15000;
+const LOCAL_FORWARD_TIMEOUT_MS = 30000;
+const CONNECT_TIMEOUT_MS = 10000;
+const MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024; // 10MB
+const MAX_RESPONSE_BODY_BYTES = 10 * 1024 * 1024; // 10MB
+
+export function createHttpTunnel(
+  options: HttpTunnelOptions,
+  callbacks?: HttpTunnelCallbacks
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let rejected = false;
+    const doReject = (err: Error) => {
+      if (rejected) return;
+      rejected = true;
+      callbacks?.onError?.(err);
+      reject(err);
+    };
+
+    const ws = new WebSocket(options.serverUrl + "/tunnel");
+    let registerTimeout: ReturnType<typeof setTimeout> | null = null;
+    let connectTimeout: ReturnType<typeof setTimeout> | null = null;
+    let ready = false;
+
+    const clearRegisterTimeout = () => {
+      if (registerTimeout) {
+        clearTimeout(registerTimeout);
+        registerTimeout = null;
+      }
+    };
+
+    const safeSend = (data: Buffer | string, opts?: { binary?: boolean }) => {
+      if (ws.readyState === 1) {
+        try {
+          if (opts) ws.send(data, opts);
+          else ws.send(data);
+        } catch (err) {
+          if (!rejected) doReject(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+    };
+
+    connectTimeout = setTimeout(() => {
+      if (ready || rejected) return;
+      connectTimeout = null;
+      ws.terminate();
+      doReject(new Error("Connection timed out – server unreachable."));
+    }, CONNECT_TIMEOUT_MS);
+
+    ws.on("open", () => {
+      if (connectTimeout) {
+        clearTimeout(connectTimeout);
+        connectTimeout = null;
+      }
+      callbacks?.onOpen?.();
+      const msg: Record<string, string> = { type: "register", endpoint: options.endpoint };
+      if (options.authToken) msg.authToken = options.authToken;
+      safeSend(JSON.stringify(msg));
+      registerTimeout = setTimeout(() => {
+        if (!ready) {
+          clearRegisterTimeout();
+          const err = new Error("Registration timed out – server may be busy. Try again.");
+          doReject(err);
+          ws.close();
+        }
+      }, REGISTER_TIMEOUT_MS);
+    });
+
+    ws.on("message", (data: Buffer | string) => {
+      const str = data.toString();
+      if (str.startsWith("{")) {
+        try {
+          const msg = JSON.parse(str);
+          if (msg.error) {
+            ready = true;
+            clearRegisterTimeout();
+            const err = new Error(msg.error || "Server error");
+            doReject(err);
+            ws.close();
+            return;
+          }
+          if (msg.ok) {
+            ready = true;
+            clearRegisterTimeout();
+            callbacks?.onReady?.();
+          }
+          return;
+        } catch {
+          // Not JSON, treat as binary (request from server)
+        }
+      }
+
+      if (Buffer.isBuffer(data) || typeof data !== "string") {
+        const buf = Buffer.isBuffer(data) ? data : Buffer.from(data as ArrayBuffer);
+        if (buf.length > MAX_REQUEST_BODY_BYTES) {
+          const errResp = `HTTP/1.1 413 Payload Too Large\r\nContent-Type: text/plain\r\n\r\nRequest body exceeds ${MAX_REQUEST_BODY_BYTES / (1024 * 1024)}MB limit`;
+          safeSend(Buffer.from(errResp));
+          return;
+        }
+        const req = parseHttpRequest(buf);
+        if (!req) {
+          const errResp = "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\n\r\nFailed to parse request";
+          safeSend(Buffer.from(errResp));
+          return;
+        }
+        forwardToLocal(buf, options.localPort)
+          .then((response) => {
+            const info = parseResponseStatus(response);
+            callbacks?.onRequest?.({
+              method: req.method,
+              path: req.path,
+              bytesIn: buf.length,
+              bytesOut: response.length,
+              statusCode: info?.statusCode,
+              timestamp: new Date(),
+            });
+            safeSend(response, { binary: true });
+          })
+          .catch((err: Error) => {
+            callbacks?.onRequest?.({
+              method: req.method,
+              path: req.path,
+              bytesIn: buf.length,
+              bytesOut: 0,
+              timestamp: new Date(),
+            });
+            const errResp = `HTTP/1.1 502 Bad Gateway\r\nContent-Type: text/plain\r\n\r\n${err.message}`;
+            safeSend(Buffer.from(errResp));
+          });
+      }
+    });
+
+    ws.on("error", (err) => {
+      clearRegisterTimeout();
+      if (connectTimeout) {
+        clearTimeout(connectTimeout);
+        connectTimeout = null;
+      }
+      const msg = err.message || String(err) || "Connection failed";
+      doReject(new Error(msg));
+    });
+
+    ws.on("close", () => {
+      clearRegisterTimeout();
+      if (connectTimeout) {
+        clearTimeout(connectTimeout);
+        connectTimeout = null;
+      }
+      if (ready && !rejected) {
+        doReject(new Error("Connection closed"));
+      }
+    });
+  });
+}
+
+async function forwardToLocal(
+  rawRequest: Buffer,
+  localPort: number
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const req = parseHttpRequest(rawRequest);
+    if (!req) {
+      reject(new Error("Failed to parse request"));
+      return;
+    }
+
+    const opts = {
+      hostname: "localhost",
+      port: localPort,
+      path: req.path,
+      method: req.method,
+      headers: req.headers,
+    };
+
+    const timeout = setTimeout(() => {
+      proxyReq.destroy(new Error("Local server did not respond in time"));
+    }, LOCAL_FORWARD_TIMEOUT_MS);
+
+    const proxyReq = http.request(opts, (res: http.IncomingMessage) => {
+      clearTimeout(timeout);
+      const chunks: Buffer[] = [];
+      let totalBytes = 0;
+      let responseExceeded = false;
+      const exceededResponse = () =>
+        Buffer.from(
+          `HTTP/1.1 502 Bad Gateway\r\nContent-Type: text/plain\r\n\r\nResponse body exceeds ${MAX_RESPONSE_BODY_BYTES / (1024 * 1024)}MB limit`
+        );
+      const finish = (buf: Buffer) => {
+        clearTimeout(timeout);
+        resolve(buf);
+      };
+      res.on("data", (chunk: Buffer) => {
+        if (responseExceeded) return;
+        if (totalBytes + chunk.length <= MAX_RESPONSE_BODY_BYTES) {
+          chunks.push(chunk);
+          totalBytes += chunk.length;
+        } else {
+          responseExceeded = true;
+          res.destroy();
+          finish(exceededResponse());
+        }
+      });
+      res.on("end", () => {
+        if (responseExceeded) return;
+        const statusLine = `HTTP/1.1 ${res.statusCode} ${res.statusMessage}\r\n`;
+        const headers = Object.entries(res.headers)
+          .filter(([, v]) => v !== undefined)
+          .map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(", ") : v}\r\n`)
+          .join("");
+        const body = Buffer.concat(chunks);
+        finish(Buffer.concat([Buffer.from(statusLine + headers + "\r\n"), body]));
+      });
+      res.on("error", (err) => {
+        if (!responseExceeded) {
+          clearTimeout(timeout);
+          reject(err);
+        }
+      });
+    });
+
+    proxyReq.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+    proxyReq.end(req.body);
+  });
+}
+
+interface ParsedRequest {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  body: Buffer;
+}
+
+function parseRequestMethod(buf: Buffer): string {
+  const firstLine = buf.subarray(0, buf.indexOf("\n")).toString();
+  return firstLine.split(" ")[0] ?? "?";
+}
+
+function parseRequestPath(buf: Buffer): string {
+  const firstLine = buf.subarray(0, buf.indexOf("\n")).toString();
+  const path = firstLine.split(" ")[1];
+  return path ?? "/";
+}
+
+function parseResponseStatus(buf: Buffer): { statusCode: number } | null {
+  const firstLine = buf.subarray(0, buf.indexOf("\n")).toString();
+  const parts = firstLine.split(" ");
+  const code = parseInt(parts[1] ?? "0", 10);
+  return isNaN(code) ? null : { statusCode: code };
+}
+
+function parseHttpRequest(buf: Buffer): ParsedRequest | null {
+  const idx = buf.indexOf("\r\n\r\n");
+  const idxLf = buf.indexOf("\n\n");
+  const sepIdx = idx >= 0 ? idx : idxLf >= 0 ? idxLf : -1;
+  const sepLen = idx >= 0 ? 4 : idxLf >= 0 ? 2 : 0;
+  if (sepIdx === -1) return null;
+
+  const headerSection = buf.subarray(0, sepIdx).toString();
+  const body = buf.subarray(sepIdx + sepLen);
+  const lineSep = idx >= 0 ? "\r\n" : "\n";
+  const lines = headerSection.split(lineSep);
+  const firstLine = lines[0];
+  if (!firstLine) return null;
+  const parts = firstLine.split(" ");
+  const method = parts[0] ?? "GET";
+  const path = parts[1] ?? "/";
+  const headers: Record<string, string> = {};
+
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const colon = line.indexOf(":");
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim().toLowerCase();
+    const value = line.slice(colon + 1).trim();
+    headers[key] = value;
+  }
+
+  return {
+    method,
+    path,
+    headers,
+    body,
+  };
+}