pinggy 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 PINGGY TECHNOLOGY PRIVATE LIMITED
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,182 @@
+# Pinggy CLI (JavaScript)
+
+Create secure, shareable tunnels to your localhost and manage them from the command line. 
+
+- Homepage: https://github.com/Pinggy-io/cli-js
+- Package name: pinggy
+
+## Key features
+- HTTP, TCP, UDP, TLS, TLSTCP tunnels to localhost
+- SSH-style and user-friendly flags
+- Web debugger for HTTP tunnels
+- Extended options for auth, header manipulation, IP allowlists, CORS handling, etc.
+- Remote management via secure WebSocket connection (works with Pinggy Dashboard)
+- Configurable logging to file and/or stdout
+- Save and load configuration files
+- Simple file server mode for quickly sharing local files
+- Built-in TUI (Text User Interface) for viewing tunnel statistics, requests, and responses in real time
+
+
+## Requirements
+- Node.js 18+ (recommended). The CLI uses modern ESM and WebSocket features.
+- A network connection that allows outgoing WebSocket/HTTPS traffic.
+
+
+## Installation
+Global install is recommended for system-wide "pinggy" command.
+
+- Using npm:
+ ``` bash
+  npm install -g pinggy
+  ```
+
+After install, verify:
+```bash
+  pinggy --help
+```
+
+
+## Quick start
+- Start a basic HTTP tunnel to localhost:3000:
+ 
+ ```bash
+  pinggy -R0:localhost:3000
+ ```
+
+- Start a TCP tunnel (e.g., SSH on port 22):
+
+```bash
+  pinggy -R0:localhost:8000 tcp@free.pinggy.io
+```
+
+- Start HTTP tunnel with web debugger on 4300:
+```bash
+pinggy -R0:localhost:8000 -L4300:localhost:4300
+```
+
+- Use a token and region/domain-like arg:
+  pinggy mytoken@a.example.com -p 3000. For more info read [docs](https://pinggy.io/docs/)
+
+The CLI prints generated public URLs (HTTP/HTTPS or TCP) and keeps running until you press Ctrl+C.
+
+
+## Usage
+Basic syntax:
+  pinggy [options] [user@domain]
+
+- user@domain is optional. Domain can be any valid domain supported by the service backend (e.g., ap.example.com).
+
+### Options
+The CLI supports both SSH-style flags and more descriptive long flags. Below is a consolidated list (only public ones are shown here). For the most up-to-date help, run pinggy --help.
+
+- -R, --R <value>              Local port forwarding (SSH-style).
+  Example: -R0:localhost:3000 forwards tunnel traffic to local port 3000.
+- -L, --L <value>              Web debugger address (SSH-style).
+  Example: -L4300:localhost:4300 starts web debugger on port 4300.
+- -p, --server-port <value>    Pinggy server port (default: 443).
+- --type <value>               Type of connection (e.g., tcp for raw TCP tunnel).
+- -l, --localport <value>      Local endpoint as [protocol:][host:]port.
+  Examples: --localport https://localhost:8000 or -l 3000
+- -d, --debugger <value>       Port for web debugger (e.g., -d 4300).
+- --token <value>              Token for authentication.
+
+Logging:
+- --loglevel <value>           Logging level: ERROR, INFO, DEBUG.
+- --logfile <path>             Path to log file.
+- -g, --printlog               Also print logs to stdout.
+
+Config:
+- --saveconf <file>            Create a configuration file based on the provided options.
+- --conf <file>                Load configuration from file; CLI options override it.
+
+File server:
+- --serve <path>               Serve files from a local directory via a simple web server.
+
+Remote control:
+- --remote-management <token>  Enable remote management of tunnels using api key.
+- --manage <addr>              Remote management server (default: dashboard.pinggy.io).
+- --NoTUI                      Disable TUI in remote management mode.
+
+Misc:
+- --version                    Print version and exit.
+- -h, --help                   Show help and exit.
+
+
+### Extended options
+Extended options provide advanced controls. Specify them as positional values like x:https or w:192.168.1.0/24 alongside other CLI flags.
+
+- x:https           Enforce HTTPS-only (HTTP redirected to HTTPS).
+- x:passpreflight | x:allowpreflight  Allow CORS preflight to pass unchanged.
+- x:reverseproxy                  Disable built-in reverse-proxy header injection.
+- x:xff                           Add X-Forwarded-For.
+- x:fullurl | x:fullrequesturl    Include original request URL.
+- w:<cidr>[,<cidr>...]            Whitelist IPs (IPv4 CIDR).
+- k:<token>                       Set Bearer token(s) for auth (repeatable).
+- b:<user:pass>                   Add Basic Auth credentials (repeatable).
+- a:<Key:Val>                     Add header.
+- u:<Key:Val>                     Update header.
+- r:<Key>                         Remove header.
+
+Examples:
+- Enforce HTTPS and XFF for local HTTPS server on 8443:
+  pinggy x:https x:xff -l https://localhost:8443
+
+- Allow only a local subnet:
+  pinggy w:192.168.1.0/24 -l 8080
+
+To generate advanced CLI arguments, use [Configure from Pinggy.io](https://pinggy.io/)
+
+
+## Remote management
+You can control tunnels remotely using a secure WebSocket connection.
+
+- Start remote management with a token:
+```bash
+ pinggy --remote-management <APIKEY>
+```
+
+- Specify a management server (default is wss://dashboard.pinggy.io):
+```bash
+ pinggy --remote-management <TOKEN> --manage wss://custom.example.com
+```
+
+
+
+## Logging
+You can control logs via CLI flags (which override environment variables). If logfile is provided, the log directory will be created if it does not exist.
+
+- To log to file and stdout at INFO level:
+```bash
+  pinggy -p 3000 --logfile ~/.pinggy/pinggy.log --loglevel INFO --printlog
+```
+
+
+
+## Saving and loading configuration
+- Save current options to a file:
+```bash  
+  pinggy -p 443 -L4300:localhost:4300 -t -R0:127.0.0.1:8000 qr+force@free.pinggy.io   x:noreverseproxy x:passpreflight x:xff --saveconf myconfig.json
+```
+- Use a config as base and override with flags:
+```bash
+pinggy --conf ./myconfig.json -p 8080
+```
+
+
+## File server mode
+Serve a local directory quickly over a tunnel:
+  pinggy --serve /path/to/files
+Optionally combine with other flags (auth, IP whitelist) as needed.
+
+
+## Signals and shutdown
+Press Ctrl+C to stop. The CLI traps SIGINT and gracefully stops active tunnels before exiting.
+
+
+
+## Versioning
+This package follows semantic versioning. See package.json for the current version.
+
+
+## License
+Apache License Version 2.0

package/dist/TunnelConfig.js

@@ -0,0 +1,39 @@
+// @ts-ignore
+export const TUNNEL_CONFIG = [
+    {
+        configId: "4ddea4c7-9c3a-4051-a3f1-04a60c55bc9a",
+        token: "adsfadsf",
+        serverAddress: "a.pinggy.io",
+        forwarding: "localhost:8000",
+        webDebugger: "",
+        tunnelType: ["http" /* TunnelType.Http */],
+        ipWhitelist: [],
+        bearerTokenAuth: [],
+        basicAuth: [],
+        headerModification: [],
+        xForwardedFor: "",
+        httpsOnly: false,
+        originalRequestUrl: false,
+        allowPreflight: false,
+        reverseProxy: false,
+        force: true,
+    },
+    {
+        configId: "4ddea4c7-9c3a-4051-a3f1-04a60c55bc9b",
+        token: "adsfadsf",
+        serverAddress: "a.pinggy.io",
+        forwarding: "localhost:8000",
+        webDebugger: "",
+        tunnelType: ["udp" /* TunnelType.Udp */],
+        ipWhitelist: [],
+        bearerTokenAuth: [],
+        basicAuth: [],
+        headerModification: [],
+        xForwardedFor: "",
+        httpsOnly: false,
+        originalRequestUrl: false,
+        allowPreflight: false,
+        reverseProxy: false,
+        force: true,
+    },
+];

package/dist/TunnelManager.js

@@ -0,0 +1,155 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TunnelManager = void 0;
+const pinggy_1 = require("@pinggy/pinggy");
+const logger_1 = require("./logger");
+class TunnelManager {
+    constructor() {
+        this.tunnelsByTunnelId = new Map();
+        this.tunnelsByConfigId = new Map();
+    }
+    /**
+     * Create (but not start) a tunnel
+     */
+    createTunnel(config) {
+        const { configId, additionalForwarding } = config;
+        if (this.tunnelsByConfigId.has(configId)) {
+            throw new Error(`Tunnel with configId "${configId}" already exists`);
+        }
+        const tunnelId = crypto.randomUUID();
+        const instance = pinggy_1.pinggy.createTunnel(config);
+        const managed = {
+            tunnelId,
+            configId,
+            instance,
+            additionalForwarding,
+        };
+        this.tunnelsByTunnelId.set(tunnelId, managed);
+        this.tunnelsByConfigId.set(configId, managed);
+        logger_1.logger.info("Tunnel created", { configId, tunnelId });
+        return managed;
+    }
+    /**
+     * Start a tunnel that was created but not yet started
+     */
+    startTunnel(tunnelId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const managed = this.tunnelsByTunnelId.get(tunnelId);
+            if (!managed)
+                throw new Error(`Tunnel with id "${tunnelId}" not found`);
+            logger_1.logger.info("Starting tunnel", { tunnelId, configId: managed.configId });
+            const urls = yield managed.instance.start();
+            logger_1.logger.info("Tunnel started", { tunnelId, urls });
+            // Apply any additional forwarding after the tunnel has started
+            if (Array.isArray(managed.additionalForwarding) && managed.additionalForwarding.length > 0) {
+                logger_1.logger.debug("Applying additional forwarding rules", managed.additionalForwarding);
+                for (const f of managed.additionalForwarding) {
+                    try {
+                        if (!f || !f.remotePort || !f.localDomain || !f.localPort)
+                            continue;
+                        const hostname = f.remoteDomain && f.remoteDomain.length > 0
+                            ? `${f.remoteDomain}:${f.remotePort}`
+                            : `${f.remotePort}`;
+                        const target = `${f.localDomain}:${f.localPort}`;
+                        managed.instance.tunnelRequestAdditionalForwarding(hostname, target);
+                        logger_1.logger.info("Applied additional forwarding", { tunnelId, hostname, target });
+                    }
+                    catch (e) {
+                        logger_1.logger.warn(`Failed to apply additional forwarding (${JSON.stringify(f)}):`, e);
+                    }
+                }
+            }
+            return urls;
+        });
+    }
+    /**
+     * Stop a tunnel by tunnelId
+     */
+    stopTunnel(tunnelId) {
+        const managed = this.tunnelsByTunnelId.get(tunnelId);
+        if (!managed)
+            throw new Error(`Tunnel "${tunnelId}" not found`);
+        logger_1.logger.info("Stopping tunnel", { tunnelId, configId: managed.configId });
+        managed.instance.stop();
+        this.tunnelsByTunnelId.delete(tunnelId);
+        this.tunnelsByConfigId.delete(managed.configId);
+        logger_1.logger.info("Tunnel stopped", { tunnelId });
+    }
+    /**
+     * Get all public URLs for a tunnel
+     */
+    getTunnelUrls(tunnelId) {
+        const managed = this.tunnelsByTunnelId.get(tunnelId);
+        if (!managed)
+            throw new Error(`Tunnel "${tunnelId}" not found`);
+        const urls = managed.instance.urls();
+        logger_1.logger.debug("Queried tunnel URLs", { tunnelId, urls });
+        return urls;
+    }
+    /**
+     * Get status of a tunnel
+     */
+    getTunnelStatus(tunnelId) {
+        const managed = this.tunnelsByTunnelId.get(tunnelId);
+        if (!managed)
+            throw new Error(`Tunnel "${tunnelId}" not found`);
+        const status = managed.instance.getStatus();
+        logger_1.logger.debug("Queried tunnel status", { tunnelId, status });
+        return status;
+    }
+    /**
+     * Stop all tunnels
+     */
+    stopAllTunnels() {
+        for (const { instance } of this.tunnelsByTunnelId.values()) {
+            try {
+                instance.stop();
+            }
+            catch (e) {
+                logger_1.logger.warn("Error stopping tunnel instance", e);
+            }
+        }
+        this.tunnelsByTunnelId.clear();
+        this.tunnelsByConfigId.clear();
+        logger_1.logger.info("All tunnels stopped and cleared");
+    }
+    getTunnelInstance(configId, tunnelId) {
+        if (configId) {
+            const managed = this.tunnelsByConfigId.get(configId);
+            if (!managed)
+                throw new Error(`Tunnel "${configId}" not found`);
+            return managed.instance;
+        }
+        if (tunnelId) {
+            const managed = this.tunnelsByTunnelId.get(tunnelId);
+            if (!managed)
+                throw new Error(`Tunnel "${tunnelId}" not found`);
+            return managed.instance;
+        }
+        throw new Error(`Either configId or tunnelId must be provided`);
+    }
+    /**
+     * Get tunnel config by tunnelId
+     */
+    getTunnelConfig(configId, tunnelId) {
+        if (configId) {
+            const tunnelInstance = this.getTunnelInstance(configId);
+            return tunnelInstance.getConfig();
+        }
+        if (tunnelId) {
+            const tunnelInstance = this.getTunnelInstance(tunnelId);
+            return tunnelInstance.getConfig();
+        }
+        throw new Error(`Either configId or tunnelId must be provided`);
+    }
+}
+exports.TunnelManager = TunnelManager;