clavarium 0.2.379-next.1 → 0.2.381-next.1

package/deploy/clavarium-host

@@ -166,7 +166,7 @@ CADDYFILE="/etc/caddy/Caddyfile"
 MESH_CADDY="/etc/caddy/clavarium-meshcentral.caddy"
 
 refuse() { echo "REFUSED: $*" >&2; exit 78; }
-usage() { echo "usage: clavarium-host [--say-only [--data DIR] [--mnt DIR]] <vm|shelf|folder|work|view|tools|mounts|operator|machines|disks|net|git|server|update|wifi|meshcentral> <verb> [arguments]" >&2; exit 64; }
+usage() { echo "usage: clavarium-host [--say-only [--data DIR] [--mnt DIR]] <vm|shelf|folder|work|view|tools|mounts|operator|machines|disks|net|git|server|update|wifi|meshcentral|relay> <verb> [arguments]" >&2; exit 64; }
 
 SAY="no"; DATA=""; MNT=""; TEST=""
 while [ $# -gt 0 ]; do
@@ -738,6 +738,8 @@ AREA="$1"; VERB="$2"; shift 2
 # verbs, and commands run inside a machine (the server's own probes, mostly), are not written.
 case "$AREA $VERB" in
     "vm exec"|"vm ping"|"vm states"|"vm info"|"server logs"|"server room"|"server usage"|"shelf info"|"shelf room"|"shelf list"|"shelf size"|"shelf exec"|"git read"|"work room"|"disks list"|"disks room"|"machines places"|"machines moving"|"machines old"|"net taps"|"net leases"|"wifi status"|"wifi scan"|"path held"|"disk room"|"update check"|"meshcentral status"|"operator "*) : ;;
+    # A one-time code is not written down, even spent.
+    "relay join") [ "$SAY" = yes ] || logger -t clavarium-host -- "relay join (a home asks to join the relay)" 2>/dev/null || true ;;
     *) [ "$SAY" = yes ] || logger -t clavarium-host -- "$AREA $VERB$(printf ' %.80s' "$@" | head -c 400)" 2>/dev/null || true ;;
 esac
 
@@ -1521,6 +1523,15 @@ OOMScoreAdjust=-900'
         systemctl stop "clvread-$1_*.service" >/dev/null 2>&1 || true
         systemctl reset-failed "clvread-$1_*.service" >/dev/null 2>&1 || true
         exit 0 ;;
+    "relay join")
+        # A HOME ASKS TO JOIN THIS MACHINE'S RELAY (server/relayjoin.mjs, POST /c/relay-join): <code>
+        # ssh-ed25519 <key>. The code is one the owner made here as root (`sudo clavarium relay invite
+        # NAME`); its hash, its name and its end are kept where the server cannot read them. Checked,
+        # spent and acted on as root by deploy/online.mjs (relay join): a wrong, used or expired code is
+        # refused (78) and counted; a good one adds this PUBLIC key to the relay, bounded to two ports
+        # of its own. What it prints holds nothing secret: the relay's address, fingerprint, two ports.
+        [ $# -eq 3 ] && [[ "$1" =~ ^[A-HJKMNP-Z2-9]{8}$ ]] && [ "$2" = "ssh-ed25519" ] && [[ "$3" =~ ^[A-Za-z0-9+/]{68}$ ]] || usage
+        run "$UPDATER_NODE" "$CODE/current/app/deploy/clavarium.mjs" relay join "$1" "$2 $3" ;;
     "update check")
         # Asks the registry what is out on the channel, now, and prints what
         # the updater knows (state.json). No argument: the registry, the name

package/deploy/clavarium-tunnel

@@ -4,7 +4,13 @@
 # written by install.sh and kept up to date by the updater). Root installs it at
 # /usr/local/sbin/clavarium-tunnel; it runs as the clavarium-tunnel account.
 #
-#   clavarium-tunnel RELAY PORT
+#   clavarium-tunnel RELAY PORT [TLS-PORT HTTP-PORT]
+#
+# WITHOUT TLS-PORT AND HTTP-PORT: the relay's first home (its principal), on
+# 8443 and 8080, held on every address of the relay, as it always was. WITH
+# THEM: a home the principal added (clavarium-relay add-home), on the ports it
+# was given, held on the relay's 127.0.0.1 only -- its router alone reaches
+# them, and the relay lets this key hold no other port.
 #
 # A CUT OF THE NETWORK is noticed in 20 to 30 seconds (a keepalive every 10 s,
 # two missed), and the tunnel is tried again 5 s later by systemd, as long as it
@@ -17,8 +23,13 @@
 # the count starts over.
 # ---------------------------------------------------------------------------
 set -u
-[ $# -eq 2 ] || { echo "usage: clavarium-tunnel RELAY PORT" >&2; exit 64; }
+[ $# -eq 2 ] || [ $# -eq 4 ] || { echo "usage: clavarium-tunnel RELAY PORT [TLS-PORT HTTP-PORT]" >&2; exit 64; }
 relay="$1"; port="$2"
+forwards=(-R '*:8443:127.0.0.1:443' -R '*:8080:127.0.0.1:80')
+if [ $# -eq 4 ]; then
+    for p in "$3" "$4"; do [[ "$p" =~ ^[0-9]{4,5}$ ]] && [ "$p" -le 65535 ] || { echo "clavarium-tunnel: not a port: $p" >&2; exit 64; }; done
+    forwards=(-R "127.0.0.1:$3:127.0.0.1:443" -R "127.0.0.1:$4:127.0.0.1:80")
+fi
 [[ "$relay" =~ ^[A-Za-z0-9.-]{1,253}$ ]] || { echo "clavarium-tunnel: not a host name: $relay" >&2; exit 64; }
 [[ "$port" =~ ^[0-9]{1,5}$ ]] || { echo "clavarium-tunnel: not a port: $port" >&2; exit 64; }
 home=/var/lib/clavarium-tunnel
@@ -30,7 +41,7 @@ trap 'rm -f "$said"' EXIT
 started=$SECONDS
 ssh -N -T -o BatchMode=yes -o IdentitiesOnly=yes -o "IdentityFile=$home/key" -o "UserKnownHostsFile=$home/known_hosts" \
     -o StrictHostKeyChecking=yes -o ExitOnForwardFailure=yes -o ServerAliveInterval=10 -o ServerAliveCountMax=2 -o ConnectTimeout=15 \
-    -R '*:8443:127.0.0.1:443' -R '*:8080:127.0.0.1:80' -p "$port" "clavarium-tunnel@$relay" 2>"$said"
+    "${forwards[@]}" -p "$port" "clavarium-tunnel@$relay" 2>"$said"
 code=$?
 # Said to the journal once it ended -- read through a second writer (tee) it could still be on its way
 # when it was looked at (found on a CI runner): the refusal then passed for a cut.

package/deploy/clavarium.mjs

@@ -11,7 +11,9 @@
  *   sudo clavarium online --relay HOST --domain NAME [...]   see deploy/online.mjs
  *   sudo clavarium online --port --domain NAME [...]
  *   sudo clavarium key                                       the public keys, text and QR
+ *   sudo clavarium online --relay PRINCIPAL --domain NAME --join CODE   another home on the same relay
  *   sudo clavarium relay status | repair | update-os | update-relay | forget-setup-key
+ *   sudo clavarium relay homes | invite NAME | add-home NAME --key KEY | remove-home NAME
  *   sudo clavarium doctor [--fix]                            what works, what does not, what to do
  *   sudo clavarium password EMAIL                            a new password for an administrator
  *   sudo clavarium client-id [ID]                            the sign-in client id (no ID: a random one)
@@ -70,7 +72,9 @@ if (verb !== 'install') {
         + '  sudo clavarium online --relay HOST --domain NAME                  then online, through a relay of yours\n'
         + '  sudo clavarium online --port --domain NAME                        or with ports 80 and 443 open\n'
         + '  sudo clavarium key                                                the public keys again (text and QR)\n'
+        + '  sudo clavarium online --relay PRINCIPAL --domain NAME --join CODE  another home on the relay of PRINCIPAL\n'
         + '  sudo clavarium relay status|repair|update-os|update-relay|forget-setup-key\n'
+        + '  sudo clavarium relay homes|invite NAME|add-home NAME --key KEY|remove-home NAME\n'
         + '  sudo clavarium doctor [--fix]                                     what works, what does not, what to do\n'
         + '  sudo clavarium password EMAIL                                     a new password for an administrator\n'
         + '  sudo clavarium client-id [ID]                                     the sign-in client id (no ID: a random one)\n\n'

package/deploy/install.sh

@@ -38,6 +38,8 @@
 #                      server mode)
 #   --relay-installed  the relay was set up already (by `clavarium online`):
 #                      do not print the command to run on it
+#   --relay-ports T,H  the two ports the relay gave this machine, when it is
+#                      not the relay's first home (`clavarium online --join`)
 #   --name NAME        the name of this Clavarium, under its icon and in its
 #                      tab (default: drawn from --domain); changed in Settings.
 #                      Letters, digits, spaces, dots, hyphens: 30 at most
@@ -118,7 +120,7 @@ bad() { echo "install: $*" >&2; echo "usage: install.sh --domain NAME --operator
 refuse() { echo "install: REFUSED: $*" >&2; exit 78; }
 step() { echo "== $*"; }
 
-DOMAIN=""; OPERATORS=""; PORT="7717"; CORE_ONLY="no"; DRY="no"; RELAY=""; RELAY_PORT="22"; LOCAL="no"; KEEP_RELEASE="no"; RELAY_INSTALLED="no"
+DOMAIN=""; OPERATORS=""; PORT="7717"; CORE_ONLY="no"; DRY="no"; RELAY=""; RELAY_PORT="22"; RELAY_PORTS=""; LOCAL="no"; KEEP_RELEASE="no"; RELAY_INSTALLED="no"
 VERSION=""; FROM_DIR=""; UPDATES=""; WINDOW=""; CHANNEL=""; APP_NAME=""; CLIENT_ID=""
 while [ $# -gt 0 ]; do
     case "$1" in
@@ -136,6 +138,7 @@ while [ $# -gt 0 ]; do
         --channel) CHANNEL="${2:-}"; shift 2 || bad "--channel needs a value" ;;
         --keep-release) KEEP_RELEASE="yes"; shift ;;
         --relay-installed) RELAY_INSTALLED="yes"; shift ;;
+        --relay-ports) RELAY_PORTS="${2:-}"; shift 2 || bad "--relay-ports needs a value" ;;
         --name) APP_NAME="${2:-}"; [ -n "$APP_NAME" ] || bad "--name needs a value"; shift 2 ;;
         --client-id) CLIENT_ID="${2:-}"; [ -n "$CLIENT_ID" ] || bad "--client-id needs a value"; shift 2 ;;
         --dry-run) DRY="yes"; shift ;;
@@ -161,7 +164,9 @@ if [ -n "$RELAY" ]; then
     [[ "$RELAY" =~ ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,24}$|^([0-9]{1,3}\.){3}[0-9]{1,3}$ ]] || bad "--relay is the name or the address of the relay machine"
     [[ "$RELAY_PORT" =~ ^[0-9]{1,5}$ ]] && [ "$RELAY_PORT" -ge 1 ] && [ "$RELAY_PORT" -le 65535 ] || bad "--relay-port is a port number"
     [ "$CORE_ONLY" = "no" ] || bad "--relay comes with the edge: it cannot go with --core-only"
+    [ -z "$RELAY_PORTS" ] || [[ "$RELAY_PORTS" =~ ^[0-9]{4,5},[0-9]{4,5}$ ]] || bad "--relay-ports is two ports: TLS,HTTP"
 fi
+[ -z "$RELAY_PORTS" ] || [ -n "$RELAY" ] || bad "--relay-ports goes with --relay"
 
 # WHAT IS INSTALLED: an exact version from npm, or a working tree (development).
 [ -z "$VERSION" ] || [[ "$VERSION" =~ ^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,6}(-[0-9A-Za-z.-]{1,40})?$ ]] || bad "--version is an exact version, like 1.2.3 or 1.3.0-next.1"
@@ -744,8 +749,8 @@ if [ -n "$RELAY" ]; then
     fi
     # The unit is the updater's (deploy/tunnel.mjs, tunnelUnit): one text, kept up to date by each update.
     install -o root -g root -m 0755 "$APP/deploy/clavarium-tunnel" /usr/local/sbin/clavarium-tunnel
-    "$NODE_DIR/bin/node" --input-type=module -e 'const { tunnelUnit } = await import(process.argv[1]); process.stdout.write(tunnelUnit(process.argv[2], process.argv[3]));' \
-        "$APP/deploy/tunnel.mjs" "$RELAY" "$RELAY_PORT" > /etc/systemd/system/clavarium-tunnel.service
+    "$NODE_DIR/bin/node" --input-type=module -e 'const { tunnelUnit } = await import(process.argv[1]); const [t, h] = (process.argv[4] || "").split(","); process.stdout.write(tunnelUnit(process.argv[2], process.argv[3], undefined, t ? { tls: t, http: h } : null));' \
+        "$APP/deploy/tunnel.mjs" "$RELAY" "$RELAY_PORT" "$RELAY_PORTS" > /etc/systemd/system/clavarium-tunnel.service
     systemctl daemon-reload
     systemctl enable --quiet clavarium-tunnel.service
     systemctl restart clavarium-tunnel.service

package/deploy/online.mjs

@@ -13,6 +13,26 @@
  *   --port         this machine is reachable on 80 and 443 (a server at a host,
  *                  or a router whose ports were opened).
  *
+ * SEVERAL HOMES ON ONE RELAY. The machine that set the relay up is its
+ * PRINCIPAL: it alone holds the relay's maintenance key. Another Clavarium
+ * joins the same relay without any access to it:
+ *
+ *   on the principal   sudo clavarium relay invite NAME      a one-time code (8 letters and
+ *                      digits, 30 minutes, good once) for the domain NAME
+ *   on the new home    sudo clavarium online --relay PRINCIPAL --domain NAME --join CODE
+ *
+ * The new home sends the code and its PUBLIC tunnel key to the principal over
+ * HTTPS (POST /c/relay-join, server/relayjoin.mjs, then the host program, then
+ * `clavarium relay join` here, as root). The principal checks the code, spends
+ * it, adds the key to the relay (clavarium-relay add-home, through its
+ * maintenance key) and answers with the relay's address, its host key's
+ * fingerprint and the two ports the relay gave. The new home checks that
+ * fingerprint against the relay itself, and goes online on its own ports.
+ * Nothing else is copied by hand. By hand all the same (no code): on the
+ * principal `sudo clavarium relay add-home NAME --key KEY`, which prints the
+ * line to type on the new home (--relay-ports, --relay-fingerprint).
+ * A second owner is let in this way only: by the principal's owner.
+ *
  * NOTHING IS CUT BEFORE A REAL TEST FROM THE INTERNET HAS PASSED: Let's
  * Encrypt's staging service is asked for a certificate for the domain, so it
  * really comes to this machine (through the relay, or through the open
@@ -24,6 +44,7 @@
  * `sys`, so the tests can stand in for SSH, npm and DNS.
  */
 import { spawn } from 'node:child_process';
+import { createHash, randomInt } from 'node:crypto';
 import { relayOfUnit, TUNNEL_UNIT } from './tunnel.mjs';
 import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, mkdtempSync, renameSync, openSync, readSync, writeSync, closeSync } from 'node:fs';
 import { promises as dns } from 'node:dns';
@@ -62,11 +83,13 @@ export class Failed extends Error {}
 export const USAGE = [
     'usage: sudo clavarium online --relay HOST --domain NAME [--relay-user USER] [--relay-port N] [--admin EMAIL]',
     '                             [--relay-fingerprint SHA256:...] [--keep-setup-key] [--yes]',
+    '   or: sudo clavarium online --relay PRINCIPAL --domain NAME --join CODE [--admin EMAIL]',
+    '   or: sudo clavarium online --relay HOST --domain NAME --relay-ports TLS,HTTP --relay-fingerprint SHA256:... [--relay-port N]',
     '   or: sudo clavarium online --port --domain NAME [--admin EMAIL]',
 ].join('\n');
 
 export function parseOnline(args) {
-    const o = { askRelay: false, relay: '', user: 'root', relayPort: '22', domain: '', admin: '', fingerprint: '', keepSetupKey: false, yes: false, port: false };
+    const o = { askRelay: false, relay: '', user: 'root', relayPort: '22', domain: '', admin: '', fingerprint: '', keepSetupKey: false, yes: false, port: false, join: '', ports: null };
     const value = (i, name) => { const v = args[i + 1]; if (v === undefined || v.startsWith('--')) throw new Bad(`${name} needs a value`); return v; };
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -80,9 +103,25 @@ export function parseOnline(args) {
             case '--keep-setup-key': o.keepSetupKey = true; break;
             case '--yes': o.yes = true; break;
             case '--port': o.port = true; break;
+            case '--join': o.join = normalCode(value(i, a)); i++; if (!CODE.test(o.join)) throw new Bad('--join is the code the principal gave: 8 letters and digits, like ABCD-EFGH'); break;
+            case '--relay-ports': {
+                const m = /^(\d{4,5}),(\d{4,5})$/.exec(value(i, a)); i++;
+                if (!m || [m[1], m[2]].some((p) => +p < 1024 || +p > 65535)) throw new Bad('--relay-ports is the two ports the relay gave: TLS,HTTP');
+                o.ports = { tls: m[1], http: m[2] }; break;
+            }
             default: throw new Bad(`unknown parameter: ${a}`);
         }
     }
+    if (o.join || o.ports) {
+        /* A home the principal adds: the relay is not set up from here, and no account of it is used. */
+        if (o.join && o.ports) throw new Bad('--join or --relay-ports, not both');
+        if (!o.relay) throw new Bad(o.join ? '--join goes with --relay PRINCIPAL: the name of the Clavarium that gave the code' : '--relay-ports goes with --relay HOST');
+        if (o.keepSetupKey || o.user !== 'root') throw new Bad('--relay-user and --keep-setup-key are for the relay\'s first home; a home that joins uses no account of the relay');
+        if (o.join && !DOMAIN.test(o.relay)) throw new Bad('--relay is the NAME of the Clavarium that gave the code (it is asked over HTTPS)');
+        if (o.join && (o.fingerprint || o.relayPort !== '22')) throw new Bad('with --join, the principal says the relay\'s address and fingerprint');
+        if (o.ports && !o.fingerprint) throw new Bad('--relay-ports goes with --relay-fingerprint (what the principal printed)');
+        if (o.join) o.principal = o.relay;
+    }
     if (o.relay && o.port) throw new Bad('say how it will be reached: --relay HOST or --port, not both');
     /* Neither: the usual case -- the domain points to the relay, which is
        reached by the domain itself (its address is not needed). */
@@ -196,6 +235,8 @@ export async function keepRelayCurrent(sys, P = PATHS, { done, unit = TUNNEL_UNI
     let conf = readRelayConf(P);
     if (!conf) { try { const at = relayOfUnit(readFileSync(unit, 'utf8')); if (at) conf = { HOST: at.relay, PORT: at.port }; } catch { /* no tunnel */ } }
     if (!conf) return { state: 'none' };
+    /* A home the principal added: the relay is the principal's to keep. */
+    if (conf.ROLE === 'home') return { state: 'none' };
     if (!existsSync(keyFiles(P).keeper)) return { state: 'no-key' };
     const version = relayVersion(P);
     if (!version) return { state: 'none' };
@@ -407,6 +448,7 @@ async function setUpRelay(sys, P, o, keys) {
     const f = keyFiles(P);
     const conf = { HOST: o.relay, PORT: o.relayPort, USER: o.user };
     const prior = readRelayConf(P);
+    if (prior?.ROLE === 'home') throw new Refused(`this machine is a home of the relay ${prior.HOST}, added by its principal: it does not set a relay up`);
     /* Run again after the relay was set up (a test that failed, a DNS record
        made late): the maintenance account answers, the setup key is not needed. */
     if (prior && prior.HOST === o.relay && existsSync(f.knownHosts)) {
@@ -447,7 +489,7 @@ async function setUpRelay(sys, P, o, keys) {
        input, a program it starts (apt-get...) could eat the rest of it. */
     const runner = 'f="$(mktemp)"; cat > "$f"; bash "$f" "$@" </dev/null; s=$?; rm -f -- "$f"; exit $s';
     const r = await sys.run(['ssh', ...sshOptions(f.setup, f.knownHosts, o.relayPort), `${o.user}@${o.relay}`,
-        `${sudo}bash -c ${quote(runner)} relay.sh --key ${quote(keys.tunnel)} --keeper-key ${quote(keys.keeper)}`], { input: script, stream: true });
+        `${sudo}bash -c ${quote(runner)} relay.sh --key ${quote(keys.tunnel)} --keeper-key ${quote(keys.keeper)} --name ${quote(o.domain)}`], { input: script, stream: true });
     if (r.code !== 0) throw new Failed(`the relay could not be set up (exit ${r.code}, above: why). This machine is still in local mode`);
     const next = { ...conf, SETUP_KEY: 'kept' };
     writeRelayConf(P, next);
@@ -459,11 +501,52 @@ async function setUpRelay(sys, P, o, keys) {
     return readRelayConf(P);
 }
 
-/* The tunnel, for the test only: the service comes with server mode. */
+/* A HOME THE PRINCIPAL ADDED: the relay's host key checked against the fingerprint the principal gave
+   (`from`: who gave it), kept for the tunnel, and the relay and its ports kept in relay.conf. The relay
+   is maintained by its principal: this machine holds no key of its maintenance account. */
+async function useRelay(sys, P, o, at, from) {
+    o.relay = at.host; o.relayPort = String(at.port); o.ports = { tls: String(at.tls), http: String(at.http) };
+    const scanned = await scanRelay(sys, o, sys.now() + WAIT_MS);
+    const { file: pending, print } = await fingerprintOf(sys, P, scanned);
+    rmSync(pending, { force: true });
+    if (print !== at.fingerprint) throw new Refused(`${o.relay} answers with the key ${print}, not ${at.fingerprint} (said by ${from}): it may not be the relay. Nothing was changed`);
+    sys.print(`The relay ${o.relay}: its fingerprint is the one ${from} gave. Its ports for this machine: ${o.ports.tls} and ${o.ports.http}.`);
+    writeFileSync(join(P.tunnel, 'known_hosts'), `${scanned}\n`, { mode: 0o644 });
+    await sys.run(['chown', 'clavarium-tunnel:clavarium-tunnel', join(P.tunnel, 'known_hosts')]);
+    writeRelayConf(P, { HOST: o.relay, PORT: o.relayPort, TLS_PORT: o.ports.tls, HTTP_PORT: o.ports.http, ROLE: 'home', ...(o.principal ? { PRINCIPAL: o.principal } : {}) });
+}
+
+/* --join: the code and this machine's PUBLIC tunnel key to the principal, over HTTPS (its certificate
+   checked as any browser would); its answer is read field by field. Run again after a failed test: the
+   relay and the ports kept from the first time, no code needed. */
+async function joinRelay(sys, P, o, keys) {
+    const prior = readRelayConf(P);
+    if (prior?.ROLE === 'home' && prior.TLS_PORT && existsSync(join(P.tunnel, 'known_hosts'))) {
+        Object.assign(o, { relay: prior.HOST, relayPort: prior.PORT, ports: { tls: prior.TLS_PORT, http: prior.HTTP_PORT } });
+        sys.print(`This machine joined the relay ${prior.HOST} already (ports ${prior.TLS_PORT} and ${prior.HTTP_PORT}).`);
+        return;
+    }
+    sys.print(`Asking ${o.principal} to add this machine to its relay (code ${o.join.slice(0, 4)}-${o.join.slice(4)})...`);
+    let r;
+    try { r = await sys.post(`https://${o.principal}${JOIN_PATH}`, { code: o.join, key: keys.tunnel.split(' ').slice(0, 2).join(' ') }); } catch (error) { throw new Failed(`${o.principal} did not answer over HTTPS: ${error.message}`); }
+    const said = typeof r?.body?.error === 'string' ? r.body.error.slice(0, 200) : '';
+    if (r?.status === 403) throw new Refused(`${o.principal} refused the code${said ? `: ${said}` : ''}. Ask its owner for a new one: sudo clavarium relay invite ${o.domain}`);
+    if (r?.status === 429) throw new Failed(`${o.principal} says too many tries: wait a minute, then run this again`);
+    if (r?.status !== 200) throw new Failed(`${o.principal} did not add this machine (HTTP ${r?.status})${said ? `: ${said}` : ''}`);
+    const a = r.body ?? {};
+    if (a.name !== o.domain) throw new Refused(`the code was made for ${String(a.name).slice(0, 80)}, not ${o.domain}`);
+    const port = (v, lo) => Number.isInteger(v) && v >= lo && v <= 65535;
+    if (!HOST.test(a.relay?.host ?? '') || !port(a.relay?.port, 1) || !PRINT.test(a.relay?.fingerprint ?? '') || !port(a.ports?.tls, 1024) || !port(a.ports?.http, 1024)) throw new Failed(`${o.principal} answered something else than a relay and two ports`);
+    await useRelay(sys, P, o, { host: a.relay.host, port: a.relay.port, fingerprint: a.relay.fingerprint, tls: a.ports.tls, http: a.ports.http }, o.principal);
+}
+
+/* The tunnel, for the test only: the service comes with server mode. The relay's first home on 8443
+   and 8080 (every address, as ever); a home it added on its own ports, on the relay's loopback. */
 function startTunnel(sys, P, o) {
     const lines = [];
+    const forwards = o.ports ? ['-R', `127.0.0.1:${o.ports.tls}:127.0.0.1:443`, '-R', `127.0.0.1:${o.ports.http}:127.0.0.1:80`] : ['-R', '*:8443:127.0.0.1:443', '-R', '*:8080:127.0.0.1:80'];
     const proc = sys.start(['sudo', '-u', 'clavarium-tunnel', 'ssh', '-N', '-T', ...sshOptions(join(P.tunnel, 'key'), join(P.tunnel, 'known_hosts'), o.relayPort),
-        '-o', 'ExitOnForwardFailure=yes', '-R', '*:8443:127.0.0.1:443', '-R', '*:8080:127.0.0.1:80', `clavarium-tunnel@${o.relay}`], { onLine: (l) => lines.push(l) });
+        '-o', 'ExitOnForwardFailure=yes', ...forwards, `clavarium-tunnel@${o.relay}`], { onLine: (l) => lines.push(l) });
     return { proc, lines };
 }
 
@@ -477,6 +560,7 @@ async function switchToServer(sys, P, o) {
     const port = readConf(P.updateConf).PORT;
     const argv = ['/bin/bash', join(app, 'deploy', 'install.sh'), '--keep-release', '--domain', o.domain, '--operator', o.admin, '--port', port];
     if (o.relay) argv.push('--relay', o.relay, '--relay-port', o.relayPort, '--relay-installed');
+    if (o.relay && o.ports) argv.push('--relay-ports', `${o.ports.tls},${o.ports.http}`);
     sys.print('');
     sys.print('Switching to server mode: HTTPS, sign-in, the administrator...');
     const r = await sys.run(argv, { stream: true, inherit: true, env: { CLAVARIUM_PASSWORDS_TO: P.passwords } });
@@ -514,7 +598,9 @@ export async function online(o, sys, P = PATHS) {
     }
     await checkDns(sys, o);
     await portsFree(sys);
-    if (o.relay) await setUpRelay(sys, P, o, keys);
+    if (o.join) await joinRelay(sys, P, o, keys);
+    else if (o.ports) await useRelay(sys, P, o, { host: o.relay, port: o.relayPort, fingerprint: o.fingerprint, tls: o.ports.tls, http: o.ports.http }, 'the principal');
+    else if (o.relay) await setUpRelay(sys, P, o, keys);
     let tunnel = null;
     try {
         if (o.relay) {
@@ -532,7 +618,13 @@ export async function online(o, sys, P = PATHS) {
         await doctor(sys, {}, { ...DOCTOR_PATHS, unit: P.unit, relayConf: P.relayConf });
         sys.print('');
         sys.print(`Online: https://${o.domain}`);
-        if (o.relay) sys.print('The relay is watched from here: sudo clavarium relay status');
+        if (o.relay && !o.ports) sys.print('The relay is watched from here: sudo clavarium relay status');
+        if (o.relay && o.ports) {
+            sys.print(`The relay is kept by its principal${o.principal ? `, ${o.principal}` : ''}.`);
+            sys.print(`TO KEEP THE RELAY BLIND for ${o.domain}, add a CAA record to your DNS that names this machine's`);
+            sys.print('certificate account (accounturi=...); without it, whoever controls the relay could obtain a');
+            sys.print(`certificate for ${o.domain}. The account address: sudo grep -rho '"location": *"[^"]*"' /var/lib/caddy/caddy/acme`);
+        }
         sys.print('Anything wrong later: sudo clavarium doctor (it says what to do; --fix repairs what it can)');
         const pw = existsSync(P.passwords) ? readFileSync(P.passwords, 'utf8') : '';
         sys.print('');
@@ -543,12 +635,138 @@ export async function online(o, sys, P = PATHS) {
     } finally { rmSync(P.passwords, { force: true }); }
 }
 
+/* ------------------------- other homes on this relay ------------------------- */
+/* 31 letters and digits a person can read and type: no I, L, O, 0, 1. Eight of them: some 10^12 codes,
+   against WRONG_MAX wrong tries before every invitation is cancelled. */
+export const CODE_LETTERS = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+const CODE = /^[A-HJKMNP-Z2-9]{8}$/;
+export const INVITE_MS = 30 * 60_000;
+export const WRONG_MAX = 10;
+export const JOIN_PATH = '/c/relay-join';
+export const normalCode = (s) => String(s ?? '').toUpperCase().replace(/[\s-]/g, '');
+const hashOf = (code) => createHash('sha256').update(code).digest('hex');
+const invitesFile = (P) => join(P.access, 'invites.json');
+/* Root's, in the access folder (0700): only the hash of each code is kept, with its name and its end. */
+function readInvites(P, now) {
+    let j = {};
+    try { j = JSON.parse(readFileSync(invitesFile(P), 'utf8')); } catch { /* none yet */ }
+    return {
+        invites: (Array.isArray(j.invites) ? j.invites : []).filter((x) => x && /^[0-9a-f]{64}$/.test(x.hash) && DOMAIN.test(x.name ?? '') && x.until > now),
+        wrong: (Array.isArray(j.wrong) ? j.wrong : []).filter((t) => typeof t === 'number' && t > now - INVITE_MS),
+    };
+}
+function writeInvites(P, v) {
+    mkdirSync(P.access, { recursive: true, mode: 0o700 });
+    writeFileSync(`${invitesFile(P)}.new`, `${JSON.stringify(v)}\n`, { mode: 0o600 });
+    renameSync(`${invitesFile(P)}.new`, invitesFile(P));
+}
+/* Only the principal adds homes: the machine that holds the relay's maintenance key, online. */
+function principal(P) {
+    const conf = readRelayConf(P);
+    if (!conf) throw new Refused('this machine has no relay (sudo clavarium online --relay HOST --domain NAME)');
+    if (conf.ROLE === 'home') throw new Refused(`this machine is a home of the relay ${conf.HOST}: only its principal${conf.PRINCIPAL ? ` (${conf.PRINCIPAL})` : ''} adds or removes homes`);
+    const domain = serverModeOf(P);
+    if (!domain) throw new Refused('this machine is not online yet (sudo clavarium online ...)');
+    return { conf, domain };
+}
+
+/* `relay invite NAME`: a one-time code for the home that will be NAME. A new one for the same name
+   replaces the one before. */
+export async function invite(sys, P, name) {
+    if (!DOMAIN.test(name ?? '')) throw new Bad('relay invite NAME: the domain of the new home, lower case, like clav2.example.com');
+    const { conf, domain } = principal(P);
+    if (name === domain) throw new Bad(`${name} is this machine`);
+    const now = sys.now();
+    const v = readInvites(P, now);
+    const code = Array.from({ length: 8 }, () => CODE_LETTERS[randomInt(CODE_LETTERS.length)]).join('');
+    v.invites = [...v.invites.filter((x) => x.name !== name), { hash: hashOf(code), name, until: now + INVITE_MS }];
+    writeInvites(P, v);
+    const shown = `${code.slice(0, 4)}-${code.slice(4)}`;
+    sys.print(`One-time code for ${name} (good once, for ${INVITE_MS / 60_000} minutes):   ${shown}`);
+    sys.print(`On that machine (Clavarium installed; ${name} leading to the relay, like ${domain}), type:`);
+    sys.print(`    sudo clavarium online --relay ${domain} --domain ${name} --join ${shown}`);
+    sys.print(`It joins the relay ${conf.HOST} on ports of its own. Then, for ${name}, a CAA record as for ${domain} keeps the relay blind.`);
+    return { code: shown, name };
+}
+
+/* The principal's name told to the relay (a relay set up before 0.2.0 knew none), then the home added.
+   What the relay printed, read line by line. */
+async function addHomeOnRelay(sys, P, conf, domain, name, key) {
+    const older = (r) => (/not a verb|unknown verb/.test(`${r.err ?? ''}`) ? ': the relay\'s program is older (sudo clavarium relay update-relay)' : '');
+    const n = await keeper(sys, P, conf, ['name-principal', domain]);
+    if (n.code !== 0) throw new Failed(`the relay did not take this machine's name (${tail(n)})${older(n)}`);
+    const r = await keeper(sys, P, conf, ['add-home', name, key]);
+    if (r.code === 78) throw new Refused(`the relay refused: ${tail(r).replace(/^clavarium-relay: REFUSED: /, '')}`);
+    if (r.code !== 0) throw new Failed(`the relay did not add ${name} (${tail(r)})${older(r)}`);
+    const get = (k) => new RegExp(`^${k} (\\S+)$`, 'm').exec(r.out ?? '')?.[1] ?? '';
+    const tls = Number(get('tls-port')); const http = Number(get('http-port')); const fingerprint = get('fingerprint');
+    if (!(tls >= 1024 && tls <= 65535 && http >= 1024 && http <= 65535) || !PRINT.test(fingerprint)) throw new Failed('the relay\'s answer is not two ports and a fingerprint');
+    return { name, relay: { host: conf.HOST, port: Number(conf.PORT), fingerprint }, ports: { tls, http } };
+}
+
+/* `relay join CODE KEY`, as root, for the server's /c/relay-join (through the host program): the code
+   must be one of the owner's, unused and not expired. It is spent BEFORE the relay is asked (good once,
+   whatever happens next); a wrong one is counted, and WRONG_MAX of them within INVITE_MS cancel every
+   invitation. The answer holds nothing secret: the relay's address, its public fingerprint, two ports. */
+export async function joinWithCode(sys, P, given, key) {
+    const code = normalCode(given);
+    if (!CODE.test(code) || !KEY.test(key ?? '')) throw new Bad('relay join CODE KEY');
+    const { conf, domain } = principal(P);
+    const now = sys.now();
+    const v = readInvites(P, now);
+    const at = v.invites.findIndex((x) => x.hash === hashOf(code));
+    if (at < 0) {
+        v.wrong.push(now);
+        const cancel = v.wrong.length >= WRONG_MAX;
+        if (cancel) v.invites = [];
+        writeInvites(P, v);
+        throw new Refused(cancel ? 'not a valid code; too many wrong codes: every invitation was cancelled' : 'not a valid code (wrong, used or expired)');
+    }
+    const [spent] = v.invites.splice(at, 1);
+    writeInvites(P, v);
+    return addHomeOnRelay(sys, P, conf, domain, spent.name, key);
+}
+
 /* `sudo clavarium relay VERB` */
 export async function relayCommand(args, sys, P = PATHS) {
     const conf = readRelayConf(P);
     if (!conf) throw new Refused('this machine has no relay (sudo clavarium online --relay HOST --domain NAME)');
     const [verb, ...rest] = args;
+    if (conf.ROLE === 'home') throw new Refused(`this machine is a home of the relay ${conf.HOST}: the relay is kept by its principal${conf.PRINCIPAL ? `, ${conf.PRINCIPAL}` : ''}`);
     switch (verb) {
+        case 'invite': {
+            if (rest.length !== 1) throw new Bad('relay invite NAME');
+            await invite(sys, P, rest[0]);
+            return;
+        }
+        case 'join': {
+            if (rest.length !== 2) throw new Bad('relay join CODE KEY');
+            sys.print(JSON.stringify(await joinWithCode(sys, P, rest[0], rest[1])));
+            return;
+        }
+        case 'add-home': {
+            const [name, flag, ...words] = rest;
+            const key = words.join(' ');
+            if (!DOMAIN.test(name ?? '') || flag !== '--key' || !KEY.test(key)) throw new Bad('relay add-home NAME --key "ssh-ed25519 AAAA..." (the new home\'s tunnel key: sudo clavarium key tunnel, there)');
+            const { domain } = principal(P);
+            const a = await addHomeOnRelay(sys, P, conf, domain, name, key);
+            sys.print(`${name} is a home of the relay ${a.relay.host}, on its ports ${a.ports.tls} and ${a.ports.http}. On that machine, type:`);
+            sys.print(`    sudo clavarium online --relay ${a.relay.host} --domain ${name} --relay-ports ${a.ports.tls},${a.ports.http} --relay-fingerprint ${a.relay.fingerprint}${a.relay.port !== 22 ? ` --relay-port ${a.relay.port}` : ''}`);
+            return;
+        }
+        case 'remove-home': {
+            if (rest.length !== 1 || !DOMAIN.test(rest[0])) throw new Bad('relay remove-home NAME');
+            principal(P);
+            const r = await keeper(sys, P, conf, ['remove-home', rest[0]], { stream: true });
+            if (r.code !== 0) throw new Failed(`the relay did not remove ${rest[0]} (exit ${r.code})`);
+            return;
+        }
+        case 'homes': {
+            if (rest.length) throw new Bad('relay homes takes nothing');
+            const r = await keeper(sys, P, conf, ['homes'], { stream: true });
+            if (r.code !== 0) throw new Failed(`the relay answered with exit ${r.code}`);
+            return;
+        }
         case 'forget-setup-key': return forgetSetupKey(sys, P, conf);
         case 'status': case 'repair': case 'update-os': {
             if (rest.length && !(verb === 'update-os' && rest.length === 1 && rest[0] === '--reboot')) throw new Bad(`relay ${verb} takes nothing`);
@@ -563,7 +781,7 @@ export async function relayCommand(args, sys, P = PATHS) {
             if (r.code !== 0) throw new Failed(`the relay did not update (exit ${r.code})`);
             return;
         }
-        default: throw new Bad('usage: sudo clavarium relay status | repair | update-os [--reboot] | update-relay [X.Y.Z] | forget-setup-key');
+        default: throw new Bad('usage: sudo clavarium relay status | repair | update-os [--reboot] | update-relay [X.Y.Z] | forget-setup-key | homes | invite NAME | add-home NAME --key KEY | remove-home NAME');
     }
 }
 
@@ -601,6 +819,13 @@ export function realSys() {
             timer = setTimeout(done, ms);
             try { tty = createReadStream('/dev/tty'); tty.on('data', (d) => { if (d.includes(10) || d.includes(13)) done(); }); tty.on('error', () => {}); } catch { /* no keyboard: the timer alone */ }
         }),
+        /* JSON to an address in https, its certificate checked; never a redirect. */
+        post: async (url, body) => {
+            const r = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), redirect: 'error', signal: AbortSignal.timeout(60_000) });
+            let json = null;
+            try { json = await r.json(); } catch { /* not JSON */ }
+            return { status: r.status, body: json };
+        },
         hasKeyboard: () => { try { closeSync(openSync('/dev/tty', 'r')); return true; } catch { return false; } },
         askLine: async (question) => {
             let fd;

package/deploy/relay.sh

@@ -1,45 +1,64 @@
 #!/bin/bash
 # ---------------------------------------------------------------------------
-# TURNS THIS MACHINE INTO THE RELAY OF ONE CLAVARIUM. One command, parameters
-# only. Run it on a small machine that has a public address; the machine at
-# home dials out to it, so home needs no open port and no fixed address.
+# TURNS THIS MACHINE INTO THE RELAY OF A CLAVARIUM -- and, later, of other
+# Clavarium homes too. One command, parameters only. Run it on a small machine
+# that has a public address; the machine at home dials out to it, so home
+# needs no open port and no fixed address.
 #
-#   sudo deploy/relay.sh --key "ssh-ed25519 AAAA... clavarium-tunnel"
+#   sudo deploy/relay.sh --key "ssh-ed25519 AAAA... clavarium-tunnel" --name clav.example.com
 #
 #   --key LINE         the PUBLIC tunnel key of the home machine (`sudo clavarium key`)
 #   --keeper-key LINE  the PUBLIC maintenance key of the home machine (optional)
+#   --name NAME        the home's name (its domain); with it, the relay routes by
+#                      name from the start, and other homes can be added later
 #   --dry-run          check the parameters, say what would be done, do nothing
 #
 # `sudo clavarium online --relay HOST` at home runs this script here by itself,
-# over SSH, with both keys.
+# over SSH, with both keys and the name. That home is the PRINCIPAL: the only
+# one that holds the maintenance key. Run again on a relay that serves homes
+# already, this script sets up the principal again (its key, its name) and
+# leaves the other homes as they are.
 #
 # THE RELAY IS BLIND. It carries bytes: TLS starts in the browser and ends at
 # home, so this machine never sees a page, a keystroke or a password. It holds
 # no certificate and no secret of yours.
 #
 # WHAT IT SETS UP:
-#   - an account, "clavarium-tunnel", that can do ONE thing: hold two
-#     listening ports (8443, 8080) forwarded to home. No shell, no terminal,
-#     no command, no other forwarding;
-#   - a rule that sends what arrives on 443 and 80 to those two ports;
+#   - an account, "clavarium-tunnel", that can do ONE thing: hold listening
+#     ports forwarded to home. Each home has its own key there, and each key
+#     may hold its own two ports only (the principal: 8443 and 8080). No
+#     shell, no terminal, no command, no other forwarding;
+#   - what takes 443 and 80: the router, which reads the name the visitor
+#     asks for and passes the bytes, untouched, to that home's ports (a name
+#     it does not know goes nowhere); or, for a relay of one home whose name
+#     it does not know (set up before names were given), a rule that sends
+#     443 and 80 to 8443 and 8080;
 #   - the maintenance program, clavarium-relay, fetched by THIS machine from
 #     npm at the version written below and checked against the registry's
 #     sha512; with --keeper-key, an account "clavarium-keeper" that may run
-#     that program, and nothing else (status, repair, updates);
+#     that program, and nothing else (status, repair, updates, the homes);
 #   - Ubuntu's security updates, by themselves (unattended-upgrades).
 #
+# ANOTHER HOME is added from the principal, never from here and never with
+# an account of this machine: `sudo clavarium relay invite NAME` there gives
+# a one-time code, typed on the new home (`sudo clavarium online --relay
+# PRINCIPAL --domain NAME --join CODE`). The principal adds the new home's
+# PUBLIC tunnel key here (clavarium-relay add-home) and tells it its ports.
+# A second owner is thus let in by the principal's owner, and by nobody else.
+#
 # WHAT A BLIND RELAY CAN STILL DO, and how to close it: whoever controls this
-# machine receives port 80 for your name, so it could answer a certificate
-# authority's challenge itself and obtain a valid certificate for your name.
-# One DNS record closes that: a CAA record that names YOUR certificate
-# account ("accounturi="). The end of this script says it again.
+# machine receives port 80 for every name it serves, so it could answer a
+# certificate authority's challenge itself and obtain a valid certificate for
+# such a name. One DNS record per name closes that: a CAA record that names
+# THAT home's certificate account ("accounturi="). The end of this script says
+# it again, and so does each home as it goes online.
 #
 # Exit codes: 0 done; 64 bad parameters; 78 this machine is refused.
 # ---------------------------------------------------------------------------
 set -euo pipefail
 
 # The version of the maintenance program this Clavarium works with.
-RELAY_VERSION="0.1.1"
+RELAY_VERSION="0.2.0-next.1"
 ACCOUNT="clavarium-tunnel"
 TLS_PORT="8443"
 HTTP_PORT="8080"
@@ -49,15 +68,16 @@ ROOT="${CLAVARIUM_RELAY_ROOT:-}"
 REGISTRY="https://registry.npmjs.org"
 [ -z "$ROOT" ] || REGISTRY="${CLAVARIUM_RELAY_REGISTRY:-$REGISTRY}"
 
-bad() { echo "relay: $*" >&2; echo "usage: relay.sh --key \"ssh-ed25519 AAAA... name\" [--keeper-key \"ssh-ed25519 AAAA... name\"] [--dry-run]" >&2; exit 64; }
+bad() { echo "relay: $*" >&2; echo "usage: relay.sh --key \"ssh-ed25519 AAAA... name\" [--keeper-key \"ssh-ed25519 AAAA... name\"] [--name NAME] [--dry-run]" >&2; exit 64; }
 refuse() { echo "relay: REFUSED: $*" >&2; exit 78; }
 step() { echo "== $*"; }
 
-KEY=""; KEEPER_KEY=""; DRY="no"
+KEY=""; KEEPER_KEY=""; NAME=""; DRY="no"
 while [ $# -gt 0 ]; do
     case "$1" in
         --key) KEY="${2:-}"; shift 2 || bad "--key needs a value" ;;
         --keeper-key) KEEPER_KEY="${2:-}"; [ -n "$KEEPER_KEY" ] || bad "--keeper-key needs a value"; shift 2 ;;
+        --name) NAME="${2:-}"; [ -n "$NAME" ] || bad "--name needs a value"; shift 2 ;;
         --dry-run) DRY="yes"; shift ;;
         *) bad "unknown parameter: $1" ;;
     esac
@@ -70,12 +90,13 @@ done
 [[ "$KEY" =~ ^ssh-ed25519\ [A-Za-z0-9+/]{68}(\ [A-Za-z0-9@._-]{1,64})?$ ]] || bad "--key is one line: ssh-ed25519, the key, and optionally a name"
 [ -z "$KEEPER_KEY" ] || [[ "$KEEPER_KEY" =~ ^ssh-ed25519\ [A-Za-z0-9+/]{68}(\ [A-Za-z0-9@._-]{1,64})?$ ]] || bad "--keeper-key is one line: ssh-ed25519, the key, and optionally a name"
 [ "$KEY" != "$KEEPER_KEY" ] || bad "the tunnel and the maintenance keys are two different keys"
+[ -z "$NAME" ] || [[ "$NAME" =~ ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,24}$ ]] || bad "--name is a host name, lower case, like clav.example.com"
 
 if [ "$DRY" = "yes" ]; then
     cat <<PLAN
 would make this machine a relay:
   account     $ACCOUNT: may hold ports $TLS_PORT and $HTTP_PORT forwarded to home, and nothing else
-  ports       443 -> $TLS_PORT, 80 -> $HTTP_PORT
+  ports       443 -> $TLS_PORT, 80 -> $HTTP_PORT, for $([ -n "$NAME" ] && echo "the name $NAME, through the router (other names: refused)" || echo "any name (no --name: one home only)")
   sees        nothing: TLS ends at home
   program     clavarium-relay@$RELAY_VERSION from npm, checked (sha512 of the registry)
   maintenance $([ -n "$KEEPER_KEY" ] && echo "clavarium-keeper: may run clavarium-relay, and nothing else" || echo "none (no --keeper-key)")
@@ -97,10 +118,12 @@ for k in "$KEY" "$KEEPER_KEY"; do
     ssh-keygen -l -f "$check" >/dev/null 2>&1 || { rm -f -- "$check"; refuse "this is not a key the SSH tools recognise"; }
 done
 rm -f -- "$check"
-for port in 443 80 "$TLS_PORT" "$HTTP_PORT"; do
-    # (On a second run, the tunnel itself holds two of them: that is the SSH server.)
-    if ss -ltnpH "sport = :$port" 2>/dev/null | grep -v '"sshd' | grep -q .; then refuse "something already listens on port $port here: a relay needs 443 and 80 for itself"; fi
-done
+# On a relay already (a second run), its own router holds 443 and 80, and the tunnels hold theirs.
+if [ ! -s "$ROOT/etc/clavarium-relay/homes" ] && [ ! -s "$ROOT/etc/ssh/clavarium-relay/$ACCOUNT" ]; then
+    for port in 443 80 "$TLS_PORT" "$HTTP_PORT"; do
+        if ss -ltnpH "sport = :$port" 2>/dev/null | grep -v '"sshd' | grep -q .; then refuse "something already listens on port $port here: a relay needs 443 and 80 for itself"; fi
+    done
+fi
 
 step "the maintenance program, from npm"
 for tool in curl openssl tar; do command -v "$tool" >/dev/null 2>&1 || { export DEBIAN_FRONTEND=noninteractive; apt-get update -qq; apt-get install -y -qq curl openssl tar ca-certificates >/dev/null; break; }; done
@@ -129,8 +152,10 @@ install -m 0755 "$work/package/clavarium-relay" "$ROOT$PROGRAM"
 rm -rf -- "$work"
 
 step "accounts, rules, ports, updates"
-if [ -n "$KEEPER_KEY" ]; then "$ROOT$PROGRAM" setup --key "$KEY" --keeper-key "$KEEPER_KEY"
-else "$ROOT$PROGRAM" setup --key "$KEY"; fi
+setup=(setup --key "$KEY")
+[ -z "$KEEPER_KEY" ] || setup+=(--keeper-key "$KEEPER_KEY")
+[ -z "$NAME" ] || setup+=(--name "$NAME")
+"$ROOT$PROGRAM" "${setup[@]}"
 
 echo
 echo "This machine is a relay. It waits for the home machine to dial in."
@@ -138,7 +163,8 @@ echo "Compare with what the home machine printed (it must be the same):"
 echo "    $(ssh-keygen -l -f "$ROOT/etc/ssh/ssh_host_ed25519_key.pub" | cut -d' ' -f2)"
 echo "Point your name at this machine's public address (ports 443 and 80 must reach it)."
 echo
-echo "TO KEEP THIS RELAY BLIND, add a CAA record to your DNS that names your certificate"
-echo "account (accounturi=...). Without it, whoever controls this machine could obtain a"
-echo "certificate for your name. The account address is at home, after the first certificate:"
+echo "TO KEEP THIS RELAY BLIND, add a CAA record to your DNS FOR EACH NAME it serves, that"
+echo "names that home's certificate account (accounturi=...). Without it, whoever controls"
+echo "this machine could obtain a certificate for that name. The account address is at"
+echo "each home, after its first certificate:"
 echo "    sudo grep -rho '\"location\": *\"[^\"]*\"' /var/lib/caddy/caddy/acme"

package/deploy/tunnel.mjs

@@ -10,7 +10,9 @@ import { fileURLToPath } from 'node:url';
    its port are read from the unit there, written as before or as now. Restarted only when it changed. */
 export const TUNNEL_UNIT = '/etc/systemd/system/clavarium-tunnel.service';
 export const TUNNEL_PROGRAM = '/usr/local/sbin/clavarium-tunnel';
-export function tunnelUnit(relay, port, program = TUNNEL_PROGRAM) {
+/* `ports`: { tls, http } for a home the relay's principal added (its own ports on the relay); none for
+   the principal itself (8443 and 8080, as ever). */
+export function tunnelUnit(relay, port, program = TUNNEL_PROGRAM, ports = null) {
     return `[Unit]
 Description=Clavarium - the outgoing tunnel to the relay
 After=network-online.target caddy.service
@@ -21,7 +23,7 @@ StartLimitIntervalSec=0
 User=clavarium-tunnel
 Group=clavarium-tunnel
 # Only TLS (443) and the certificate challenge (80) are carried: see ${program}.
-ExecStart=${program} ${relay} ${port}
+ExecStart=${program} ${relay} ${port}${ports ? ` ${ports.tls} ${ports.http}` : ''}
 Restart=always
 RestartSec=5
 # What it counts of the relay's refusals, kept across its restarts.
@@ -37,8 +39,8 @@ WantedBy=multi-user.target
 `;
 }
 export function relayOfUnit(text) {
-    const now = new RegExp(`^ExecStart=\\S+clavarium-tunnel ([A-Za-z0-9.-]{1,253}) (\\d{1,5})$`, 'm').exec(text);
-    if (now) return { relay: now[1], port: now[2] };
+    const now = new RegExp(`^ExecStart=\\S+clavarium-tunnel ([A-Za-z0-9.-]{1,253}) (\\d{1,5})(?: (\\d{4,5}) (\\d{4,5}))?$`, 'm').exec(text);
+    if (now) return { relay: now[1], port: now[2], ...(now[3] ? { ports: { tls: now[3], http: now[4] } } : {}) };
     const before = /-p (\d{1,5}) clavarium-tunnel@([A-Za-z0-9.-]{1,253})\s*$/m.exec(text);
     return before ? { relay: before[2], port: before[1] } : null;
 }
@@ -56,7 +58,7 @@ export async function ensureTunnel({ file = TUNNEL_UNIT, program = TUNNEL_PROGRA
     if (!existsSync(program)) return false;
     const at = relayOfUnit(text);
     if (!at) return false;
-    const wanted = tunnelUnit(at.relay, at.port, program);
+    const wanted = tunnelUnit(at.relay, at.port, program, at.ports ?? null);
     if (text === wanted) {
         /* The same unit, a new program: what runs now is the old one until it is started again. */
         if (installed && process.getuid?.() === 0) await run(['systemctl', 'try-restart', 'clavarium-tunnel.service'], { timeoutMs: 60_000 });

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "clavarium",
-  "version": "0.2.379-next.1",
+  "version": "0.2.381-next.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clavarium",
-      "version": "0.2.379-next.1",
+      "version": "0.2.381-next.1",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavarium",
-  "version": "0.2.379-next.1",
+  "version": "0.2.381-next.1",
   "license": "MIT",
   "type": "module",
   "description": "A conversation is a VM with a terminal in it. Everything else is a folder.",

package/server/main.mjs

@@ -87,6 +87,7 @@ import { Pocket } from './pocket.mjs';
 import { Speech } from './speech.mjs';
 import { Features, handleFeatures, cached } from './features.mjs';
 import { ApiKeys, handleExternal, handleApiKeys, statusOf } from './apikeys.mjs';
+import { RelayJoin, handleRelayJoin, RELAY_JOIN_PATH } from './relayjoin.mjs';
 import { WebSocketServer } from 'ws';
 
 const ROOT = fileURLToPath(new URL('..', import.meta.url));
@@ -184,7 +185,7 @@ const withoutTmux = (env) => Object.fromEntries(Object.entries(env).filter(([key
 
 const REFUSED = 'This Clavarium belongs to someone else: your account is not one of its operators.\n';
 
-function serve(port, conversations, resources, { gate = () => 'local', originOk, shortcuts, voice, sharing, door, secrets, network, signin, mailboxes, gitReview, platform, answerer, wakeups, alerts, talk, gitAccess, gitKeeper, shelf, health, setup, guide, repair, capacity, updates, instance = new Instance(), certificate, team, reacting, machinesMove, serverLogs, history, events, bundles, wifi, binders, meshcentral, tethers, accounts, groups, boxes, catalogue, rooms, features, apikeys } = {}) {
+function serve(port, conversations, resources, { gate = () => 'local', originOk, shortcuts, voice, sharing, door, secrets, network, signin, mailboxes, gitReview, platform, answerer, wakeups, alerts, talk, gitAccess, gitKeeper, shelf, health, setup, guide, repair, capacity, updates, instance = new Instance(), certificate, team, reacting, machinesMove, serverLogs, history, events, bundles, wifi, binders, meshcentral, tethers, accounts, groups, boxes, catalogue, rooms, features, apikeys, relayJoin } = {}) {
     /* Its manifest carries the name of this Clavarium, or the one a device chose (instance.mjs). */
     const sendManifest = (response, url) => response.writeHead(200, { ...HEADERS, 'content-type': 'application/manifest+json' }).end(instance.manifest(new URL(url ?? '/', 'http://local').searchParams.get('name') ?? undefined));
     const sendFile = async (response, file) => {
@@ -232,6 +233,8 @@ function serve(port, conversations, resources, { gate = () => 'local', originOk,
             try { say(200, boxes.pair(JSON.parse(text || '{}'))); } catch (error) { say(error.status ?? 400, { error: error instanceof SyntaxError ? 'Not JSON.' : error.message }); }
             return;
         }
+        /* Another home joins this machine's relay: under /c/, no sign-on; the one-time code is the right (relayjoin.mjs). */
+        if (relayJoin && pathname === RELAY_JOIN_PATH) { await handleRelayJoin(request, response, relayJoin, HEADERS); return; }
         /* THE DOOR FOR PROGRAMS (apikeys.mjs): an API key is the right, never the gate -- the front lets
            /api/ext/ through without sign-on, and strips the identity headers there. */
         if (apikeys && (pathname === '/api/ext' || pathname.startsWith('/api/ext/'))) {
@@ -781,7 +784,7 @@ export async function startHome({ port, host, dataDir, mntDir = dataDir, gitRese
         answerer: answererConfig(env)?.models.length ?? 0, updates: updates.about(), team: team ? team.list().length : null,
         screen: await quick(screenNow(), 1500, null), catalogue: await quick(catalogue.providers().catch(() => []), 1500, []),
     }) });
-    const { server, listening } = serve(port, all, folders, { gate, originOk, shortcuts, voice, sharing, door, secrets, network, signin, mailboxes, gitReview, platform, answerer, wakeups, alerts, talk, gitAccess, gitKeeper, shelf, health, setup, guide, capacity, updates, instance, certificate, team, reacting, machinesMove, serverLogs, history, events, wifi, binders, meshcentral, tethers, accounts, groups, boxes, catalogue, rooms, features, apikeys, bundles: new Bundles({ dir: `${dataDir}/imports`, folder: (name) => folders.folder(name) }), repair: (name) => repairTerminal(name) });
+    const { server, listening } = serve(port, all, folders, { gate, originOk, shortcuts, voice, sharing, door, secrets, network, signin, mailboxes, gitReview, platform, answerer, wakeups, alerts, talk, gitAccess, gitKeeper, shelf, health, setup, guide, capacity, updates, instance, certificate, team, reacting, machinesMove, serverLogs, history, events, wifi, binders, meshcentral, tethers, accounts, groups, boxes, catalogue, rooms, features, apikeys, relayJoin: host.length ? new RelayJoin({ host: asHost }) : null, bundles: new Bundles({ dir: `${dataDir}/imports`, folder: (name) => folders.folder(name) }), repair: (name) => repairTerminal(name) });
     server.on('close', () => { closing = true; stopBinders(); stopTethers(); clearInterval(historyTimer); clearInterval(secretsTimer); history.save(); stopVmWatch(); stopShelf(); stopHealth(); stopNetworkWatch(); stopUpdates(); stopWatch(); clearInterval(mailTimer); clearInterval(restartTimer); clearInterval(expiryTimer); clearInterval(answerTimer); clearInterval(wakeTimer); clearInterval(docketTimer); dockets.stop(); clearInterval(gitTimer); talk.stop(); });
     let closing = false;
     boxes.attach(server, WebSocketServer);

package/server/relayjoin.mjs

@@ -0,0 +1,67 @@
+/* ANOTHER HOME JOINS THIS MACHINE'S RELAY: POST /c/relay-join, with no sign-in (the front lets /c/
+ * through), the one-time code being the right. See deploy/online.mjs ("SEVERAL HOMES ON ONE RELAY").
+ *
+ *   POST /c/relay-join   {"code": "ABCD-EFGH", "key": "ssh-ed25519 AAAA..."}
+ *   200  {"name", "relay": {"host", "port", "fingerprint"}, "ports": {"tls", "http"}}
+ *   400  not this shape;  403  not a valid code (wrong, used or expired);  429  too many tries;  502  the relay did not add it
+ *
+ * The server only carries it: the code is checked, spent and acted on by root (host program, "relay
+ * join"), where the server cannot read the codes. Here: a body of exactly these two fields, a code of
+ * the right shape, a PUBLIC ed25519 key (its comment dropped) and nothing else; at most PER_MINUTE
+ * tries a minute, from everybody together (behind the relay, every caller has the same address). The
+ * answer is rebuilt field by field from what root printed: nothing else can go out.
+ */
+import { Refusal } from './conversations.mjs';
+
+export const RELAY_JOIN_PATH = '/c/relay-join';
+export const PER_MINUTE = 6;
+const CODE = /^[A-HJKMNP-Z2-9]{8}$/;
+const KEY = /^ssh-ed25519 ([A-Za-z0-9+/]{68})( [A-Za-z0-9@._-]{1,64})?$/;
+const HOST = /^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,24}$|^([0-9]{1,3}\.){3}[0-9]{1,3}$/;
+const PRINT = /^SHA256:[A-Za-z0-9+/]{43}$/;
+const NOT_VALID = 'This code is not valid: wrong, used or expired. Ask the owner of that Clavarium for a new one.';
+
+export class RelayJoin {
+    #host; #now; #tries = [];
+    /* `host(argv)`: the host program (vm.mjs, runner) -> { code, stdout, stderr }. */
+    constructor({ host, now = Date.now }) { this.#host = host; this.#now = now; }
+
+    /* -> { status, body }. `text`: the request's body. */
+    async join(text) {
+        const now = this.#now();
+        this.#tries = this.#tries.filter((t) => t > now - 60_000);
+        if (this.#tries.length >= PER_MINUTE) return { status: 429, body: { error: 'Too many tries: wait a minute.' } };
+        this.#tries.push(now);
+        let given;
+        try { given = JSON.parse(text); } catch { return { status: 400, body: { error: 'Not JSON.' } }; }
+        if (!given || typeof given !== 'object' || Array.isArray(given) || Object.keys(given).sort().join(',') !== 'code,key') return { status: 400, body: { error: 'Send {"code", "key"} and nothing else.' } };
+        const code = String(given.code).toUpperCase().replace(/[\s-]/g, '');
+        const key = KEY.exec(typeof given.key === 'string' ? given.key.trim() : '');
+        if (typeof given.code !== 'string' || !CODE.test(code)) return { status: 403, body: { error: NOT_VALID } };
+        if (!key) return { status: 400, body: { error: 'The key is the PUBLIC tunnel key: one line, ssh-ed25519 and the key.' } };
+        const r = await this.#host(['relay', 'join', code, 'ssh-ed25519', key[1]], { timeoutMs: 120_000 });
+        if (r.code === 78) return { status: 403, body: { error: NOT_VALID } };
+        if (r.code !== 0) return { status: 502, body: { error: 'The relay did not add this home just now: try again, or ask the owner of that Clavarium.' } };
+        let a;
+        try { a = JSON.parse(String(r.stdout).trim().split('\n').pop()); } catch { a = null; }
+        const port = (v, lo) => Number.isInteger(v) && v >= lo && v <= 65535;
+        if (!a || typeof a.name !== 'string' || !HOST.test(a.name) || !HOST.test(a.relay?.host ?? '') || !port(a.relay?.port, 1) || !PRINT.test(a.relay?.fingerprint ?? '')
+            || !port(a.ports?.tls, 1024) || !port(a.ports?.http, 1024)) return { status: 502, body: { error: 'The relay did not answer as expected.' } };
+        return { status: 200, body: { name: a.name, relay: { host: a.relay.host, port: a.relay.port, fingerprint: a.relay.fingerprint }, ports: { tls: a.ports.tls, http: a.ports.http } } };
+    }
+}
+
+/* The route, answered here when it is this one (true). */
+export async function handleRelayJoin(request, response, join, headers = {}) {
+    const say = (status, body) => { response.writeHead(status, { ...headers, 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' }).end(JSON.stringify(body)); return true; };
+    if (request.method !== 'POST') return say(405, { error: 'Call this address with POST.' });
+    let text = '';
+    for await (const piece of request) { text += piece; if (text.length > 2048) return say(413, { error: 'Too long.' }); }
+    try {
+        const { status, body } = await join.join(text);
+        return say(status, body);
+    } catch (error) {
+        if (error instanceof Refusal) return say(error.status, { error: error.message });
+        return say(502, { error: 'The relay did not add this home just now.' });
+    }
+}

package/web/app.js

@@ -2124,6 +2124,7 @@
     let voiceOn = false;
     const chatVoice = () => (voiceOn && window.clavariumVoice ? window.clavariumVoice : null);
     async function offerVoice() {
+        if (DEVICE && !pairing) return;          /* asked again by start(), once there is a pairing to ask with */
         voiceOn = window.clavariumVoice ? await window.clavariumVoice.available() : false;
         $('mic').hidden = $('auto').hidden = !voiceOn;
         keysForChat();
@@ -3017,6 +3018,8 @@
     const deviceLang = () => (navigator.language || 'en');
     let chatWords = null;
     async function readWords() {
+        /* A device asks its own door only once it has its pairing (start): asked before, it was refused (401), and kept empty. */
+        if (DEVICE && !pairing) return {};
         if (!chatWords) chatWords = await fetch(`${API}/talk/words?${new URLSearchParams({ lang: deviceLang() })}`).then((r) => (r.ok ? r.json() : {})).catch(() => ({}));
         return chatWords;
     }
@@ -8922,7 +8925,7 @@
         await paintAssets();
     });
     setConnexionProvider('google');
-    getJson('/accounts', null).then((d) => { if (d?.supported) { accountSupported = { ...d.supported, classic: ['mail', 'calendar', 'contacts'] }; setConnexionProvider($('connexion-new').dataset.provider || 'google'); } });
+    if (!DEVICE) getJson('/accounts', null).then((d) => { if (d?.supported) { accountSupported = { ...d.supported, classic: ['mail', 'calendar', 'contacts'] }; setConnexionProvider($('connexion-new').dataset.provider || 'google'); } });
     $('list-new').addEventListener('submit', async (event) => {
         event.preventDefault();
         $('assets-error').hidden = true; $('cassets-error').hidden = true;