From 28955f8e85c5484eb73191bc08b0f96dfcaf3545 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Sun, 27 May 2018 01:58:37 -0600 Subject: [PATCH] moving to telebit --- README.md | 192 +++++++++++++++++++++++++++------ TODO.md | 26 +++++ bin/{stunnel.js => telebit.js} | 10 +- package.json | 24 ++--- wsclient.js => remote.js | 0 5 files changed, 201 insertions(+), 51 deletions(-) rename bin/{stunnel.js => telebit.js} (94%) rename wsclient.js => remote.js (100%) diff --git a/README.md b/README.md index 368ffba..f987ac8 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,172 @@ -| Sponsored by [ppl](https://ppl.family) | [tunnel-server.js](https://git.coolaj86.com/coolaj86/tunnel-server.js) | **tunnel-client.js** | +# Telebit Remote -# stunnel.js +Because friends don't let friends localhost™ -A client that works in combination with [stunneld.js](https://git.coolaj86.com/coolaj86/tunnel-server.js) -to allow you to serve http and https from any computer, anywhere through a secure tunnel. +| Sponsored by [ppl](https://ppl.family) +| **Telebit Remote** +| [Telebit Relay](https://git.coolaj86.com/coolaj86/telebitd.js) +| + +Break out of localhost. +----- + +If you need to get bits from here to there, Telebit gets the job done. + +Install Telebit Remote on any device - your laptop, raspberry pi, whatever - +and now you can access that device from anywhere, even securely in a web browser. + +How does it work? +It's a net server that uses a relay to allow multiplexed incoming connections +on any external port. + +Features +-------- + +* [x] Show your mom the web app you're working on +* [x] Access your Raspberry Pi from behind a firewall +* [x] Watch Netflix without region restrictions while traveling +* [x] SSH over HTTPS on networks with restricted ports or protocols +* [x] Access your wife's laptop while she's on a flight + + + +Install +======= + +Mac & Linux +----------- + +Open Terminal and run this install script: + +``` +curl -fsSL https://get.telebit.cloud/ | bash +``` + +Of course, feel free to inspect the install script before you run it. + +This will install Telebit Remote to `/opt/telebit` and +put a symlink to `/opt/telebit/bin/telebit` in `/usr/local/bin/telebit` +for convenience. + +You can customize the installation: + +```bash +export NODEJS_VER=v10.2 +export TELEBIT_PATH=/opt/telebit +curl -fsSL https://get.telebit.cloud/ +``` + +That will change the bundled version of node.js is bundled with Telebit Relay +and the path to which Telebit Relay installs. + +You can get rid of the tos + email and server domain name prompts by providing them right away: + +```bash +curl -fsSL https://get.telebit.cloud/ | bash -- jon@example.com example.com telebit.example.com xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +Windows & Node.js +----------------- + +1. Install [node.js](https://nodejs.org) +2. Open _Node.js_ +2. Run the command `npm install -g telebit` + +**Note**: Use node.js v8.x or v10.x + +There is [a bug](https://github.com/nodejs/node/issues/20241) in node v9.x that causes telebit to crash. + +Usage +==== + +```bash +telebit --config /etc/telebit/telebit.yml +``` + +Options + +`/etc/telebit/telebit.yml:` +``` +email: 'jon@example.com' # must be valid (for certificate recovery and security alerts) +agree_tos: true # agree to the Telebit, Greenlock, and Let's Encrypt TOSes +community_member: true # receive infrequent relevant but non-critical updates +telemetry: true # contribute to project telemetric data +secret: '' # JWT authorization secret. Generate like so: + # node -e "console.log(crypto.randomBytes(16).toString('hex'))" +remote_options: + https_redirect: false # don't redirect http to https remotely +servernames: # servernames that will be forwarded here + - example.com +local_ports: # ports to forward + 3000: 'http' + 8443: 'https' + 5050: true +``` + + + +Using Telebit with node.js +-------------------------- + +Telebit has two parts: + * the local server + * the relay service + +This repository is for the local server, which you run on the computer or device that you would like to access. + +This is the portion that runs on your computer +You will need both Telebit (this, telebit.js) and a Telebit Relay +(such as [telebitd.js](https://git.coolaj86.com/coolaj86/telebitd.js)). + +You can **integrate telebit.js into your existing codebase** or use the **standalone CLI**. * CLI -* Library +* Node.js Library +* Browser Library -CLI -=== +Telebit CLI +----------- Installs as `stunnel.js` with the alias `jstunnel` (for those that regularly use `stunnel` but still like commandline completion). ### Install +```bash +npm install -g telebit +``` + ```bash npm install -g 'git+https://git@git.coolaj86.com/coolaj86/tunnel-client.js.git#v1' ``` Or if you want to bow down to the kings of the centralized dictator-net: -```bash -npm install -g stunnel -``` - -### Usage with OAuth3.org - -The OAuth3.org tunnel service is in Beta. - -**Terms of Service**: The Software and Services shall be used for Good, not Evil. -Examples of good: education, business, pleasure. Examples of evil: crime, abuse, extortion. - -```bash -stunnel.js --agree-tos --email john@example.com --locals http:*:4080,https:*:8443 --device -``` - -```bash -stunnel.js \ - --agree-tos --email \ - --locals ::> \ - --device [HOSTNAME] \ - --domains [Comma-separated list of domains to attach to device] \ - --oauth3-url -``` - -### Advanced Usage (DIY) - How to use `stunnel.js` with your own instance of `stunneld.js`: ```bash @@ -83,7 +202,7 @@ stunnel.js \ -k, --insecure ignore invalid ssl certificates from stunneld ``` -Library +Node.js Library ======= ### Example @@ -166,3 +285,8 @@ stunnel.connect({ } }); ``` + +Browser Library +======= + +This is implemented with websockets, so you should be able to diff --git a/TODO.md b/TODO.md index 622d22c..fb2d6df 100644 --- a/TODO.md +++ b/TODO.md @@ -4,3 +4,29 @@ TODO * [ ] Hijack HTTPS connection directly (without WebSockets) * [p] Raw TCP (for transporting https once, not twice) (partial) * [ ] Let's Encrypt Support (for connecting to a plain http server locally) + +A pure-JavaScript tunnel client for http and https similar to localtunnel.me, but uses TLS (SSL) with ServerName Indication (SNI) over https to work even in harsh network conditions such as in student dorms and behind HOAs, corporate firewalls, public libraries, airports, airplanes, etc. Can also tunnel tls and plain tcp. + +### Usage with OAuth3.org + +The OAuth3.org tunnel service is in Beta. + +**Terms of Service**: The Software and Services shall be used for Good, not Evil. +Examples of good: education, business, pleasure. Examples of evil: crime, abuse, extortion. + +```bash +stunnel.js --agree-tos --email john@example.com --locals http:*:4080,https:*:8443 --device +``` + +```bash +stunnel.js \ + --agree-tos --email \ + --locals ::> \ + --device [HOSTNAME] \ + --domains [Comma-separated list of domains to attach to device] \ + --oauth3-url +``` + +### Advanced Usage (DIY) + + diff --git a/bin/stunnel.js b/bin/telebit.js similarity index 94% rename from bin/stunnel.js rename to bin/telebit.js index 9261807..ed5fe5e 100755 --- a/bin/stunnel.js +++ b/bin/telebit.js @@ -121,14 +121,14 @@ program .action(function (url) { program.url = url; }) - .option('-k --insecure', 'Allow TLS connections to stunneld without valid certs (rejectUnauthorized: false)') + .option('-k --insecure', 'Allow TLS connections to a Telebit Relay without valid certs (rejectUnauthorized: false)') .option('--locals ', 'comma separated list of : to which matching incoming http and https should forward (reverse proxy). Ex: https:8443,smtps:8465', collectProxies, [ ]) // --reverse-proxies .option('--domains ', 'comma separated list of domain names to set to the tunnel (to capture a specific protocol to a specific local port use the format https:example.com:1337 instead). Ex: example.com,example.net', collectDomains, [ ]) .option('--device [HOSTNAME]', 'Tunnel all domains associated with this device instead of specific domainnames. Use with --locals :. Ex: macbook-pro.local (the output of `hostname`)') - .option('--stunneld ', 'the domain (or ip address) at which you are running stunneld.js (the proxy)') // --proxy - .option('--secret ', 'the same secret used by stunneld (used for JWT authentication)') - .option('--token ', 'a pre-generated token for use with stunneld (instead of generating one with --secret)') - .option('--agree-tos', 'agree to the Daplie Terms of Service (requires user validation)') + .option('--relay ', 'the domain (or ip address) at which you are running Telebit Relay (the proxy)') // --proxy + .option('--secret ', 'the same secret used by the Telebit Relay (used for JWT authentication)') + .option('--token ', 'a pre-generated token for use with the Telebit Relay (instead of generating one with --secret)') + .option('--agree-tos', 'agree to the Telebit Terms of Service (requires user validation)') .option('--email ', 'email address (or cloud address) for user validation') .option('--oauth3-url ', 'Cloud Authentication to use (default: https://oauth3.org)') .parse(process.argv) diff --git a/package.json b/package.json index 4f52270..329d2fa 100644 --- a/package.json +++ b/package.json @@ -1,19 +1,17 @@ { - "name": "stunnel", - "version": "0.10.4", - "description": "A pure-JavaScript tunnel client for http and https similar to localtunnel.me, but uses TLS (SSL) with ServerName Indication (SNI) over https to work even in harsh network conditions such as in student dorms and behind HOAs, corporate firewalls, public libraries, airports, airplanes, etc. Can also tunnel tls and plain tcp.", - "main": "wsclient.js", + "name": "telebit", + "version": "0.10.0", + "description": "Break out of localhost. Connect to any device from anywhere over any tcp port or securely in a browser. A secure tunnel. A poor man's reverse VPN.", + "main": "remote.js", "bin": { - "jstunnel": "bin/stunnel.js", - "stunnel.js": "bin/stunnel.js", - "stunnel-js": "bin/stunnel.js" + "telebit": "bin/telebit.js" }, "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "repository": { "type": "git", - "url": "git+ssh://git@git.coolaj86.com/coolaj86/tunnel-client.js.git" + "url": "https://git.coolaj86.com/coolaj86/telebit.js.git" }, "keywords": [ "cli", @@ -32,6 +30,9 @@ "tunnel", "localtunnel", "localtunnel.me", + "underpass", + "ngrok", + "ngrok.io", "proxy", "reverse", "reverse-proxy", @@ -42,14 +43,13 @@ "author": "AJ ONeal (https://coolaj86.com/)", "license": "(MIT OR Apache-2.0)", "bugs": { - "url": "https://git.coolaj86.com/coolaj86/tunnel-client.js/issues" + "url": "https://git.coolaj86.com/coolaj86/telebit.js/issues" }, - "homepage": "https://git.coolaj86.com/coolaj86/tunnel-client.js#readme", + "homepage": "https://git.coolaj86.com/coolaj86/telebit.js#readme", "dependencies": { - "bluebird": "^3.5.0", + "bluebird": "^3.5.1", "commander": "^2.9.0", "jsonwebtoken": "^7.1.9", - "oauth3.js": "git+https://git.oauth3.org/OAuth3/oauth3.js.git#v1", "sni": "^1.0.0", "tunnel-packer": "^1.2.0", "ws": "^2.2.3" diff --git a/wsclient.js b/remote.js similarity index 100% rename from wsclient.js rename to remote.js