Run a front door

A front door lets ordinary Open Payments clients pay nodes that have no public address, such as a desktop app on a laptop. Each node that picks it is reached at <node ID>.<your domain>. The project runs one for dassiepay.net, which a node without a hostname keeps as its relay by default. This page is for running your own.

What it does

A front door is a mode of the dassie binary, dassie front-door, and not a node: it has no ledger, no wallet and no database. Nodes that choose it as their relay keep a connection open to it. When a request comes in for <node ID>.<domain>, it passes the request down that node's connection and the node's answer back.

• It passes on Open Payments requests only. Anything else is turned away before it reaches a node.
• It returns only JSON and only the headers an Open Payments client needs, so no node can put a page, a download or a cookie on your domain.
• A browser that opens a node's address gets a small page of the front door's own, saying what the address is and whether the node is connected.
• It also answers at <name>.<domain> for the names nodes hold, which it reads from the registrars' lists on the bootstrap nodes.

What you need

• A Linux server with a public address, with TCP and UDP port 443 open. Nodes connect over QUIC on UDP, clients over HTTPS on TCP, and nodes without a hostname whose UDP is blocked carry QUIC over a WebSocket on TCP. A front door takes port 443 for itself, so give it a host of its own, apart from your node.
• A domain, with a wildcard record, *.<domain>, of type A (and AAAA if the server has IPv6) pointing at the server. It covers every node's address, and relay.<domain>, where nodes connect.
• A certificate for *.<domain>. A wildcard certificate needs the DNS-01 challenge, such as certbot's with the plugin for your DNS provider.

Set it up

1. Make the front door's user, before anything that needs its group:

   $sudo useradd --system --no-create-home --shell /usr/sbin/nologin dassie-front-door

2. Get the certificate. Install deploy-certificate.sh as certbot's deploy hook first, /etc/letsencrypt/renewal-hooks/deploy/dassie-front-door.sh: it copies each new certificate to /etc/dassie-front-door/tls/, readable by the front door's user. With Google Cloud DNS, for example:

   $sudo certbot certonly --non-interactive --agree-tos -m you@example.com \
       --dns-google --dns-google-credentials /etc/letsencrypt/dns.json \
       -d '*.example.com' \
       --deploy-hook /etc/letsencrypt/renewal-hooks/deploy/dassie-front-door.sh

   The front door reads the files again every minute, so a renewal takes effect without a restart. Give certbot a DNS credential that can change your front door's zone and nothing else: the front door's README shows how on Google Cloud.

3. Install dassie without a node. The installer checks the release's signature, as it does for a node, and --no-service leaves out the node's units:

   $curl --proto =https --tlsv1.2 -sSf https://sh.dassie.land | sh -s -- --no-service

4. Install the unit, dassie-front-door.service, as /etc/systemd/system/dassie-front-door.service, from the repository at your release's tag. Set your domain in it:

   Environment=DASSIE_FRONT_DOOR_DOMAIN=example.com

   Then start it:

   $sudo systemctl enable --now dassie-front-door

   At its first start, it makes its own key, in /var/lib/dassie-front-door/front-door.key.

5. Read the line that names your front door, which it logs at every start:

   $journalctl -u dassie-front-door | grep DASSIE_RELAY
   … nodes name this front door as their relay with DASSIE_RELAY='{"id":"…","url":"https://relay.example.com","publicKey":"…","slhDsaPublicKey":"…"}'

   That is what you hand the owners of nodes, below.

Settings

Each setting is an environment variable. Most have a flag of dassie front-door that overrides it; the last two have none.

dassie front-door --make-key makes the key file if there is none, prints the line that names the front door, and exits. The unit runs it before each start. Environment variables and The dassie command have the details.

Naming it as a node's relay

A node keeps one relay. Without a hostname, that is the dassiepay.net front door by default, unless its owner names another. A node uses your front door once its owner puts your line in DASSIE_RELAY, and its address under your domain in DASSIE_PUBLIC_NAMES. A node with a hostname answers under its hostname alone, so it has no use for a front door. On a server without a hostname, a periphery node:

$sudo systemctl edit dassie

[Service]
Environment='DASSIE_RELAY={"id":"…","url":"https://relay.example.com","publicKey":"…","slhDsaPublicKey":"…"}'
Environment=DASSIE_PUBLIC_NAMES=<node ID>.example.com

The node then keeps a connection to your front door, and answers at https://<node ID>.example.com. The second variable also lets it answer at <name>.example.com for each name it holds. Your front door takes the place of the default one, so the node's address at dassiepay.net, still the payment pointer its wallet shows, no longer reaches it. The wallet says so; hand out the address under your domain instead. For the desktop app, see How others reach you.

What a front door sees

A front door holds the secure connection to each client, so it reads every request it passes on and every answer, including the secret that sets up an incoming payment. It also learns which nodes are online, since when, and from which address. Run it as you would want others to run yours, on a host that runs nothing else. The project's front door at dassiepay.net sees the same of every node that keeps it, which a node without a hostname does by default. The unit runs it as its own user, sandboxed, with nothing but the right to bind port 443.

What it cannot do is change a node's answers unseen: each node signs its answers with its own key, and a Dassie client checks the signature against the node ID. Signed responses and names says more.

Each node counts every request through your front door as coming from one client, at the rate it allows any one client. Your front door gives each of its clients a share of that, but a few busy clients can still use up a node's whole budget for it.

Updating it

Install the new release as in step 3, take the release's unit file again, keeping your changes such as the domain, and restart:

$sudo systemctl daemon-reload
$sudo systemctl restart dassie-front-door

A new release may need more of the unit, such as a higher file limit, so do not skip the unit. Without daemon-reload, systemd keeps the unit it read before.

Nodes of 0.3.0 and later speak only version 2 of the peer protocol, dassie/2, so they reach no front door of 0.2.x. A front door's ID changed in 0.3.0 too, since an ID now commits to a second key derived from the key file. The key file stays, but after that update, hand nodes the new line it logs.

Not there yet

A node owner's own domain pointed at a front door, with a certificate for that name and a DNS record that names the node, is not there yet. Neither is the consent page for owner apps (a front door answers that route with an error that says so), a node telling clients apart behind its front door, or a front door finding nodes that chose another relay. What's next

How front doors work, in the spec, and why nodes without a public address need them.