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

package/bin/w2m-rabbit.mjs

@@ -0,0 +1,396 @@
+/**
+ * w2m-rabbit — start the W2M relay (Rabbit).
+ *
+ * The relay is a plain `node:http` server with no third-party dependencies, so
+ * it can run on any machine that has Node: a laptop, a small VPS, or whichever
+ * of your machines happens to be on all the time.
+ *
+ * Design notes that matter at this layer:
+ *
+ * * The pairing code is the only credential that grants admission, it is shown
+ *   once, and it is consumed on first successful use. A relay that started
+ *   silently accepting unknown devices would be a relay anyone on the LAN could
+ *   join.
+ * * State lives in `--state`, and `state.json` records the pairing code so that
+ *   restarting the relay does not silently invalidate every paired machine.
+ * * Nothing about a project is read here. The relay never holds a working copy
+ *   and never holds a model credential.
+ */
+
+import { parseArgs } from 'node:util';
+import { createRelayServer } from '../src/relay/server.mjs';
+import { resolveStateDir, formatError } from '../src/util/cli.mjs';
+
+const USAGE = `w2m-rabbit — W2M relay (Rabbit)
+
+Usage:
+  w2m-rabbit [options]
+
+Deployment:
+  --host <addr>          Bind address. Default 127.0.0.1. Use 0.0.0.0 to accept
+                         other machines (see README, "Security").
+  --port <n>             Port. Default 8787. 0 asks the OS for a free port.
+  --base-path <p>        Prefix the relay is mounted under, e.g. /w2m, for a
+                         reverse proxy or tunnel that forwards the prefix
+                         through unchanged. Default /.  [env W2M_BASE_PATH]
+  --trust-proxy          Believe X-Forwarded-Proto / X-Forwarded-For. Enable ONLY
+                         behind a proxy you control: otherwise a client can forge
+                         its address and bypass the pairing rate limit.
+  --tls-cert <file>      Terminate TLS here. Requires --tls-key.
+  --tls-key <file>       Private key for --tls-cert.
+  --pair-rate-limit <n>  Pairing attempts per IP per minute. Default 5. 0 = off.
+
+Credentials and state:
+  --operator-token <t>   Token that authorises SENDING work. Generated and
+                         written to <state>/operator-token.txt if omitted.
+                         Pass an empty string to remove the requirement.
+                         [env W2M_OPERATOR_TOKEN]
+  --state <dir>          State directory. Default <DSH_HOME>/xclient/rabbit.
+  --no-persist           Keep everything in memory; forget devices and tasks on
+                         restart.
+  --pairing-code <c>     Use a fixed pairing code instead of a generated one.
+
+Request signing (v0.3.0):
+  --signing-secret <s>   Shared secret for HMAC-signed requests. Unset means the relay does
+                         not verify signatures at all, which is the v0.2.3 behaviour.
+                         Pass an empty string to switch signing off explicitly.
+                         [env W2M_SIGNING_SECRET]
+  --signing-secret-previous <s>
+                         The outgoing secret during a rotation. Both are accepted, so machines
+                         can be moved over one at a time instead of all at once.
+                         Requires --signing-secret.
+  --require-signature    Reject unsigned requests with 401 SIGNATURE_REQUIRED. Only takes
+                         effect once a secret is configured; the relay refuses to start if
+                         this is set without one, rather than silently verifying nothing.
+  --signature-skew <s>   Allowed clock difference in seconds. Default 120.
+
+Observability:
+  --metrics              Serve GET /metrics in Prometheus text format. Off by default, and
+                         token-free like /healthz, so a scraper never needs a credential in
+                         its own config file.
+
+Tuning:
+  --heartbeat-ms <n>     Expected heartbeat interval. Default 10000.
+  --grace-ms <n>         Extra grace before a silent lease is expired. Default 30000.
+  --json                 Print machine-readable status lines instead of prose.
+  -h, --help             Show this help.
+
+Exit codes:
+  0  stopped normally (SIGINT/SIGTERM)
+  2  bad usage
+  3  failed to bind or to start
+`;
+
+function fail(message, code = 2) {
+  process.stderr.write(`w2m-rabbit: ${message}\n`);
+  process.exit(code);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    options: {
+      host: { type: 'string' },
+      port: { type: 'string' },
+      state: { type: 'string' },
+      'pairing-code': { type: 'string' },
+      'heartbeat-ms': { type: 'string' },
+      'grace-ms': { type: 'string' },
+      'base-path': { type: 'string' },
+      'trust-proxy': { type: 'boolean', default: false },
+      'tls-cert': { type: 'string' },
+      'tls-key': { type: 'string' },
+      'pair-rate-limit': { type: 'string' },
+      'operator-token': { type: 'string' },
+      // v0.3.0 request signing. `--signing-secret ''` switches signing off explicitly.
+      'signing-secret': { type: 'string' },
+      'signing-secret-previous': { type: 'string' },
+      'require-signature': { type: 'boolean', default: false },
+  metrics: { type: 'boolean', default: false },
+      'signature-skew': { type: 'string' },
+      'no-persist': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+    allowPositionals: false,
+  });
+} catch (error) {
+  fail(`${error.message}\n\n${USAGE}`);
+}
+
+const { values } = parsed;
+if (values.help) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+const port = values.port === undefined ? 8787 : Number(values.port);
+if (!Number.isInteger(port) || port < 0 || port > 65535) {
+  fail(`--port must be an integer in 0..65535, got ${JSON.stringify(values.port)}`);
+}
+
+const heartbeatMs = values['heartbeat-ms'] === undefined ? undefined : Number(values['heartbeat-ms']);
+if (heartbeatMs !== undefined && (!Number.isFinite(heartbeatMs) || heartbeatMs <= 0)) {
+  fail(`--heartbeat-ms must be a positive number, got ${JSON.stringify(values['heartbeat-ms'])}`);
+}
+
+const graceMs = values['grace-ms'] === undefined ? undefined : Number(values['grace-ms']);
+if (graceMs !== undefined && (!Number.isFinite(graceMs) || graceMs < 0)) {
+  fail(`--grace-ms must be a non-negative number, got ${JSON.stringify(values['grace-ms'])}`);
+}
+
+/* ---------- v0.1.2 deployment options ---------- */
+
+// A base path is normalised to either '/' or '/prefix' with no trailing slash,
+// so the router can compare one canonical form instead of guessing.
+const rawBasePath = values['base-path'] ?? process.env.W2M_BASE_PATH ?? '/';
+let basePath = String(rawBasePath).trim();
+if (basePath === '' || basePath === '/') {
+  basePath = '/';
+} else {
+  if (!basePath.startsWith('/')) basePath = `/${basePath}`;
+  basePath = basePath.replace(/\/+$/, '');
+}
+
+const tlsCert = values['tls-cert'];
+const tlsKey = values['tls-key'];
+if ((tlsCert && !tlsKey) || (!tlsCert && tlsKey)) {
+  fail('--tls-cert and --tls-key must be given together');
+}
+
+const pairRateLimit = values['pair-rate-limit'] === undefined
+  ? undefined
+  : Number(values['pair-rate-limit']);
+if (pairRateLimit !== undefined && (!Number.isInteger(pairRateLimit) || pairRateLimit < 0)) {
+  fail(`--pair-rate-limit must be a non-negative integer, got ${JSON.stringify(values['pair-rate-limit'])}`);
+}
+
+// Distinguish "not supplied" (generate one) from "supplied empty" (explicitly
+// turn the requirement off). `parseArgs` gives the same value for both, so the
+// presence of the flag is checked separately -- silently treating `''` as
+// "generate one" would leave a user who asked for no operator token with one
+// they do not know.
+const operatorTokenFlag = process.argv.some((a) => a === '--operator-token' || a.startsWith('--operator-token='));
+const operatorTokenValue = values['operator-token'] ?? process.env.W2M_OPERATOR_TOKEN;
+const operatorToken = operatorTokenValue === undefined
+  ? undefined
+  : (String(operatorTokenValue) === '' ? null : String(operatorTokenValue));
+const operatorTokenRequired = !(operatorTokenFlag && operatorToken === null);
+
+/* ---------- v0.3.0 request signing ---------- */
+
+// `''` means "explicitly off", the same convention as --operator-token. A *non-string* value is a
+// configuration error and must not become "signing disabled": silently losing signature
+// verification because a flag was misspelled is precisely the failure the signing module is written
+// to prevent, and it is invisible from the client side.
+/**
+ * Resolve one signing secret from a flag, falling back to an environment variable.
+ *
+ * @param {unknown} flagValue - Value from `--signing-secret*`.
+ * @param {string} envName - Environment variable to fall back to.
+ * @param {string} label - Flag name for the error message.
+ * @returns {string|undefined} The secret, or undefined when not configured.
+ */
+function resolveSigningSecret(flagValue, envName, label) {
+  const raw = flagValue ?? process.env[envName];
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string') {
+    fail(
+      `${label} must be a string; got ${typeof raw}. Signing is never silently disabled -- ` +
+        'pass an empty string to switch it off deliberately.',
+    );
+  }
+  if (raw === '') return undefined; // explicit opt-out
+  return raw;
+}
+
+const signingSecret = resolveSigningSecret(values['signing-secret'], 'W2M_SIGNING_SECRET', '--signing-secret');
+const signingSecretPrevious = resolveSigningSecret(
+  values['signing-secret-previous'],
+  'W2M_SIGNING_SECRET_PREVIOUS',
+  '--signing-secret-previous',
+);
+const requireSignature = values['require-signature'] === true;
+
+// Requiring a signature with no secret to verify against is a contradiction, and the relay must say
+// so at startup rather than accept every request and report 500 on each one.
+if (requireSignature && signingSecret === undefined) {
+  fail(
+    '--require-signature needs --signing-secret (or W2M_SIGNING_SECRET). Refusing to start: ' +
+      'every request would be rejected as a server misconfiguration instead of being verified.',
+  );
+}
+if (signingSecretPrevious !== undefined && signingSecret === undefined) {
+  fail('--signing-secret-previous only makes sense alongside --signing-secret. Refusing to start.');
+}
+
+const skewRaw = values['signature-skew'];
+const signatureSkewSeconds = skewRaw === undefined ? undefined : Number(skewRaw);
+if (signatureSkewSeconds !== undefined && (!Number.isFinite(signatureSkewSeconds) || signatureSkewSeconds <= 0)) {
+  fail(`--signature-skew must be a positive number of seconds, got ${JSON.stringify(skewRaw)}`);
+}
+
+const stateDir = resolveStateDir(values.state, 'rabbit');
+// Diagnostics go to stderr, data goes to stdout. `--json` promises one machine
+// readable line on stdout, so the pairing-code rotation notice must not land
+// there and break `| jq` / `| ConvertFrom-Json`.
+const log = (line) => process.stdout.write(`${line}\n`);
+const diag = (line) => process.stderr.write(`${line}\n`);
+
+let relay;
+let listenInfo;
+let pairingCode;
+try {
+  relay = createRelayServer({
+    stateDir,
+    pairingCode: values['pairing-code'],
+    heartbeatIntervalMs: heartbeatMs,
+    leaseGraceMs: graceMs,
+    // v0.1.2 deployment options
+    basePath,
+    trustProxy: Boolean(values['trust-proxy']),
+    tlsCert: tlsCert ?? null,
+    tlsKey: tlsKey ?? null,
+    operatorToken,
+    operatorTokenRequired,
+    pairRateLimitPerMinute: pairRateLimit,
+    persist: !values['no-persist'],
+    // v0.3.0 request signing. Undefined means "not configured", which the relay treats as
+    // "do not verify" -- byte-for-byte the v0.2.3 behaviour.
+    signingSecret,
+    signingSecretPrevious,
+    requireSignature,
+    metrics: values.metrics === true,
+    signatureSkewSeconds,
+  });
+  // The pairing code rotates on every successful pairing, so the CLI has to
+  // follow it rather than print it once: an operator pairing a second machine
+  // needs the *current* code, not the one that was already consumed.
+  //
+  // Listeners receive the buffered *entry* (`{seq, event, target}`), not the
+  // event itself -- `entry.event` is the frame that goes on the wire.
+  relay.state.onEvent((entry) => {
+    const event = entry?.event ?? entry;
+    if (event?.type === 'notice' && event.code === 'PAIRING_CODE_ROTATED' && event.pairing_code) {
+      pairingCode = event.pairing_code;
+      // In --json mode this must not touch stdout: a rotation would otherwise
+      // corrupt the very output the flag exists to produce.
+      const out = values.json ? diag : log;
+      out('');
+      out('  Pairing code rotated after a successful pairing.');
+      out(`  新的配对码 / NEW PAIRING CODE:  ${pairingCode}`);
+      out('');
+    }
+  });
+  listenInfo = await relay.listen({
+    host: values.host ?? '127.0.0.1',
+    port,
+  });
+  pairingCode = listenInfo.pairingCode;
+} catch (error) {
+  fail(formatError(error), 3);
+}
+
+const boundPort = listenInfo.port;
+const boundHost = listenInfo.host;
+const scheme = listenInfo.scheme ?? (tlsCert ? 'https' : 'http');
+// Prefer what the relay reports (it knows whether TLS is active); fall back to
+// the bound address so a 0.0.0.0 bind is not advertised as a usable URL.
+const publicUrl = listenInfo.publicUrl ?? `${scheme}://${boundHost === '0.0.0.0' ? '<this-host>' : boundHost}:${boundPort}${basePath === '/' ? '' : basePath}`;
+const resolvedOperatorToken = listenInfo.operatorToken ?? operatorToken ?? null;
+
+if (values.json) {
+  log(JSON.stringify({
+    event: 'listening',
+    url: listenInfo.url,
+    publicUrl,
+    host: boundHost,
+    port: boundPort,
+    scheme,
+    basePath,
+    stateDir,
+    persist: !values['no-persist'],
+    trustProxy: Boolean(values['trust-proxy']),
+    pairRateLimit: pairRateLimit ?? 5,
+    operatorTokenRequired,
+    // The token itself is deliberately absent. This line is the one people pipe
+    // into a log or a file, and a credential written there is a credential
+    // leaked; it is printed to stderr and stored at
+    // <stateDir>/operator-token.txt (0600), which is where a secret belongs.
+    operatorTokenPresent: Boolean(operatorTokenRequired && resolvedOperatorToken),
+    pairingCode,
+    relayId: listenInfo.relayId ?? null,
+    protocolVersion: 1,
+  }));
+} else {
+  log('');
+  log('  W2M relay (Rabbit) is listening.');
+  log('');
+  log(`  URL          ${publicUrl}`);
+  log(`  Bind         ${boundHost}:${boundPort}${scheme === 'https' ? ' (TLS)' : ''}`);
+  if (basePath !== '/') log(`  Base path    ${basePath}`);
+  log(`  State        ${stateDir}${values['no-persist'] ? '  (persistence DISABLED)' : ''}`);
+  log(`  Protocol     v1   relay id ${listenInfo.relayId ?? '(none)'}`);
+
+  if (values['trust-proxy']) {
+    log('');
+    log('  NOTE: --trust-proxy is ON. The relay believes X-Forwarded-For and');
+    log('        X-Forwarded-Proto. Only safe behind a proxy you control.');
+  }
+  if (boundHost === '0.0.0.0' && scheme === 'http') {
+    log('');
+    log('  NOTE: bound to 0.0.0.0 over plain HTTP. Fine on a Tailscale/WireGuard');
+    log('        address (already encrypted); NOT fine on a public interface --');
+    log('        use --tls-cert/--tls-key or a TLS-terminating proxy there.');
+  }
+
+  log('');
+  if (operatorTokenRequired && resolvedOperatorToken) {
+    log('  ┌────────────────────────────────────────────────────────────┐');
+    log('  │  OPERATOR TOKEN (needed to SEND instructions, keep secret)  │');
+    log(`  │  ${String(resolvedOperatorToken).padEnd(56)}│`);
+    log('  └────────────────────────────────────────────────────────────┘');
+    log(`  Also written to ${stateDir}/operator-token.txt`);
+    log('  Device tokens cannot send work; this is what authorises it.');
+  } else if (!operatorTokenRequired) {
+    log('  ⚠  OPERATOR TOKEN REQUIREMENT IS OFF (--operator-token "").');
+    log('     Any paired device can send work to any other. Trusted LAN only.');
+  }
+
+  log('');
+  if (pairingCode) {
+    log('  ┌──────────────────────────────────────────────┐');
+    log(`  │  配对码 / PAIRING CODE:  ${String(pairingCode).padEnd(19)}│`);
+    log('  └──────────────────────────────────────────────┘');
+    log('');
+    log('  Run this on every machine you want in the group:');
+    log('');
+    log(`    w2m-localside --rabbit ${listenInfo.url} --pair ${pairingCode} \\`);
+    log('                  --project <path-to-project> --name <machine-name>');
+    log('');
+    log('  The code rotates after each successful pairing; the new one is');
+    log('  printed here, so you can pair the next machine without restarting.');
+  }
+  if (boundHost === '0.0.0.0') {
+    log('  NOTE: bound to 0.0.0.0 -- other machines on your network can reach this');
+    log('        relay. It carries no TLS and no authentication beyond device tokens.');
+    log('');
+  }
+}
+
+let stopping = false;
+async function shutdown(signal) {
+  if (stopping) return;
+  stopping = true;
+  if (!values.json) log(`\n  ${signal} received, shutting down...`);
+  try {
+    await relay.close();
+  } catch (error) {
+    process.stderr.write(`w2m-rabbit: error while closing: ${formatError(error)}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+process.on('SIGINT', () => { void shutdown('SIGINT'); });
+process.on('SIGTERM', () => { void shutdown('SIGTERM'); });

package/bin/w2m-stun.mjs

@@ -0,0 +1,231 @@
+/**
+ * w2m-stun — run the W2M STUN responder (RFC 5389 Binding server).
+ *
+ * This is the other half of `src/agent/stun.mjs`. Every machine that wants a
+ * direct path must learn the *public* address a peer can reach it on, and the
+ * port a NAT hands out cannot be guessed from the inside: a host sees its own
+ * `192.168.x.y`, the peer must be told the translated address. That translation is
+ * the one fact only an outside observer can supply, which is what this process is.
+ *
+ * Design notes that matter at this layer:
+ *
+ * * **UDP only, and stateless.** Each datagram is answered from the address it
+ *   arrived on and from nothing else. Nothing is stored, so there is no state for
+ *   an attacker to exhaust and no session to hijack.
+ * * **Not a reflector.** A Binding request is answered to its *source*, never to
+ *   an address carried in the message, so this server cannot be aimed at a third
+ *   party. Binding responses arriving here are dropped, not answered — answering a
+ *   response is how a loop starts.
+ * * **The single bug that matters is a crash on malformed input.** A malformed
+ *   datagram is counted and dropped; nothing in the responder throws out of the
+ *   socket handler, because an uncaught exception here would take down the whole
+ *   relay host with it.
+ * * **A taken port must be loud.** The default port is 3478 and it is a
+ *   well-known one: the most likely failure is another STUN server already
+ *   holding it, and that has to be a clear line and a non-zero exit, not a
+ *   half-started process.
+ */
+
+import { parseArgs } from 'node:util';
+import { createStunServer, DEFAULT_SOFTWARE } from '../src/relay/stun-server.mjs';
+import { formatError } from '../src/util/cli.mjs';
+
+const USAGE = `w2m-stun — W2M STUN responder (RFC 5389 Binding server)
+
+Usage:
+  w2m-stun [options]
+
+What it is for:
+  A machine behind NAT cannot see the public address and port its packets come
+  from — only the far side can. This server reports that translation back to the
+  caller, which is what lets two machines exchange reachable addresses and punch
+  a direct path instead of routing every task through the relay.
+
+Deployment:
+  --host <addr>          Bind address. Default 0.0.0.0, because a STUN server
+                         bound to loopback answers nobody. It must be reachable
+                         on UDP from the machines that will use it, and the port
+                         must be forwarded if this host is itself behind NAT.
+  --port <n>             UDP port. Default 3478 (the IANA STUN port). 0 asks the
+                         OS for a free port.
+  --software <name>      Value of the SOFTWARE attribute. Default ${DEFAULT_SOFTWARE}.
+                         Printed to clients; keep secrets out of it.
+
+Observability:
+  --log-level <level>    info | debug. Default info. "debug" prints one line per
+                         request, including every datagram that was dropped and
+                         why — the only way to tell "the NAT is blocking UDP"
+                         apart from "something is answering but not with STUN".
+
+  -h, --help             Show this help.
+
+Protocol:
+  0x0001 Binding request   -> 0x0101 Binding success, with XOR-MAPPED-ADDRESS
+                              (0x0020), MAPPED-ADDRESS (0x0001) and SOFTWARE
+                              (0x8022). The 96-bit transaction id is echoed.
+  0x0001 with an unknown comprehension-required attribute
+                           -> 0x0111 Binding error, ERROR-CODE 400.
+  Anything else            -> dropped silently: UDP has no error channel worth
+                              using here, and a wrong magic cookie is not STUN.
+
+Notes:
+  * IPv4 only (the socket is udp4), no authentication, no TLS: the answer is the
+    source address of the request, which any STUN client can ask for.
+  * This server reports the mapping a NAT applied. It does not test filtering
+    behaviour (RFC 5780 CHANGE-REQUEST), so a client's "endpoint-independent"
+    verdict here is a statement about mapping only.
+
+Exit codes:
+  0  stopped normally (SIGINT/SIGTERM)
+  2  bad usage
+  3  failed to bind (port already in use?)
+`;
+
+function fail(message, code = 2) {
+  process.stderr.write(`w2m-stun: ${message}\n`);
+  process.exit(code);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    options: {
+      host: { type: 'string' },
+      port: { type: 'string' },
+      software: { type: 'string' },
+      'log-level': { type: 'string' },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+    allowPositionals: false,
+  });
+} catch (error) {
+  fail(`${error.message}\n\n${USAGE}`);
+}
+
+const { values } = parsed;
+if (values.help) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+const host = values.host ?? '0.0.0.0';
+
+const port = values.port === undefined ? 3478 : Number(values.port);
+if (!Number.isInteger(port) || port < 0 || port > 65535) {
+  fail(`--port must be an integer in 0..65535, got ${JSON.stringify(values.port)}`);
+}
+
+// An empty --software is a configuration error rather than "use the default":
+// the attribute is what a client sees when it asks who answered, and silently
+// substituting a name the operator did not choose makes a deployment
+// indistinguishable from the library default.
+const software = values.software ?? DEFAULT_SOFTWARE;
+if (String(software).trim() === '') {
+  fail('--software must not be empty; omit it to use the default');
+}
+
+const logLevel = values['log-level'] ?? 'info';
+if (logLevel !== 'info' && logLevel !== 'debug') {
+  fail(`--log-level must be "info" or "debug", got ${JSON.stringify(logLevel)}`);
+}
+const debug = logLevel === 'debug';
+
+// Data goes to stdout, diagnostics to stderr, as everywhere else in this project.
+const log = (line) => process.stdout.write(`${line}\n`);
+
+/**
+ * One line per request, in `--log-level debug` only.
+ *
+ * The disposition is the interesting field: "binding_success" is a working
+ * client, and every other value names the exact reason a datagram went
+ * unanswered, which is what an operator needs to tell a blocked port from a
+ * non-STUN client.
+ *
+ * @param {object} entry
+ */
+function logRequest(entry) {
+  if (!debug) return;
+  const unknown = entry.unknown?.length
+    ? ` unknown=${entry.unknown.map((t) => `0x${t.toString(16)}`).join(',')}`
+    : '';
+  const at = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+  log(
+    `  ${at}  ${entry.from.padEnd(21)} ${String(entry.type ?? '-').padEnd(6)} ${entry.disposition}${unknown}`,
+  );
+}
+
+let server;
+let listen;
+const startedAt = Date.now();
+try {
+  server = createStunServer({ host, port, software, log: logRequest });
+  listen = await server.start();
+} catch (error) {
+  fail(formatError(error), 3);
+}
+
+if (!listen.ok) {
+  // EADDRINUSE deserves its own sentence: it is the one failure an operator will
+  // actually hit, and the fix (find the other listener, or pick another port) is
+  // not obvious from "EADDRINUSE".
+  if (listen.error === 'EADDRINUSE') {
+    fail(
+      `UDP port ${port} is already in use on ${host} — another STUN server or another ` +
+        `w2m-stun is holding it. Stop it, or choose a different --port.`,
+      3,
+    );
+  }
+  fail(`failed to bind ${host}:${port} — ${listen.error}`, 3);
+}
+
+const bound = server.address() ?? { address: listen.host, port: listen.port };
+log('');
+log('  W2M STUN responder is listening.');
+log('');
+log(`  Bind          udp4 ${bound.address}:${bound.port}`);
+log(`  Software      ${software}`);
+log('  Answers       Binding requests (0x0001) -> 0x0101 with XOR-MAPPED-ADDRESS,');
+log('                MAPPED-ADDRESS and SOFTWARE. Anything else is dropped.');
+log('');
+log('  NAT translation:');
+log('    A machine behind NAT cannot see the public address and port its packets');
+log(
+  `    leave from. Point clients at ${bound.address === '0.0.0.0' ? '<this-host>' : bound.address}:${bound.port} (UDP) and`,
+);
+log('    this server reports the translated address back, which is what lets two');
+log('    machines punch a direct path instead of relaying every task.');
+if (bound.address === '0.0.0.0') {
+  log('');
+  log('  NOTE: bound to 0.0.0.0 — reachable from anywhere that can route UDP to this');
+  log('        host. There is no authentication and no state: every request is');
+  log('        answered on the address it came from, and nothing else is possible.');
+}
+log('');
+log(`  Log level     ${logLevel}${debug ? '' : '   (--log-level debug prints one line per request)'}`);
+log('');
+
+let stopping = false;
+async function shutdown(signal) {
+  if (stopping) return;
+  stopping = true;
+  const stats = server.stats();
+  log(
+    `\n  ${signal} received, shutting down. ` +
+      `requests=${stats.requests} responses=${stats.responses} errors=${stats.errors} ` +
+      `uptime=${Math.round((Date.now() - startedAt) / 100) / 10}s`,
+  );
+  try {
+    await server.stop();
+  } catch (error) {
+    process.stderr.write(`w2m-stun: error while closing: ${formatError(error)}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+process.on('SIGINT', () => {
+  void shutdown('SIGINT');
+});
+process.on('SIGTERM', () => {
+  void shutdown('SIGTERM');
+});