@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/relay/main.ts

@@ -0,0 +1,642 @@
+// W59 S4: the standalone relay, `wmd-relay`. No setup: with no arguments it serves Wisp (and
+// the wmd-relay.v1 endpoint, for token clients) on 127.0.0.1:8780 and prints one line, the URL.
+//
+//   wmd-relay [flags]                 serve (flags below; --help lists them)
+//   wmd-relay key add <id> [--keys F] make an owner key; the secret is printed once, F keeps its hash
+//   wmd-relay key list|remove <id>    (F defaults to ~/.wmd/relay/keys.json)
+//   wmd-relay version
+//
+// Everything a flag sets can also come from --config <file.json|file.toml>; flags win. Logs
+// (connection metadata only) go to stderr with --log. Plan: docs/plans/w59-wisp-relay.md §7.
+
+import { randomBytes } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { networkInterfaces } from 'node:os'
+import { dirname, join } from 'node:path'
+import { type HostedOptions } from './hosted.ts'
+import { type OwnerKey, newKey } from './keys.ts'
+import { ControlError, COMMANDS, ctl, startControl } from './control.ts'
+import { createLogFile } from './logfile.ts'
+import { isPrivateBind, parseCidr } from './policy.ts'
+import { breakIfStale, release, tryTake } from './lock.ts'
+import { localTls, relayDir } from './local-tls.ts'
+import { type RelayOptions, createRelay } from './relay.ts'
+
+declare const RELAY_VERSION: string // --define at `make relay`
+export const VERSION = typeof RELAY_VERSION === 'string' ? RELAY_VERSION : 'dev'
+export const DEFAULT_PORT = 8780
+export const DEFAULT_TLS_PORT = 8781
+
+const HELP = `wmd-relay ${VERSION}: a Wisp relay for wmd guests in the browser
+
+  wmd-relay                      serve on 127.0.0.1:${DEFAULT_PORT}, no key; prints the URL
+  wmd-relay key add <id>         make an owner key (the secret is shown once)
+  wmd-relay key list | remove <id>
+  wmd-relay version
+  wmd-relay ctl stop-new|resume|drain|status   operate a running --hosted relay (its control socket)
+  wmd-relay check                can this machine run it? (own addresses refused, lookups work)
+
+Flags:
+  --host <addr>                  bind address (127.0.0.1). A reachable address with no key
+                                 lets anyone who can reach it use the relay; see --origin
+  --port <n>                     port (${DEFAULT_PORT})
+  --origin <url>                 only pages from this origin (repeatable)
+  --keys <file>                  owner keys (see 'key add'); then every client needs one
+  --tls-cert <f> --tls-key <f>   serve wss:// with this certificate
+  --local-tls                    also serve wss://127.0.0.1:${DEFAULT_TLS_PORT} with a certificate made
+                                 for this computer (for Safari; you trust it once)
+  --behind-tls                   a TLS proxy or tunnel is in front (keys on a reachable bind)
+  --trust-proxy [list]           per-client caps by X-Forwarded-For (only behind a proxy you run). With a list of
+                                 proxy addresses or CIDRs, only those peers are believed (required by --hosted)
+  --proxy-header <name>          the header the proxy sets (X-Forwarded-For; e.g. CF-Connecting-IP)
+  --allow-lan                    guests may reach private addresses (10/8, 192.168/16, ...)
+  --allow-loopback-ports <list>  guests may reach this computer's loopback on these ports
+  --block-ports <list>           destination ports refused (25)
+  --allow-hosts <list>           only these names (name[:port|port], a leading . for subdomains)
+  --hosted                       the public hosted profile (docs/relay-hosted.md): per-address, network and origin
+                                 limits, byte ceilings, deny lists, a control socket, /healthz, /readyz
+    --abuse-contact <text>       required: an address or URL, shown in the MOTD, /healthz and every refusal
+    --deny-cidr <list>           dialled addresses to refuse besides the built-in ranges (the fleet's private neighbours)
+    --deny-file <file>           JSON {addresses, origins, destinations}; re-read on SIGHUP, denied sessions end
+    --max-bytes-per-day <n>      stop taking new connections after this many bytes relayed in a UTC day (both ways)
+    --max-bytes-per-month <n>    the same for a UTC month
+    --allow-ports <list>         only these destination ports (25, 465 and 587 are always blocked)
+    --control-dir <dir>          the control socket's directory, mode 0700, never under /tmp (~/.wmd/relay/ctl)
+    --state-dir <dir>            where the byte counters are kept (~/.wmd/relay)
+    --start-stopped              start in stop-new until 'ctl resume' (a stop does not persist a restart otherwise)
+    --log-dir <dir>              metadata log files, rotated by size and age; --log-retention-days <n> (14)
+  --config <file>                JSON or TOML with any of the above, and the caps
+  --log                          connection metadata (never payloads or secrets) on stderr
+`
+
+// config keys: flags (camelCase) plus the relay's caps
+const FLAG_KEYS = ['host', 'port', 'origins', 'keys', 'tlsCert', 'tlsKey', 'localTls', 'behindTls', 'trustProxy', 'proxyHeader', 'allowLan', 'allowLoopbackPorts', 'blockPorts', 'allowHosts', 'log', 'hosted', 'abuseContact', 'denyCidr', 'denyFile', 'maxBytesPerDay', 'maxBytesPerMonth', 'allowPorts', 'controlDir', 'stateDir', 'startStopped', 'logDir', 'logRetentionDays', 'logMaxBytes', 'logDirMaxBytes'] as const
+const CAP_KEYS = ['maxConns', 'maxSessions', 'maxSessionsPerGroup', 'opensPerMin', 'connectsPerMin', 'dnsPerMin', 'rateDown', 'rateUp', 'maxBytes', 'selfAddrs', 'dnsServers', 'connectTimeoutMs', 'dnsTimeoutMs'] as const
+const WISP_KEYS = ['path', 'buffer', 'maxPayload', 'maxHeldBytes', 'maxSessionHeldBytes', 'maxHeldTotal', 'maxGroupHeldBytes', 'instancesPerHour', 'maxPrincipals', 'preAuthPerAddr', 'handshakeMs', 'streamIdleMs', 'prefixKeys'] as const
+// the limits of the hosted profile, under "hosted" in a config file (hosted.ts HostedOptions; all whole numbers)
+const HOSTED_KEYS = ['groupStreams', 'groupConnectsPerMin', 'groupBytesPerHour', 'groupDnsPerMin', 'coarseSessions', 'coarseInstancesPerHour', 'coarseRateDown', 'coarseRateUp', 'originTable', 'originSessions', 'otherOriginSessions', 'noOriginSessions', 'originsPerAddrPerHour', 'originRateDown', 'originRateUp', 'maxStreams', 'maxRateDown', 'maxRateUp', 'destConnectsPerMin', 'destStreams', 'distinctDests', 'failedConnects', 'failedWindowMs', 'failedCoolMs'] as const
+const BOOL_FLAGS = new Set(['localTls', 'behindTls', 'allowLan', 'log', 'hosted', 'startStopped'])
+const LIST_FLAGS = new Set(['origins', 'allowLoopbackPorts', 'blockPorts', 'allowHosts', 'denyCidr', 'allowPorts'])
+
+export class UsageError extends Error {}
+
+type Conf = Record<string, any>
+
+const camel = (f: string) => f.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+
+/** argv (after the program) to a config object. Throws UsageError in words. */
+export function parseFlags(argv: string[]): Conf {
+  const c: Conf = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a.startsWith('--')) throw new UsageError(`unexpected argument '${a}' (see --help)`)
+    let [name, val] = a.slice(2).split(/=(.*)/s, 2) as [string, string | undefined]
+    let k = camel(name)
+    if (k === 'origin') k = 'origins'
+    if (k === 'config') {
+      c.config = val ?? argv[++i]
+      if (!c.config) throw new UsageError('--config needs a file')
+      continue
+    }
+    if (!(FLAG_KEYS as readonly string[]).includes(k)) throw new UsageError(`unknown flag --${name} (see --help)`)
+    if (k === 'trustProxy') {
+      // bare: the legacy "the last X-Forwarded-For entry"; with a list: only those proxies (required by --hosted)
+      const v = val ?? (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') ? argv[++i] : undefined)
+      c.trustProxy = v === undefined ? true : [...(Array.isArray(c.trustProxy) ? c.trustProxy : []), ...v.split(',').map(x => x.trim()).filter(Boolean)]
+      continue
+    }
+    if (BOOL_FLAGS.has(k)) {
+      if (val !== undefined) throw new UsageError(`--${name} takes no value`)
+      c[k] = true
+      continue
+    }
+    if (val === undefined) val = argv[++i]
+    if (val === undefined || val.startsWith('--')) throw new UsageError(`--${name} needs a value`)
+    if (LIST_FLAGS.has(k)) c[k] = [...(c[k] ?? []), ...val.split(',').map(x => x.trim()).filter(Boolean)]
+    else c[k] = val
+  }
+  return c
+}
+
+/** A config file (JSON, or TOML by extension). Unknown keys are refused, so a typo is not a silent default. */
+export function readConfig(file: string): Conf {
+  const text = readFileSync(file, 'utf8')
+  const c: Conf = /\.toml$/i.test(file) ? (Bun.TOML.parse(text) as Conf) : JSON.parse(text)
+  if (!c || typeof c !== 'object' || Array.isArray(c)) throw new UsageError(`${file}: expected an object`)
+  for (const k of Object.keys(c)) {
+    if (k === 'wisp') {
+      for (const w of Object.keys(c.wisp ?? {})) if (!(WISP_KEYS as readonly string[]).includes(w)) throw new UsageError(`${file}: unknown key wisp.${w}`)
+    } else if (k === 'hosted' && c.hosted && typeof c.hosted === 'object') {
+      // "hosted": true turns the profile on; "hosted": {limits} turns it on with those limits
+      for (const w of Object.keys(c.hosted)) if (!(HOSTED_KEYS as readonly string[]).includes(w)) throw new UsageError(`${file}: unknown key hosted.${w}`)
+    } else if (k === 'origin') throw new UsageError(`${file}: the key is 'origins' (a list)`)
+    else if (!(FLAG_KEYS as readonly string[]).includes(k) && !(CAP_KEYS as readonly string[]).includes(k)) throw new UsageError(`${file}: unknown key '${k}'`)
+  }
+  return c
+}
+
+// A timer longer than 2^31-1 ms fires after 1 ms (Bun and Node both clamp it), so a huge handshakeMs or connectTimeoutMs
+// would end every connection at once; CONTINUE carries `buffer` as a u32; Bun refuses a frame limit past what it can hold.
+const MS_MAX = 2 ** 31 - 1
+const BOUNDS: Record<string, [number, number]> = {
+  connectTimeoutMs: [1, MS_MAX], dnsTimeoutMs: [1, MS_MAX],
+  'wisp.handshakeMs': [1, MS_MAX], 'wisp.buffer': [1, 2 ** 32 - 1], 'wisp.maxPayload': [1, MS_MAX],
+}
+const num = (v: any, what: string, lo = 0, hi = Number.MAX_SAFE_INTEGER) => {
+  if (v === undefined) return undefined
+  // digits only: Number('') is 0, Number('1e3') is 1000 and Number('0x10') is 16, none of which a person typed as a port
+  const n = typeof v === 'number' ? v : typeof v === 'string' && /^\d{1,16}$/.test(v.trim()) ? Number(v) : NaN
+  if (!Number.isInteger(n) || n < lo || n > hi) throw new UsageError(`${what} must be a whole number from ${lo} to ${hi} (got '${v}')`)
+  return n
+}
+const ports = (v: any, what: string) => (v === undefined ? undefined : (Array.isArray(v) ? v : typeof v === 'string' ? v.split(',').filter(x => x.trim()) : [v]).map((p: any) => num(p, what, 1, 65535)!))
+const isLoopbackBind = (h: string) => /^(127\.\d+\.\d+\.\d+|::1|localhost)$/i.test(h)
+
+
+/** Config values with the types a flag would have: a wrong type is refused in words, never coerced ("false" is not false). */
+function checkTypes(c: Conf) {
+  for (const k of BOOL_FLAGS) {
+    if (k === 'hosted' && c.hosted && typeof c.hosted === 'object' && !Array.isArray(c.hosted)) continue
+    if (c[k] !== undefined && typeof c[k] !== 'boolean') throw new UsageError(`${k} must be true or false (got ${JSON.stringify(c[k])})`)
+  }
+  for (const k of ['host', 'keys', 'tlsCert', 'tlsKey', 'proxyHeader', 'abuseContact', 'denyFile', 'controlDir', 'stateDir', 'logDir'] as const) {
+    if (c[k] !== undefined && c[k] !== null && (typeof c[k] !== 'string' || !c[k])) throw new UsageError(`${k} must be a non-empty string (got ${JSON.stringify(c[k])})`)
+  }
+  if (c.host === null) delete c.host
+  if (c.trustProxy !== undefined && c.trustProxy !== true && c.trustProxy !== false) {
+    if (!Array.isArray(c.trustProxy) || c.trustProxy.some((x: any) => typeof x !== 'string')) throw new UsageError(`trustProxy must be true or a list of proxy addresses or CIDRs (got ${JSON.stringify(c.trustProxy)})`)
+    for (const x of c.trustProxy) {
+      const cidr = parseCidr(x)
+      if (!cidr) throw new UsageError(`--trust-proxy ${x} is not an address or CIDR (e.g. 10.0.0.0/8)`)
+      if (cidr.bits < (cidr.v === 4 ? 8 : 16)) throw new UsageError(`--trust-proxy ${x} trusts too much of the internet: a prefix shorter than /8 (IPv4) or /16 (IPv6) is refused in every mode, because ranges like 0.0.0.0/1,128.0.0.0/1 together cover every address and any sender could pick the client address the limits use; list your proxy's address or network`)
+    }
+  }
+  for (const k of ['maxBytesPerDay', 'maxBytesPerMonth', 'logRetentionDays', 'logMaxBytes', 'logDirMaxBytes'] as const) if (c[k] !== undefined) c[k] = num(c[k], k, k === 'logRetentionDays' || k === 'logMaxBytes' || k === 'logDirMaxBytes' ? 1 : 0)
+  if (c.hosted && typeof c.hosted === 'object') {
+    if (Array.isArray(c.hosted)) throw new UsageError('hosted must be true or a table of limits')
+    for (const k of HOSTED_KEYS) if (c.hosted[k] !== undefined) c.hosted[k] = num(c.hosted[k], `hosted.${k}`, 0)
+  }
+  for (const k of LIST_FLAGS) {
+    if (c[k] === undefined) continue
+    if (typeof c[k] === 'string') c[k] = c[k].split(',').map((x: string) => x.trim()).filter(Boolean)
+    if (!Array.isArray(c[k]) || c[k].some((x: any) => (k === 'allowLoopbackPorts' || k === 'blockPorts' ? typeof x !== 'string' && typeof x !== 'number' : typeof x !== 'string'))) {
+      throw new UsageError(`${k} must be a list of ${k.endsWith('Ports') ? 'ports' : 'strings'} (got ${JSON.stringify(c[k])})`)
+    }
+  }
+  for (const k of CAP_KEYS) {
+    if (c[k] === undefined) continue
+    if (k === 'selfAddrs' || k === 'dnsServers') {
+      if (!Array.isArray(c[k]) || c[k].some((x: any) => typeof x !== 'string')) throw new UsageError(`${k} must be a list of addresses (got ${JSON.stringify(c[k])})`)
+    } else c[k] = num(c[k], k, ...(BOUNDS[k] ?? []))
+  }
+  if (c.wisp !== undefined && (!c.wisp || typeof c.wisp !== 'object' || Array.isArray(c.wisp))) throw new UsageError('wisp must be a table of settings')
+  if (c.wisp) {
+    // the same rule as the top level: "false" is not false, 'x' is not a size (Bun refused it with a raw message, or a limit went NaN)
+    if (c.wisp.prefixKeys !== undefined && typeof c.wisp.prefixKeys !== 'boolean') throw new UsageError(`wisp.prefixKeys must be true or false (got ${JSON.stringify(c.wisp.prefixKeys)})`)
+    for (const k of WISP_KEYS) {
+      if (k === 'path' || k === 'prefixKeys' || c.wisp[k] === undefined) continue
+      const n = num(c.wisp[k], `wisp.${k}`, ...(BOUNDS[`wisp.${k}`] ?? []))
+      c.wisp[k] = n
+    }
+  }
+  const path = c.wisp?.path
+  if (path !== undefined && (typeof path !== 'string' || !/^\/([A-Za-z0-9._~-]+\/)*$/.test(path))) throw new UsageError(`wisp.path must start and end with '/' (got ${JSON.stringify(path)})`)
+}
+
+/** Owner keys file: {"keys": [OwnerKey, ...]}, mode 0600 (refused when others can read it). */
+export function readKeys(file: string): OwnerKey[] {
+  const st = statSync(file)
+  if (process.platform !== 'win32' && st.mode & 0o077) {
+    throw new UsageError(`${file} can be read by other users (mode ${(st.mode & 0o777).toString(8)}); run: chmod 600 ${file}`)
+  }
+  const dir = dirname(realpathSync(file))
+  if (process.platform !== 'win32' && !safeDir(dir)) {
+    throw new UsageError(`${file} is in ${dir}, which other users can write to: they could swap the file. Move it to a directory only you can write (the default is ~/.wmd/relay)`)
+  }
+  const j = JSON.parse(readFileSync(file, 'utf8'))
+  const keys = Array.isArray(j?.keys) ? j.keys : null
+  if (!keys) throw new UsageError(`${file}: expected {"keys": [...]}`)
+  for (const k of keys) {
+    if (typeof k?.id !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(k.id)) throw new UsageError(`${file}: a key id must be 1-64 letters, digits, '-' or '_'`)
+    if (typeof k.hash !== 'string' || !k.hash.startsWith('scrypt:')) throw new UsageError(`${file}: key '${k.id}' has no scrypt hash (secrets are never stored, only hashes)`)
+  }
+  return keys
+}
+
+/** A directory only its owner (or root) can change entries in: not group/other writable, unless sticky (/tmp). */
+const safeDir = (d: string) => {
+  const m = statSync(d).mode
+  return !(m & 0o022) || !!(m & 0o1000)
+}
+
+function writeKeys(file: string, keys: OwnerKey[]) {
+  const real = existsSync(file) ? realpathSync(file) : file // a symlinked keys file stays a symlink
+  mkdirSync(dirname(real), { recursive: true, mode: 0o700 })
+  if (process.platform !== 'win32' && !safeDir(dirname(real))) throw new UsageError(`${dirname(real)} can be written by other users; keep the keys file in a directory only you can write`)
+  // a name nobody can have planted ('wx' fails on an existing path, a symlink included) and a mode of 0600 from the first byte
+  const tmp = `${real}.${process.pid}.${randomBytes(6).toString('hex')}.new`
+  try {
+    writeFileSync(tmp, JSON.stringify({ keys }, null, 2) + '\n', { mode: 0o600, flag: 'wx' })
+    renameSync(tmp, real)
+  } catch (e) {
+    rmSync(tmp, { force: true })
+    throw e
+  }
+}
+
+/** One writer at a time (two `key add` at once must not lose a key whose secret was already printed). */
+async function withLock<T>(file: string, fn: () => Promise<T>): Promise<T> {
+  const real = existsSync(file) ? realpathSync(file) : file
+  mkdirSync(dirname(real), { recursive: true, mode: 0o700 })
+  const lock = `${real}.lock`
+  const t0 = Date.now()
+  while (!tryTake(lock, 'file')) {
+    breakIfStale(lock, 'file') // left by a killed process
+    if (Date.now() - t0 > 20_000) throw new UsageError(`${lock} is held by another wmd-relay; if none is running, delete it`)
+    await Bun.sleep(25)
+  }
+  try {
+    return await fn()
+  } finally {
+    release(lock)
+  }
+}
+
+/** The relay options for a config (flags merged over the file). */
+/** What `serve` needs besides the relay's options when --hosted is on. */
+export type HostedRun = { controlDir: string; stateDir: string; denyFile?: string; logDir?: string; logMaxBytes?: number; logDirMaxBytes?: number; logRetentionDays?: number; tlsCert?: string; tlsKey?: string }
+
+/**
+ * Defaults of the hosted profile (docs/relay-hosted.md, section "Measured on this machine"): the per-guest and per-address
+ * numbers one instance carried in the loopback load test, with headroom. Each is a flag, a config key or a `hosted` table key.
+ */
+export const HOSTED_DEFAULTS = {
+  caps: { maxSessions: 4000, maxSessionsPerGroup: 8, maxConns: 32, opensPerMin: 20, connectsPerMin: 120, dnsPerMin: 300, rateDown: 4 << 20, rateUp: 1 << 20, maxBytes: 2 ** 30 },
+  wisp: { instancesPerHour: 30 },
+  hosted: {} as Partial<HostedOptions>,
+}
+
+export function relayOptions(c: Conf, env: Record<string, string | undefined> = process.env): { opts: RelayOptions; notes: string[]; url: string; localTls: boolean; hosted?: HostedRun } {
+  const notes: string[] = []
+  checkTypes(c)
+  const host = c.host ?? '127.0.0.1'
+  const loopback = isLoopbackBind(host)
+  const port = num(c.port, '--port', 0, 65535) ?? DEFAULT_PORT
+  const keys = c.keys ? readKeys(c.keys) : undefined
+  if (keys && !keys.length) throw new UsageError(`${c.keys} has no keys; add one with: wmd-relay key add <id> --keys ${c.keys}`)
+  if (!!c.tlsCert !== !!c.tlsKey) throw new UsageError('--tls-cert and --tls-key go together')
+  const tls = c.tlsCert ? { cert: readFileSync(c.tlsCert, 'utf8'), key: readFileSync(c.tlsKey, 'utf8') } : undefined
+  if (tls && c.localTls) throw new UsageError('--local-tls makes its own certificate; give it or --tls-cert, not both')
+  const origins: string[] = c.origins ?? []
+  for (const o of origins) {
+    let u: URL
+    try {
+      u = new URL(o)
+    } catch {
+      throw new UsageError(`--origin ${o} is not a URL (e.g. https://site.example)`)
+    }
+    if (u.origin !== o.replace(/\/$/, '')) throw new UsageError(`--origin ${o}: give only the origin, e.g. ${u.origin}`)
+  }
+  const isHosted = !!c.hosted
+  if (isHosted) {
+    // the refusals a public relay owes its operator before it takes a single connection (plan §15)
+    if (!c.abuseContact || !String(c.abuseContact).trim()) throw new UsageError('--hosted needs --abuse-contact <email or URL>: it is shown in the MOTD, /healthz and every refusal, and abuse complaints are answered there')
+    if (/[\x00-\x1f]/.test(c.abuseContact)) throw new UsageError('--abuse-contact must be one line of plain text')
+    if (c.allowLan) throw new UsageError('--hosted does not allow --allow-lan: a public relay must never reach private (LAN) addresses')
+    if (Array.isArray(c.allowLoopbackPorts) ? c.allowLoopbackPorts.length : c.allowLoopbackPorts) throw new UsageError('--hosted does not allow --allow-loopback-ports: a public relay must never reach its own loopback')
+    const list = Array.isArray(c.trustProxy) ? c.trustProxy : []
+    if (c.trustProxy === true) throw new UsageError('--hosted needs --trust-proxy <list of proxy addresses or CIDRs>: a bare --trust-proxy would believe any sender about the client address')
+    if (c.behindTls && !list.length) throw new UsageError('--hosted --behind-tls needs --trust-proxy <your proxy address or CIDR>: otherwise every reader shares the proxy\'s address and its limits')
+    if (c.behindTls && !isPrivateBind(host)) throw new UsageError(`--hosted --behind-tls binds only to loopback or a private address (the proxy\'s side), not ${host}: a public bind would let anyone skip the proxy and its TLS`)
+    if (!tls && !c.behindTls && !isPrivateBind(host)) throw new UsageError(`--hosted refuses plain ws:// on the public address ${host}: give --tls-cert and --tls-key, or put a TLS proxy in front with --behind-tls (bound to loopback)`)
+    if (c.localTls) throw new UsageError('--local-tls is for a person\'s own computer, not --hosted')
+  }
+  const w = c.wisp ?? {}
+  const secret = env.WMD_RELAY_SECRET || randomBytes(32).toString('base64url') // tokens (wmn's issuer) only when the secret is shared
+  if (env.WMD_RELAY_SECRET && env.WMD_RELAY_SECRET.length < 16) throw new UsageError('WMD_RELAY_SECRET must be at least 16 characters')
+  const opts: RelayOptions = {
+    secret,
+    host,
+    port,
+    tls,
+    behindTls: !!c.behindTls,
+    origins: origins.map(o => o.replace(/\/$/, '')),
+    allowLan: !!c.allowLan,
+    allowLoopbackPorts: ports(c.allowLoopbackPorts, '--allow-loopback-ports'),
+    blockedPorts: ports(c.blockPorts, '--block-ports'),
+    allowHosts: c.allowHosts,
+    ...(isHosted ? HOSTED_DEFAULTS.caps : {}),
+    ...Object.fromEntries(CAP_KEYS.filter(k => c[k] !== undefined).map(k => [k, c[k]])),
+    ...(Array.isArray(c.trustProxy) ? { trustProxy: c.trustProxy } : {}),
+    ...(c.proxyHeader ? { proxyHeader: c.proxyHeader } : {}),
+    ...(c.allowPorts ? { allowPorts: ports(c.allowPorts, '--allow-ports') } : {}),
+    ...(isHosted
+      ? {
+          hosted: {
+            ...HOSTED_DEFAULTS.hosted,
+            ...(typeof c.hosted === 'object' ? c.hosted : {}),
+            abuseContact: String(c.abuseContact).trim(),
+            version: VERSION,
+            startStopped: !!c.startStopped,
+            usageFile: join(c.stateDir ?? relayDir(), 'usage.json'),
+            maxBytesPerDay: c.maxBytesPerDay,
+            maxBytesPerMonth: c.maxBytesPerMonth,
+            denyCidrs: c.denyCidr,
+          } as HostedOptions,
+        }
+      : {}),
+    log: c.log ? e => process.stderr.write(JSON.stringify({ t: Date.now(), ...e }) + '\n') : undefined,
+    wisp: {
+      ...w,
+      enabled: true,
+      open: !keys,
+      keys,
+      origins: origins.length ? origins.map(o => o.replace(/\/$/, '')) : undefined,
+      checkHost: loopback && !isHosted, // a hosted relay answers to its own name
+      trustProxy: c.trustProxy === true, // a list is the relay's `trustProxy` option (only those peers are believed)
+      version: VERSION,
+      ...(isHosted ? HOSTED_DEFAULTS.wisp : {}),
+      ...Object.fromEntries(WISP_KEYS.filter(k => w[k] !== undefined).map(k => [k, w[k]])),
+    },
+  }
+  if (!loopback && !keys && !isHosted) {
+    notes.push(
+      `note: ${host} can be reached from other machines and there is no key: anyone who can reach port {port} can open connections from this machine through it.` +
+        (origins.length ? '' : ' To allow only your site, add --origin https://your.site'),
+    )
+  }
+  if (c.trustProxy && loopback) notes.push('note: --trust-proxy on a loopback bind: only right if a proxy on this computer forwards to it')
+  if (opts.allowLoopbackPorts?.length) notes.push(`note: guests may reach this computer's loopback on port(s) ${opts.allowLoopbackPorts.join(', ')}`)
+  if (opts.allowLan) notes.push('note: guests may reach private (LAN) addresses')
+  const shown = host === '0.0.0.0' || host === '::' ? 'HOST' : host.includes(':') ? `[${host.replace(/%/g, '%25')}]` : host // a zone id is %25 in a URL
+  const url = `${tls ? 'wss' : 'ws'}://${shown}:${port}${w.path ?? '/wisp/'}`
+  const hostedRun: HostedRun | undefined = isHosted
+    ? { controlDir: c.controlDir ?? join(relayDir(), 'ctl'), stateDir: c.stateDir ?? relayDir(), denyFile: c.denyFile, logDir: c.logDir, logMaxBytes: c.logMaxBytes, logDirMaxBytes: c.logDirMaxBytes, logRetentionDays: c.logRetentionDays, tlsCert: c.tlsCert, tlsKey: c.tlsKey }
+    : undefined
+  return { opts, notes, url, localTls: !!c.localTls, hosted: hostedRun }
+}
+
+function ownAddress(host: string): boolean {
+  if (/^(0\.0\.0\.0|::|localhost)$/i.test(host)) return true
+  const h = host.replace(/^\[|\]$/g, '').toLowerCase()
+  return Object.values(networkInterfaces()).some(l => (l || []).some(i => i.address.split('%')[0].toLowerCase() === h))
+}
+
+async function serve(argv: string[]) {
+  let c = parseFlags(argv)
+  let fromFile: [string, string][] = [] // [flag text, key in the file] for the settings the file gave and no flag overrode
+  let file = ''
+  if (c.config) {
+    file = c.config
+    delete c.config
+    const f = readConfig(file)
+    fromFile = Object.keys(f).filter(k => !(k in c)).map(k => [`--${(k === 'origins' ? 'origin' : k).replace(/[A-Z]/g, m => '-' + m.toLowerCase())}`, k])
+    c = { ...f, ...c }
+  }
+  let made: ReturnType<typeof relayOptions>
+  try {
+    made = relayOptions(c)
+  } catch (e) {
+    // a value from the file is not a flag the person typed: name where it is
+    if (e instanceof UsageError) for (const [flag, k] of fromFile) e.message = e.message.replace(new RegExp(`${flag}(?![\\w-])`, 'g'), `${k} (in ${file})`)
+    throw e
+  }
+  const { opts, notes, url, localTls: wantTls, hosted: hostedRun } = made
+  // hosted: metadata logs go to rotating files with --log-dir, else to stderr
+  const logFile = hostedRun?.logDir ? createLogFile({ dir: hostedRun.logDir, maxBytes: hostedRun.logMaxBytes, maxLogDirBytes: hostedRun.logDirMaxBytes, retainDays: hostedRun.logRetentionDays }) : null
+  if (logFile) opts.log = e => logFile.write(e)
+  else if (hostedRun && !opts.log) opts.log = e => process.stderr.write(JSON.stringify({ t: Date.now(), ...e }) + '\n')
+  const relays: ReturnType<typeof createRelay>[] = []
+  const start = (o: RelayOptions) => {
+    try {
+      relays.push(createRelay({ ...o, alsoOwnPorts: () => relays.map(r => r.port) }))
+    } catch (e: any) {
+      const m = String(e?.message || e)
+      if (e?.code === 'EADDRINUSE' || e?.code === 'EADDRNOTAVAIL' || /EADDRINUSE|in use/i.test(m)) {
+        // Bun says EADDRINUSE for an address this computer does not have, too
+        if (!ownAddress(o.host!)) throw new UsageError(`${o.host} is not an address of this computer`)
+        throw new UsageError(`port ${o.port} on ${o.host} is already in use (another wmd-relay?). Pick another with --port`)
+      }
+      if (e?.code === 'EACCES' || /EACCES|permission/i.test(m)) throw new UsageError(`not allowed to listen on ${o.host}:${o.port}`)
+      throw new UsageError(m)
+    }
+  }
+  if (wantTls && !isLoopbackBind(opts.host!)) throw new UsageError('--local-tls is for this computer only; use --tls-cert and --tls-key on a reachable address')
+  start(opts)
+  const urls = [url.replace(/:\d+(\/[^:]*)$/, `:${relays[0].port}$1`)]
+  for (let i = 0; i < notes.length; i++) notes[i] = notes[i].replace('{port}', String(relays[0].port))
+  if (wantTls) {
+    const t = localTls()
+    if (opts.port === 65535) throw new UsageError('--local-tls serves wss on the next port up; 65535 has none (pick a lower --port)')
+    const tlsPort = opts.port === 0 ? 0 : opts.port === DEFAULT_PORT ? DEFAULT_TLS_PORT : opts.port! + 1 // --port N: wss on N+1
+    start({ ...opts, port: tlsPort, tls: { cert: t.cert, key: t.key } })
+    urls.push(`wss://127.0.0.1:${relays[1].port}${opts.wisp?.path ?? '/wisp/'}`)
+    notes.push(`${t.made ? 'made' : 'using'} ${t.certPath}`, ...t.trust)
+  }
+  let control: { path: string; stop: () => void } | null = null
+  if (hostedRun) {
+    const r = relays[0]
+    const readDeny = () => JSON.parse(readFileSync(hostedRun.denyFile!, 'utf8'))
+    try {
+      if (hostedRun.denyFile) r.reloadDeny(readDeny())
+      control = await startControl(hostedRun.controlDir, {
+        'stop-new': () => (r.hosted!.stopNew(), r.status()),
+        resume: () => (r.hosted!.resume(), r.status()),
+        drain: () => ({ drained: r.drain(), ...r.status() }),
+        status: () => r.status(),
+      })
+    } catch (e: any) {
+      for (const x of relays) x.stop()
+      logFile?.close()
+      if (e instanceof ControlError) throw new UsageError(e.message)
+      throw new UsageError(hostedRun.denyFile && !control ? `${hostedRun.denyFile}: ${e?.message || e}` : e?.message || String(e))
+    }
+    notes.push(`control socket: ${control.path} (wmd-relay ctl status --control-dir ${hostedRun.controlDir})`)
+    // SIGHUP: the new certificate for new connections, and the deny lists again (denied sessions end). A bad file keeps the old one.
+    process.on('SIGHUP', () => {
+      const say = (m: string) => process.stderr.write(`wmd-relay: ${m}\n`)
+      if (hostedRun.tlsCert) {
+        try {
+          r.reloadTls({ cert: readFileSync(hostedRun.tlsCert, 'utf8'), key: readFileSync(hostedRun.tlsKey!, 'utf8') })
+          say('certificate reloaded')
+        } catch (e: any) {
+          say(`certificate NOT reloaded (the old one stays): ${e?.message || e}`)
+        }
+      }
+      if (hostedRun.denyFile) {
+        try {
+          const x = r.reloadDeny(readDeny())
+          say(`deny lists reloaded (ended ${x.sessions} session(s), ${x.streams} stream(s))`)
+        } catch (e: any) {
+          say(`deny lists NOT reloaded (the old ones stay): ${e?.message || e}`)
+        }
+      }
+    })
+  }
+  for (const n of notes) process.stderr.write(n + '\n') // before the URLs: whoever waits for a URL has the notes too
+  for (const u of urls) console.log(u)
+  const stop = () => {
+    control?.stop()
+    for (const r of relays) r.stop()
+    logFile?.close()
+    process.exit(0)
+  }
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+}
+
+async function key(argv: string[]) {
+  const [sub, ...rest] = argv
+  let file = join(relayDir(), 'keys.json')
+  const args: string[] = []
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--keys') file = rest[++i] ?? ''
+    else if (rest[i].startsWith('--keys=')) file = rest[i].slice(7)
+    else args.push(rest[i])
+  }
+  if (!file) throw new UsageError('--keys needs a file')
+  const body = async () => {
+    const keys = existsSync(file) ? readKeys(file) : []
+    if (sub === 'add') {
+      const id = args[0]
+      if (!id || !/^[A-Za-z0-9_-]{1,64}$/.test(id)) throw new UsageError('usage: wmd-relay key add <id>  (1-64 letters, digits, - or _)')
+      if (keys.some(k => k.id === id)) throw new UsageError(`a key '${id}' is already in ${file}; remove it first`)
+      const k = await newKey(id)
+      writeKeys(file, [...keys, { id: k.id, hash: k.hash }])
+      console.log(`key id: ${k.id}`)
+      console.log(`secret: ${k.secret}`)
+      process.stderr.write(`The secret is shown only now; ${file} keeps only its hash. Serve with: wmd-relay --keys ${file}\n`)
+    } else if (sub === 'list') {
+      for (const k of keys) console.log(k.id)
+    } else if (sub === 'remove') {
+      const id = args[0]
+      if (!keys.some(k => k.id === id)) throw new UsageError(`no key '${id}' in ${file}`)
+      writeKeys(file, keys.filter(k => k.id !== id))
+      process.stderr.write(`removed '${id}'; a running relay keeps it until restarted\n`)
+    } else throw new UsageError('usage: wmd-relay key add <id> | list | remove <id>  [--keys file]')
+  }
+  if (sub === 'add' || sub === 'remove') await withLock(file, body)
+  else await body()
+}
+
+/** `wmd-relay ctl stop-new|resume|drain|status [--control-dir D]`: one command to a running hosted relay. Prints its JSON answer. */
+async function ctlCommand(argv: string[]): Promise<number> {
+  let dir = join(relayDir(), 'ctl')
+  const rest: string[] = []
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--control-dir') dir = argv[++i] ?? ''
+    else if (argv[i].startsWith('--control-dir=')) dir = argv[i].slice(14)
+    else rest.push(argv[i])
+  }
+  if (!dir) throw new UsageError('--control-dir needs a directory')
+  if (rest.length !== 1 || !(COMMANDS as readonly string[]).includes(rest[0])) throw new UsageError(`usage: wmd-relay ctl ${COMMANDS.join('|')} [--control-dir <dir>]`)
+  const sock = join(dir, 'ctl.sock')
+  let r: any
+  try {
+    r = await ctl(sock, rest[0])
+  } catch (e: any) {
+    throw new UsageError(`cannot reach the relay's control socket ${sock}: ${e?.code === 'EACCES' ? 'permission denied (it is for the relay\'s user)' : e?.code === 'ENOENT' || e?.code === 'ECONNREFUSED' ? 'no hosted relay is listening there' : e?.message || e}`)
+  }
+  console.log(JSON.stringify(r))
+  return r.ok ? 0 : 1
+}
+
+/**
+ * `wmd-relay check`: can this machine run the relay as built? Starts one on a free loopback port, connects to it as
+ * a Wisp client, and checks that this host's own addresses (os.networkInterfaces) and loopback are refused, that
+ * names are looked up (node:dns), and that a public name gets an answer. Prints a line per check; exit 0 when the
+ * refusals hold (the lookup of a public name only reports, since the network may be offline).
+ */
+async function check(): Promise<number> {
+  const { CLOSE, ClientHandshake, PT, connectPacket, ext, lookupPacket, parse } = await import('../src/net/wisp.js')
+  const r = createRelay({ secret: randomBytes(32).toString('base64url'), port: 0, host: '127.0.0.1', wisp: { enabled: true, open: true, checkHost: true, version: VERSION } })
+  console.log(`relay: ws://127.0.0.1:${r.port}/wisp/ (wmd-relay ${VERSION}, ${process.platform}-${process.arch})`)
+  const ws = new WebSocket(`ws://127.0.0.1:${r.port}/wisp/`, ['wisp-v2'])
+  ws.binaryType = 'arraybuffer'
+  const hs = new ClientHandshake({ exts: [ext.confirm(), ext.wmdDns(), ext.wmdHalfclose(), ext.wmdCredit(65536), ext.wmdInstance(crypto.getRandomValues(new Uint8Array(16)))] })
+  const msgs: any[] = []
+  const ready = new Promise<any>(res => {
+    let done = false
+    ws.onmessage = e => {
+      const m = parse(e.data)
+      if (done) return void msgs.push(m)
+      const x = hs.step(m)
+      for (const b of x.send) ws.send(b)
+      if (x.done || x.fail) res(((done = true), x))
+    }
+    ws.onclose = () => res({ fail: 'closed' })
+  })
+  const wait = async (pred: (m: any) => boolean, ms = 8000) => {
+    const t0 = Date.now()
+    while (Date.now() - t0 < ms) {
+      const m = msgs.find(pred)
+      if (m) return m
+      await Bun.sleep(10)
+    }
+    return null
+  }
+  let bad = 0
+  const say = (ok: boolean, what: string) => {
+    if (!ok) bad++
+    console.log(`${ok ? 'ok' : 'FAIL'}: ${what}`)
+  }
+  const h = await Promise.race([ready, Bun.sleep(8000).then(() => ({ fail: 'timeout' }))])
+  say(!!h.done, `Wisp ${h.done?.version ?? '?'} handshake${h.done ? '' : ` (${JSON.stringify(h.fail)})`}`)
+  if (h.done) {
+    let id = 1
+    const refused = async (host: string, port: number, what: string) => {
+      const n = (id += 2)
+      ws.send(connectPacket(n, host, port))
+      const m = await wait(x => x.id === n && (x.type === PT.CLOSE || x.type === PT.CONTINUE))
+      say(m?.type === PT.CLOSE && m.reason === CLOSE.BLOCKED, `${what} ${host}:${port} refused${m ? (m.type === PT.CLOSE ? ` (0x${m.reason.toString(16)})` : ' -- it was OPENED') : ' -- no answer'}`)
+    }
+    const nics = Object.values(networkInterfaces()).flat().filter(i => i && !i.internal)
+    const own = [...new Set([...nics.filter(i => i!.family === 'IPv4'), ...nics.filter(i => i!.family !== 'IPv4')].map(i => i!.address.split('%')[0]))]
+    if (own.length) for (const a of own.slice(0, 4)) await refused(a, 22, 'own address')
+    else console.log('note: no non-loopback interface; own-address refusal not checked')
+    await refused('127.0.0.1', r.port, 'loopback (the relay itself)')
+    await refused('169.254.169.254', 80, 'metadata')
+    const look = async (name: string) => {
+      const n = (id += 2)
+      ws.send(lookupPacket(n, name, 1))
+      return wait(x => x.id === n && x.type === PT.ANSWER)
+    }
+    const lh = await look('localhost')
+    say(lh?.rcode === 5, `lookup localhost refused${lh ? ` (rcode ${lh.rcode})` : ' -- no answer'}`)
+    const pub = await look('one.one.one.one')
+    console.log(`info: lookup one.one.one.one: ${pub ? `rcode ${pub.rcode}${pub.rcode === 0 ? ' (the resolver works)' : ' (offline, or the resolver refused)'}` : 'no answer'}`)
+  }
+  ws.close()
+  r.stop()
+  console.log(bad ? `${bad} check(s) failed` : 'all checks passed')
+  return bad ? 1 : 0
+}
+
+export async function main(argv: string[]): Promise<number> {
+  try {
+    if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if (argv[0] === 'version' || argv[0] === '--version') {
+      console.log(`wmd-relay ${VERSION}`)
+      return 0
+    }
+    if (argv[0] === 'check') return await check()
+    if (argv[0] === 'ctl') return await ctlCommand(argv.slice(1))
+    if (argv[0] === 'key') {
+      await key(argv.slice(1))
+      return 0
+    }
+    await serve(argv)
+    return -1 // serving
+  } catch (e: any) {
+    process.stderr.write(`wmd-relay: ${e instanceof UsageError || e instanceof SyntaxError ? e.message : e?.code === 'ENOENT' ? `no such file: ${e.path}` : e?.message || e}\n`)
+    return 2
+  }
+}
+
+if (import.meta.main) {
+  const code = await main(process.argv.slice(2))
+  if (code >= 0) process.exit(code)
+}