@twinsearth/w2m-dsh-plugin 0.0.0-stage → 0.4.7

package/deploy/nginx/w2m.conf.example

@@ -0,0 +1,196 @@
+# ============================================================================
+#  W2M relay behind nginx  --  example reverse-proxy configuration
+# ============================================================================
+#
+#  This file is a TEMPLATE. Replace every <placeholder> before using it.
+#  Nothing here contains a real domain, IP or token.
+#
+#  Validated how: nginx is not installed on the authoring machine, so this
+#  file was NOT checked with `nginx -t`. It was written against the nginx
+#  directives' documented semantics, and the three Server-Sent-Events settings
+#  it depends on were verified against the relay's actual response headers
+#  (see docs/DEPLOY.md, "SSE and reverse proxies").
+#
+#  ---------------------------------------------------------------------------
+#  THE THREE THINGS THAT MAKE SSE WORK (drop any one and events silently stop)
+#  ---------------------------------------------------------------------------
+#   1. `proxy_buffering off;`      nginx otherwise buffers the event stream and
+#                                  holds frames until its buffer fills, so the
+#                                  client connects, receives nothing, and looks
+#                                  "connected but dead".
+#   2. `proxy_read_timeout <long>;` the stream is a long-lived response with no
+#                                  data between keepalives (the relay sends
+#                                  `: keepalive` every 15s). The nginx default
+#                                  of 60s is survivable, but any shorter value
+#                                  kills idle connections.
+#   3. `proxy_http_version 1.1;`   SSE is an HTTP/1.1 chunked response. With the
+#                                  nginx default (1.0) the connection is closed
+#                                  at the end of the first response, so the
+#                                  stream ends immediately after it starts.
+#  The relay also sends `X-Accel-Buffering: no` and
+#  `Cache-Control: no-cache, no-transform`, which handles (1) for nginx
+#  automatically -- but keep `proxy_buffering off` anyway, because that header
+#  is nginx-specific and you do not want correctness to depend on one vendor.
+#
+#  ---------------------------------------------------------------------------
+#  TWO DEPLOYMENT SHAPES -- pick ONE
+#  ---------------------------------------------------------------------------
+#   Shape 1 (recommended, simplest): the relay is mounted at the ROOT of a
+#   dedicated hostname. Everything below marked [ROOT] applies; delete the
+#   sub-path block at the bottom. Relay flags: no --base-path.
+#
+#   Shape 2: the relay shares a hostname and lives under a prefix, e.g.
+#   https://<your-domain>/w2m/. Everything marked [ROOT] applies, PLUS the
+#   sub-path block at the bottom, and the relay MUST be started with
+#   `--base-path /w2m`. See docs/DEPLOY.md, "Sub-path deployments".
+# ============================================================================
+
+# Upstream: the relay listening on loopback. Keep it on loopback and let nginx
+# be the only thing exposed; the relay then needs no TLS of its own.
+upstream w2m_relay {
+    server 127.0.0.1:8787;
+    keepalive 16;
+}
+
+# ---------------------------------------------------------------------------
+# HTTP -> HTTPS redirect.
+# Remove this block if something else (CDN, load balancer) already redirects.
+# ---------------------------------------------------------------------------
+server {
+    listen 80;
+    listen [::]:80;
+    server_name <your-domain>;
+
+    # Let's Encrypt HTTP-01 challenge. Keep this even after issuance: renewal
+    # needs it every ~60 days.
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+# ---------------------------------------------------------------------------
+# The relay itself.
+# ---------------------------------------------------------------------------
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    http2 on;
+    server_name <your-domain>;
+
+    # --- certificates -------------------------------------------------------
+    # Paths are what certbot writes by default; adjust to your own layout.
+    ssl_certificate     /etc/letsencrypt/live/<your-domain>/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/<your-domain>/privkey.pem;
+    ssl_protocols       TLSv1.2 TLSv1.3;
+    ssl_session_cache   shared:SSL:10m;
+    ssl_session_timeout 1d;
+
+    # --- request size -------------------------------------------------------
+    # Task results carry command output inline, so the default 1m is too small
+    # for a build log. Match `max_frame_bytes` on the relay side; 16m is a
+    # comfortable default for text output.
+    client_max_body_size 16m;
+
+    # --- SSE-friendly defaults ---------------------------------------------
+    # HTTP/1.1 is required for chunked event streams (reason 3 above). gzip
+    # must stay OFF here: compressing an event stream makes nginx buffer it,
+    # which reintroduces the exact failure this file exists to prevent.
+    proxy_http_version 1.1;
+    proxy_set_header Connection "";
+    gzip off;
+
+    # --- identity headers ---------------------------------------------------
+    # Host is what the relay (and its rate limiter) sees. X-Forwarded-* are
+    # only believed by the relay when it is started with --trust-proxy, which
+    # is exactly the case here, so these three must be set correctly.
+    proxy_set_header Host              $host;
+    proxy_set_header X-Real-IP         $remote_addr;
+    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host  $host;
+    # The port the client actually used, needed when it is not the scheme
+    # default (the relay uses it to build its public URL hints).
+    proxy_set_header X-Forwarded-Port  $server_port;
+
+    # ======================= [ROOT] health check ==========================
+    # Kept unauthenticated so `curl https://<your-domain>/healthz` from a
+    # laptop answers "is the relay alive, and has it restarted?".
+    location = /healthz {
+        proxy_pass http://w2m_relay/healthz;
+
+        # --- the three SSE settings also apply to this endpoint's server block
+        # but buffering is harmless for a small JSON body, so only the timeout
+        # matters here.
+        proxy_read_timeout 30s;
+    }
+
+    # ======================= [ROOT] event stream ==========================
+    # The SSE endpoint gets its own location so the long timeout and disabled
+    # buffering cannot be forgotten for the one route that needs them.
+    location = /v1/stream {
+        proxy_pass http://w2m_relay/v1/stream;
+
+        # 1. no buffering: frames must leave immediately
+        proxy_buffering off;
+        proxy_cache off;
+        # 2. long-lived response: keepalives arrive every 15s; allow a wide
+        #    margin (this is 24h, i.e. effectively "do not time out")
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+        # 3. HTTP/1.1 chunked (set for the whole server block above; repeated
+        #    here so this file is safe to copy location-by-location)
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+    }
+
+    # ======================= [ROOT] everything else =======================
+    location / {
+        proxy_pass http://w2m_relay;
+
+        proxy_buffering off;
+        proxy_read_timeout 120s;
+        proxy_send_timeout 120s;
+    }
+
+    # ======================= Shape 2: sub-path ============================
+    # Uncomment this block ONLY if the relay is mounted under a prefix.
+    #
+    #   nginx passes the prefix through unchanged (`proxy_pass` with no URI),
+    #   and the relay is started with `--base-path /w2m`, which is the
+    #   combination PROTOCOL-v0.1.2 §3 describes as "反代原样透传".
+    #
+    #   Client `rabbitUrl` must then include the same prefix:
+    #       https://<your-domain>/w2m
+    #
+    #   Do NOT use a trailing-slash rewrite (`proxy_pass http://w2m_relay/;`)
+    #   here: stripping the prefix in nginx while the relay also expects it is
+    #   the single most common misconfiguration, and it produces 404 on every
+    #   /v1/* call.
+    #
+    # location /w2m/ {
+    #     proxy_pass http://w2m_relay;
+    #
+    #     proxy_http_version 1.1;
+    #     proxy_set_header Connection "";
+    #     proxy_set_header Host              $host;
+    #     proxy_set_header X-Real-IP         $remote_addr;
+    #     proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+    #     proxy_set_header X-Forwarded-Proto $scheme;
+    #     proxy_set_header X-Forwarded-Port  $server_port;
+    #
+    #     proxy_buffering off;
+    #     proxy_read_timeout 86400s;
+    #     proxy_send_timeout 86400s;
+    # }
+    #
+    # # The relay answers /healthz both with and without the prefix, so a
+    # # monitoring probe pointed at the bare path keeps working:
+    # location = /healthz {
+    #     proxy_pass http://w2m_relay/healthz;
+    #     proxy_read_timeout 30s;
+    # }
+}

package/deploy/shared-server/README.md

@@ -0,0 +1,118 @@
+# The shared server
+
+One always-on host that gives every machine in the fleet the two things a machine behind
+NAT cannot provide for itself: **a place to meet** (rendezvous + signalling + the task
+ledger) and **an honest answer about its own address** (a STUN responder, so a hole punch
+has somewhere to aim).
+
+This directory deploys that host in one command. It is the same sequence the public
+instance was built with.
+
+## What runs where
+
+| Component | Listens | Why it is there |
+|---|---|---|
+| `w2m-rabbit` (relay) | `0.0.0.0:8787` tcp | Pairing, the SSE downlink, task offers, the result ledger, `POST /v1/peer/announce` and `GET /v1/peer/{machine_id}` — the rendezvous the punch needs |
+| `w2m-stun` | `0.0.0.0:3478` udp | Answers "what address and port does the world see me as", which is the address a peer must aim at |
+| nginx | `:80` tcp | A second path to the same relay on a port that is open on most hosts, with SSE-safe settings (`proxy_buffering off`, 24 h read timeout on `/v1/stream`) |
+| (optional) `w2m-localside` | outbound only | Makes the server itself a machine in the fleet — useful for a cross-region check that does not involve a second laptop |
+
+Everything is outbound from the machines' point of view. The server never dials a machine;
+it answers, and it introduces peers to each other.
+
+## Install
+
+```bash
+scp twinsearth-w2m-dsh-plugin-<version>.tgz root@<host>:/tmp/w2m-pkg.tgz
+scp deploy/shared-server/install.sh root@<host>:/tmp/
+ssh root@<host> 'bash /tmp/install.sh /tmp/w2m-pkg.tgz'          # relay + STUN + proxy
+ssh root@<host> 'bash /tmp/install.sh /tmp/w2m-pkg.tgz PAIR-XXXXXXXX'   # ... and join the fleet
+```
+
+The pairing code comes from the relay's first start (`journalctl -u w2m-rabbit` or
+`/var/log/w2m/rabbit.log`); it rotates after each successful pairing.
+
+Then point every machine at it — in v0.4.0 that is the **default**, so an empty `rabbitUrl`
+already means "the shared server":
+
+```yaml
+- id: w2m
+  config:
+    rabbitUrl: 'http://202.182.123.154:8787'   # optional: this is the default anyway
+    operatorToken: '<from /var/lib/w2m/rabbit/operator-token.txt>'
+    p2pMode: auto
+```
+
+## The two decisions worth knowing
+
+**1. The relay binds `0.0.0.0`, unlike `deploy/systemd/w2m-rabbit.service`.** That template
+binds loopback on purpose, because on a private host something else terminates TLS or the
+network is already encrypted. A *shared* server has no such thing in front of it: it is the
+public endpoint. Binding loopback would mean the machines cannot reach it at all, so the
+public port is the point rather than an oversight. Port 80 through nginx reaches exactly the
+same relay; the two differ in nothing but the port number.
+
+**2. There is no TLS on the reference instance, and that is a real, stated cost.** Without a
+hostname there is nothing to issue a certificate for. Everything the relay sees — pairing
+codes, device tokens, the operator token, task offers and every result — crosses the wire in
+clear text. What can be said honestly about the exposure:
+
+* the two sockets that matter most for a fleet are still the machines' own: with the direct
+  path up, the payload does not traverse the relay at all (`transport` says which path a task
+  actually took);
+* the relay is not a shell: it can forge tasks, and the machine-side allow-list is the
+  load-bearing control;
+* the operator token is a bearer credential in clear text. Treat it as compromised if the
+  path is hostile, and rotate it by deleting `operator-token.txt` and restarting the relay.
+
+**To add TLS**, point a subdomain at the host (`w2m.example.com`), then run certbot with the
+webroot inside the nginx block this script installs, and add the `listen 443 ssl` server from
+`deploy/nginx/w2m.conf.example`. Nothing on the machines has to change except `rabbitUrl`.
+
+## Verify the deployment
+
+```bash
+# 1. the relay answers
+curl -fsS http://127.0.0.1:8787/healthz | head -c 200
+
+# 2. the relaying is real: pair a machine and watch it appear
+curl -fsS -H "Authorization: Bearer $(cat /var/lib/w2m/rabbit/operator-token.txt)" ...   # needs a device token, not the operator token
+
+# 3. STUN answers through the responder (the number it returns is the NAT's opinion of you)
+node -e "import('/opt/w2m/app/src/agent/stun.mjs').then(async (s) => {
+  const { socket } = await s.bindUdpSocket();
+  console.log(await s.stunQuery(socket, '<host>:3478')); socket.close(); })"
+```
+
+A healthy instance answers all three. From a machine **behind another network**, run
+`src/agent/stun.mjs`'s `discoverReflexive` against two or three servers: if every server
+reports the same mapped port, the network is `endpoint-independent` and punching can work; if
+each reports a different one, the network is `endpoint-dependent` (symmetric) and the punch
+cannot succeed **from that network** whatever the server does. Measured, and written down
+rather than discovered later: the reference client network (China Mobile) is
+`endpoint-dependent`, so it falls back to the relay — which is exactly why `auto` and not
+`direct` is the default.
+
+## Operating it
+
+```bash
+systemctl status w2m-rabbit w2m-stun
+journalctl -u w2m-rabbit -f
+tail -f /var/log/w2m/rabbit.log /var/log/w2m/stun.log
+```
+
+* State lives in `/var/lib/w2m/rabbit` (`devices.json` + `ledger.jsonl`), so a restart keeps
+  every paired machine and the task history. Losing that directory means every machine pairs
+  again — see `docs/TROUBLESHOOTING.md`.
+* `ufw` needs `8787/tcp` and `3478/udp`; port 80 only if you use the proxy path.
+* **If this host must *accept* a punch** (it runs a Localside agent and a peer dials it), its punch
+  socket needs a reachable UDP port *and* the port has to survive a restart. Pin it — until v0.4.1
+  the node bound an ephemeral one, so the rule had to be re-pointed after every agent start, and a
+  stale rule showed up only as a punch that timed out and tasks that quietly used the relay:
+
+  ```bash
+  # add to the agent's ExecStart, then: ufw allow 41234/udp
+  --p2p-port 41234
+  ```
+* Upgrades are the same command: fetch the new tarball, run `install.sh` again. The relay
+  restarts; machines reconnect on their own (the agent's stream reconnects with backoff).

package/deploy/shared-server/install.sh

@@ -0,0 +1,255 @@
+#!/bin/bash
+# ============================================================================
+#  W2M shared server -- relay + STUN + reverse proxy, one command.
+# ============================================================================
+#
+#  This is the script the shared server at 202.182.123.154 was deployed with (the
+#  same steps, parameterised). It is idempotent: re-running it re-deploys the
+#  package and restarts the services, which is how an upgrade is done.
+#
+#  Usage, on a fresh Debian/Ubuntu host as root:
+#
+#      curl -fsSL https://nodejs.org/... # not needed: this script installs Node itself
+#      scp twinsearth-w2m-dsh-plugin-<version>.tgz root@<host>:/tmp/w2m-pkg.tgz
+#      bash install.sh /tmp/w2m-pkg.tgz [PAIR-XXXXXXXX]
+#
+#  What it creates:
+#      /opt/w2m/app                    the package (bin/, src/, lib/)
+#      /var/lib/w2m/rabbit             relay state: devices.json, ledger, operator token
+#      /etc/systemd/system/w2m-rabbit.service   relay on 0.0.0.0:8787
+#      /etc/systemd/system/w2m-stun.service     STUN responder on 0.0.0.0:3478/udp
+#      /etc/nginx/conf.d/w2m.conf      port 80 -> 127.0.0.1:8787, SSE-safe
+#      ufw: 8787/tcp, 3478/udp
+#
+#  With a package tarball the archive root is `package/` (npm pack layout); a git
+#  checkout tarball has no root directory. Both are handled below.
+#
+#  WHY THE RELAY BINDS 0.0.0.0 HERE, when deploy/systemd/w2m-rabbit.service
+#  deliberately binds 127.0.0.1: on a *shared* server the relay IS the public
+#  endpoint -- there is no private network in front of it and no TLS terminator
+#  unless one is added. Port 80 through nginx is the same relay, so the two paths
+#  differ in nothing but the port. See deploy/shared-server/README.md for the
+#  security consequences, which are real: without TLS the operator token and every
+#  result travel in clear text.
+# ============================================================================
+set -euo pipefail
+
+PKG="${1:?usage: install.sh <package.tgz|checkout.tar.gz> [PAIR-XXXXXXXX]}"
+PAIR_CODE="${2:-}"
+RABBIT_PORT="${RABBIT_PORT:-8787}"
+STUN_PORT="${STUN_PORT:-3478}"
+NODE_DIR=/opt/node22
+APP_DIR=/opt/w2m/app
+STATE_DIR=/var/lib/w2m/rabbit
+LOG_DIR=/var/log/w2m
+
+say() { printf '\n== %s ==\n' "$1"; }
+
+say "node"
+if [ ! -x "${NODE_DIR}/bin/node" ]; then
+  case "$(uname -m)" in
+    x86_64) NODE_ARCH=linux-x64 ;;
+    aarch64) NODE_ARCH=linux-arm64 ;;
+    *) echo "unsupported architecture $(uname -m)"; exit 1 ;;
+  esac
+  NODE_VERSION=v22.14.0
+  ( cd /tmp
+    curl -fsSL -o "node.tar.xz" "https://nodejs.org/dist/${NODE_VERSION}/node-${NODE_VERSION}-${NODE_ARCH}.tar.xz"
+    mkdir -p "${NODE_DIR}"
+    tar -xJf node.tar.xz -C "${NODE_DIR}" --strip-components=1
+    rm -f node.tar.xz )
+fi
+ln -sf "${NODE_DIR}/bin/node" /usr/local/bin/node
+ln -sf "${NODE_DIR}/bin/npm" /usr/local/bin/npm
+node -v
+
+say "package"
+mkdir -p "${APP_DIR}" "${STATE_DIR}" "${LOG_DIR}"
+STAGE="$(mktemp -d)"
+tar -xzf "${PKG}" -C "${STAGE}"
+if [ -d "${STAGE}/package/bin" ]; then APP_SRC="${STAGE}/package"; else APP_SRC="${STAGE}"; fi
+[ -f "${APP_SRC}/bin/w2m-rabbit.mjs" ] || { echo "not a W2M package: ${PKG}"; exit 1; }
+tar -C "${APP_SRC}" -cf - . | tar -C "${APP_DIR}" -xf -
+rm -rf "${STAGE}"
+
+if ! id w2m >/dev/null 2>&1; then useradd --system --home /var/lib/w2m --shell /usr/sbin/nologin w2m; fi
+chown -R w2m:w2m /opt/w2m /var/lib/w2m "${LOG_DIR}"
+node --check "${APP_DIR}/bin/w2m-rabbit.mjs"
+node --check "${APP_DIR}/bin/w2m-stun.mjs"
+echo "version: $(node -p "require('${APP_DIR}/package.json').version")"
+
+say "services"
+cat > /etc/systemd/system/w2m-rabbit.service <<UNIT
+[Unit]
+Description=W2M Rabbit relay (P2P rendezvous, signalling and task ledger)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+WorkingDirectory=${APP_DIR}
+ExecStart=/usr/local/bin/node ${APP_DIR}/bin/w2m-rabbit.mjs --host 0.0.0.0 --port ${RABBIT_PORT} --state ${STATE_DIR}
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=true
+ReadWritePaths=/var/lib/w2m
+StandardOutput=append:${LOG_DIR}/rabbit.log
+StandardError=append:${LOG_DIR}/rabbit.log
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+
+cat > /etc/systemd/system/w2m-stun.service <<UNIT
+[Unit]
+Description=W2M STUN responder - reflexive address discovery for P2P hole punching
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=w2m
+Group=w2m
+ExecStart=/usr/local/bin/node ${APP_DIR}/bin/w2m-stun.mjs --host 0.0.0.0 --port ${STUN_PORT} --log-level info
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6
+StandardOutput=append:${LOG_DIR}/stun.log
+StandardError=append:${LOG_DIR}/stun.log
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+
+systemctl daemon-reload
+systemctl enable w2m-rabbit w2m-stun >/dev/null
+systemctl restart w2m-stun
+systemctl restart w2m-rabbit
+sleep 2
+systemctl is-active w2m-rabbit w2m-stun
+
+say "firewall"
+if command -v ufw >/dev/null 2>&1; then
+  ufw allow "${RABBIT_PORT}/tcp" >/dev/null
+  ufw allow "${STUN_PORT}/udp" >/dev/null
+  ufw status | grep -E "${RABBIT_PORT}|${STUN_PORT}" || true
+else
+  echo "ufw not installed; open ${RABBIT_PORT}/tcp and ${STUN_PORT}/udp yourself"
+fi
+
+say "reverse proxy on :80"
+if command -v nginx >/dev/null 2>&1; then
+  cat > /etc/nginx/conf.d/w2m.conf <<NGINX
+# Port 80 in front of the relay. \`proxy_pass\` with no URI passes the path through
+# unchanged, so the relay needs no --base-path here. /v1/stream is SSE: buffering must
+# be off and the read timeout must exceed the stream's lifetime.
+upstream w2m_relay {
+    server 127.0.0.1:${RABBIT_PORT};
+    keepalive 16;
+}
+
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name _;
+    client_max_body_size 8m;
+
+    location = /healthz {
+        proxy_pass http://w2m_relay/healthz;
+        proxy_set_header Host \$host;
+        proxy_read_timeout 30s;
+        access_log off;
+    }
+
+    location = /v1/stream {
+        proxy_pass http://w2m_relay/v1/stream;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host              \$host;
+        proxy_set_header X-Real-IP         \$remote_addr;
+        proxy_set_header X-Forwarded-For   \$proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto \$scheme;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+    }
+
+    location / {
+        proxy_pass http://w2m_relay;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host              \$host;
+        proxy_set_header X-Real-IP         \$remote_addr;
+        proxy_set_header X-Forwarded-For   \$proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto \$scheme;
+        proxy_buffering off;
+        proxy_read_timeout 120s;
+        proxy_send_timeout 120s;
+    }
+}
+NGINX
+  # Transactional: this host may already front something else.
+  if nginx -t 2>/tmp/w2m-nginx-test.log; then
+    systemctl reload nginx
+    echo "nginx reloaded"
+  else
+    echo "nginx config test failed:"
+    cat /tmp/w2m-nginx-test.log
+    rm -f /etc/nginx/conf.d/w2m.conf
+    exit 1
+  fi
+else
+  echo "nginx not installed; the relay is still reachable directly on :${RABBIT_PORT}"
+fi
+
+say "health"
+curl -fsS "http://127.0.0.1:${RABBIT_PORT}/healthz" >/dev/null && echo "relay: ok"
+node -e "
+import('${APP_DIR}/src/agent/stun.mjs').then(async (stun) => {
+  const { socket } = await stun.bindUdpSocket();
+  const one = await stun.stunQuery(socket, '127.0.0.1:${STUN_PORT}');
+  console.log('stun :', one.ok ? 'ok reflexive=' + JSON.stringify(one.reflexive) : 'FAILED ' + one.error);
+  socket.close();
+});
+"
+echo "operator token: ${STATE_DIR}/operator-token.txt"
+
+say "optional: this host as a fleet machine"
+if [ -n "${PAIR_CODE}" ]; then
+  DEMO=/opt/w2m/demo
+  mkdir -p "${DEMO}"
+  printf '* text=auto eol=lf\n' > "${DEMO}/.gitattributes"
+  printf 'console.log("w2m-wan-ok");\n' > "${DEMO}/demo.mjs"
+  ( cd "${DEMO}"
+    git config --global --add safe.directory "${DEMO}" >/dev/null 2>&1 || true
+    [ -d .git ] || git init -q -b main
+    git -c user.email=w2m@localhost -c user.name=w2m add -A
+    git -c user.email=w2m@localhost -c user.name=w2m commit -qm "w2m demo project" || true )
+  chown -R w2m:w2m "${DEMO}" /var/lib/w2m
+  # `--once` streams after pairing, so the pair run is bounded by timeout on purpose.
+  timeout 25 sudo -u w2m env HOME=/var/lib/w2m DSH_HOME=/var/lib/w2m/.dsh \
+    /usr/local/bin/node "${APP_DIR}/bin/w2m-localside.mjs" \
+      --rabbit "http://127.0.0.1:${RABBIT_PORT}" --pair "${PAIR_CODE}" \
+      --project "${DEMO}" --name "$(hostname)" --state /var/lib/w2m/localside \
+      --allowed-commands '["node --version","node -e","git status --porcelain"]' >/tmp/w2m-pair.log 2>&1 || true
+  grep -E 'paired|error' /tmp/w2m-pair.log | head -3 || true
+  chown -R w2m:w2m /var/lib/w2m
+  echo "pairing done; start the agent with:"
+  echo "  sudo -u w2m env HOME=/var/lib/w2m node ${APP_DIR}/bin/w2m-localside.mjs --rabbit http://127.0.0.1:${RABBIT_PORT} --project ${DEMO} --name $(hostname) --state /var/lib/w2m/localside --allowed-commands '[\"node --version\"]'"
+fi
+
+say "done"
+echo "relay : http://<host>:${RABBIT_PORT}   (also http://<host>/ through nginx)"
+echo "stun  : <host>:${STUN_PORT}/udp"