@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/relay/engine.ts

@@ -0,0 +1,787 @@
+// W59: the relay engine, shared by both wire protocols (v1.ts: wmd-relay.v1, wisp.ts: Wisp v2).
+//
+// The engine owns everything that is not the wire format:
+//   - policy (policy.ts): names and addresses checked on the address actually dialled, the
+//     allowlist with its per-guest pins, blocked ports
+//   - principals (a guest identity) and their caps: connections, connect/DNS/open rates,
+//     bandwidth buckets, total bytes; sessions per group; one live session per identity
+//   - resolve-and-check, dial, the stream lifecycle and byte accounting
+//   - logging (metadata only, never payloads)
+//
+// An adapter owns the wire: it decodes client messages into engine calls, and implements `Wire`
+// for what the engine tells the client. It also owns the flow-control *unit*: the engine counts
+// bytes (download credit, upload bytes written), the adapter turns them into its own messages
+// (v1: byte CREDIT; Wisp: CONTINUE packet counts, the 0xE1 byte credit).
+
+import { Resolver } from 'node:dns'
+import { connect as netConnect, type Socket } from 'node:net'
+import { E, MAX_DATA, RCODE, WINDOW } from '../src/net/proto.js'
+import { type Addr, addrKey, addrString, badName, blockedReason, hostAddresses, isLanRange, parseIP } from './policy.ts'
+
+// a principal's caps outlive its tokens by at least this long (short-lived tokens must not reset them)
+const PRINCIPAL_FLOOR_MS = 60 * 60_000
+
+export type ResolveFn = (name: string) => Promise<{ address: string; ttl: number }[]>
+export type DialFn = (host: string, port: number) => Socket
+
+/** What the hosted profile (hosted.ts) asks of the engine; absent outside it. Each method is a hook at one point of the stream lifecycle. */
+export interface Guard {
+  /** An extra reason to refuse a dialled address (NAT64, `--deny-cidr`). */
+  blockedAddr(a: Addr): string | null
+  /** A destination on the operator's deny list. */
+  isDeniedDest(host: string, port: number): boolean
+  /** Before a connect is resolved: the words to refuse it with, or null. */
+  admitConnect(s: Session, host: string, port: number): string | null
+  /** Just before the dial: concurrent caps. Sets `st.rel`. */
+  openStream(s: Session, st: Stream, host: string, port: number): string | null
+  dialFailed(s: Session): void
+  dnsAllowed(s: Session): boolean
+  dnsClosed?(): string | null // words when lookups are refused too (stop-new, drain, ceiling)
+  /** Bytes moved for a session; false when its address group is over its bytes for the hour. */
+  bytes(s: Session, n: number): boolean
+  limitWhy?(): string // why `bytes` said no
+  /** Of n bytes the session's own bucket let through, how many the coarse, origin and relay-wide buckets allow. */
+  take(s: Session, dir: 'down' | 'up', n: number): number
+  waitMs(s: Session, dir: 'down' | 'up', n: number): number
+}
+
+export type EngineOptions = {
+  maxConns?: number
+  maxSessions?: number
+  maxSessionsPerGroup?: number
+  opensPerMin?: number
+  connectsPerMin?: number
+  dnsPerMin?: number
+  rateDown?: number
+  rateUp?: number
+  maxBytes?: number
+  allowHosts?: string[]
+  selfAddrs?: string[]
+  dnsServers?: string[]
+  blockedPorts?: number[]
+  allowPorts?: number[] // when set, only these destination ports (a stricter deployment)
+  guard?: Guard
+  allowLan?: boolean // private ranges (10/8, 172.16/12, 192.168/16, fc00::/7) may be dialled; metadata, link-local and this host's LAN addresses stay refused
+  allowLoopbackPorts?: number[] // loopback (127/8, ::1) may be dialled on these ports only; never the relay's own port
+  ownPort?: () => number // the relay's own port (refused on loopback whatever allowLoopbackPorts says)
+  alsoOwnPorts?: () => number[] // listeners of the same program (the --local-tls wss port): refused on loopback too
+  connectTimeoutMs?: number
+  dnsTimeoutMs?: number
+  testRoutes?: Record<string, string>
+  testHosts?: Record<string, string>
+  resolve4?: ResolveFn
+  dial?: DialFn
+  log?: (e: Record<string, unknown>) => void
+}
+
+export class Bucket {
+  tokens: number
+  last = performance.now()
+  constructor(public rate: number) {
+    this.tokens = rate
+  }
+  /** The smallest take worth a message: 16 KiB, or less for a small request or a small rate (the bucket holds at most `rate`). */
+  floor(n: number): number {
+    return Math.max(1, Math.min(n, 16 << 10, Math.floor(this.rate)))
+  }
+  /** Up to n bytes, or 0 when fewer than floor(n) are there (no trickle of tiny messages). */
+  take(n: number): number {
+    const t = performance.now()
+    this.tokens = Math.min(this.rate, this.tokens + ((t - this.last) / 1000) * this.rate)
+    this.last = t
+    if (this.tokens < this.floor(n)) return 0
+    const k = Math.max(0, Math.min(n, Math.floor(this.tokens)))
+    this.tokens -= k
+    return k
+  }
+  /** ms until n tokens are there. */
+  waitMs(n: number): number {
+    return Math.max(1, Math.ceil(((this.floor(n) - this.tokens) / this.rate) * 1000))
+  }
+}
+
+export class Window {
+  times: number[] = []
+  constructor(public max: number, public ms: number) {}
+  hit(): boolean {
+    const t = performance.now()
+    while (this.times.length && t - this.times[0] > this.ms) this.times.shift()
+    if (this.times.length >= this.max) return false
+    this.times.push(t)
+    return true
+  }
+}
+
+export type Stream = {
+  id: number
+  sock: Socket | null
+  connected: boolean
+  clientCredit: number // bytes we may send the client
+  ourGrant: number // v1: bytes the client may still send us (the v1 adapter's unit)
+  outQ: Buffer[]
+  outBytes: number
+  remoteEnded: boolean // the remote's FIN arrived
+  endSent: boolean
+  clientEnded: boolean
+  closed: boolean
+  to: string
+  bytesDown: number
+  bytesUp: number
+  openedAt: number
+  w?: any // adapter state for the stream
+  rel?: () => void // the guard's release, called once when the stream is gone
+}
+
+/** A guest identity: every cap and counter, kept across its WebSocket sessions. */
+export type Principal = {
+  uid: string
+  grp: string
+  connects: Window
+  dnsHits: Window
+  opens: Window
+  down: Bucket
+  up: Bucket
+  bytes: number
+  exp: number // the latest expiry of a token seen for it; the state is dropped after it
+  live: Session | null
+  pins: Map<string, number> // allowlist: "address:port" -> expiry (ms)
+  overBytes: boolean
+}
+
+/** What the engine tells the client. The adapter encodes it. */
+export interface Wire {
+  /** The stream is open; `detail` is "address:port" dialled. The adapter grants the first upload window (engine.takeUp / engine.owe). */
+  connected(s: Session, st: Stream, detail: string): void
+  /** The connect failed or was refused before the stream opened. */
+  refused(s: Session, id: number, code: number, why: string): void
+  data(s: Session, st: Stream, bytes: Uint8Array): void
+  /** The remote closed cleanly (FIN) and every byte was sent. */
+  end(s: Session, st: Stream): void
+  /** The stream failed after it opened: never a clean end. */
+  abort(s: Session, st: Stream, code: number, why: string): void
+  /** Upload credit: `n` more bytes of the stream may come (out of the up bucket). */
+  grant(s: Session, st: Stream, n: number): void
+  dnsReply(s: Session, id: number, rcode: number, ttl: number, addrs: Uint8Array[], why: string): void
+  /** The stream is done both ways (after end() and the client's end). Optional. */
+  done?(s: Session, st: Stream): void
+}
+
+export type Session = {
+  ws: any
+  sid: string
+  p: Principal
+  wire: Wire
+  streams: Map<number, Stream>
+  bytes: number // this session's bytes (for the log)
+  pumpTimer: ReturnType<typeof setTimeout> | null
+  closed: boolean
+  expTimer: ReturnType<typeof setTimeout> | null
+  grantQueued?: boolean
+  /** The download credit a new stream starts with (v1: WINDOW; Wisp without 0xE1: Infinity). */
+  window: number
+  w?: any // adapter state for the session
+  hx?: any // the hosted governor's admission for this session
+  allow?: AllowEntry[] // replaces the relay's allowlist for this session (an owner key's)
+}
+
+export type AllowEntry = { name: string; ports: Set<number> }
+
+/** Allowlist entries: name[:port|port...]; no ports: 80 and 443; a leading "." matches subdomains. */
+export function compileAllow(list: string[] | undefined): AllowEntry[] {
+  return (list || []).map(h => h.toLowerCase().trim()).filter(Boolean).map(h => {
+    const i = h.indexOf(':')
+    const name = i < 0 ? h : h.slice(0, i)
+    const ports = i < 0 ? [80, 443] : h.slice(i + 1).split('|').map(Number).filter(n => n > 0 && n < 65536)
+    return { name, ports: new Set(ports) }
+  })
+}
+
+/** Bandwidth buckets shared by several identities (Wisp: one client address, or one owner key). */
+export type Shared = { down: Bucket; up: Bucket }
+export const newShared = (o: { rateDown?: number; rateUp?: number }): Shared => ({ down: new Bucket(o.rateDown ?? 16 << 20), up: new Bucket(o.rateUp ?? 4 << 20) })
+
+export type Admission = { ok: true; p: Principal } | { ok: false; status: number; body: string }
+
+const ERR_CODE: Record<string, number> = {
+  ECONNREFUSED: E.REFUSED, ETIMEDOUT: E.TIMEOUT, ECONNRESET: E.RESET, EPIPE: E.RESET,
+  EHOSTUNREACH: E.UNREACHABLE, ENETUNREACH: E.UNREACHABLE, EADDRNOTAVAIL: E.UNREACHABLE,
+}
+
+export const codeName = (code: number) => Object.keys(E).find(k => (E as any)[k] === code)?.toLowerCase()
+
+export type Engine = ReturnType<typeof createEngine>
+
+export function createEngine(o: EngineOptions) {
+  const log = o.log || (() => {})
+  const maxConns = o.maxConns ?? 64
+  const maxSessions = o.maxSessions ?? 100
+  const maxBytes = o.maxBytes ?? 4 * 2 ** 30
+  const blockedPorts = new Set(o.blockedPorts ?? [25])
+  const allowPorts = o.allowPorts?.length ? new Set(o.allowPorts) : null
+  const guard = o.guard
+  const relStream = (st: Stream) => {
+    const r = st.rel
+    st.rel = undefined
+    r?.()
+  }
+  const connectTimeoutMs = o.connectTimeoutMs ?? 10_000
+  // allowlist entries: name[:port|port...]; no ports: 80 and 443
+  const allow = compileAllow(o.allowHosts)
+  const maxPerGroup = o.maxSessionsPerGroup ?? 8
+  const testRoutes: Record<string, string> = Object.assign(Object.create(null), o.testRoutes) // no prototype keys ("constructor", "__proto__")
+  const testHosts: Record<string, string> = Object.assign(Object.create(null), o.testHosts)
+  let self = hostAddresses(o.selfAddrs)
+  const loopPorts = new Set(o.allowLoopbackPorts ?? [])
+  const isLoop = (a: Addr) => (a.v === 4 ? a.b[0] === 127 : a.b.every((x, i) => x === (i === 15 ? 1 : 0)))
+  /** blockedReason with the owner's exceptions; `port` undefined is a lookup (the port is checked at the connect). */
+  function whyBlocked(a: Addr, port?: number): string | null {
+    const extra = o.guard?.blockedAddr(a)
+    if (extra) return extra
+    const why = blockedReason(a, self)
+    if (!why) return null
+    if (o.allowLan && why === 'private' && isLanRange(a)) return null
+    if (loopPorts.size && isLoop(a) && (why === 'loopback' || why === 'self')) {
+      if (port === undefined) return null
+      if (port === o.ownPort?.() || o.alsoOwnPorts?.().includes(port)) return `${why} (the relay's own port)`
+      if (loopPorts.has(port)) return null
+      return `${why} (port ${port} is not in allowLoopbackPorts)`
+    }
+    return why
+  }
+  const selfTimer = setInterval(() => (self = hostAddresses(o.selfAddrs)), 30_000)
+  const sessions = new Map<string, Session>() // by sid
+  const principals = new Map<string, Principal>() // by uid
+  const groupLive = new Map<string, number>()
+  // a principal's state lives as long as a token for it can: dropped after its latest expiry
+  const pruneTimer = setInterval(() => {
+    const t = Date.now()
+    for (const [uid, p] of principals) {
+      if (!p.live && p.exp + PRINCIPAL_FLOOR_MS < t) principals.delete(uid)
+      else for (const [k, exp] of p.pins) if (exp < t) p.pins.delete(k)
+    }
+  }, 60_000)
+  function principal(uid: string, grp: string, exp: number, share?: Shared): Principal {
+    let p = principals.get(uid)
+    if (p) {
+      principals.delete(uid) // re-inserted: the map is least recently admitted first
+      principals.set(uid, p)
+    } else {
+      p = {
+        uid, grp, connects: new Window(o.connectsPerMin ?? 600, 60_000), dnsHits: new Window(o.dnsPerMin ?? 1200, 60_000),
+        opens: new Window(o.opensPerMin ?? 30, 60_000), down: share?.down ?? new Bucket(o.rateDown ?? 16 << 20), up: share?.up ?? new Bucket(o.rateUp ?? 4 << 20),
+        bytes: 0, exp, live: null, pins: new Map(), overBytes: false,
+      }
+      principals.set(uid, p)
+    }
+    p.exp = Math.max(p.exp, exp)
+    return p
+  }
+  const stats = { sessions: 0, refusedSessions: 0, connects: 0, refused: {} as Record<string, number>, dns: 0, bytesDown: 0, bytesUp: 0 }
+
+  let resolve4: ResolveFn = o.resolve4 as ResolveFn
+  if (!resolve4) {
+    const r = new Resolver({ timeout: o.dnsTimeoutMs ?? 3000, tries: 2 })
+    if (o.dnsServers?.length) r.setServers(o.dnsServers)
+    resolve4 = name =>
+      new Promise((res, rej) => r.resolve4(name, { ttl: true }, (err, addrs) => (err ? rej(err) : res(addrs as { address: string; ttl: number }[]))))
+  }
+  const dial: DialFn = o.dial || ((host, port) => netConnect({ host, port, allowHalfOpen: true, noDelay: true } as any))
+
+  // a session may carry its own allowlist (an owner key's), which replaces the relay's
+  const listFor = (s: Session) => s.allow ?? allow
+  const entryFor = (A: AllowEntry[], name: string) =>
+    A.find(a => (a.name.startsWith('.') ? name.endsWith(a.name) || name === a.name.slice(1) : name === a.name))
+  const allowed = (A: AllowEntry[], name: string) => !A.length || !!entryFor(A, name)
+
+  function refuse(s: Session, id: number, code: number, why: string, to: string) {
+    const name = codeName(code)!
+    stats.refused[name] = (stats.refused[name] || 0) + 1
+    log({ ev: 'refused', sid: s.sid, id, to, code: name, why })
+    if (!s.closed) s.wire.refused(s, id, code, why)
+  }
+
+  /** The address to dial for a name: resolved here, filtered by the policy. */
+  async function resolveChecked(s: Session, name: string, port?: number): Promise<{ addrs: { a: Addr; ttl: number }[]; rcode: number; why: string; code: number }> {
+    const n = name.toLowerCase().replace(/\.$/, '')
+    const A = listFor(s)
+    const bad = badName(n)
+    if (bad) return { addrs: [], rcode: RCODE.REFUSED, why: `name refused: ${bad}`, code: E.BAD }
+    if (testHosts[n]) return { addrs: [{ a: parseIP(testHosts[n])!, ttl: 60 }], rcode: RCODE.NOERROR, why: '', code: E.OK } // test only
+    if (!allowed(A, n)) return { addrs: [], rcode: RCODE.REFUSED, why: 'name not on the allowlist', code: E.NOT_ALLOWED }
+    let list: { address: string; ttl: number }[]
+    {
+      try {
+        list = await resolve4(n)
+      } catch (e: any) {
+        const code = e?.code || ''
+        if (code === 'ENOTFOUND' || code === 'ENODATA' || code === 'NXDOMAIN') return { addrs: [], rcode: code === 'ENODATA' ? RCODE.NOERROR : RCODE.NXDOMAIN, why: code, code: E.DNS }
+        return { addrs: [], rcode: RCODE.SERVFAIL, why: `resolver: ${code || e?.message}`, code: E.DNS }
+      }
+    }
+    const out: { a: Addr; ttl: number }[] = []
+    const blocked: string[] = []
+    for (const x of list) {
+      const a = parseIP(x.address)
+      if (!a || a.v !== 4) continue
+      const why = whyBlocked(a, port)
+      if (why) blocked.push(`${x.address} (${why})`)
+      else out.push({ a, ttl: x.ttl })
+    }
+    if (!out.length && blocked.length) return { addrs: [], rcode: RCODE.REFUSED, why: `resolves only to refused addresses: ${blocked.join(', ')}`, code: E.BLOCKED }
+    if (A.length) {
+      const ports = entryFor(A, n)!.ports
+      const exp = Date.now() + Math.max(maxTtl(out), 300) * 1000
+      for (const x of out) for (const port of ports) s.p.pins.set(`${addrKey(x.a)}:${port}`, exp)
+    }
+    return { addrs: out, rcode: RCODE.NOERROR, why: blocked.length ? `refused: ${blocked.join(', ')}` : '', code: out.length ? E.OK : E.DNS }
+  }
+
+  function maxTtl(out: { ttl: number }[]) {
+    return out.reduce((m, x) => Math.max(m, x.ttl), 0)
+  }
+
+  async function dns(s: Session, id: number, name: string, qtype: number) {
+    stats.dns++
+    if (!s.p.dnsHits.hit()) return s.wire.dnsReply(s, id, RCODE.REFUSED, 0, [], 'dns rate limit')
+    const closed = guard?.dnsClosed?.()
+    if (closed) return s.wire.dnsReply(s, id, RCODE.REFUSED, 0, [], closed)
+    if (guard && !guard.dnsAllowed(s)) return s.wire.dnsReply(s, id, RCODE.REFUSED, 0, [], 'dns rate limit for this address')
+    if (qtype !== 1) return s.wire.dnsReply(s, id, RCODE.NOERROR, 60, [], 'only A')
+    let r: Awaited<ReturnType<typeof resolveChecked>>
+    try {
+      r = await resolveChecked(s, name)
+    } catch (e: any) {
+      log({ ev: 'error', sid: s.sid, error: String(e) })
+      return s.wire.dnsReply(s, id, RCODE.SERVFAIL, 0, [], 'lookup failed')
+    }
+    if (r.rcode !== RCODE.NOERROR || r.why) log({ ev: 'dns', sid: s.sid, name, rcode: r.rcode, why: r.why })
+    const ttl = r.addrs.length ? Math.min(...r.addrs.map(x => x.ttl)) : 30
+    if (!s.closed) s.wire.dnsReply(s, id, r.rcode, ttl, r.addrs.slice(0, 16).map(x => x.a.b), r.why)
+  }
+
+  async function connect(s: Session, id: number, host: string, port: number) {
+    const to = `${host}:${port}`
+    const A = listFor(s)
+    if (s.streams.has(id)) return refuse(s, id, E.BAD, 'stream id in use', to)
+    if (!port) return refuse(s, id, E.BAD, 'port 0', to)
+    if (blockedPorts.has(port)) return refuse(s, id, E.PORT, `port ${port} is blocked`, to)
+    if (allowPorts && !allowPorts.has(port)) return refuse(s, id, E.PORT, `port ${port} is not allowed on this relay`, to)
+    if (s.streams.size >= maxConns) return refuse(s, id, E.LIMIT, `more than ${maxConns} connections at once`, to)
+    if (!s.p.connects.hit()) return refuse(s, id, E.LIMIT, 'connect rate limit', to)
+    if (guard?.isDeniedDest(host, port)) return refuse(s, id, E.BLOCKED, 'this destination is blocked by the operator', to)
+    const held = guard?.admitConnect(s, host, port)
+    if (held) return refuse(s, id, E.LIMIT, held, to)
+    const st: Stream = {
+      id, sock: null, connected: false, clientCredit: s.window, ourGrant: 0, outQ: [], outBytes: 0, remoteEnded: false, endSent: false,
+      clientEnded: false, closed: false, to, bytesDown: 0, bytesUp: 0, openedAt: performance.now(),
+    }
+    s.streams.set(id, st) // reserve the id while resolving
+    let addr = parseIP(host)
+    let dialHost: string
+    let dialPort = port
+    if (addr) {
+      const key = addrKey(addr)
+      const route = testRoutes[`${key}:${port}`]
+      const why = route ? null : whyBlocked(addr, port)
+      if (why) {
+        s.streams.delete(id)
+        return refuse(s, id, E.BLOCKED, `${key} is ${why}`, to)
+      }
+      if (A.length && !route) {
+        const exp = s.p.pins.get(`${key}:${port}`)
+        if (!exp || exp < Date.now()) {
+          s.streams.delete(id)
+          return refuse(s, id, E.NOT_ALLOWED, `${key}:${port} was not resolved from an allowed name (for this port) by this guest`, to)
+        }
+      }
+      if (route) {
+        const i = route.lastIndexOf(':')
+        dialHost = route.slice(0, i)
+        dialPort = Number(route.slice(i + 1))
+      } else dialHost = addrString(addr)
+    } else {
+      let r: Awaited<ReturnType<typeof resolveChecked>>
+      try {
+        r = await resolveChecked(s, host, port)
+      } catch (e: any) {
+        // whatever fails, the stream id is freed and the guest gets an answer
+        if (!st.closed && !s.closed) {
+          s.streams.delete(id)
+          log({ ev: 'error', sid: s.sid, error: String(e) })
+          refuse(s, id, E.DNS, 'lookup failed', to)
+        }
+        return
+      }
+      if (st.closed || s.closed) return
+      if (r.addrs.length && A.length && !testHosts[host.toLowerCase().replace(/\.$/, '')] && !entryFor(A, host.toLowerCase().replace(/\.$/, ''))?.ports.has(port)) {
+        s.streams.delete(id)
+        return refuse(s, id, E.NOT_ALLOWED, `port ${port} is not allowed for ${host}`, to)
+      }
+      if (!r.addrs.length) {
+        s.streams.delete(id)
+        if (r.code === E.DNS) guard?.dialFailed(s)
+        return refuse(s, id, r.code || E.DNS, r.why || 'no address', to)
+      }
+      addr = r.addrs[0].a
+      const route = testRoutes[`${addrKey(addr)}:${port}`]
+      if (route) {
+        const i = route.lastIndexOf(':')
+        dialHost = route.slice(0, i)
+        dialPort = Number(route.slice(i + 1))
+      } else dialHost = addrString(addr) // exactly the address that was checked: no second lookup
+    }
+    if (st.closed || s.closed) return
+    const full = guard?.openStream(s, st, host, port)
+    if (full) {
+      s.streams.delete(id)
+      return refuse(s, id, E.LIMIT, full, to)
+    }
+    stats.connects++
+    let sock: Socket
+    try {
+      sock = dial(dialHost, dialPort)
+    } catch (e: any) {
+      relStream(st)
+      guard?.dialFailed(s)
+      s.streams.delete(id)
+      return refuse(s, id, E.UNREACHABLE, e?.message || 'dial failed', to)
+    }
+    st.sock = sock
+    const timer = setTimeout(() => {
+      if (!st.connected) {
+        sock.destroy()
+        fail(s, st, E.TIMEOUT, `no connection in ${connectTimeoutMs} ms`)
+      }
+    }, connectTimeoutMs)
+    sock.on('connect', () => {
+      clearTimeout(timer)
+      if (st.closed) return sock.destroy()
+      st.connected = true
+      log({ ev: 'connect', sid: s.sid, id, to, via: `${dialHost}:${dialPort}`, ms: Math.round(performance.now() - st.openedAt) })
+      if (!s.closed) s.wire.connected(s, st, `${addrKey(addr!)}:${port}`)
+    })
+    sock.on('data', (b: Buffer) => {
+      if (st.closed) return
+      st.outQ.push(b)
+      st.outBytes += b.length
+      pump(s, st)
+    })
+    sock.on('end', () => {
+      st.remoteEnded = true
+      pump(s, st)
+    })
+    sock.on('error', (e: any) => {
+      clearTimeout(timer)
+      fail(s, st, ERR_CODE[e?.code] ?? (st.connected ? E.RESET : E.UNREACHABLE), e?.code || e?.message || 'socket error')
+    })
+    sock.on('close', () => {
+      clearTimeout(timer)
+      if (st.closed) return
+      // closed without an error: clean only if the remote's FIN came and everything was sent
+      if (!st.connected) return fail(s, st, E.UNREACHABLE, 'closed before connecting')
+      if (st.remoteEnded) {
+        st.sock = null
+        pump(s, st)
+        return
+      }
+      fail(s, st, E.RESET, 'closed')
+    })
+  }
+
+  /** connect(), with any failure before the dial answered as a refusal (the stream id is freed). */
+  function connectSafe(s: Session, id: number, host: string, port: number) {
+    connect(s, id, host, port).catch(e => {
+      log({ ev: 'error', sid: s.sid, error: String(e) })
+      const st = s.streams.get(id) // a failure before the dial: free the id and answer
+      if (st && !st.sock && !st.connected && !st.closed) {
+        s.streams.delete(id)
+        refuse(s, id, E.UNREACHABLE, 'connect failed', `${host}:${port}`)
+      }
+    })
+  }
+
+  /** Send the remote's bytes as credit, bandwidth and the WebSocket allow; end() after the last. */
+  function pump(s: Session, st: Stream) {
+    if (st.closed || s.closed) return
+    while (st.outBytes > 0 && st.clientCredit > 0) {
+      if (s.ws.getBufferedAmount?.() > 8 << 20) break // the drain handler pumps again
+      const want = Math.min(st.outBytes, st.clientCredit, MAX_DATA)
+      let n = s.p.down.take(want)
+      if (!n) {
+        schedulePump(s, s.p.down.waitMs(want))
+        break
+      }
+      if (guard) {
+        const k = guard.take(s, 'down', n)
+        if (k < n) s.p.down.tokens = Math.min(s.p.down.rate, s.p.down.tokens + n - k)
+        n = k
+        if (!n) {
+          schedulePump(s, guard.waitMs(s, 'down', want))
+          break
+        }
+      }
+      const out = Buffer.allocUnsafe(n)
+      let o = 0
+      while (o < n) {
+        const h = st.outQ[0]
+        const k = Math.min(h.length, n - o)
+        h.copy(out, o, 0, k)
+        o += k
+        if (k === h.length) st.outQ.shift()
+        else st.outQ[0] = h.subarray(k)
+      }
+      st.outBytes -= n
+      st.clientCredit -= n
+      st.bytesDown += n
+      stats.bytesDown += n
+      s.bytes += n
+      s.p.bytes += n
+      s.wire.data(s, st, out)
+      if (overBytes(s) || overHour(s, n)) return
+    }
+    if (st.sock) {
+      if (st.outBytes > 0) st.sock.pause()
+      else if (!st.remoteEnded) st.sock.resume()
+    }
+    if (st.remoteEnded && st.outBytes === 0 && !st.endSent) {
+      st.endSent = true
+      s.wire.end(s, st)
+      maybeDone(s, st)
+    }
+  }
+
+  function pumpAll(s: Session) {
+    for (const st of s.streams.values()) pump(s, st)
+  }
+
+  function schedulePump(s: Session, ms: number) {
+    if (s.pumpTimer) return
+    s.pumpTimer = setTimeout(() => {
+      s.pumpTimer = null
+      for (const st of s.streams.values()) pump(s, st)
+      grantPending(s)
+    }, ms)
+  }
+
+  /** The hosted profile's per-hour bytes for the session's address group: past them the session's streams end. */
+  function overHour(s: Session, n: number): boolean {
+    if (!guard || guard.bytes(s, n)) return false
+    const why = guard.limitWhy?.() ?? 'this address has used its bytes for this hour'
+    log({ ev: 'limit', sid: s.sid, why })
+    for (const st of [...s.streams.values()]) fail(s, st, E.LIMIT, why)
+    return true
+  }
+
+  function overBytes(s: Session): boolean {
+    if (s.p.bytes <= maxBytes) return false
+    s.p.overBytes = true // the identity stays over its cap: later sessions are refused
+    log({ ev: 'limit', sid: s.sid, why: 'session byte limit' })
+    for (const st of [...s.streams.values()]) fail(s, st, E.LIMIT, 'session byte limit')
+    s.ws.close(4008, 'session byte limit')
+    return true
+  }
+
+  // upload credit waiting for bandwidth
+  const owed = new Map<Session, Map<number, number>>()
+  function owe(s: Session, id: number, n: number, now = true) {
+    let m = owed.get(s)
+    if (!m) owed.set(s, (m = new Map()))
+    m.set(id, (m.get(id) || 0) + n)
+    if (now) grantPending(s)
+  }
+
+  function grantPending(s: Session) {
+    const m = owed.get(s)
+    if (!m) return
+    for (const [id, n] of m) {
+      const st = s.streams.get(id)
+      if (!st || st.closed) {
+        m.delete(id)
+        continue
+      }
+      let k = s.p.up.take(n)
+      if (k && guard) {
+        const g = guard.take(s, 'up', k)
+        if (g < k) s.p.up.tokens = Math.min(s.p.up.rate, s.p.up.tokens + k - g)
+        k = g
+      }
+      if (k) s.wire.grant(s, st, k)
+      if (k === n) m.delete(id)
+      else {
+        m.set(id, n - k)
+        schedulePump(s, Math.max(s.p.up.waitMs(n - k), guard ? guard.waitMs(s, 'up', n - k) : 1))
+      }
+    }
+  }
+
+  /** Upload bytes for a connected stream (the adapter has checked its flow-control unit). */
+  function write(s: Session, st: Stream, data: Uint8Array) {
+    st.bytesUp += data.length
+    stats.bytesUp += data.length
+    s.bytes += data.length
+    s.p.bytes += data.length
+    if (overBytes(s) || overHour(s, data.length)) return
+    const n = data.length
+    st.sock!.write(Buffer.from(data.buffer, data.byteOffset, data.byteLength), () => {
+      if (st.closed) return
+      owe(s, st.id, n, false)
+      // one grant per stream for all the writes that finished in this turn, not one per write
+      if (!s.grantQueued) {
+        s.grantQueued = true
+        setImmediate(() => {
+          s.grantQueued = false
+          grantPending(s)
+        })
+      }
+    })
+  }
+
+  function fail(s: Session, st: Stream, code: number, why: string) {
+    if (st.closed) return
+    st.closed = true
+    relStream(st)
+    s.streams.delete(st.id)
+    st.sock?.destroy()
+    if (!st.connected && guard && (code === E.REFUSED || code === E.UNREACHABLE || code === E.TIMEOUT)) guard.dialFailed(s)
+    if (!st.connected) return refuse(s, st.id, code, why, st.to)
+    log({ ev: 'abort', sid: s.sid, id: st.id, to: st.to, code: codeName(code), why, down: st.bytesDown, up: st.bytesUp })
+    if (!s.closed) s.wire.abort(s, st, code, why)
+  }
+
+  function maybeDone(s: Session, st: Stream) {
+    if (st.endSent && st.clientEnded && !st.closed) {
+      st.closed = true
+      relStream(st)
+      s.streams.delete(st.id)
+      st.sock?.end()
+      log({ ev: 'done', sid: s.sid, id: st.id, to: st.to, down: st.bytesDown, up: st.bytesUp })
+      s.wire.done?.(s, st)
+    }
+  }
+
+  /** The client half-closed the stream (the guest sent FIN). */
+  function clientEnd(s: Session, id: number) {
+    const st = s.streams.get(id)
+    if (st && st.connected && !st.clientEnded) {
+      st.clientEnded = true
+      st.sock?.end()
+      maybeDone(s, st)
+    }
+  }
+
+  /** The client reset the stream. */
+  function clientAbort(s: Session, id: number) {
+    const st = s.streams.get(id)
+    if (st) {
+      st.closed = true
+      relStream(st)
+      s.streams.delete(id)
+      st.sock?.destroy()
+      log({ ev: 'client-abort', sid: s.sid, id, to: st.to, down: st.bytesDown, up: st.bytesUp })
+    }
+  }
+
+  /** The client may take n more download bytes on the stream. */
+  function credit(s: Session, id: number, n: number) {
+    const st = s.streams.get(id)
+    if (st) {
+      st.clientCredit = Math.min(st.clientCredit + n, 0xffffffff)
+      pump(s, st)
+    }
+  }
+
+  /**
+   * Session admission for an identity, after the adapter's own checks (origin, auth). Counts the
+   * open against the identity's rate. On success the caller upgrades and then calls open().
+   */
+  function admit(uid: string, grp: string, exp: number, extra: Record<string, unknown> = {}, share?: Shared): Admission {
+    const known = principals.get(uid)
+    const replaces = !!known?.live
+    if (sessions.size >= maxSessions && !replaces) {
+      stats.refusedSessions++
+      return { ok: false, status: 503, body: 'too many sessions\n' }
+    }
+    if ((groupLive.get(grp) || 0) >= maxPerGroup && !replaces) {
+      stats.refusedSessions++
+      log({ ev: 'session-refused', why: 'group session limit', grp, ...extra })
+      return { ok: false, status: 429, body: `more than ${maxPerGroup} sessions for this client\n` }
+    }
+    const p = principal(uid, grp, exp, share)
+    if (p.overBytes) {
+      stats.refusedSessions++
+      return { ok: false, status: 429, body: 'byte limit reached for this guest\n' }
+    }
+    if (!p.opens.hit()) {
+      stats.refusedSessions++
+      log({ ev: 'session-refused', why: 'open rate limit', uid, ...extra })
+      return { ok: false, status: 429, body: 'too many connections for this guest; wait\n' }
+    }
+    return { ok: true, p }
+  }
+
+  function refusedSession(why: string, fields: Record<string, unknown> = {}) {
+    stats.refusedSessions++
+    if (why) log({ ev: 'session-refused', why, ...fields })
+  }
+
+  /** A WebSocket opened for an admitted identity. Returns null when the sid is already live. */
+  function open(ws: any, sid: string, p: Principal, exp: number, wire: Wire, window: number, logFields: Record<string, unknown> = {}): Session | null {
+    if (sessions.has(sid)) {
+      ws.close(4009, 'session already connected')
+      return null
+    }
+    // one live session per guest identity: a newer one (a reconnect the old side has not noticed) replaces it
+    if (p.live) {
+      const old = p.live
+      old.ws.close(4010, 'replaced by a newer session of this guest')
+      closeSession(old, 'replaced by a newer session')
+    }
+    const s: Session = { ws, sid, p, wire, streams: new Map(), bytes: 0, pumpTimer: null, closed: false, expTimer: null, window }
+    p.live = s
+    groupLive.set(p.grp, (groupLive.get(p.grp) || 0) + 1)
+    if (Number.isFinite(exp)) s.expTimer = setTimeout(() => ws.close(4001, 'token expired'), Math.max(0, exp - Date.now()))
+    sessions.set(sid, s)
+    stats.sessions++
+    log({ ev: 'session', sid, uid: p.uid, grp: p.grp, ...logFields })
+    return s
+  }
+
+  function closeSession(s: Session, why: string) {
+    if (s.closed) return
+    s.closed = true
+    if (s.pumpTimer) clearTimeout(s.pumpTimer)
+    if (s.expTimer) clearTimeout(s.expTimer)
+    for (const st of s.streams.values()) {
+      st.closed = true
+      relStream(st)
+      st.sock?.destroy()
+    }
+    s.streams.clear()
+    owed.delete(s)
+    if (sessions.get(s.sid) === s) sessions.delete(s.sid)
+    if (s.p.live === s) s.p.live = null
+    const g = (groupLive.get(s.p.grp) || 1) - 1
+    if (g > 0) groupLive.set(s.p.grp, g)
+    else groupLive.delete(s.p.grp)
+    log({ ev: 'session-end', sid: s.sid, why, bytes: s.bytes })
+  }
+
+  function limits(p: Principal, A: AllowEntry[] = allow) {
+    return {
+      maxConns, window: WINDOW, rateDown: p.down.rate, rateUp: p.up.rate, bytesLeft: Math.max(0, maxBytes - p.bytes),
+      allowHosts: A.length ? A.map(a => `${a.name}:${[...a.ports].join('|')}`) : null,
+    }
+  }
+
+  return {
+    log, stats, sessions, principals,
+    hasSession: (sid: string) => sessions.has(sid),
+    admit, refusedSession, open, closeSession, limits,
+    connect, connectSafe, refuse, dns, write, credit, clientEnd, clientAbort, fail, owe, pump, pumpAll, grantPending,
+    stop() {
+      clearInterval(selfTimer)
+      clearInterval(pruneTimer)
+      for (const s of sessions.values()) closeSession(s, 'relay stopping')
+    },
+  }
+}