Goldilocks

The node.js netserver that's just right.

• HTTPS Web Server with Automatic TLS (SSL) via ACME (Let's Encrypt)
  • 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

# 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

goldilocks

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)

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)

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

index       Set to `false` to disable the default behavior of loading `index.html` in directories
            ex: `false`

dotfiles    Set to `allow` to load dotfiles rather than ignoring them
            ex: `"allow"`

redirect    Set to `false` to disable the default behavior of ensuring that directory paths end in '/'
            ex: `false`

indexes     An array of directories which should be have indexes served rather than blocked
            ex: `[ '/' ]` will allow all directories indexes to be served

Example config:

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:

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:

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:

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:

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:

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

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

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:

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:

tunnel:
  - 'some.jwt_encoded.token'
  - jwt: 'other.jwt_encoded.token'
    tunnelUrl: 'wss://api.tunnel.example.com/'

NOTE: The more common way to use the tunnel with goldilocks is to use the API to have goldilocks get a token from oauth3.org. In order to do this you will need to have initialized goldilocks with a token that has the dns and domains scopes. This is probably easiest to do with the daplie-desktop-app, which will also get the first tunnel token for you.

If you want to add more domains to handle on your device while using the tunnel you will need to manually get a new token that will tell the tunnel server to deliver the requests to the new domain(s) to your device. The first step in this is to attach the new domains to your device. To get the name of the device you can use the config API, but it's probably easiest to ssh onto the device and get the hostname. You can also use the daplie cli tool to see what device name your other domains are routed to.

# for every new domain you want to route attach the domain to your device
daplie devices:attach -n $new_domain -d $device_name

After that step you will need to use the API to get goldilocks to get a new token that includes the new domains you attached. It is also recommended but not required to remove the older token with the incomplete list of domains. Run the following commands from the unit.

# remove the old token
rm /opt/goldilocks/lib/node_modules/goldilocks/var/tokens.json

# set the "refresh_token" to a bash variable `token`
TOKEN=$(python -mjson.tool /opt/goldilocks/lib/node_modules/goldilocks/var/owners.json | sed -n 's|\s*"refresh_token": "\(.*\)",|\1|p')

# tell goldilocks to get a new tunnel token
curl -H "authorization: bearer $TOKEN" -X POST https://localhost.admin.daplie.me/api/goldilocks@daplie.com/tunnel

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.

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.

socks5:
  enable: true
  port: 1080

api

See 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