pinggy 0.1.0

package/src/cli/buildConfig.ts

@@ -0,0 +1,357 @@
+import { defaultOptions } from "./defaults.js";
+import { parseExtendedOptions } from "./extendedOptions.js";
+import { logger } from "../logger.js";
+import { FinalConfig, Forwarding } from "../types.js";
+import { ParsedValues } from "../utils/parseArgs.js";
+import { cliOptions } from "./options.js";
+import { isValidPort } from "../utils/util.js";
+import { v4 as uuidv4 } from "uuid";
+import { TunnelType } from "@pinggy/pinggy";
+import fs from "fs";
+import path from "path";
+
+
+const domainRegex = /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
+
+function parseUserAndDomain(str: string) {
+  let token: string | undefined;
+  let type: string | undefined;
+  let server: string | undefined;
+  let qrCode: boolean | undefined;
+
+  if (!str) return { token, type, server, qrCode } as const;
+
+  if (str.includes('@')) {
+    const [user, domain] = str.split('@', 2);
+    if (domainRegex.test(domain)) {
+      server = domain;
+      // parse user modifiers like token+type or just type
+      const parts = user.split('+');
+      for (const part of parts) {
+        if ([TunnelType.Http, TunnelType.Tcp, TunnelType.Tls, TunnelType.Udp, TunnelType.TlsTcp].includes(part.toLowerCase() as typeof TunnelType[keyof typeof TunnelType])) {
+          type = part;
+        } else if (part === 'force') {
+          token = (token ? token + '+' : '') + part;
+        } else if (part === 'qr') {
+          qrCode = true;
+        } else {
+          token = (token ? token + '+' : '') + part;
+        }
+      }
+    }
+  } else if (domainRegex.test(str)) {
+    server = str;
+  }
+  return { token, type, server, qrCode } as const;
+}
+
+function parseUsers(positionalArgs: string[], explicitToken?: string) {
+  let token: string | undefined;
+  let server: string | undefined;
+  let type: string | undefined;
+  let forceFlag = false;
+  let qrCode = false;
+  let remaining: string[] = [...positionalArgs];
+
+  // Allow explicit token to carry user@domain 
+  if (typeof explicitToken === 'string') {
+    const parsed = parseUserAndDomain(explicitToken);
+    if (parsed.server) server = parsed.server;
+    if (parsed.type) type = parsed.type;
+    if (parsed.token) token = parsed.token;
+  }
+
+  if (remaining.length > 0) {
+    const first = remaining[0];
+    const parsed = parseUserAndDomain(first);
+    if (parsed.server) {
+      server = parsed.server;
+      if (parsed.type) type = parsed.type;
+      if (parsed.token) {
+        if (parsed.token.includes('+')) {
+          const parts = parsed.token.split('+');
+          const tOnly = parts.filter((p) => p !== 'force').join('+');
+          if (tOnly) token = tOnly;
+          if (parts.includes('force')) forceFlag = true;
+        } else {
+          token = parsed.token;
+        }
+      } if (parsed.qrCode) {
+        // QR code request detected
+        qrCode = true;
+      }
+      remaining = remaining.slice(1);
+    }
+  }
+
+  return { token, server, type, forceFlag, qrCode, remaining } as const;
+}
+
+function parseType(finalConfig: FinalConfig, values: ParsedValues<typeof cliOptions>, inferredType?: string) {
+  const t = inferredType || values.type || finalConfig.tunnelType;
+  if (t === TunnelType.Http || t === TunnelType.Tcp || t === TunnelType.Tls || t === TunnelType.Udp) {
+    finalConfig.tunnelType = [t];
+  }
+}
+
+function parseLocalPort(finalConfig: FinalConfig, values: ParsedValues<typeof cliOptions>): Error | null {
+  if (typeof values.localport !== 'string') return null;
+  let lp = values.localport.trim();
+
+  let isHttps = false;
+  if (lp.startsWith('https://')) {
+    isHttps = true;
+    lp = lp.replace(/^https:\/\//, '');
+  } else if (lp.startsWith('http://')) {
+    lp = lp.replace(/^http:\/\//, '');
+  }
+
+  const parts = lp.split(':');
+  if (parts.length === 1) {
+    const port = parseInt(parts[0], 10);
+    if (!Number.isNaN(port) && isValidPort(port)) {
+      finalConfig.forwarding = `localhost:${port}`;
+    } else {
+      return new Error('Invalid local port');
+    }
+  } else if (parts.length === 2) {
+    const host = parts[0] || 'localhost';
+    const port = parseInt(parts[1], 10);
+    if (!Number.isNaN(port) && isValidPort(port)) {
+      finalConfig.forwarding = `${host}:${port}`;
+    } else {
+      return new Error('Invalid local port. Please use -h option for help.');
+    }
+  } else {
+    return new Error('Invalid --localport format. Please use -h option for help.');
+  }
+
+  return null;
+}
+
+// Remove IPv6 Brackets
+// Example: From [::1] to ::1
+function removeIPv6Brackets(ip: string): string {
+  if (ip.startsWith("[") && ip.endsWith("]")) {
+    return ip.slice(1, -1);
+  }
+  return ip;
+}
+
+function ipv6SafeSplitColon(s: string): string[] {
+  const result: string[] = [];
+  let buf = "";
+  const stack: string[] = [];
+
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+
+    if (c === "[") {
+      stack.push(c);
+    } else if (c === "]" && stack.length > 0) {
+      stack.pop();
+    }
+
+    if (c === ":" && stack.length === 0) {
+      result.push(buf);
+      buf = "";
+    } else {
+      buf += c;
+    }
+  }
+
+  result.push(buf);
+  return result;
+}
+
+function parseForwarding(forwarding: string): Forwarding | Error {
+  const parts = ipv6SafeSplitColon(forwarding);
+
+  // Format: 5555:localhost:6666
+  if (parts.length === 3) {
+    const remotePort = parseInt(parts[0], 10);
+    const localDomain = removeIPv6Brackets(parts[1] || "localhost");
+    const localPort = parseInt(parts[2], 10);
+    return { remotePort, localDomain, localPort };
+  }
+
+  // Format: domain.com:5555:localhost:6666
+  if (parts.length === 4) {
+    const remoteDomain = removeIPv6Brackets(parts[0]);
+    const remotePort = parseInt(parts[1], 10);
+    const localDomain = removeIPv6Brackets(parts[2] || "localhost");
+    const localPort = parseInt(parts[3], 10);
+    return { remoteDomain, remotePort, localDomain, localPort };
+  }
+
+  return new Error("forwarding address incorrect");
+}
+
+function parseReverseTunnelAddr(finalConfig: FinalConfig, values: ParsedValues<typeof cliOptions>): Error | null {
+  const reverseTunnel = values.R;
+
+  if (!Array.isArray(reverseTunnel) || reverseTunnel.length === 0) {
+    return new Error("local port not specified. Please use '-h' option for help.");
+  }
+  const forwarding = parseForwarding(reverseTunnel[0]);
+  if (forwarding instanceof Error) {
+    return forwarding;
+  }
+  finalConfig.forwarding = `${forwarding.localDomain}:${forwarding.localPort}`;
+  // Additional forwarding
+  if (reverseTunnel.length > 1) {
+    finalConfig.additionalForwarding = []
+    for (const t of reverseTunnel.slice(1)) {
+      const f = parseForwarding(t);
+      if (f instanceof Error) {
+        return f;
+      }
+      finalConfig.additionalForwarding.push(f);
+    }
+  }
+  return null
+
+}
+
+function parseLocalTunnelAddr(finalConfig: FinalConfig, values: ParsedValues<typeof cliOptions>) {
+  if (!Array.isArray(values.L) || values.L.length === 0) return null;
+  const firstL = values.L[0] as string;
+  const parts = firstL.split(':');
+  if (parts.length === 3) {
+    const lp = parseInt(parts[2], 10);
+    if (!Number.isNaN(lp) && isValidPort(lp)) {
+      finalConfig.webDebugger = `localhost:${lp}`;
+    } else {
+      return new Error(`Invalid debugger port ${lp}`);
+
+    }
+  } else {
+    return new Error("Incorrect command line arguments: web debugger address incorrect. Please use '-h' option for help.");
+
+  }
+}
+
+function parseDebugger(finalConfig: FinalConfig, values: ParsedValues<typeof cliOptions>) {
+  let dbg = values.debugger;
+  if (typeof dbg !== 'string') return;
+  dbg = dbg.startsWith(':') ? dbg.slice(1) : dbg;
+  const d = parseInt(dbg, 10);
+  if (!Number.isNaN(d) && isValidPort(d)) {
+    finalConfig.webDebugger = `localhost:${d}`;
+  } else {
+    logger.error('Invalid debugger port:', dbg);
+    return new Error(`Invalid debugger port ${dbg}. Please use '-h' option for help.`);
+  }
+}
+
+function parseToken(finalConfig: FinalConfig, explicitToken?: string) {
+  if (typeof explicitToken === 'string' && explicitToken) {
+    finalConfig.token = explicitToken;
+  }
+}
+
+
+function parseArgs(finalConfig: FinalConfig, remainingPositionals: string[]) {
+  parseExtendedOptions(remainingPositionals, finalConfig);
+}
+
+function storeJson(config: FinalConfig, saveconf: string | null) {
+  if (saveconf) {
+    const path = saveconf;
+    try {
+      fs.writeFileSync(path, JSON.stringify(config, null, 2), { encoding: 'utf-8', flag: 'w' });
+      logger.info(`Configuration saved to ${path}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error("Error loading configuration:", msg);
+    }
+
+  }
+}
+
+function loadJsonConfig(config: ParsedValues<typeof cliOptions>): FinalConfig | null {
+  const configpath = config["conf"];
+  if (typeof configpath === "string" && configpath.trim().length > 0) {
+    const filepath = path.resolve(configpath);
+    try {
+      const data = fs.readFileSync(filepath, { encoding: 'utf-8' });
+      const json = JSON.parse(data);
+      return json;
+    } catch (err) {
+      logger.error("Error loading configuration:", err);
+    }
+
+  }
+  return null;
+
+}
+
+function isSaveConfOption(values: ParsedValues<typeof cliOptions>): string | null {
+  const saveconf = values["saveconf"];
+  if (typeof saveconf === "string" && saveconf.trim().length > 0) {
+    return saveconf;
+  }
+  return null;
+}
+
+export function buildFinalConfig(values: ParsedValues<typeof cliOptions>, positionals: string[]): FinalConfig {
+  let token: string | undefined;
+  let server: string | undefined;
+  let type: string | undefined;
+  let forceFlag = false;
+  let qrCode = false;
+  let finalConfig = new Object() as FinalConfig;
+  let saveconf = isSaveConfOption(values);
+
+  const configFromFile = loadJsonConfig(values);
+  if (configFromFile !== null) {
+    finalConfig = { ...configFromFile };
+  }
+
+  const userParse = parseUsers(positionals, values.token);
+  token = userParse.token;
+  server = userParse.server;
+  type = userParse.type;
+  forceFlag = userParse.forceFlag;
+  qrCode = userParse.qrCode;
+  const remainingPositionals: string[] = userParse.remaining;
+
+  const initialTunnel = (type || values.type) as TunnelType;
+  finalConfig = {
+    ...defaultOptions,
+    configid: uuidv4(),
+    token: token || (typeof values.token === 'string' ? values.token : ''),
+    serverAddress: server || defaultOptions.serverAddress,
+    tunnelType: initialTunnel ? [initialTunnel] : defaultOptions.tunnelType,
+    NoTUI: values.NoTUI || false,
+    qrCode: qrCode || false,
+  };
+
+
+  parseType(finalConfig, values, type);
+
+  // Apply token
+  parseToken(finalConfig, token || values.token);
+
+  const dbgErr = parseDebugger(finalConfig, values);
+  if (dbgErr instanceof Error) throw dbgErr;
+
+  const lpErr = parseLocalPort(finalConfig, values);
+  if (lpErr instanceof Error) throw lpErr;
+
+  const rErr = parseReverseTunnelAddr(finalConfig, values);
+  if (rErr instanceof Error) throw rErr;
+
+  const lErr = parseLocalTunnelAddr(finalConfig, values);
+  if (lErr instanceof Error) throw lErr;
+
+  // Apply force flag if indicated via user
+  if (forceFlag) finalConfig.force = true;
+
+  // Parse positional extended options (like x:, w:, b:, k:, a:, u:, r:)
+  parseArgs(finalConfig, remainingPositionals);
+
+  storeJson(finalConfig, saveconf);
+
+  return finalConfig;
+}

package/src/cli/defaults.ts

@@ -0,0 +1,20 @@
+import { PinggyOptions, TunnelType } from "@pinggy/pinggy";
+
+// Default configuration for Tunnel
+export const defaultOptions: Omit<PinggyOptions, 'token'> & { token: string | undefined } = {
+  token: undefined, // No default token
+  serverAddress: "a.pinggy.io",
+  forwarding: "localhost:8000",
+  webDebugger: "",
+  tunnelType: [TunnelType.Http],
+  ipWhitelist: [],
+  basicAuth: [],
+  bearerTokenAuth: [],
+  headerModification: [],
+  force: true,
+  xForwardedFor: false,
+  httpsOnly: false,
+  originalRequestUrl: false,
+  allowPreflight: false,
+  reverseProxy: false,
+};

package/src/cli/extendedOptions.ts

@@ -0,0 +1,134 @@
+import { PinggyOptions } from "@pinggy/pinggy";
+import { isIP } from 'net';
+import { logger } from "../logger.js";
+import CLIPrinter from "../utils/printer.js";
+
+export function parseExtendedOptions(options: string[] | undefined, config: PinggyOptions) {
+  if (!options) return;
+
+  for (const opt of options) {
+    const [key, value] = opt.replace(/^"|"$/g, "").split(/:(.+)/).filter(Boolean);
+
+    switch (key) {
+      case "x":
+        switch (value) {
+          case "https":
+          case "httpsonly":
+            config.httpsOnly = true;
+            break;
+            
+          case "passpreflight":
+          case "allowpreflight":
+            config.allowPreflight = true;
+            break;
+
+          case "reverseproxy":
+            config.reverseProxy = false;
+            break;
+
+          case "xff":
+            config.xForwardedFor = true;
+            break;
+
+          case "fullurl":
+          case "fullrequesturl":
+            config.originalRequestUrl = true;
+            break;
+
+          default:
+            CLIPrinter.warn(`Unknown extended option "${key}"`);
+            logger.warn(`Warning: Unknown extended option "${key}"`);
+            break;
+        }
+        break;
+      case "w":
+        // Whitelist IPs
+        if (value) {
+          const ips = value.split(",").map(ip => ip.trim()).filter(Boolean);
+          const invalidIps = ips.filter(ip => !isValidIpV4Cidr(ip));
+
+          if (invalidIps.length > 0) {
+            CLIPrinter.warn(`Invalid IP/CIDR(s) in whitelist: ${invalidIps.join(", ")}`);
+            logger.warn(`Warning: Invalid IP/CIDR(s) in whitelist: ${invalidIps.join(", ")}`);
+          }
+          if (!(invalidIps.length > 0)) {
+            config.ipWhitelist = ips;
+          }
+        } else {
+          CLIPrinter.warn(`Extended option "${opt}" for 'w' requires IP(s)`);
+          logger.warn(`Warning: Extended option "${opt}" for 'w' requires IP(s)`);
+        }
+        break;
+      case "k":
+        //bearer tokens
+        if (!config.bearerTokenAuth) config.bearerTokenAuth = [];
+        if (value) {
+          config.bearerTokenAuth.push(value);
+        } else {
+          CLIPrinter.warn(`Extended option "${opt}" for 'k' requires a value`);
+          logger.warn(`Warning: Extended option "${opt}" for 'k' requires a value`);
+        }
+        break;
+
+      case "b":
+        // basicauth "username:password"
+        if (value && value.includes(":")) {
+          const [username, password] = value.split(/:(.+)/);
+          if (!config.basicAuth) config.basicAuth = [];
+          config.basicAuth.push({ username, password });
+        } else {
+          CLIPrinter.warn(`Extended option "${opt}" for 'b' requires value in format username:password`);
+          logger.warn(`Warning: Extended option "${opt}" for 'b' requires value in format username:password`);
+        }
+        break;
+
+      case "a":
+        // Add header
+        if (value && value.includes(":")) {
+          const [key, val] = value.split(/:(.+)/);
+          if (!config.headerModification) config.headerModification = [];
+          config.headerModification.push({ type: "add", key, value: [val] });
+        } else {
+          CLIPrinter.warn(`Extended option "${opt}" for 'a' requires key:value`);
+          logger.warn(`Warning: Extended option "${opt}" for 'a' requires key:value`);
+        }
+        break;
+      case "u":
+        // Update header
+        if (value && value.includes(":")) {
+          const [key, val] = value.split(/:(.+)/);
+          if (!config.headerModification) config.headerModification = [];
+          config.headerModification.push({ type: "update", key, value: [val] });
+        } else {
+          CLIPrinter.warn(`Extended option "${opt}" for 'u' requires key:value`);
+          logger.warn(`Warning: Extended option "${opt}" for 'u' requires key:value`);
+        }
+        break;
+      case "r":
+        // Remove header
+        if (value) {
+          if (!config.headerModification) config.headerModification = [];
+          config.headerModification.push({ type: "remove", key: value });
+        } else {
+          CLIPrinter.warn(`Extended option "${opt}" for 'r' requires a key`);
+        }
+        break;
+      default:
+        CLIPrinter.warn(`Unknown extended option "${key}"`);
+        break;
+    }
+  }
+}
+
+function isValidIpV4Cidr(input: string): boolean {
+  // Check for CIDR notation
+  if (input.includes('/')) {
+    const [ip, mask] = input.split('/');
+    if (!ip || !mask) return false;
+    const isIp4 = isIP(ip) === 4;
+    const maskNum = parseInt(mask, 10);
+    const isMaskValid = !isNaN(maskNum) && maskNum >= 0 && maskNum <= 32;
+    return isIp4 && isMaskValid;
+  }
+  return false;
+}

package/src/cli/help.ts

@@ -0,0 +1,41 @@
+import { cliOptions } from "./options.js";
+
+export function printHelpMessage() {
+  console.log("\nPinggy CLI Tool - Create secure tunnels to your localhost.");
+  console.log("\nUsage:");
+  console.log("  pinggy [options] [user@domain]             # Domain can be any valid domain\n");
+
+  console.log("Options:");
+  for (const [key, value] of Object.entries(cliOptions)) {
+    if ((value as any).hidden) continue;
+    const short = 'short' in value && (value as any).short ? `-${(value as any).short}, ` : '    ';
+    const optType = (value as any).type === 'boolean' ? '' : '<value>';
+    console.log(`  ${short}--${key.padEnd(17)} ${optType.padEnd(8)} ${(value as any).description}`);
+  }
+
+  console.log("\nExtended options :");
+  console.log("  x:https                 Enforce HTTPS only (redirect HTTP to HTTPS)");
+  console.log("  x:noreverseproxy        Disable built-in reverse-proxy header injection");
+  console.log("  x:localservertls:host   Connect to local HTTPS server with SNI");
+  console.log("  x:passpreflight         Pass CORS preflight requests unchanged");
+  console.log("  a:Key:Val               Add header");
+  console.log("  u:Key:Val               Update header");
+  console.log("  r:Key                   Remove header");
+  console.log("  b:user:pass             Basic auth");
+  console.log("  k:BEARER                Bearer token");
+  console.log("  w:192.168.1.0/24        IP whitelist (CIDR)\n");
+
+  console.log("Examples (SSH-style):");
+  console.log("  pinggy -R0:localhost:3000                        # Basic HTTP tunnel");
+  console.log("  pinggy --type tcp -R0:localhost:22               # TCP tunnel for SSH");
+  console.log("  pinggy -R0:localhost:8080 -L4300:localhost:4300  # HTTP tunnel with debugger");
+  console.log("  pinggy tcp@ap.example.com -R0:localhost:22       # TCP tunnel to region\n");
+
+  console.log("Examples (User-friendly):");
+  console.log("  pinggy -p 3000                           # Basic HTTP tunnel");
+  console.log("  pinggy --type tcp -p 22                  # TCP tunnel for SSH");
+  console.log("  pinggy -l 8080 -d 4300                   # HTTP tunnel with debugger");
+  console.log("  pinggy mytoken@a.example.com -p 3000     # Authenticated tunnel");
+  console.log("  pinggy x:https x:xff -l https://localhost:8443  # HTTPS-only + XFF");
+  console.log("  pinggy w:192.168.1.0/24 -l 8080          # IP whitelist restriction");
+}

package/src/cli/options.ts

@@ -0,0 +1,46 @@
+export const cliOptions = {
+  // SSH-like options
+  R: { type: 'string' as const, multiple: true, description: 'Local port. Eg. -R0:localhost:3000 will forward tunnel connections to local port 3000.' },
+  L: { type: 'string' as const, multiple: true, description: 'Web Debugger address. Eg. -L4300:localhost:4300 will start web debugger on port 4300.' },
+  o: { type: 'string' as const, multiple: true, description: 'Options', hidden: true },
+  'server-port': { type: 'string' as const, short: 'p', description: 'Pinggy server port. Default: 443' },
+
+  v4: { type: 'boolean' as const, short: '4', description: 'IPv4 only', hidden: true },
+  v6: { type: 'boolean' as const, short: '6', description: 'IPv6 only', hidden: true },
+
+  // These options appear in the ssh command, but we ignore it in CLI
+  t: { type: 'boolean' as const, description: 'hidden', hidden: true },
+  T: { type: 'boolean' as const, description: 'hidden', hidden: true },
+  n: { type: 'boolean' as const, description: 'hidden', hidden: true },
+  N: { type: 'boolean' as const, description: 'hidden', hidden: true },
+
+  // Better options
+  type: { type: 'string' as const, description: 'Type of the connection. Eg. --type tcp' },
+  localport: { type: 'string' as const, short: 'l', description: 'Takes input as [protocol:][host:]port. Eg. --localport https://localhost:8000 OR -l 3000' },
+  debugger: { type: 'string' as const, short: 'd', description: 'Port for web debugger. Eg. --debugger 4300 OR -d 4300' },
+  token: { type: 'string' as const, description: 'Token for authentication. Eg. --token TOKEN_VALUE' },
+
+  // Logging options (CLI overrides env)
+  loglevel: { type: 'string' as const, description: 'Logging level: ERROR, INFO, DEBUG. Overrides PINGGY_LOG_LEVEL environment variable' },
+  logfile: { type: 'string' as const, description: 'Path to log file. Overrides PINGGY_LOG_FILE environment variable' },
+  printlog: { type: 'boolean' as const, short: 'g', description: 'Also print logs to stdout. Overrides PINGGY_LOG_STDOUT environment variable' },
+
+  // Save and load config
+  saveconf: { type: 'string' as const, description: 'Create the configuration file based on the options provided here' },
+  conf: { type: 'string' as const, description: 'Use the configuration file as base. Other options will be used to override this file' },
+
+  // File server
+  serve: { type: 'string' as const, description: 'Start a webserver to serve files from the specified path. Eg --serve /path/to/files' },
+
+  // Remote Control
+  'remote-management': { type: 'string' as const, description: 'Enable remote management of tunnels with token. Eg. --remote-management API_KEY' },
+  manage: { type: 'string' as const, description: 'Provide a server address to manage tunnels. Eg --manage dashboard.pinggy.io' },
+  NoTUI:{ type: 'boolean' as const, description: 'Disable TUI in remote management mode'},
+  // Misc
+  version: { type: 'boolean' as const, description: 'Print version' },
+
+  // Help
+  help: { type: 'boolean' as const, short: 'h', description: 'Show this help message' },
+} as const;
+
+export type CliOptions = typeof cliOptions;