Goldilocks ========== The node.js netserver that's just right. * **HTTPS Web Server** with Automatic TLS (SSL) via ACME ([Let's Encrypt](https://letsencrypt.org)) * Static Web Server * URL Redirects * SSL on localhost (with bundled localhost.daplie.me certificates) * Uses node cluster to take advantage of multiple CPUs (in progress) * **TLS** name-based (SNI) proxy * **TCP** port-based proxy * WS **Tunnel Server** (i.e. run on Digital Ocean and expose a home-firewalled Raspberry Pi to the Internet) * WS **Tunnel Client** (i.e. run on a Raspberry Pi and connect to a Daplie Tunnel) * UPnP / NAT-PMP forwarding and loopback testing (in progress) * Configurable via API * mDNS Discoverable (configure in home or office with mobile and desktop apps) * OAuth3 Authentication Install Standalone ------- ```bash # v1 in npm npm install -g goldilocks # v1 in git (via ssh) npm install -g git+ssh://git@git.daplie.com:Daplie/goldilocks.js#v1 # v1 in git (unauthenticated) npm install -g git+https://git@git.daplie.com:Daplie/goldilocks.js#v1 ``` ```bash goldilocks ``` ```bash Serving /Users/foo/ at https://localhost.daplie.me:8443 ``` Install as a System Service (daemon-mode) We have service support for * systemd (Linux, Ubuntu) * launchd (macOS) ```bash curl https://git.daplie.com/Daplie/goldilocks.js/raw/master/install.sh | bash ``` Modules & Configuration ----- Goldilocks has several core systems, which all have their own configuration and some of which have modules: ``` * http - static - redirect - proxy (reverse proxy) * tls - acme - proxy (reverse proxy) * tcp - forward * tunnel_server * tunnel_client * mdns * api ``` ### http The HTTP system handles plain http (TLS / SSL is handled by the tls system) ```yml http: trust_proxy: true # allow localhost, 192.x, 10.x, 172.x, etc to set headers allow_insecure: false # allow non-https even without proxy https headers primary_domain: example.com # attempts to access via IP address will redirect here # modules can be nested in domains domains: - names: - example.com modules: - name: static root: /srv/www/:hostname # The configuration above could also be represented as follows: modules: - name: static domains: - example.com root: /srv/www/:hostname ``` ### http.static - how to serve a web page The static module is for serving static web pages and assets and has the following options: ``` root The path to serve as a string. The template variable `:hostname` represents the HTTP Host header without port information ex: `root: /srv/www/example.com` would load the example.com folder for any domain listed ex: `root: /srv/www/:hostname` would load `/srv/www/example.com` if so indicated by the Host header ``` Example config: ```yml http: modules: - name: static domains: - example.com root: /srv/www/:hostname ``` ### http.proxy - how to reverse proxy (ruby, python, etc) The proxy module is for reverse proxying, typically to an application on the same machine. It has the following options: ``` host The DNS-resolvable hostname (or IP address) of the system to which the request will be proxied ex: localhost ex: 192.168.1.100 port The port on said system to which the request will be proxied ex: 3000 ex: 80 ``` Example config: ```yml http: modules: - name: proxy domains: - example.com host: localhost port: 3000 ``` ### http.redirect - how to redirect URLs The redirect module is for, you guessed it, redirecting URLs. It has the following options: ``` status The HTTP status code to issue (301 is usual permanent redirect, 302 is temporary) ex: 301 from The URL path that was used in the request. The `*` wildcard character can be used for matching a full segment of the path ex: /photos/ ex: /photos/*/*/ to The new URL path which should be used. If wildcards matches were used they will be available as `:1`, `:2`, etc. ex: /pics/ ex: /pics/:1/:2/ ``` Example config: ```yml http: modules: - name: proxy domains: - example.com status: 301 from: /archives/*/*/*/ to: https://example.net/year/:1/month/:2/day/:3/ ``` ### tls The tls system handles encrypted connections, including fetching certificates, and uses ServerName Indication (SNI) to determine if the connection should be handled by the http system, a tls system module, or rejected. It has the following options: ``` acme.email The default email address for ACME certificate issuance ex: john.doe@example.com acme.server The default ACME server to use ex: https://acme-v01.api.letsencrypt.org/directory ex: https://acme-staging.api.letsencrypt.org/directory acme.challenge_type The default ACME challenge to request ex: http-01, dns-01, tls-01 acme.approved_domains The domains for which to request certificates ex: example.com ``` Example config: ```yml tls: acme: email: 'joe.shmoe@example.com' # IMPORTANT: Switch to in production 'https://acme-v01.api.letsencrypt.org/directory' server: 'https://acme-staging.api.letsencrypt.org/directory' challenge_type: 'http-01' approved_domains: - example.com - example.net modules: - name: proxy domains: - example.com - example.net address: '127.0.0.1:6443' ``` Certificates are saved to `~/acme`, which may be `/var/www/acme` if Goldilocks is run as the www-data user. ### tls.acme The acme module overrides the acme defaults of the tls system and uses the same options except that `approved_domains` (in favor of the domains in the scope of the module). Example config: ```yml tls: modules: - name: acme domains: - example.com - example.net email: 'joe.shmoe@example.com' server: 'https://acme-staging.api.letsencrypt.org/directory' challenge_type: 'http-01' ``` ### tls.proxy The proxy module routes the traffic based on the ServerName Indication (SNI) **without decrypting** it. It has the following options: ``` address The hostname (or IP) and port of the system or application that should receive the traffic ``` Example config: ```yml tls: modules: - name: proxy domains: - example.com address: '127.0.0.1:5443' ``` ### tcp The tcp system handles all tcp network traffic **before decryption** and may use port numbers or traffic sniffing to determine how the connection should be handled. It has the following options: ``` bind An array of numeric ports on which to bind ex: 80 ``` Example Config ```yml tcp: bind: - 22 - 80 - 443 modules: - name: forward ports: - 22 address: '127.0.0.1:2222' ``` ### tcp.forward The forward module routes traffic based on port number **without decrypting** it. It has the following options: ``` ports A numeric array of source ports ex: 22 address The destination hostname and port ex: 127.0.0.1:2222 ``` Example Config ```yml tcp: bind: - 22 - 80 - 443 modules: - name: forward ports: - 22 address: '127.0.0.1:2222' ``` ### tunnel\_server The tunnel server system is meant to be run on a publicly accessible IP address to server tunnel clients which are behind firewalls, carrier-grade NAT, or otherwise Internet-connect but inaccessible devices. It has the following options: ``` secret A 128-bit or greater string to use for signing tokens (HMAC JWT) ex: abc123 servernames An array of string servernames that should be captured as the tunnel server, ignoring the TLS forward module ex: api.tunnel.example.com ``` Example config: ```yml tunnel_server: secret: abc123def456ghi789 servernames: - 'api.tunnel.example.com' ``` ### tunnel The tunnel client is meant to be run from behind a firewalls, carrier-grade NAT, or otherwise inaccessible devices to allow them to be accessed publicly on the internet. It has no options per se, but is rather a list of tokens that can be used to connect to tunnel servers. If the token does not have an `aud` field it must be provided in an object with the token provided in the `jwt` field and the tunnel server url provided in the `tunnelUrl` field. Example config: ```yml tunnel: - 'some.jwt_encoded.token' - jwt: 'other.jwt_encoded.token' tunnelUrl: 'wss://api.tunnel.example.com/' ``` ### ddns TODO ### mdns enabled by default Although it does not announce itself, Goldilocks is discoverable via mDNS with the special query `_cloud._tcp.local`. This is so that it can be easily configured via Desktop and Mobile apps when run on devices such as a Raspberry Pi or SOHO servers. ```yaml mdns: disabled: false port: 5353 broadcast: '224.0.0.251' ttl: 300 ``` You can discover goldilocks with `mdig`. ``` npm install -g git+https://git.daplie.com/Daplie/mdig.git mdig _cloud._tcp.local ``` ### socks5 Run a Socks5 proxy server. ```yaml socks5: enable: true port: 1080 ``` ### api See [API.md](/API.md) @tigerbot: How are the APIs used (in terms of URL, Method, Headers, etc)? TODO ---- * http - nowww module * http - Allow match styles of `www.*`, `*`, and `*.example.com` equally * http - redirect based on domain name (not just path) * tcp - bind should be able to specify localhost, uniquelocal, private, or ip * tcp - if destination host is omitted default to localhost, if dst port is missing, default to src * sys - handle SIGHUP * sys - `curl https://daplie.me/goldilocks | bash -s example.com` * oauth3 - `example.com/.well-known/domains@oauth3.org/directives.json` * oauth3 - commandline questionnaire * modules - use consistent conventions (i.e. address vs host + port) * tls - tls.acme vs tls.modules.acme * tls - forward should be able to match on source port to reach different destination ports