moving to telebit

This commit is contained in:
AJ ONeal 2018-05-27 01:58:37 -06:00
parent 17467d74b1
commit 28955f8e85
5 changed files with 201 additions and 51 deletions

192
README.md
View File

@ -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
<!-- TODO use some imagery -->
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
```
<!--
```
redirect:
example.com/foo: /bar
'*': whatever.com/
vhost: # securely serve local sites from this path (or false)
example.com: /srv/example.com # (uses template string, i.e. /var/www/:hostname/public)
'*': /srv/www/:hostname
reverse_proxy: /srv/
example.com: 3000
'*': 3000
terminated_tls:
'example.com': 3000
'*': 3000
sni_forward:
'example.com': 8443
'*': 8443
port_forward:
2020: 2020
'*': 4040
greenlock:
store: le-store-certbot # certificate storage plugin
config_dir: /etc/acme # directory for ssl certificates
```
-->
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 <EMAIL> \
--locals <List of <SCHEME>:<EXTERNAL_DOMAINNAME>:<INTERNAL_PORT>> \
--device [HOSTNAME] \
--domains [Comma-separated list of domains to attach to device] \
--oauth3-url <Tunnel Service 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

26
TODO.md
View File

@ -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 <EMAIL> \
--locals <List of <SCHEME>:<EXTERNAL_DOMAINNAME>:<INTERNAL_PORT>> \
--device [HOSTNAME] \
--domains [Comma-separated list of domains to attach to device] \
--oauth3-url <Tunnel Service OAuth3 URL>
```
### Advanced Usage (DIY)

View File

@ -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 <LIST>', 'comma separated list of <proto>:<port> to which matching incoming http and https should forward (reverse proxy). Ex: https:8443,smtps:8465', collectProxies, [ ]) // --reverse-proxies
.option('--domains <LIST>', '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 <proto>:<port>. Ex: macbook-pro.local (the output of `hostname`)')
.option('--stunneld <URL>', 'the domain (or ip address) at which you are running stunneld.js (the proxy)') // --proxy
.option('--secret <STRING>', 'the same secret used by stunneld (used for JWT authentication)')
.option('--token <STRING>', '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 <URL>', 'the domain (or ip address) at which you are running Telebit Relay (the proxy)') // --proxy
.option('--secret <STRING>', 'the same secret used by the Telebit Relay (used for JWT authentication)')
.option('--token <STRING>', '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>', 'email address (or cloud address) for user validation')
.option('--oauth3-url <URL>', 'Cloud Authentication to use (default: https://oauth3.org)')
.parse(process.argv)

View File

@ -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 <coolaj86@gmail.com> (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"