@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/relay/policy.ts

@@ -0,0 +1,241 @@
+// P-B10 relay: which addresses the relay may connect to. Every check is on the address the
+// relay actually dials (after its own DNS resolution), never on a name, so a name that
+// resolves to a private address (DNS rebinding included) is refused like the address.
+
+import { networkInterfaces } from 'node:os'
+
+export type Addr = { v: 4 | 6; b: Uint8Array }
+
+/** Strict dotted-decimal IPv4 ("127.1", "0x7f.0.0.1", "010.0.0.1" and "2130706433" are not addresses). */
+export function parseIPv4(s: string): Uint8Array | null {
+  const m = s.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
+  if (!m) return null
+  const b = new Uint8Array(4)
+  for (let i = 0; i < 4; i++) {
+    const p = m[i + 1]
+    if (p.length > 1 && p[0] === '0') return null
+    const n = Number(p)
+    if (n > 255) return null
+    b[i] = n
+  }
+  return b
+}
+
+/** IPv6 (with "::" and a trailing dotted IPv4); zone ids ("%en0") are refused. */
+export function parseIPv6(s: string): Uint8Array | null {
+  if (s.startsWith('[') && s.endsWith(']')) s = s.slice(1, -1)
+  if (!s.includes(':') || !/^[0-9a-fA-F:.]+$/.test(s)) return null
+  let tail: number[] = []
+  if (s.includes('.')) {
+    const i = s.lastIndexOf(':')
+    const v4 = parseIPv4(s.slice(i + 1))
+    if (!v4) return null
+    tail = [(v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3]]
+    s = s.slice(0, i + 1)
+    if (!s.endsWith('::')) s = s.slice(0, -1)
+  }
+  const dbl = s.split('::')
+  if (dbl.length > 2) return null
+  const grp = (x: string) => (x === '' ? [] : x.split(':'))
+  const head = grp(dbl[0])
+  const rest = dbl.length === 2 ? grp(dbl[1]) : []
+  for (const g of [...head, ...rest]) if (!/^[0-9a-fA-F]{1,4}$/.test(g)) return null
+  const given = head.length + rest.length + tail.length
+  if (dbl.length === 1 ? given !== 8 : given > 7) return null
+  const words = [...head.map(h => parseInt(h, 16)), ...new Array(8 - given).fill(0), ...rest.map(h => parseInt(h, 16)), ...tail]
+  const b = new Uint8Array(16)
+  words.forEach((w, i) => {
+    b[i * 2] = w >> 8
+    b[i * 2 + 1] = w & 255
+  })
+  return b
+}
+
+export function parseIP(s: string): Addr | null {
+  const v4 = parseIPv4(s)
+  if (v4) return { v: 4, b: v4 }
+  const v6 = parseIPv6(s)
+  return v6 ? { v: 6, b: v6 } : null
+}
+
+export function addrString(a: Addr): string {
+  if (a.v === 4) return Array.from(a.b).join('.')
+  const w: string[] = []
+  for (let i = 0; i < 16; i += 2) w.push(((a.b[i] << 8) | a.b[i + 1]).toString(16))
+  return w.join(':')
+}
+
+function inV4(b: Uint8Array, net: string, bits: number): boolean {
+  const n = parseIPv4(net)!
+  const x = ((b[0] << 24) | (b[1] << 16) | (b[2] << 8) | b[3]) >>> 0
+  const y = ((n[0] << 24) | (n[1] << 16) | (n[2] << 8) | n[3]) >>> 0
+  const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0
+  return (x & mask) >>> 0 === (y & mask) >>> 0
+}
+
+function inV6(b: Uint8Array, net: string, bits: number): boolean {
+  const n = parseIPv6(net)!
+  for (let i = 0; i < 16 && bits > 0; i++, bits -= 8) {
+    const m = bits >= 8 ? 0xff : (0xff << (8 - bits)) & 0xff
+    if ((b[i] & m) !== (n[i] & m)) return false
+  }
+  return true
+}
+
+const V4_BLOCKED: [string, number, string][] = [
+  ['169.254.169.254', 32, 'metadata'],
+  ['100.100.100.200', 32, 'metadata'], // Alibaba Cloud
+  ['0.0.0.0', 8, 'reserved'], // "this network"
+  ['10.0.0.0', 8, 'private'],
+  ['100.64.0.0', 10, 'private'], // shared address space (CGNAT)
+  ['127.0.0.0', 8, 'loopback'],
+  ['169.254.0.0', 16, 'link-local'],
+  ['172.16.0.0', 12, 'private'],
+  ['192.0.0.0', 24, 'reserved'], // IETF protocol assignments (incl. 192.0.0.192, a cloud metadata address)
+  ['192.0.2.0', 24, 'reserved'], // TEST-NET-1
+  ['192.88.99.0', 24, 'reserved'], // 6to4 relay anycast
+  ['192.168.0.0', 16, 'private'],
+  ['198.18.0.0', 15, 'reserved'], // benchmarking
+  ['198.51.100.0', 24, 'reserved'], // TEST-NET-2
+  ['203.0.113.0', 24, 'reserved'], // TEST-NET-3
+  ['224.0.0.0', 4, 'multicast'],
+  ['240.0.0.0', 4, 'reserved'], // incl. 255.255.255.255
+]
+
+const V6_BLOCKED: [string, number, string][] = [
+  ['fd00:ec2::254', 128, 'metadata'], // AWS IMDS over IPv6
+  ['::', 128, 'reserved'],
+  ['::1', 128, 'loopback'],
+  ['::', 96, 'reserved'], // IPv4-compatible (deprecated)
+  ['::ffff:0:0:0', 96, 'reserved'], // IPv4-translated (SIIT, RFC 2765): refused whatever it carries
+  ['64:ff9b:1::', 48, 'reserved'], // local-use NAT64
+  ['100::', 64, 'reserved'], // discard
+  ['2001::', 23, 'reserved'], // IETF protocol assignments, incl. Teredo (2001::/32)
+  ['2001:db8::', 32, 'reserved'], // documentation
+  ['3fff::', 20, 'reserved'], // documentation
+  ['5f00::', 16, 'reserved'], // SRv6 SIDs
+  ['fc00::', 7, 'private'], // unique local
+  ['fe80::', 10, 'link-local'],
+  ['fec0::', 10, 'private'], // site-local (deprecated)
+  ['ff00::', 8, 'multicast'],
+]
+
+/** The ranges `allowLan` opens: RFC 1918 (10/8, 172.16/12, 192.168/16) and IPv6 unique local (fc00::/7) only. Not CGNAT (100.64/10: tailnets, some clouds' internals), site-local or anything embedded. */
+export function isLanRange(a: Addr): boolean {
+  if (a.v === 4) return inV4(a.b, '10.0.0.0', 8) || inV4(a.b, '172.16.0.0', 12) || inV4(a.b, '192.168.0.0', 16)
+  return inV6(a.b, 'fc00::', 7) && !embeddedV4(a.b)
+}
+
+/** The IPv4 address inside an IPv6 one that carries it (mapped, translated, NAT64, 6to4, ISATAP), or null. */
+export function embeddedV4(b: Uint8Array): Uint8Array | null {
+  if (inV6(b, '::ffff:0:0', 96)) return b.slice(12)
+  if (inV6(b, '::ffff:0:0:0', 96)) return b.slice(12)
+  if (inV6(b, '64:ff9b::', 96)) return b.slice(12)
+  if (inV6(b, '2002::', 16)) return b.slice(2, 6)
+  // ISATAP interface ids (RFC 5214): ...:0:5efe:a.b.c.d and ...:200:5efe:a.b.c.d
+  if (b[10] === 0x5e && b[11] === 0xfe && (b[8] & 0xfd) === 0 && b[9] === 0) return b.slice(12)
+  return null
+}
+
+/** A comparable form: an IPv4-mapped IPv6 address is its IPv4 address. */
+export function addrKey(a: Addr): string {
+  if (a.v === 6 && inV6(a.b, '::ffff:0:0', 96)) return Array.from(a.b.slice(12)).join('.')
+  return addrString(a)
+}
+
+/** The relay host's own addresses (every interface, plus `extra`). */
+export function hostAddresses(extra: string[] = []): Set<string> {
+  const out = new Set<string>()
+  for (const list of Object.values(networkInterfaces())) {
+    for (const i of list || []) {
+      const a = parseIP(i.address.split('%')[0])
+      if (a) out.add(addrKey(a))
+    }
+  }
+  for (const x of extra) {
+    const a = parseIP(x.trim())
+    if (a) out.add(addrKey(a))
+  }
+  return out
+}
+
+/**
+ * Why the relay must not connect to this address, or null when it may. `self` holds the
+ * relay host's own addresses (addrKey form).
+ */
+export function blockedReason(a: Addr, self: Set<string> = new Set()): string | null {
+  if (self.has(addrKey(a))) return 'self'
+  if (a.v === 4) {
+    for (const [net, bits, why] of V4_BLOCKED) if (inV4(a.b, net, bits)) return why
+    return null
+  }
+  const e = embeddedV4(a.b)
+  if (e) {
+    const r = blockedReason({ v: 4, b: e }, self)
+    if (r) return `${r} (embedded IPv4 ${Array.from(e).join('.')})`
+  }
+  for (const [net, bits, why] of V6_BLOCKED) if (inV6(a.b, net, bits)) return why
+  return null
+}
+
+/** Why the relay will not look up this name, or null: letters, digits, '-', '_', at most 253 bytes, not numeric-looking, not localhost. */
+export function badName(name: string): string | null {
+  const n = name.toLowerCase().replace(/\.$/, '')
+  if (!n || n.length > 253) return 'bad length'
+  const labels = n.split('.')
+  for (const l of labels) if (!/^[a-z0-9_]([a-z0-9_-]{0,61}[a-z0-9_])?$/.test(l)) return 'bad characters'
+  // "127.1", "0x7f000001", "2130706433": numeric forms a resolver might take as addresses
+  if (/^(0x[0-9a-f]+|\d+)$/.test(labels[labels.length - 1])) return 'numeric name'
+  if (n === 'localhost' || n.endsWith('.localhost')) return 'localhost'
+  return null
+}
+
+export type Cidr = { v: 4 | 6; b: Uint8Array; bits: number }
+
+/** "10.1.0.0/16", "2001:db8::/32" or a bare address (a host route); null when it is not one. */
+export function parseCidr(s: string): Cidr | null {
+  const [a, len, ...more] = s.trim().split('/')
+  if (more.length) return null
+  const ip = parseIP(a)
+  if (!ip) return null
+  const max = ip.v === 4 ? 32 : 128
+  if (len !== undefined && !/^\d{1,3}$/.test(len)) return null
+  const bits = len === undefined ? max : Number(len)
+  return bits > max ? null : { v: ip.v, b: ip.b, bits }
+}
+
+export function cidrContains(c: Cidr, a: Addr): boolean {
+  if (c.v !== a.v) return false
+  let bits = c.bits
+  for (let i = 0; i < c.b.length && bits > 0; i++, bits -= 8) {
+    const m = bits >= 8 ? 0xff : (0xff << (8 - bits)) & 0xff
+    if ((a.b[i] & m) !== (c.b[i] & m)) return false
+  }
+  return true
+}
+
+/**
+ * The hosted profile's extra refusals on a dialled address (plan §15), on top of blockedReason: all of NAT64
+ * (64:ff9b::/96, whatever IPv4 it carries: a NAT64 gateway on the path would reach it) and the operator's `--deny-cidr`
+ * list (the fleet's own private neighbours). IPv4-mapped and -compatible forms of a refused IPv4 range are already
+ * refused by blockedReason (embeddedV4), and 100.64/10 and fd00:ec2::254 are in its tables; a test pins that.
+ */
+export function hostedBlockedReason(a: Addr, deny: Cidr[]): string | null {
+  if (a.v === 6 && inV6(a.b, '64:ff9b::', 96)) return 'NAT64'
+  for (const c of deny) {
+    if (cidrContains(c, a)) return 'operator deny-cidr'
+    const e = a.v === 6 ? embeddedV4(a.b) : null
+    if (e && c.v === 4 && cidrContains(c, { v: 4, b: e })) return 'operator deny-cidr (embedded IPv4)'
+  }
+  return null
+}
+
+/** A bind address a person on the open internet cannot reach: loopback, private or link-local. Names other than localhost are public (not resolved here). */
+export function isPrivateBind(host: string): boolean {
+  if (/^localhost$/i.test(host)) return true
+  const a = parseIP(host.replace(/%.*$/, '').replace(/^\[|\]$/g, ''))
+  if (!a) return false
+  const r = blockedReason(a)
+  if (r === 'loopback' || r === 'private' || r === 'link-local') return true
+  return false
+}

package/relay/relay.ts

@@ -0,0 +1,266 @@
+// P-B10: the network relay for wmd-web. A browser guest's TCP connections and DNS lookups
+// arrive here over one WebSocket per guest (src/net/proto.js), and the relay makes the real
+// connections. Small and self-hostable:
+//
+//   WMD_RELAY_SECRET=<at least 16 chars> bun relay/relay.ts
+//
+// Environment (all optional but the secret):
+//   WMD_RELAY_PORT (4571), WMD_RELAY_HOST (127.0.0.1)
+//   WMD_RELAY_ORIGINS        comma list of page origins allowed to connect, at /relay and at /wisp/ (default: any)
+//   WMD_RELAY_ALLOW_HOSTS    comma list of DNS names, each optionally with ports ("pypi.org:443",
+//                            "example.com:80|443"; no ports means 80 and 443; a leading "."
+//                            matches subdomains); when set the relay answers only those names and
+//                            connects only to (address, port) pairs it gave out for them to this
+//                            guest (default: any public address)
+//   WMD_RELAY_SELF           extra addresses that are this host (a public IP behind NAT); every
+//                            interface address is included anyway
+//   WMD_RELAY_DNS            resolvers to ask (ip or ip:port, comma list; default: the system's)
+//   Caps are per guest identity (the token's uid: one guest machine of one page; the token's
+//   sid when it has none) and survive reconnects for as long as that identity holds a token:
+//   WMD_RELAY_MAX_CONNS (64) connections at once; WMD_RELAY_CONNECTS_PER_MIN (600),
+//   WMD_RELAY_DNS_PER_MIN (1200), WMD_RELAY_OPENS_PER_MIN (30) WebSocket opens;
+//   WMD_RELAY_RATE_DOWN (16777216), WMD_RELAY_RATE_UP (4194304) bytes/s, every byte (a new
+//   stream's first window too); WMD_RELAY_MAX_BYTES (4294967296) bytes, both ways.
+//   One live WebSocket per identity (a newer one replaces it). WMD_RELAY_MAX_SESSIONS (100) in
+//   all, WMD_RELAY_MAX_SESSIONS_PER_GROUP (8) per token group (grp: the client the issuer saw,
+//   e.g. its address or user). The relay's state is in memory: a relay restart resets it.
+//   WMD_RELAY_BLOCK_PORTS (25)        destination ports refused
+//   WMD_RELAY_LOG=0                   no JSON log lines on stdout
+//   WMD_RELAY_WISP=0                  do not serve Wisp at /wisp/ (W59, on by default since D-444; token
+//                                     clients only here: the standalone wmd-relay, relay/main.ts, is the keyless one)
+// Test only (the relay prints a warning when they are set):
+//   WMD_RELAY_TEST_ROUTES   "203.0.113.10:80=127.0.0.1:4572,..." dial the right side for the left
+//   WMD_RELAY_TEST_HOSTS    "bulk.wmd.test=203.0.113.10,..." answer these names without DNS
+//
+// Security: every connect is checked on the address actually dialled, after the relay's
+// own resolution (policy.ts): private, loopback, link-local, metadata, reserved and
+// multicast ranges and this host's own addresses are refused, so a name that resolves (or
+// rebinds) to one of them cannot reach it. A session needs a token (token.ts); connections,
+// connect and DNS rates, bandwidth and total bytes are capped per session.
+
+import { E, MAX_DATA, PROTOCOL } from '../src/net/proto.js'
+import { type DialFn, type EngineOptions, type ResolveFn, createEngine } from './engine.ts'
+import { createV1 } from './v1.ts'
+import { type Governor, type HostedOptions, type DenySpec, createGovernor } from './hosted.ts'
+import { type Cidr, parseCidr } from './policy.ts'
+import { DRAIN_WORDS, type WispOptions, createWisp } from './wisp.ts'
+
+export type { DialFn, ResolveFn, WispOptions }
+
+export type RelayOptions = EngineOptions & {
+  port?: number
+  host?: string
+  secret: string
+  origins?: string[]
+  /** The Wisp endpoint (W59) at /wisp/. On unless `enabled: false` (on by default since S6, D-444: proven in Chromium, Firefox, WebKit and Safari). */
+  wisp?: WispOptions
+  tls?: { cert: string; key: string }
+  /** A TLS proxy or tunnel is in front: secrets on a reachable plain-ws bind are acceptable. */
+  behindTls?: boolean
+  /** The hosted profile (plan §15, hosted.ts): limits, lists, ceilings, /healthz and /readyz. */
+  hosted?: HostedOptions
+  /** Proxy addresses or CIDRs: only these peers are believed about the client address, which is the first entry from the right of `proxyHeader` that is not one of them. No "trust any". */
+  trustProxy?: string[]
+  proxyHeader?: string // (x-forwarded-for; a provider's own, e.g. cf-connecting-ip)
+}
+
+const MAIL_PORTS = [25, 465, 587]
+
+const isLoopbackHost = (h: string) => /^(127\.\d+\.\d+\.\d+|::1|localhost)$/i.test(h)
+
+export function createRelay(o: RelayOptions) {
+  if (!o.secret || o.secret.length < 16) throw new Error('WMD_RELAY_SECRET must be set (at least 16 characters)')
+  const host = o.host ?? '127.0.0.1'
+  const wispOn = o.wisp?.enabled !== false
+  if (wispOn && o.wisp?.keys?.length && !o.tls && !o.behindTls && !isLoopbackHost(host)) {
+    throw new Error(`keys on plain ws:// at ${host} would cross the network in clear text; give a TLS certificate or say a TLS proxy is in front (behindTls)`)
+  }
+  let port = 0
+  // the grace after a byte ceiling is over: every open stream ends (CLOSE 0x49); the sessions stay for the next day
+  const endStreams = (words: string) => {
+    for (const s of [...engine.sessions.values()]) for (const st of [...s.streams.values()]) engine.fail(s, st, E.LIMIT, words)
+  }
+  const gov: Governor | null = o.hosted ? createGovernor({ onCeilingGrace: w => endStreams(w), ...o.hosted }) : null
+  // hosted: mail ports are always refused, whatever the operator adds
+  const blockedPorts = gov ? [...new Set([...MAIL_PORTS, ...(o.blockedPorts ?? [])])] : o.blockedPorts
+  const trusted: Cidr[] = (o.trustProxy ?? []).map(x => {
+    const c = parseCidr(x)
+    if (!c) throw new Error(`trust-proxy '${x}' is not an address or CIDR`)
+    if (c.bits < (c.v === 4 ? 8 : 16)) throw new Error(`trust-proxy '${x}' trusts too much of the internet: a prefix shorter than /8 (IPv4) or /16 (IPv6) is refused; list the proxy's address or network`)
+    return c
+  })
+  const proxy = trusted.length ? { trusted, header: (o.proxyHeader || 'x-forwarded-for').toLowerCase() } : undefined
+  const engine = createEngine({ ...o, blockedPorts, ownPort: () => port, ...(gov ? { guard: gov } : {}) })
+  const v1 = createV1(engine, o)
+  const wisp = wispOn ? createWisp(engine, { ...o, blockedPorts, port: () => port, wisp: { ...o.wisp, origins: o.wisp?.origins ?? o.origins, enabled: true, ...(gov ? { hosted: gov } : {}), ...(proxy ? { proxy } : {}) } }) : null
+
+  const streams = () => {
+    let n = 0
+    for (const s of engine.sessions.values()) n += s.streams.size
+    return n
+  }
+  // /healthz and /readyz hold counts and the abuse contact, nothing about any client, origin, destination or key
+  function health(path: string): Response {
+    const why = gov!.notAccepting()
+    const ceiling = gov!.ceiling()
+    if (path === '/readyz') return new Response(why ? `not ready: ${why}\n${gov!.contactLine}` : 'ready\n', { status: why ? 503 : 200 })
+    return Response.json({
+      version: gov!.version ?? null, sessions: engine.sessions.size, streams: streams(), accepting: !why,
+      state: gov!.isDraining() ? 'draining' : gov!.isStopped() ? 'stopped' : 'running', ceiling, abuseContact: gov!.contact,
+    })
+  }
+
+  const serverOptions = (tls?: { cert: string; key: string }): any => ({
+    port: tls && server ? port : o.port ?? 4571,
+    hostname: host,
+    // two listeners may share the port for a moment when the certificate is reloaded (reloadTls)
+    ...(tls ? { tls, reusePort: true } : {}),
+    fetch(req: Request, srv: any) {
+      const url = new URL(req.url)
+      if (gov && (req.method === 'GET' || req.method === 'HEAD') && (url.pathname === '/healthz' || url.pathname === '/readyz')) {
+        const r = health(url.pathname)
+        return req.method === 'HEAD' ? new Response(null, { status: r.status, headers: r.headers }) : r // same status and headers, no body
+      }
+      if (url.pathname === '/relay') {
+        const protos = req.headers.get('sec-websocket-protocol') || ''
+        if (wisp && protos.includes('wisp-v2') && !protos.includes(PROTOCOL)) return new Response(`this is the wmd-relay.v1 endpoint; Wisp is at ${wisp.path}\n`, { status: 400 })
+        return v1.fetch(req, srv)
+      }
+      if (wisp && url.pathname.startsWith(wisp.path)) return wisp.fetch(req, srv, url)
+      return new Response('not found\n', { status: 404 })
+    },
+    websocket: {
+      maxPayloadLength: wisp ? Math.max(MAX_DATA + 1024, wisp.maxPayload + (64 << 10)) : MAX_DATA + 1024, // headroom: the adapters close an oversized frame with 1009 in words
+      backpressureLimit: 32 << 20,
+      idleTimeout: 120,
+      sendPings: true,
+      open(ws: any) {
+        if (ws.data.kind === 'wisp') wisp!.open(ws)
+        else v1.open(ws)
+      },
+      message(ws: any, data: any) {
+        if (ws.data.kind === 'wisp') wisp!.message(ws, data)
+        else v1.message(ws, data)
+      },
+      drain(ws: any) {
+        const s = ws.data.session
+        if (s) engine.pumpAll(s)
+      },
+      close(ws: any, code: number, reason: string) {
+        if (ws.data.kind === 'wisp') return wisp!.close(ws, code, reason)
+        const s = ws.data.session
+        if (s) engine.closeSession(s, `websocket closed ${code} ${reason || ''}`.trim())
+      },
+    },
+  })
+
+  let server: any = null
+  server = Bun.serve(serverOptions(o.tls))
+  port = server.port
+  return {
+    get server() {
+      return server
+    },
+    port: server.port,
+    hosted: gov,
+    stats: () => ({ ...engine.stats, live: engine.sessions.size, principals: engine.principals.size }),
+    /** Hosted: end every session (CLOSE 0x01 per stream, then 1001 in words) and take no new ones until `resume`. */
+    drain(): number {
+      gov?.startDrain()
+      const all = [...engine.sessions.values()]
+      for (const s of all) {
+        if (s.ws.data.kind === 'wisp' && wisp) wisp.drain(s.ws)
+        else s.ws.close(1001, DRAIN_WORDS)
+      }
+      return all.length
+    },
+    /** Hosted: the state `ctl status` prints (counts only). */
+    status() {
+      return {
+        accepting: gov ? gov.accepting() : true, state: gov?.isDraining() ? 'draining' : gov?.isStopped() ? 'stopped' : 'running',
+        ceiling: gov?.ceiling() ?? null, sessions: engine.sessions.size, streams: streams(), usage: gov?.usage() ?? null, origins: gov?.originStats() ?? null,
+      }
+    },
+    /** Hosted: replace the deny lists; sessions and streams they now deny end. Returns how many sessions and streams. */
+    reloadDeny(spec: DenySpec): { sessions: number; streams: number } {
+      const r = gov!.reloadDeny(spec)
+      let n = 0
+      for (const s of [...engine.sessions.values()]) {
+        for (const st of [...s.streams.values()]) {
+          const i = st.to.lastIndexOf(':')
+          if (gov!.isDeniedDest(st.to.slice(0, i), Number(st.to.slice(i + 1)))) {
+            n++
+            engine.fail(s, st, E.BLOCKED, 'this destination is blocked by the operator')
+          }
+        }
+      }
+      return { sessions: r.ended, streams: n }
+    },
+    /** A new certificate for new connections (SIGHUP). The new listener takes the port before the old one stops listening; open sockets keep the old certificate. */
+    reloadTls(tls: { cert: string; key: string }) {
+      const next = Bun.serve(serverOptions(tls))
+      const old = server
+      server = next
+      old.stop(false)
+    },
+    stop() {
+      wisp?.stop()
+      engine.stop()
+      gov?.stop()
+      server.stop(true)
+    },
+  }
+}
+
+function envList(v: string | undefined): string[] {
+  return (v || '').split(',').map(x => x.trim()).filter(Boolean)
+}
+function envMap(v: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const kv of envList(v)) {
+    const i = kv.indexOf('=')
+    if (i > 0) out[kv.slice(0, i).toLowerCase()] = kv.slice(i + 1)
+  }
+  return out
+}
+const envNum = (v: string | undefined) => (v ? Number(v) : undefined)
+
+if (import.meta.main) {
+  const env = process.env
+  const testRoutes = envMap(env.WMD_RELAY_TEST_ROUTES)
+  const testHosts = envMap(env.WMD_RELAY_TEST_HOSTS)
+  const quiet = env.WMD_RELAY_LOG === '0'
+  const relay = createRelay({
+    secret: env.WMD_RELAY_SECRET || '',
+    port: envNum(env.WMD_RELAY_PORT),
+    host: env.WMD_RELAY_HOST,
+    origins: envList(env.WMD_RELAY_ORIGINS),
+    allowHosts: envList(env.WMD_RELAY_ALLOW_HOSTS),
+    selfAddrs: envList(env.WMD_RELAY_SELF),
+    dnsServers: envList(env.WMD_RELAY_DNS),
+    maxConns: envNum(env.WMD_RELAY_MAX_CONNS),
+    maxSessions: envNum(env.WMD_RELAY_MAX_SESSIONS),
+    maxSessionsPerGroup: envNum(env.WMD_RELAY_MAX_SESSIONS_PER_GROUP),
+    opensPerMin: envNum(env.WMD_RELAY_OPENS_PER_MIN),
+    connectsPerMin: envNum(env.WMD_RELAY_CONNECTS_PER_MIN),
+    dnsPerMin: envNum(env.WMD_RELAY_DNS_PER_MIN),
+    rateDown: envNum(env.WMD_RELAY_RATE_DOWN),
+    rateUp: envNum(env.WMD_RELAY_RATE_UP),
+    maxBytes: envNum(env.WMD_RELAY_MAX_BYTES),
+    blockedPorts: env.WMD_RELAY_BLOCK_PORTS !== undefined ? envList(env.WMD_RELAY_BLOCK_PORTS).map(Number) : undefined,
+    testRoutes,
+    testHosts,
+    log: quiet ? undefined : e => console.log(JSON.stringify({ t: Date.now(), ...e })),
+    wisp: env.WMD_RELAY_WISP === '0' ? { enabled: false } : undefined, // on by default (D-444); WMD_RELAY_WISP=0 turns it off
+  })
+  if (Object.keys(testRoutes).length || Object.keys(testHosts).length) {
+    console.log(JSON.stringify({ ev: 'warning', why: 'TEST ROUTES/HOSTS ARE SET: some refused addresses are reachable; never run a public relay like this', testRoutes, testHosts }))
+  }
+  console.log(JSON.stringify({ ev: 'listening', port: relay.port, pid: process.pid }))
+  const stop = () => {
+    relay.stop()
+    process.exit(0)
+  }
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+}

package/relay/token.ts

@@ -0,0 +1,116 @@
+// P-B10 relay: session tokens. A token is "v1.<payload>.<mac>", base64url without padding,
+// where the payload is JSON {sid, exp (ms since the epoch), uid?, grp?} and the mac is
+// HMAC-SHA256 of "v1.<payload>" with the relay's secret. Whoever serves the page
+// (test/serve.ts, or wmn's server) mints them with the same secret (TokenIssuer below); the
+// browser presents one as a WebSocket subprotocol "t.<token>" (not in the URL, so it stays
+// out of access logs).
+//
+//   sid  this token (one live connection per sid)
+//   uid  the guest identity the relay keeps caps for, across reconnects and fresh tokens
+//        (one guest machine of one page); defaults to sid
+//   grp  the client the issuer saw (an address, a user): the relay caps sessions per grp
+//
+// Parsing is strict: a token is exactly one encoding of its payload and MAC, so the same
+// token never verifies under two spellings.
+
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+
+const b64u = (b: Buffer) => b.toString('base64url')
+const B64U = /^[A-Za-z0-9_-]+$/
+const ID = /^[A-Za-z0-9_.:\/-]{1,128}$/
+
+export type TokenFields = { sid?: string; uid?: string; grp?: string; ttlMs?: number; now?: number }
+
+export function mintToken(secret: string, { sid = b64u(randomBytes(12)), uid, grp, ttlMs = 60 * 60_000, now = Date.now() }: TokenFields = {}): string {
+  if (!secret || secret.length < 16) throw new Error('relay secret: at least 16 characters')
+  const body: Record<string, unknown> = { sid, exp: now + ttlMs }
+  if (uid) body.uid = uid
+  if (grp) body.grp = grp
+  const payload = b64u(Buffer.from(JSON.stringify(body)))
+  const mac = createHmac('sha256', secret).update(`v1.${payload}`).digest()
+  return `v1.${payload}.${b64u(mac)}`
+}
+
+export type TokenInfo = { sid: string; exp: number; uid?: string; grp?: string }
+
+/** The token's session, or an error string. */
+export function verifyToken(secret: string, token: string, now = Date.now()): TokenInfo | string {
+  if (typeof token !== 'string' || token.length > 1024) return 'bad token'
+  const parts = token.split('.')
+  if (parts.length !== 3 || parts[0] !== 'v1' || !B64U.test(parts[1]) || !B64U.test(parts[2])) return 'bad token'
+  const want = createHmac('sha256', secret).update(`v1.${parts[1]}`).digest()
+  const got = Buffer.from(parts[2], 'base64url')
+  // the canonical spelling only (base64url decoding ignores trailing bits and junk)
+  if (b64u(got) !== parts[2] || got.length !== want.length || !timingSafeEqual(got, want)) return 'bad token signature'
+  const raw = Buffer.from(parts[1], 'base64url')
+  if (b64u(raw) !== parts[1]) return 'bad token'
+  let info: TokenInfo
+  try {
+    info = JSON.parse(raw.toString('utf8'))
+  } catch {
+    return 'bad token'
+  }
+  if (typeof info !== 'object' || !info || typeof info.sid !== 'string' || !ID.test(info.sid) || typeof info.exp !== 'number') return 'bad token'
+  for (const k of ['uid', 'grp'] as const) if (info[k] !== undefined && (typeof info[k] !== 'string' || !ID.test(info[k]!))) return 'bad token'
+  if (info.exp <= now) return 'token expired'
+  return { sid: info.sid, exp: info.exp, uid: info.uid, grp: info.grp }
+}
+
+/** The key a client's limits are kept under: IPv6 addresses by their /64 (one subscriber holds 2^64 of them). */
+export function clientKey(client: string): string {
+  if (!client.includes(':') || /^\d+\.\d+\.\d+\.\d+$/.test(client)) return client
+  const m = client.toLowerCase().match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/) // ::ffff:1.2.3.4
+  if (m) return m[2]
+  const [head, tail] = client.toLowerCase().split('::')
+  const h = head ? head.split(':') : []
+  const t = tail === undefined ? [] : tail ? tail.split(':') : []
+  if (tail === undefined && h.length !== 8) return client
+  const groups = tail === undefined ? h : [...h, ...Array(Math.max(0, 8 - h.length - t.length)).fill('0'), ...t]
+  if (groups.length !== 8 || groups.some(g => !/^[0-9a-f]{1,4}$/.test(g))) return client
+  return `v6:${groups.slice(0, 4).map(g => g.padStart(4, '0')).join(':')}`
+}
+
+/**
+ * Mints tokens for page instances, with limits per client (the address the request came
+ * from, or a user id; IPv6 by /64): at most `perMinute` tokens a minute and `instancesPerHour`
+ * distinct page instances an hour, each token valid at least `MIN_TTL_MS` and at most `maxTtlMs`.
+ * The relay keeps caps per uid (client/instance) across reconnects, so a client cannot reset
+ * its caps by asking for fresh tokens, and cannot open more than `instancesPerHour` identities
+ * an hour. At most `maxClients` clients are remembered (the least recently used go first).
+ */
+export const MIN_TTL_MS = 60_000
+export class TokenIssuer {
+  perMinute: number
+  instancesPerHour: number
+  maxTtlMs: number
+  maxClients: number
+  minTtlMs: number
+  clients = new Map<string, { times: number[]; instances: Map<string, number> }>() // least recently used first
+  constructor(public secret: string, { perMinute = 60, instancesPerHour = 20, maxTtlMs = 60 * 60_000, maxClients = 10_000, minTtlMs = MIN_TTL_MS } = {}) {
+    this.perMinute = perMinute
+    this.instancesPerHour = instancesPerHour
+    this.maxTtlMs = maxTtlMs
+    this.maxClients = maxClients
+    this.minTtlMs = Number.isFinite(minTtlMs) && minTtlMs > 0 ? minTtlMs : MIN_TTL_MS // a NaN (an env var that is not a number) would make every token's lifetime NaN; below MIN_TTL_MS only for tests of expiry (test/serve.ts WMD_RELAY_MIN_TTL_MS)
+  }
+  /** A token for this client's page instance, or {error, status}. A bad request is not counted against the limits. */
+  issue(client: string, instance: string, ttlMs: number = this.maxTtlMs, now = Date.now()): { token: string } | { error: string; status: number } {
+    if (!ID.test(client)) return { error: 'bad client', status: 400 }
+    if (!/^[A-Za-z0-9_-]{8,64}$/.test(instance || '')) return { error: 'instance: 8-64 characters [A-Za-z0-9_-]', status: 400 }
+    if (typeof ttlMs !== 'number' || !Number.isFinite(ttlMs)) return { error: 'ttl: a number of milliseconds', status: 400 }
+    const key = clientKey(client)
+    let c = this.clients.get(key)
+    if (c) this.clients.delete(key) // re-inserted below: most recently used last
+    else c = { times: [], instances: new Map() }
+    this.clients.set(key, c)
+    while (this.clients.size > this.maxClients) this.clients.delete(this.clients.keys().next().value as string)
+    c.times = c.times.filter(t => now - t < 60_000)
+    for (const [k, t] of c.instances) if (now - t > 60 * 60_000) c.instances.delete(k)
+    if (c.times.length >= this.perMinute) return { error: `more than ${this.perMinute} tokens a minute`, status: 429 }
+    if (!c.instances.has(instance) && c.instances.size >= this.instancesPerHour) return { error: `more than ${this.instancesPerHour} page instances an hour`, status: 429 }
+    c.times.push(now)
+    if (!c.instances.has(instance)) c.instances.set(instance, now)
+    const ttl = Math.min(Math.max(ttlMs, this.minTtlMs), this.maxTtlMs)
+    return { token: mintToken(this.secret, { uid: `${key}/${instance}`, grp: key, ttlMs: ttl, now }) }
+  }
+}