clavarium 0.1.0-next.6 → 0.1.0-next.7

package/README.md

@@ -213,6 +213,16 @@ The host needs `tmux` and `bindfs` (the read-only views).
     # to try it on a machine of your own, with no domain: this machine only, no sign-in
     sudo deploy/install.sh --local
 
+    # the stable version from npm, in local mode, asking nothing (Node.js pinned and
+    # checked first); it prints the next command and the public keys (text and QR)
+    curl -fsSL https://clavarium.org/install.sh | sudo bash
+    # then online: HTTPS, an administrator, a password shown once -- after a real
+    # test from the internet (Let's Encrypt staging); the relay is set up over SSH
+    sudo clavarium online --relay relay.example.net --domain clav.example.com
+    sudo clavarium online --port --domain clav.example.com
+    sudo clavarium key                  # the public keys again
+    sudo clavarium relay status         # status | repair | update-os | update-relay | forget-setup-key
+
     # from npm, an exact version, checked (integrity, provenance, signatures);
     # it then updates itself (Settings, Updates; --updates auto|asap|ask|off,
     # --update-window 02:00-05:00, --channel latest|next) and keeps the last

package/deploy/clavarium.mjs

@@ -5,6 +5,14 @@
  *   sudo npx clavarium@X.Y.Z install --local
  *   npx clavarium --version
  *
+ * Once installed, the same program is the command `clavarium` (install.sh
+ * puts it in /usr/local/bin), with what is done from the keyboard:
+ *
+ *   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 relay status | repair | update-os | update-relay | forget-setup-key
+ *
  * `install` runs deploy/install.sh of this package, which installs THIS
  * version from npm (checked) into /opt/clavarium/releases/X.Y.Z; every other
  * parameter is the installer's (install.sh --help-like usage on a bad one).
@@ -17,11 +25,31 @@ import { fileURLToPath } from 'node:url';
 const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const [verb, ...rest] = process.argv.slice(2);
 if (verb === '--version' || verb === '-v') { console.log(version); process.exit(0); }
+if (['online', 'key', 'relay'].includes(verb)) {
+    const o = await import('./online.mjs');
+    if (process.getuid?.() !== 0) { console.error(`clavarium ${verb}: run it as root: sudo clavarium ${verb} ...`); process.exit(78); }
+    const sys = o.realSys();
+    try {
+        if (verb === 'online') await o.online(o.parseOnline(rest), sys);
+        else if (verb === 'key') {
+            if (rest.length > 1 || (rest[0] && !['setup', 'tunnel'].includes(rest[0]))) throw new o.Bad('usage: sudo clavarium key [setup|tunnel]');
+            await o.showKeys(sys, o.PATHS, { which: rest[0] ?? 'all' });
+        } else await o.relayCommand(rest, sys);
+        process.exit(0);
+    } catch (error) {
+        if (error instanceof o.Bad) { console.error(`clavarium ${verb}: ${error.message}`); if (verb === 'online') console.error(o.USAGE); process.exit(64); }
+        console.error(`clavarium ${verb}: ${error instanceof o.Refused ? 'REFUSED: ' : ''}${error.message}`);
+        process.exit(error instanceof o.Refused ? 78 : 1);
+    }
+}
 if (verb !== 'install') {
     console.error(`Clavarium ${version}: each AI agent in its own machine, with only what you attach.\n\n`
-        + `  sudo npx clavarium@${version} install --domain NAME --operator EMAIL   on an Ubuntu server\n`
-        + `  sudo npx clavarium@${version} install --local                          to try it on this machine\n\n`
-        + 'https://github.com/clavarium/clavarium');
+        + '  curl -fsSL https://clavarium.org/install.sh | sudo bash          install, on Ubuntu 24.04 or 26.04 (local mode)\n'
+        + '  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 relay status|repair|update-os|update-relay|forget-setup-key\n\n'
+        + 'https://clavarium.org');
     process.exit(verb ? 64 : 0);
 }
 const script = fileURLToPath(new URL('./install.sh', import.meta.url));

package/deploy/install.sh

@@ -33,8 +33,17 @@
 #                      Settings and waits; off. Changed later in Settings.
 #   --update-window HH:MM-HH:MM   when "auto" may update (default 02:00-05:00)
 #   --channel C        latest (default) or next (versions with a "-": tests)
+#   --keep-release     keep the release that runs (change the settings only:
+#                      what `clavarium online` does to go from local mode to
+#                      server mode)
+#   --relay-installed  the relay was set up already (by `clavarium online`):
+#                      do not print the command to run on it
 #   --dry-run          check the parameters, say what would be done, do nothing
 #
+# AFTER --local, going online is one command: `sudo clavarium online --relay
+# HOST --domain NAME` or `sudo clavarium online --port --domain NAME` (see
+# deploy/online.mjs); `sudo clavarium key` shows the public keys again.
+#
 # RUN AGAIN on an installation, it installs the version asked for beside the
 # one that runs and switches to it. An installation made before releases
 # existed (code copied into /opt/clavarium) is moved to them; the old copy is
@@ -102,7 +111,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"
+DOMAIN=""; OPERATORS=""; PORT="7717"; CORE_ONLY="no"; DRY="no"; RELAY=""; RELAY_PORT="22"; LOCAL="no"; KEEP_RELEASE="no"; RELAY_INSTALLED="no"
 VERSION=""; FROM_DIR=""; UPDATES=""; WINDOW=""; CHANNEL=""
 while [ $# -gt 0 ]; do
     case "$1" in
@@ -118,6 +127,8 @@ while [ $# -gt 0 ]; do
         --updates) UPDATES="${2:-}"; shift 2 || bad "--updates needs a value" ;;
         --update-window) WINDOW="${2:-}"; shift 2 || bad "--update-window needs a value" ;;
         --channel) CHANNEL="${2:-}"; shift 2 || bad "--channel needs a value" ;;
+        --keep-release) KEEP_RELEASE="yes"; shift ;;
+        --relay-installed) RELAY_INSTALLED="yes"; shift ;;
         --dry-run) DRY="yes"; shift ;;
         *) bad "unknown parameter: $1" ;;
     esac
@@ -178,7 +189,7 @@ would install Clavarium:
   address     $([ "$LOCAL" = "yes" ] && echo "http://127.0.0.1:$PORT, from this machine only (--local)" || echo "https://$DOMAIN")
   operators   $([ "$LOCAL" = "yes" ] && echo "whoever can open a page on this machine: no sign-in" || echo "$OPERATORS")
   server      127.0.0.1:$PORT, as the account "$ACCOUNT", Node.js $NODE_VERSION
-  release     $([ -n "$VERSION" ] && echo "clavarium@$VERSION from npm, checked (integrity, provenance from github.com/clavarium/clavarium, npm audit signatures)" || echo "the working tree $FROM_DIR, as it is (development: not checked)")
+  release     $([ "$KEEP_RELEASE" = "yes" ] && echo "the one that runs, kept (--keep-release)" || [ -n "$VERSION" ] && echo "clavarium@$VERSION from npm, checked (integrity, provenance from github.com/clavarium/clavarium, npm audit signatures)" || echo "the working tree $FROM_DIR, as it is (development: not checked)")
   updates     $(case "$SHOW_MODE" in auto) echo "automatic, between ${SHOW_WINDOW%-*} and ${SHOW_WINDOW#*-}" ;; asap) echo "as soon as a version is out" ;; ask) echo "said in Settings, done when you say" ;; off) echo "off" ;; esac), channel $SHOW_CHANNEL
   code        $CODE/releases/<version>, $CODE/current (root)      data  $DATA      folders  $MNT (root's chain)      vault key  $VAULT
   root rule   $ACCOUNT may run $HOST_PROGRAM, and nothing else
@@ -209,7 +220,8 @@ export NEEDRESTART_SUSPEND=1
 apt-get update -qq
 # bindfs: the read-only views. nftables: the network rules. build-essential
 # and python3: one module of the server (the terminal) is compiled here.
-apt-get install -y -qq bindfs nftables build-essential python3 curl ca-certificates xz-utils sudo snapd openssl git >/dev/null
+# qrencode: the public keys, shown as QR codes on a screen. openssh-client: the tunnel.
+apt-get install -y -qq bindfs nftables build-essential python3 curl ca-certificates xz-utils sudo snapd openssl git qrencode openssh-client >/dev/null
 snap list multipass >/dev/null 2>&1 || snap install multipass >/dev/null
 
 step "account"
@@ -246,6 +258,11 @@ if [ ! -x "$NODE_DIR/bin/node" ]; then
     mv -- "$NODE_DIR.partial" "$NODE_DIR"
 fi
 updater() { PATH="$NODE_DIR/bin:$PATH" "$NODE_DIR/bin/node" "$HERE/deploy/updater.mjs" "$@"; }
+if [ "$KEEP_RELEASE" = "yes" ]; then
+    [ -L "$CODE/current" ] || refuse "--keep-release: no release runs here yet"
+    release="$(basename "$(readlink -f "$CODE/current")")"
+    echo "   the release that runs is kept: $release"
+else
 if [ -n "$VERSION" ]; then
     echo "   clavarium@$VERSION from npm: fetched, checked, built, tried (a few minutes)"
     release="$(updater prepare --version "$VERSION")" || refuse "clavarium@$VERSION was not installed (above: why)"
@@ -255,6 +272,7 @@ else
 fi
 systemctl stop clavarium.service 2>/dev/null || true
 updater switch "$release"
+fi
 APP="$CODE/current/app"
 NODE="$CODE/current/node/bin/node"
 # The updater of the release now in place, for what follows and from now on.
@@ -268,6 +286,10 @@ install -o root -g root -m 0755 "$APP/deploy/git-read" "$GIT_READ"
 
 step "the one privileged program"
 install -o root -g root -m 0755 "$APP/deploy/clavarium-host" "$HOST_PROGRAM"
+# The command for the keyboard (sudo clavarium online, key, relay): the
+# program of the package, from the release that runs.
+printf '#!/bin/sh\n# Clavarium: the command of the release that runs. Written by install.sh.\nexec %s %s "$@"\n' "$CODE/current/node/bin/node" "$CODE/current/app/deploy/clavarium.mjs" > /usr/local/bin/clavarium
+chmod 0755 /usr/local/bin/clavarium
 install -d -o root -g root -m 0755 "$ETC"
 printf 'DATA=%s\nMNT=%s\n' "$DATA" "$MNT" > "$ETC/host.conf"; chmod 0644 "$ETC/host.conf"
 rule="$(mktemp)"
@@ -368,20 +390,8 @@ updater prune
 systemctl start clavarium-update.timer
 echo "   running: $(sed -n 's/^  "version": "\([^"]*\)",$/\1/p' "$APP/package.json" | head -1) ($release)"
 
-if [ "$LOCAL" = "yes" ]; then
-    echo "Clavarium is installed, to try it:   http://127.0.0.1:$PORT   (from this machine only)"
-    echo "From another computer of yours:      ssh -L $PORT:127.0.0.1:$PORT <you>@<this machine>, then the same address there."
-    echo "There is no sign-in: whoever can open a page on this machine is its operator."
-    echo "For real use, run it again with --domain and --operator."
-    exit 0
-fi
-if [ "$CORE_ONLY" = "yes" ]; then
-    echo "Clavarium is installed: 127.0.0.1:$PORT, for $OPERATORS."
-    echo "It answers nobody yet: put an authenticating proxy in front, for https://$DOMAIN."
-    exit 0
-fi
-
-# ------------------------------- THE EDGE ---------------------------------
+# THE EDGE'S PROGRAMS: also in local mode, switched off, so that going online
+# (sudo clavarium online) has them, and can test from the internet first.
 # Downloads one file and refuses it unless it has the expected checksum.
 fetch() { # <url> <sha256> <destination> [extra curl arguments...]
     local url="$1" sum="$2" to="$3"; shift 3
@@ -390,6 +400,7 @@ fetch() { # <url> <sha256> <destination> [extra curl arguments...]
 }
 account() { id "$1" >/dev/null 2>&1 || useradd --system --home-dir "$2" --no-create-home --shell /usr/sbin/nologin "$1"; }
 
+if [ "$LOCAL" = "yes" ] || [ "$CORE_ONLY" = "no" ]; then
 step "edge: programs"
 work="$(mktemp -d)"
 if [ "$(/usr/local/bin/caddy version 2>/dev/null | cut -d' ' -f1)" != "v$CADDY_VERSION" ]; then
@@ -411,6 +422,29 @@ if [ "$(sha256sum /usr/local/bin/dex 2>/dev/null | cut -d' ' -f1)" != "$DEX_SHA2
     install -o root -g root -m 0755 "$work/usr/local/bin/dex" /usr/local/bin/dex
 fi
 rm -rf -- "$work"
+fi
+
+if [ "$LOCAL" = "yes" ]; then
+    echo
+    # The keys for going online, as text and as QR codes (a screen and a keyboard may be all there is).
+    /usr/local/bin/clavarium key || echo "install: the keys could not be shown: sudo clavarium key" >&2
+    echo
+    echo "Clavarium is installed, in local mode:   http://127.0.0.1:$PORT   (this machine only, no sign-in)"
+    echo "From another computer of yours:          ssh -L $PORT:127.0.0.1:$PORT <you>@<this machine>"
+    echo
+    echo "NEXT, to go online (HTTPS, an administrator, a password shown once):"
+    echo "    sudo clavarium online --relay RELAY_HOST --domain clav.example.com     through a relay of yours"
+    echo "    sudo clavarium online --port --domain clav.example.com                 or with ports 80 and 443 open here"
+    echo "The keys again: sudo clavarium key"
+    exit 0
+fi
+if [ "$CORE_ONLY" = "yes" ]; then
+    echo "Clavarium is installed: 127.0.0.1:$PORT, for $OPERATORS."
+    echo "It answers nobody yet: put an authenticating proxy in front, for https://$DOMAIN."
+    exit 0
+fi
+
+# ------------------------------- THE EDGE ---------------------------------
 
 step "edge: accounts and settings"
 account caddy /var/lib/caddy; account dex /var/lib/dex; account oauth2-proxy /nonexistent
@@ -657,7 +691,9 @@ if [ -n "$PASSWORDS" ]; then
 else
     echo "Operators and passwords: unchanged."
 fi
-if [ -n "$RELAY" ]; then
+if [ -n "$RELAY" ] && [ "$RELAY_INSTALLED" = "yes" ]; then
+    echo "The relay $RELAY is set up; the tunnel comes up by itself.   Its fingerprint: $RELAY_PRINT"
+elif [ -n "$RELAY" ]; then
     echo
     echo "ON THE RELAY ($RELAY), run this one command; the tunnel then comes up by itself:"
     echo "    sudo deploy/relay.sh --key \"$TUNNEL_KEY\""

package/deploy/online.mjs

@@ -0,0 +1,492 @@
+/* GOING ONLINE FROM THE KEYBOARD: `sudo clavarium online`, `sudo clavarium key`,
+ * `sudo clavarium relay ...`. Run as root, on the Clavarium machine.
+ *
+ * An installation always ends in LOCAL MODE (this computer only, no sign-in).
+ * Going online means SERVER MODE: HTTPS, an administrator and a password, a
+ * domain, and one of two ways in:
+ *
+ *   --relay HOST   this machine is not reachable: it dials out to a small
+ *                  machine of yours that has a public address. This command
+ *                  sets that machine up ITSELF over SSH, with a "setup key" the
+ *                  operator puts once on an account of it that has sudo; the
+ *                  key is taken out again at the end (unless --keep-setup-key).
+ *   --port         this machine is reachable on 80 and 443 (a server at a host,
+ *                  or a router whose ports were opened).
+ *
+ * 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
+ * ports). On failure, the exact cause is said and the machine stays in local
+ * mode. Only then does install.sh switch it to server mode and print the
+ * administrator's password, once.
+ *
+ * Everything outside this file (processes, DNS, the terminal) goes through
+ * `sys`, so the tests can stand in for SSH, npm and DNS.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, mkdtempSync, renameSync, openSync, readSync, writeSync, closeSync } from 'node:fs';
+import { promises as dns } from 'node:dns';
+import { createInterface } from 'node:readline';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readConf } from './updater.mjs';
+
+export const PATHS = {
+    access: '/var/lib/clavarium-relay-access',
+    tunnel: '/var/lib/clavarium-tunnel',
+    relayConf: '/etc/clavarium/relay.conf',
+    updateConf: '/etc/clavarium/update.conf',
+    unit: '/etc/systemd/system/clavarium.service',
+    code: '/opt/clavarium',
+    caddy: '/usr/local/bin/caddy',
+};
+export const STAGING = 'https://acme-staging-v02.api.letsencrypt.org/directory';
+const DOMAIN = /^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,24}$/;
+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 EMAIL = /^[a-z0-9._+-]{1,64}@([a-z0-9-]{1,63}\.)+[a-z]{2,24}$/;
+const USER = /^[a-z_][a-z0-9_-]{0,31}$/;
+const PRINT = /^SHA256:[A-Za-z0-9+/]{43}$/;
+const KEY = /^ssh-ed25519 [A-Za-z0-9+/]{68}( [A-Za-z0-9@._-]{1,64})?$/;
+const KEEPER = 'clavarium-keeper';
+const WAIT_MS = 30 * 60_000;
+
+export class Bad extends Error {}
+export class Refused extends Error {}
+export class Failed extends Error {}
+
+/* ------------------------------ parameters ------------------------------ */
+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 --port --domain NAME [--admin EMAIL]',
+].join('\n');
+
+export function parseOnline(args) {
+    const o = { relay: '', user: 'root', relayPort: '22', domain: '', admin: '', fingerprint: '', keepSetupKey: false, yes: false, port: false };
+    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];
+        switch (a) {
+            case '--relay': o.relay = value(i, a); i++; break;
+            case '--relay-user': o.user = value(i, a); i++; break;
+            case '--relay-port': o.relayPort = value(i, a); i++; break;
+            case '--domain': o.domain = value(i, a); i++; break;
+            case '--admin': o.admin = value(i, a); i++; break;
+            case '--relay-fingerprint': o.fingerprint = value(i, a); i++; break;
+            case '--keep-setup-key': o.keepSetupKey = true; break;
+            case '--yes': o.yes = true; break;
+            case '--port': o.port = true; break;
+            default: throw new Bad(`unknown parameter: ${a}`);
+        }
+    }
+    if (!o.relay === !o.port) throw new Bad('say how it will be reached: --relay HOST or --port');
+    if (!DOMAIN.test(o.domain)) throw new Bad('--domain is a host name, lower case, like clav.example.com');
+    o.admin ||= `admin@${o.domain}`;
+    if (!EMAIL.test(o.admin)) throw new Bad('--admin is an e-mail address, lower case');
+    if (o.relay) {
+        if (!HOST.test(o.relay)) throw new Bad('--relay is the name or the address of the relay machine');
+        if (!USER.test(o.user)) throw new Bad('--relay-user is an account name');
+        if (!/^\d{1,5}$/.test(o.relayPort) || +o.relayPort < 1 || +o.relayPort > 65535) throw new Bad('--relay-port is a port number');
+        if (o.fingerprint && !PRINT.test(o.fingerprint)) throw new Bad('--relay-fingerprint looks like SHA256:... (ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the relay)');
+    } else if (o.fingerprint || o.keepSetupKey || o.user !== 'root' || o.relayPort !== '22') throw new Bad('--relay-user, --relay-port, --relay-fingerprint and --keep-setup-key go with --relay');
+    return o;
+}
+
+/* --------------------------------- keys --------------------------------- */
+const keyFiles = (P) => ({
+    setup: join(P.access, 'setup-key'),
+    keeper: join(P.access, 'keeper-key'),
+    tunnel: join(P.tunnel, 'key'),
+    knownHosts: join(P.access, 'known_hosts'),
+});
+
+/* The three keys of this machine, made here if missing; private halves never leave it. */
+export async function ensureKeys(sys, P = PATHS) {
+    const f = keyFiles(P);
+    mkdirSync(P.access, { recursive: true, mode: 0o700 });
+    for (const [file, name] of [[f.setup, 'clavarium-setup'], [f.keeper, KEEPER]]) {
+        if (existsSync(`${file}.pub`)) continue;
+        const r = await sys.run(['ssh-keygen', '-q', '-t', 'ed25519', '-N', '', '-C', name, '-f', file]);
+        if (r.code !== 0) throw new Failed(`the key ${name} could not be made: ${tail(r)}`);
+    }
+    if (!existsSync(`${f.tunnel}.pub`)) {
+        if ((await sys.run(['id', 'clavarium-tunnel'])).code !== 0) await sys.run(['useradd', '--system', '--home-dir', '/nonexistent', '--no-create-home', '--shell', '/usr/sbin/nologin', 'clavarium-tunnel']);
+        await sys.run(['install', '-d', '-o', 'clavarium-tunnel', '-g', 'clavarium-tunnel', '-m', '0700', P.tunnel]);
+        const r = await sys.run(['sudo', '-u', 'clavarium-tunnel', 'ssh-keygen', '-q', '-t', 'ed25519', '-N', '', '-C', 'clavarium-tunnel', '-f', f.tunnel]);
+        if (r.code !== 0) throw new Failed(`the tunnel key could not be made: ${tail(r)}`);
+    }
+    const read = (file) => readFileSync(`${file}.pub`, 'utf8').trim();
+    return { setup: read(f.setup), keeper: read(f.keeper), tunnel: read(f.tunnel) };
+}
+
+async function qr(sys, text) {
+    const r = await sys.run(['qrencode', '-t', 'ANSIUTF8', '-m', '2', '--', text]);
+    if (r.code === 0 && r.out) sys.print(r.out.replace(/\n$/, ''));
+}
+
+/* `sudo clavarium key`: the public keys, as text and as QR codes for a phone. */
+export async function showKeys(sys, P = PATHS, { which = 'all' } = {}) {
+    const keys = await ensureKeys(sys, P);
+    if (which === 'all' || which === 'setup') {
+        sys.print('SETUP KEY: for `clavarium online --relay`. Put it once on the relay, in');
+        sys.print('~/.ssh/authorized_keys of an account that has sudo. It is taken out at the end.');
+        sys.print(`    ${keys.setup}`);
+        await qr(sys, keys.setup);
+    }
+    if (which === 'all' || which === 'tunnel') {
+        sys.print('TUNNEL KEY: only if you set up the relay yourself:');
+        sys.print(`    sudo deploy/relay.sh --key "${keys.tunnel}"`);
+        await qr(sys, keys.tunnel);
+    }
+    sys.print('These are PUBLIC keys: showing them is safe.');
+    return keys;
+}
+
+/* ---------------------------------- SSH ---------------------------------- */
+const sshOptions = (key, knownHosts, port) => [
+    '-o', 'BatchMode=yes', '-o', 'IdentitiesOnly=yes', '-o', `IdentityFile=${key}`,
+    '-o', `UserKnownHostsFile=${knownHosts}`, '-o', 'StrictHostKeyChecking=yes', '-o', 'ConnectTimeout=10', '-p', String(port),
+];
+const quote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const tail = (r) => String(r.err || r.out || '').trim().split('\n').filter(Boolean).pop()?.slice(0, 300) ?? `exit ${r.code}`;
+
+export function readRelayConf(P = PATHS) {
+    const conf = {};
+    try { for (const line of readFileSync(P.relayConf, 'utf8').split('\n')) { const m = /^([A-Z_]+)=(.*)$/.exec(line.trim()); if (m) conf[m[1]] = m[2]; } } catch { return null; }
+    return conf.HOST ? conf : null;
+}
+function writeRelayConf(P, conf) {
+    mkdirSync(join(P.relayConf, '..'), { recursive: true });
+    writeFileSync(`${P.relayConf}.new`, `# The relay of this Clavarium. Written by clavarium online.\n${Object.entries(conf).map(([k, v]) => `${k}=${v}`).join('\n')}\n`, { mode: 0o644 });
+    renameSync(`${P.relayConf}.new`, P.relayConf);
+}
+
+/* The relay's own maintenance program, through the account that may run it only. */
+export async function keeper(sys, P, conf, words, { stream = false } = {}) {
+    const f = keyFiles(P);
+    return sys.run(['ssh', ...sshOptions(f.keeper, f.knownHosts, conf.PORT), `${KEEPER}@${conf.HOST}`, words.join(' ')], { stream });
+}
+
+/* The version of the relay program this Clavarium works with: the one relay.sh installs. */
+export function relayVersion(P = PATHS) {
+    const text = readFileSync(join(P.code, 'current', 'app', 'deploy', 'relay.sh'), 'utf8');
+    return /^RELAY_VERSION="([^"]+)"$/m.exec(text)?.[1];
+}
+
+/* Takes the setup key out of the relay account it was put in, and checks it no longer opens it. */
+export async function forgetSetupKey(sys, P, conf) {
+    const f = keyFiles(P);
+    const body = readFileSync(`${f.setup}.pub`, 'utf8').trim().split(' ')[1];
+    const at = [...sshOptions(f.setup, f.knownHosts, conf.PORT), `${conf.USER}@${conf.HOST}`];
+    const script = `f="$HOME/.ssh/authorized_keys"; [ -f "$f" ] || exit 0; t="$(mktemp)"; grep -vF -- ${quote(body)} "$f" > "$t" || true; cat "$t" > "$f"; rm -f -- "$t"`;
+    const r = await sys.run(['ssh', ...at, script]);
+    if (r.code !== 0 && !/Permission denied/i.test(r.err)) throw new Failed(`the setup key could not be taken out: ${tail(r)}`);
+    const again = await sys.run(['ssh', ...at, 'true']);
+    if (again.code === 0) throw new Failed(`the setup key still opens ${conf.USER}@${conf.HOST}: take it out of ~/.ssh/authorized_keys there`);
+    writeRelayConf(P, { ...conf, SETUP_KEY: 'removed' });
+    sys.print(`The setup key no longer opens ${conf.USER}@${conf.HOST}.`);
+}
+
+/* ---------------------------------- DNS ---------------------------------- */
+export function isPrivate(ip) {
+    return /^(10\.|127\.|169\.254\.|192\.168\.|0\.)/.test(ip) || /^172\.(1[6-9]|2\d|3[01])\./.test(ip)
+        || /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(ip) || /^(::1$|f[cd]|fe80:)/i.test(ip);
+}
+export async function addresses(sys, name) {
+    if (/^([0-9]{1,3}\.){3}[0-9]{1,3}$/.test(name)) return [name];
+    return sys.resolve(name);
+}
+
+/* What the DNS must say, checked before anything changes. */
+export async function checkDns(sys, o) {
+    const got = await addresses(sys, o.domain);
+    if (o.relay) {
+        const relay = await addresses(sys, o.relay);
+        if (!relay.length) throw new Failed(`${o.relay} has no address in the DNS`);
+        if (!got.length) throw new Failed(`${o.domain} has no DNS record yet. Create it at your DNS provider:\n    ${o.domain}  A  ${relay[0]}\n(then run this command again)`);
+        if (!got.some((a) => relay.includes(a))) throw new Failed(`${o.domain} points to ${got.join(', ')}, not to the relay (${relay.join(', ')}). Change the record:\n    ${o.domain}  A  ${relay[0]}`);
+        sys.print(`DNS: ${o.domain} -> ${got.join(', ')}, the relay. Good.`);
+        return got;
+    }
+    if (!got.length) throw new Failed(`${o.domain} has no DNS record yet. Create one at your DNS provider: ${o.domain}  A  <the public address of this machine>`);
+    const pub = got.filter((a) => !isPrivate(a));
+    if (!pub.length) throw new Failed(`${o.domain} points to ${got.join(', ')}: a private address, which the internet cannot reach. Use the public one (your router's, or your server's)`);
+    sys.print(`DNS: ${o.domain} -> ${got.join(', ')}.`);
+    return got;
+}
+
+/* ------------------------ the test from the internet ------------------------ */
+/* What Let's Encrypt (or Caddy) said, as the operator needs to read it. */
+export function explain(error, { domain, port, relay }) {
+    const e = String(error);
+    const where = relay ? `the relay ${relay}` : 'this machine';
+    if (/address already in use/i.test(e)) return `port ${port} is already used by another program on this machine`;
+    if (/NXDOMAIN|no valid A records|DNS problem/i.test(e)) return `Let's Encrypt cannot find ${domain} in the DNS yet (${e.match(/DNS problem: [^;"]*/)?.[0] ?? 'DNS'}). Wait a few minutes after creating the record, then try again`;
+    if (/timeout|timed out|likely firewall/i.test(e)) return relay ? `port ${port} of ${relay} cannot be reached from the internet: open it in the relay's firewall (at its host, too)` : `port ${port} is not open on your router or firewall: Let's Encrypt waited and nothing answered`;
+    if (/connection refused/i.test(e)) return relay ? `port ${port} of ${relay} refuses connections: the relay does not pass it to the tunnel (sudo clavarium relay repair)` : `port ${port} reaches a machine that refuses it: forward it to this machine on your router`;
+    if (/unauthorized|invalid response|404|403/i.test(e)) return `${domain} leads to another machine than ${where}: check the DNS record`;
+    if (/rate ?limit|too many/i.test(e)) return 'Let\'s Encrypt says too many tries: wait an hour and try again';
+    return `the test failed: ${e.slice(0, 300)}`;
+}
+
+/* One certificate asked of Let's Encrypt's STAGING service (no real
+   certificate, no limit worth worrying about), with one challenge only, so
+   that what fails says which port: http-01 comes on 80, tls-alpn-01 on 443. */
+export async function acmeTest(sys, P, { domain, relay, challenge, timeoutMs = 150_000 }) {
+    const dir = mkdtempSync(join(sys.tmp ?? tmpdir(), 'clavarium-test-'));
+    const port = challenge === 'http' ? 80 : 443;
+    try {
+        writeFileSync(join(dir, 'Caddyfile'), [
+            '{', '\tadmin off', '\tpersist_config off', `\tstorage file_system ${join(dir, 'data')}`, '\tlog {', '\t\toutput stderr', '\t\tformat json', '\t}', '}',
+            `${domain} {`, relay ? '\tbind 127.0.0.1' : '',
+            '\ttls {', '\t\tissuer acme {', `\t\t\tdir ${STAGING}`, challenge === 'http' ? '\t\t\tdisable_tlsalpn_challenge' : '\t\t\tdisable_http_challenge', '\t\t}', '\t}',
+            '\trespond "Clavarium: test" 200', '}', '',
+        ].join('\n'));
+        let finish;
+        const result = new Promise((resolve) => { finish = resolve; });
+        const timer = setTimeout(() => finish({ ok: false, why: `no answer from Let's Encrypt within ${Math.round(timeoutMs / 1000)} s: port ${port} probably does not reach ${relay ? 'the relay' : 'this machine'}` }), timeoutMs);
+        const proc = sys.start([P.caddy, 'run', '--config', join(dir, 'Caddyfile'), '--adapter', 'caddyfile'], {
+            env: { HOME: dir, XDG_DATA_HOME: dir, XDG_CONFIG_HOME: dir },
+            onLine: (line) => {
+                let j = null;
+                try { j = JSON.parse(line); } catch { /* not a log line */ }
+                if (j?.msg === 'certificate obtained successfully') finish({ ok: true });
+                else if (j && j.level === 'error' && /could not get certificate|obtaining certificate|job failed|obtain/i.test(j.msg ?? '')) finish({ ok: false, why: explain(j.error ?? j.msg, { domain, port, relay }) });
+                else if (!j && /address already in use|Error:/i.test(line)) finish({ ok: false, why: explain(line, { domain, port, relay }) });
+            },
+        });
+        proc.exited.then((r) => finish({ ok: false, why: `the test program stopped (exit ${r.code})` }));
+        const got = await result;
+        clearTimeout(timer);
+        proc.stop();
+        await proc.exited;
+        return got;
+    } finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+async function internetTest(sys, P, o) {
+    for (const challenge of ['http', 'tls']) {
+        const port = challenge === 'http' ? 80 : 443;
+        sys.print(`Test from the internet, port ${port}: Let's Encrypt (staging) comes to ${o.domain}...`);
+        const r = await acmeTest(sys, P, { domain: o.domain, relay: o.relay, challenge });
+        if (!r.ok) throw new Failed(`${r.why}.\nNothing was changed: this machine is still in local mode.`);
+        sys.print(`   port ${port}: reached. Good.`);
+    }
+}
+
+async function portsFree(sys) {
+    for (const port of [80, 443]) {
+        const r = await sys.run(['ss', '-ltnpH', `sport = :${port}`]);
+        if (r.out.trim()) throw new Failed(`port ${port} is already used on this machine: ${r.out.trim().split('\n')[0].replace(/\s+/g, ' ')}`);
+    }
+}
+
+/* ------------------------------ the relay path ------------------------------ */
+async function scanRelay(sys, o, deadline) {
+    for (;;) {
+        const r = await sys.run(['ssh-keyscan', '-T', '10', '-t', 'ed25519', '-p', o.relayPort, o.relay]);
+        const line = r.out.split('\n').find((l) => / ssh-ed25519 [A-Za-z0-9+/=]+$/.test(l.trim()));
+        if (line) return line.trim();
+        if (sys.now() > deadline) throw new Failed(`${o.relay} does not answer on port ${o.relayPort} (SSH)`);
+        sys.print(`${o.relay} does not answer on port ${o.relayPort} yet; trying again...`);
+        await sys.sleep(5000);
+    }
+}
+
+async function fingerprintOf(sys, P, line) {
+    const file = join(P.access, 'known_hosts.pending');
+    writeFileSync(file, `${line}\n`, { mode: 0o600 });
+    const r = await sys.run(['ssh-keygen', '-l', '-f', file]);
+    const print = /SHA256:[A-Za-z0-9+/]{43}/.exec(r.out)?.[0];
+    if (!print) throw new Failed(`the relay's key could not be read: ${tail(r)}`);
+    return { file, print };
+}
+
+async function waitForSetupKey(sys, o, at, deadline) {
+    const check = o.user === 'root' ? 'true' : 'sudo -n true';
+    let said = '';
+    const say = (text) => { if (text !== said) { said = text; sys.print(text); } };
+    for (;;) {
+        const r = await sys.run(['ssh', ...at, `${o.user}@${o.relay}`, check]);
+        if (r.code === 0) { sys.print(`The setup key opens ${o.user}@${o.relay}${o.user === 'root' ? '' : ', with sudo'}.`); return; }
+        const err = r.err || '';
+        if (/password is required|not in the sudoers|may not run sudo/i.test(err)) say(`${o.user} on ${o.relay} needs sudo without a password: add "${o.user} ALL=(ALL) NOPASSWD: ALL" in /etc/sudoers.d there. Waiting...`);
+        else if (/Permission denied/i.test(err)) say(`Waiting for the setup key on ${o.user}@${o.relay} (Ctrl-C to stop)...`);
+        else if (/Host key verification failed|REMOTE HOST IDENTIFICATION/i.test(err)) throw new Refused(`${o.relay} answered with another key than a moment ago: stopped`);
+        else say(`${o.relay} does not answer yet (${tail(r)}). Waiting...`);
+        if (sys.now() > deadline) throw new Failed(`the setup key was not accepted on ${o.user}@${o.relay} within ${WAIT_MS / 60000} minutes`);
+        await sys.sleep(5000);
+    }
+}
+
+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);
+    /* 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)) {
+        const r = await keeper(sys, P, { ...prior, PORT: o.relayPort }, ['version']);
+        if (r.code === 0 && /^\d/.test(r.out.trim())) { sys.print(`The relay ${o.relay} is set up already (clavarium-relay ${r.out.trim()}).`); return { ...prior, ...conf, SETUP_KEY: prior.SETUP_KEY ?? 'removed' }; }
+    }
+
+    sys.print('');
+    sys.print(`1. Put this SETUP KEY on the relay, in ~${o.user}/.ssh/authorized_keys of ${o.relay}${o.user === 'root' ? '' : ` (${o.user} needs sudo without a password)`}:`);
+    sys.print(`    ${keys.setup}`);
+    await qr(sys, keys.setup);
+    sys.print('(A public key: safe to show. It is taken out again at the end.)');
+    sys.print('');
+    const deadline = sys.now() + WAIT_MS;
+    const scanned = await scanRelay(sys, o, deadline);
+    const { file: pending, print } = await fingerprintOf(sys, P, scanned);
+    if (o.fingerprint && o.fingerprint !== print) {
+        rmSync(pending, { force: true });
+        throw new Refused(`${o.relay} answers with the key ${print}, not ${o.fingerprint}: it may not be your relay. Nothing was changed`);
+    }
+    await waitForSetupKey(sys, o, sshOptions(f.setup, pending, o.relayPort), deadline);
+
+    sys.print(`2. The relay's fingerprint:  ${print}`);
+    if (o.fingerprint) sys.print('   It is the one given with --relay-fingerprint. Good.');
+    else if (o.yes) sys.print('   Accepted without a check (--yes).');
+    else {
+        sys.print('   To compare, on the relay: ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub');
+        if (!(await sys.ask('   Is it the same?'))) { rmSync(pending, { force: true }); throw new Refused('not confirmed: nothing was changed'); }
+    }
+    renameSync(pending, f.knownHosts);
+    writeFileSync(join(P.tunnel, 'known_hosts'), `${scanned}\n`, { mode: 0o644 });
+    await sys.run(['chown', 'clavarium-tunnel:clavarium-tunnel', join(P.tunnel, 'known_hosts')]);
+
+    sys.print('3. Setting up the relay (tunnel account, maintenance account, port rule, automatic updates)...');
+    const script = readFileSync(join(P.code, 'current', 'app', 'deploy', 'relay.sh'), 'utf8');
+    const sudo = o.user === 'root' ? '' : 'sudo -n ';
+    /* The script is read whole into a file before it runs: run from standard
+       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 });
+    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);
+    const v = await keeper(sys, P, next, ['version']);
+    if (v.code !== 0) throw new Failed(`the relay's maintenance account does not answer: ${tail(v)}`);
+    sys.print(`   The relay is set up (clavarium-relay ${v.out.trim()}).`);
+    if (o.keepSetupKey) sys.print('   The setup key stays on the relay (--keep-setup-key). Later: sudo clavarium relay forget-setup-key');
+    else await forgetSetupKey(sys, P, next);
+    return readRelayConf(P);
+}
+
+/* The tunnel, for the test only: the service comes with server mode. */
+function startTunnel(sys, P, o) {
+    const lines = [];
+    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) });
+    return { proc, lines };
+}
+
+/* ------------------------------- the switch ------------------------------- */
+function serverModeOf(P) {
+    try { return /--public-origin https:\/\/(\S+)/.exec(readFileSync(P.unit, 'utf8'))?.[1] ?? null; } catch { return null; }
+}
+
+async function switchToServer(sys, P, o) {
+    const app = join(P.code, 'current', 'app');
+    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');
+    sys.print('');
+    sys.print('Switching to server mode: HTTPS, sign-in, the administrator...');
+    const r = await sys.run(argv, { stream: true, inherit: true });
+    if (r.code !== 0) throw new Failed(`the switch to server mode failed (exit ${r.code}, above: why)`);
+}
+
+/* `sudo clavarium online ...` */
+export async function online(o, sys, P = PATHS) {
+    const was = serverModeOf(P);
+    if (was) throw new Refused(`this machine is in server mode already: https://${was}`);
+    if (!existsSync(P.caddy)) throw new Failed('the HTTPS programs are not on this machine: run the installer again (curl -fsSL https://clavarium.org/install.sh | sudo bash)');
+    const keys = await ensureKeys(sys, P);
+    await checkDns(sys, o);
+    await portsFree(sys);
+    if (o.relay) await setUpRelay(sys, P, o, keys);
+    let tunnel = null;
+    try {
+        if (o.relay) {
+            tunnel = startTunnel(sys, P, o);
+            await sys.sleep(4000);
+            if (tunnel.proc.ended?.()) throw new Failed(`the tunnel to ${o.relay} did not come up: ${tunnel.lines.filter(Boolean).pop() ?? 'no reason given'}`);
+        }
+        await internetTest(sys, P, o);
+    } finally {
+        tunnel?.proc.stop();
+    }
+    await switchToServer(sys, P, o);
+    sys.print('');
+    sys.print(`Online: https://${o.domain}   (sign in as ${o.admin}, with the password above)`);
+    if (o.relay) sys.print('The relay is watched from here: sudo clavarium relay status');
+}
+
+/* `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;
+    switch (verb) {
+        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`);
+            const r = await keeper(sys, P, conf, [verb, ...rest], { stream: true });
+            if (r.code !== 0) throw new Failed(`the relay answered with exit ${r.code}`);
+            return;
+        }
+        case 'update-relay': {
+            const version = rest[0] ?? relayVersion(P);
+            if (!/^\d{1,4}\.\d{1,4}\.\d{1,6}(-[0-9A-Za-z.-]{1,40})?$/.test(version ?? '')) throw new Bad('relay update-relay [X.Y.Z]');
+            const r = await keeper(sys, P, conf, ['update-relay', version], { stream: true });
+            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');
+    }
+}
+
+/* ---------------------------- the real world ---------------------------- */
+export function realSys() {
+    return {
+        print: (text) => process.stdout.write(`${text}\n`),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        resolve: async (name) => {
+            const all = [];
+            for (const f of [dns.resolve4, dns.resolve6]) { try { all.push(...await f.call(dns, name)); } catch { /* none of that kind */ } }
+            return all;
+        },
+        run: (argv, { input, stream = false, inherit = false, env } = {}) => new Promise((resolve) => {
+            const child = spawn(argv[0], argv.slice(1), { env: env ? { ...process.env, ...env } : process.env, stdio: inherit ? 'inherit' : [input === undefined ? 'ignore' : 'pipe', stream ? 'inherit' : 'pipe', 'pipe'] });
+            let out = ''; let err = '';
+            child.stdout?.on('data', (d) => { out = (out + d).slice(-50_000); });
+            child.stderr?.on('data', (d) => { err = (err + d).slice(-50_000); if (stream) process.stderr.write(d); });
+            if (input !== undefined) child.stdin.end(input);
+            child.on('error', (e) => resolve({ code: 127, out, err: e.message }));
+            child.on('close', (code) => resolve({ code: code ?? 1, out, err }));
+        }),
+        start: (argv, { env, onLine }) => {
+            const child = spawn(argv[0], argv.slice(1), { env: env ? { ...process.env, ...env } : process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+            let ended = false;
+            for (const s of [child.stdout, child.stderr]) createInterface({ input: s }).on('line', (l) => onLine?.(l));
+            const exited = new Promise((resolve) => { child.on('error', () => { ended = true; resolve({ code: 127 }); }); child.on('close', (code) => { ended = true; resolve({ code: code ?? 1 }); }); });
+            return { exited, ended: () => ended, stop: () => { if (!ended) child.kill('SIGTERM'); } };
+        },
+        ask: async (question) => {
+            let fd;
+            try { fd = openSync('/dev/tty', 'r+'); } catch { return false; }
+            try {
+                writeSync(fd, `${question} [y/N] `);
+                const buf = Buffer.alloc(256); let s = '';
+                while (!s.includes('\n')) { const n = readSync(fd, buf, 0, buf.length, null); if (!n) break; s += buf.toString('utf8', 0, n); }
+                return /^y(es)?$/i.test(s.trim());
+            } finally { closeSync(fd); }
+        },
+    };
+}

package/deploy/relay.sh

@@ -6,8 +6,12 @@
 #
 #   sudo deploy/relay.sh --key "ssh-ed25519 AAAA... clavarium-tunnel"
 #
-#   --key LINE     the PUBLIC key of the home machine (install.sh prints it)
-#   --dry-run      check the parameters, say what would be done, do nothing
+#   --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)
+#   --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.
 #
 # 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
@@ -17,7 +21,12 @@
 #   - 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.
+#   - a rule that sends what arrives on 443 and 80 to those two ports;
+#   - 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);
+#   - Ubuntu's security updates, by themselves (unattended-upgrades).
 #
 # 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
@@ -29,30 +38,38 @@
 # ---------------------------------------------------------------------------
 set -euo pipefail
 
+# The version of the maintenance program this Clavarium works with.
+RELAY_VERSION="0.1.0"
 ACCOUNT="clavarium-tunnel"
 TLS_PORT="8443"
 HTTP_PORT="8080"
-SSHD_FILE="/etc/ssh/sshd_config.d/10-clavarium-relay.conf"
-KEYS_DIR="/etc/ssh/clavarium-relay"
-RULES="/etc/clavarium-relay.nft"
-UNIT="/etc/systemd/system/clavarium-relay-ports.service"
+PROGRAM="/usr/local/sbin/clavarium-relay"
+# Tests run it on a folder that stands for "/".
+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\" [--dry-run]" >&2; exit 64; }
+bad() { echo "relay: $*" >&2; echo "usage: relay.sh --key \"ssh-ed25519 AAAA... name\" [--keeper-key \"ssh-ed25519 AAAA... name\"] [--dry-run]" >&2; exit 64; }
 refuse() { echo "relay: REFUSED: $*" >&2; exit 78; }
 step() { echo "== $*"; }
 
-KEY=""; DRY="no"
+KEY=""; KEEPER_KEY=""; 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 ;;
         --dry-run) DRY="yes"; shift ;;
         *) bad "unknown parameter: $1" ;;
     esac
 done
-# The key goes into a file that gives rights: it must be exactly a public
-# key, on one line, with nothing that could add an option next to it.
-case "$KEY" in *"PRIVATE KEY"*) bad "this is a PRIVATE key: it must never leave home. Give the public one (one line, starts with ssh-ed25519)" ;; esac
+# A key goes into a file that gives rights: it must be exactly a public key,
+# on one line, with nothing that could add an option next to it.
+for k in "$KEY" "$KEEPER_KEY"; do
+    case "$k" in *"PRIVATE KEY"*) bad "this is a PRIVATE key: it must never leave home. Give the public one (one line, starts with ssh-ed25519)" ;; esac
+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"
 
 if [ "$DRY" = "yes" ]; then
     cat <<PLAN
@@ -60,94 +77,65 @@ 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
   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)")
+  updates     Ubuntu's security updates, automatic
 PLAN
     exit 0
 fi
 
-[ "$(id -u)" -eq 0 ] || refuse "run it as root (sudo)"
+[ -n "$ROOT" ] || [ "$(id -u)" -eq 0 ] || refuse "run it as root (sudo)"
 # shellcheck disable=SC1091
-. /etc/os-release
-case "${ID:-} ${ID_LIKE:-}" in *ubuntu*|*debian*) : ;; *) refuse "this is ${PRETTY_NAME:-an unknown system}; the relay installs on Ubuntu or Debian" ;; esac
+OS="$(. "$ROOT/etc/os-release" 2>/dev/null; printf '%s %s|%s' "${ID:-}" "${ID_LIKE:-}" "${PRETTY_NAME:-}")"
+case "${OS%%|*}" in *ubuntu*|*debian*) : ;; *) refuse "this is ${OS#*|}; the relay installs on Ubuntu or Debian" ;; esac
 command -v sshd >/dev/null 2>&1 || refuse "there is no SSH server on this machine (package openssh-server)"
-grep -Eqs '^\s*Include\s+/etc/ssh/sshd_config\.d/' /etc/ssh/sshd_config || refuse "/etc/ssh/sshd_config does not include /etc/ssh/sshd_config.d: the account could not be bounded"
-check="$(mktemp)"; printf '%s\n' "$KEY" > "$check"
-ssh-keygen -l -f "$check" >/dev/null 2>&1 || { rm -f -- "$check"; refuse "this is not a key the SSH tools recognise"; }
+grep -Eqs '^\s*Include\s+/etc/ssh/sshd_config\.d/' "$ROOT/etc/ssh/sshd_config" || refuse "/etc/ssh/sshd_config does not include /etc/ssh/sshd_config.d: the account could not be bounded"
+check="$(mktemp)"
+for k in "$KEY" "$KEEPER_KEY"; do
+    [ -n "$k" ] || continue
+    printf '%s\n' "$k" > "$check"
+    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
 
-step "packages"
-command -v nft >/dev/null 2>&1 || { export DEBIAN_FRONTEND=noninteractive; apt-get update -qq; apt-get install -y -qq nftables >/dev/null; }
-
-step "account"
-id "$ACCOUNT" >/dev/null 2>&1 || useradd --system --home-dir /nonexistent --no-create-home --shell /usr/sbin/nologin "$ACCOUNT"
-install -d -o root -g root -m 0755 "$KEYS_DIR"
-# The key file belongs to root: the account cannot give itself another key.
-printf 'restrict,port-forwarding,permitlisten="%s",permitlisten="%s" %s\n' "$TLS_PORT" "$HTTP_PORT" "$KEY" > "$KEYS_DIR/$ACCOUNT"
-chmod 0644 "$KEYS_DIR/$ACCOUNT"
-cat > "$SSHD_FILE" <<SSHD
-# Clavarium relay: what the tunnel account may do. Written by relay.sh.
-Match User $ACCOUNT
-    AuthorizedKeysFile $KEYS_DIR/%u
-    PasswordAuthentication no
-    KbdInteractiveAuthentication no
-    AllowTcpForwarding remote
-    GatewayPorts clientspecified
-    PermitListen $TLS_PORT $HTTP_PORT
-    PermitOpen none
-    PermitTTY no
-    X11Forwarding no
-    AllowAgentForwarding no
-    PermitTunnel no
-    ForceCommand /bin/false
-    # A tunnel that died without saying so gives its ports back within minutes.
-    ClientAliveInterval 30
-    ClientAliveCountMax 3
-# What follows this file in the server's settings is for everybody again.
-Match all
-SSHD
-if ! sshd -t; then rm -f -- "$SSHD_FILE"; refuse "the SSH server refused these settings; they were taken out again"; fi
-systemctl reload ssh.service 2>/dev/null || systemctl reload sshd.service
-
-step "ports"
-cat > "$RULES" <<NFT
-# Clavarium relay: what arrives on 443 and 80 goes to the tunnel. Written by relay.sh.
-table inet clavarium_relay
-delete table inet clavarium_relay
-table inet clavarium_relay {
-  chain arriving {
-    type nat hook prerouting priority dstnat;
-    tcp dport 443 redirect to :$TLS_PORT
-    tcp dport 80 redirect to :$HTTP_PORT
-  }
+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
+# --- fetch_relay: shared, word for word, with deploy/relay.sh (a test says so) ---
+# fetch_relay VERSION DIR: the package clavarium-relay@VERSION from the registry,
+# checked against the registry's sha512, unpacked in DIR (DIR/package/...).
+fetch_relay() {
+    local version="$1" dir="$2" meta integrity got proto="=https"
+    case "$REGISTRY" in file://*) proto="=file" ;; esac
+    meta="$(curl --proto "$proto" -fsSL --max-time 60 "$REGISTRY/clavarium-relay/$version")" || { echo "the registry did not answer for clavarium-relay@$version" >&2; return 1; }
+    printf '%s' "$meta" | grep -Eq "\"version\" *: *\"${version//./\\.}\"" || { echo "the registry has no clavarium-relay@$version" >&2; return 1; }
+    integrity="$(printf '%s' "$meta" | grep -Eo '"integrity" *: *"sha512-[A-Za-z0-9+/=]+"' | head -1 | sed 's/.*"\(sha512-[^"]*\)"$/\1/')"
+    [ -n "$integrity" ] || { echo "the registry gave no sha512 for clavarium-relay@$version" >&2; return 1; }
+    curl --proto "$proto" -fsSL --max-time 120 -o "$dir/relay.tgz" "$REGISTRY/clavarium-relay/-/clavarium-relay-$version.tgz" || { echo "the package could not be downloaded" >&2; return 1; }
+    got="sha512-$(openssl dgst -sha512 -binary "$dir/relay.tgz" | base64 -w0)"
+    [ "$got" = "$integrity" ] || { echo "the package is not the one the registry describes (sha512)" >&2; return 1; }
+    tar -xzf "$dir/relay.tgz" -C "$dir" --no-same-owner package/clavarium-relay package/package.json || { echo "the package does not hold the program" >&2; return 1; }
+    grep -Eq "\"name\" *: *\"clavarium-relay\"" "$dir/package/package.json" && grep -Eq "\"version\" *: *\"${version//./\\.}\"" "$dir/package/package.json" || { echo "the package is not clavarium-relay@$version" >&2; return 1; }
+    bash -n "$dir/package/clavarium-relay" || { echo "the program in the package does not parse" >&2; return 1; }
 }
-NFT
-cat > "$UNIT" <<UNITFILE
-[Unit]
-Description=Clavarium relay - 443 and 80 go to the tunnel
-After=network-pre.target
-Before=network.target
-
-[Service]
-Type=oneshot
-RemainAfterExit=yes
-ExecStart=/usr/sbin/nft -f $RULES
-ExecStop=/usr/sbin/nft delete table inet clavarium_relay
+# --- end of fetch_relay ---
+work="$(mktemp -d)"
+if ! fetch_relay "$RELAY_VERSION" "$work"; then rm -rf -- "$work"; refuse "clavarium-relay@$RELAY_VERSION could not be installed (above: why)"; fi
+install -d "$ROOT$(dirname "$PROGRAM")"
+install -m 0755 "$work/package/clavarium-relay" "$ROOT$PROGRAM"
+rm -rf -- "$work"
 
-[Install]
-WantedBy=multi-user.target
-UNITFILE
-systemctl daemon-reload
-systemctl enable --quiet clavarium-relay-ports.service
-systemctl restart clavarium-relay-ports.service
-systemctl is-active --quiet clavarium-relay-ports.service || refuse "the port rule could not be loaded: journalctl -u clavarium-relay-ports"
+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
 
 echo
 echo "This machine is a relay. It waits for the home machine to dial in."
 echo "Compare with what the home machine printed (it must be the same):"
-echo "    $(ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub | cut -d' ' -f2)"
+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"

package/npm-shrinkwrap.json

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

package/package.json

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