@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/relay/wisp.ts

@@ -0,0 +1,615 @@
+// W59: the Wisp v2 adapter (src/net/wisp.js, docs/wisp-wmd-extensions.md) over the relay engine.
+//
+// Who may use it (plan §5):
+//   - token: the HMAC `t.<token>` subprotocol, as wmd-relay.v1 (wmn's bundled relay)
+//   - open: no key (the standalone relay's default); identity = the client's instance id (0xE7)
+//     plus its address group, bandwidth shared per address
+//   - keys (optional): Wisp password auth, scrypt hashes; a relay with keys refuses keyless clients
+// Pre-auth limits: sockets in their handshake per address, a handshake deadline, failed keys
+// throttled per address.
+//
+// Flow control: upload is Wisp's CONTINUE (packets), released as the bytes reach the remote and
+// the up bucket allows (so the bucket delays CONTINUE); download is wmd-credit (0xE1) bytes when
+// the client lists it, otherwise WebSocket backpressure only.
+
+import { randomBytes } from 'node:crypto'
+import { E } from '../src/net/proto.js'
+import {
+  CLOSE, EXT, PT, STREAM, SUBPROTOCOL, ServerHandshake, answerPacket, closePacket, closeWords, continuePacket,
+  dataPacket, ext, parse, shutdownPacket,
+} from '../src/net/wisp.js'
+import { type AllowEntry, type Engine, type Principal, type Session, type Shared, type Stream, Window, type Wire, compileAllow, newShared } from './engine.ts'
+import { type Governor, resolveClient } from './hosted.ts'
+import { type OwnerKey, verifySecret } from './keys.ts'
+import type { Cidr } from './policy.ts'
+import { clientKey, verifyToken } from './token.ts'
+
+export type WispOptions = {
+  enabled?: boolean
+  path?: string // URL prefix, ends with "/" (default "/wisp/")
+  open?: boolean // serve clients that bring no token and no key (the standalone default)
+  keys?: OwnerKey[] // when set, a client needs one of them (or a token)
+  prefixKeys?: boolean // Wisp v1 clients may put a key in the URL: /wisp/<id>.<secret>/
+  origins?: string[] // page origins allowed (default: any); a request without Origin is refused when set
+  checkHost?: boolean // the Host header must be a loopback name with the port (a loopback bind, open mode)
+  trustProxy?: boolean // caps per X-Forwarded-For client (the last entry, added by the trusted proxy)
+  proxy?: { trusted: Cidr[]; header: string } // hosted: only these peers are proxies; the header is walked from the right (hosted.ts resolveClient)
+  hosted?: Governor // the hosted profile's limits, lists and state (plan §15)
+  buffer?: number // CONTINUE: packets buffered per stream (32)
+  maxPayload?: number // largest WebSocket frame (1 MiB + 1 KiB)
+  maxHeldBytes?: number // upload bytes held per stream before CONTINUE is withheld (4 MiB). Never a close by itself: a client
+  //                       that keeps the packet rule may hold 2 x buffer packets of up to maxPayload each (the session cap bounds that)
+  maxSessionHeldBytes?: number // upload bytes held for one session, all streams (default: 2 x buffer x maxPayload, at least 64 MiB,
+  //                              so one stream that keeps the packet rule never reaches it); past it the stream that sent more gets 0x49
+  maxHeldTotal?: number // upload bytes held by the whole relay (512 MiB); past it, DATA from a group over its fair share gets 0x49
+  maxGroupHeldBytes?: number // upload bytes held by one address group or key, all its sessions (2 x the session cap)
+  instancesPerHour?: number // new identities per address (or key) an hour (120)
+  maxPrincipals?: number // identities remembered (10000)
+  preAuthPerAddr?: number // sockets in their handshake per address (8)
+  handshakeMs?: number // (10000)
+  streamIdleMs?: number // a stream with no bytes either way this long is closed, 0x47 (30 min)
+  version?: string // the relay's version, in the MOTD
+}
+
+type Mode = 'token' | 'open' | 'key' | 'key-pending'
+
+const REASON: Record<number, number> = {
+  [E.BLOCKED]: CLOSE.BLOCKED, [E.NOT_ALLOWED]: CLOSE.BLOCKED, [E.PORT]: CLOSE.BLOCKED, [E.REFUSED]: CLOSE.REFUSED,
+  [E.TIMEOUT]: CLOSE.TIMEOUT, [E.DNS]: CLOSE.UNREACHABLE, [E.UNREACHABLE]: CLOSE.UNREACHABLE, [E.LIMIT]: CLOSE.THROTTLED,
+  [E.BAD]: CLOSE.INVALID, [E.RESET]: CLOSE.NETWORK, [E.GONE]: CLOSE.NETWORK,
+}
+const reasonFor = (code: number) => REASON[code] ?? CLOSE.UNKNOWN
+
+export const DRAIN_WORDS = 'the relay is closed for maintenance'
+const LOOPBACK_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i
+// a key id that does not exist is still checked against this, so the time does not tell
+const DUMMY_HASH = 'scrypt:16384:8:1:AAAAAAAAAAAAAAAAAAAAAA:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
+
+type StreamW = {
+  pending: Uint8Array[] | null // DATA that came before the remote connected
+  sizes: number[] // sizes of packets written to the remote, not yet released
+  released: number // bytes released by the engine, not yet a whole packet
+  held: number // packets received and not yet released
+  heldBytes: number
+  drained: number // packets released since the last CONTINUE
+  last: number // the last time a byte moved either way
+  idle: boolean
+  shutPending: boolean // SHUTDOWN before the remote connected
+}
+
+type SessionW = {
+  engine: Engine
+  v2: boolean
+  confirm: boolean
+  credit: boolean
+  halfclose: boolean
+  dns: boolean
+  buffer: number
+  idleTimer: ReturnType<typeof setInterval> | null
+  unknownLogged: boolean
+}
+
+export function createWisp(engine: Engine, o: { secret?: string; port: () => number; maxConns?: number; rateDown?: number; rateUp?: number; blockedPorts?: number[]; wisp: WispOptions }) {
+  const w = o.wisp
+  const path = w.path ?? '/wisp/'
+  const keys = w.keys ?? []
+  const open = !!w.open && !keys.length
+  const buffer = w.buffer ?? 32
+  const maxPayload = w.maxPayload ?? (1 << 20) + 1024
+  const maxHeld = w.maxHeldBytes ?? 4 << 20
+  const maxSessHeld = w.maxSessionHeldBytes ?? Math.max(64 << 20, 2 * buffer * maxPayload)
+  const maxGroupHeld = w.maxGroupHeldBytes ?? 2 * maxSessHeld
+  const maxHeldAll = w.maxHeldTotal ?? 512 << 20
+  // The relay's and each group's held bytes at the last count, plus what came since (they decrease only at the next
+  // count, so they never go negative and only overestimate). When the relay is over its total, only a group holding
+  // more than its fair share (the total over the groups holding bytes) is refused: one party cannot fill the relay
+  // and break everyone else's uploads.
+  let heldSwept = 0
+  let groupHeld = new Map<string, number>()
+  const heldCount = setInterval(() => {
+    let n = 0
+    const g = new Map<string, number>()
+    for (const s of engine.sessions.values()) {
+      let k = 0
+      for (const st of s.streams.values()) k += st.w?.heldBytes || 0
+      if (k) g.set(s.p.grp, (g.get(s.p.grp) || 0) + k)
+      n += k
+    }
+    heldSwept = n
+    groupHeld = g
+  }, 1000)
+  const handshakeMs = w.handshakeMs ?? 10_000
+  const streamIdleMs = w.streamIdleMs ?? 30 * 60_000
+  const preAuth = w.preAuthPerAddr ?? 8
+  const maxPrincipals = w.maxPrincipals ?? 10_000
+  const instancesPerHour = w.instancesPerHour ?? 120
+  const inHandshake = new Map<string, number>()
+  const failed = new Map<string, { fails: number; until: number; at: number }>()
+  const newIds = new Map<string, Window>() // per address or key: new identities this hour
+  const shared = new Map<string, Shared>() // per address or key: bandwidth
+  const sweep = setInterval(() => {
+    const t = Date.now()
+    for (const [k, f] of failed) if (Math.max(f.until, f.at) + 10 * 60_000 < t) failed.delete(k)
+    for (const [k, win] of newIds) if (!win.times.length || performance.now() - win.times[win.times.length - 1] > win.ms) newIds.delete(k)
+    const groups = new Set<string>()
+    for (const p of engine.principals.values()) groups.add(p.grp)
+    for (const k of shared.keys()) if (!groups.has(k)) shared.delete(k)
+  }, 60_000)
+  const log = engine.log
+  const stats = engine.stats
+
+  const motd = () =>
+    w.hosted
+      ? `wmd hosted relay${w.version ? ` ${w.version}` : ''}: the operator sees destination names, DNS names and plain-http content (TLS traffic is not visible); ` +
+        `abuse contact ${w.hosted.contact}; ${w.hosted.limitsLine()}; blocked ports: ${(o.blockedPorts ?? [25]).join(', ') || 'none'}`
+      :
+    `wmd-relay${w.version ? ` ${w.version}` : ''}: up to ${o.maxConns ?? 64} streams per guest; ${o.rateDown ?? 16 << 20} B/s down and ` +
+    `${o.rateUp ?? 4 << 20} B/s up; blocked ports: ${(o.blockedPorts ?? [25]).join(', ') || 'none'}; private, loopback and metadata addresses are refused`
+
+  function serverExts(mode: Mode) {
+    const e = [ext.confirm(), ext.motd(motd()), ext.wmdCredit(0), ext.wmdHalfclose(), ext.wmdDns(), ext.wmdInstance()]
+    if (mode === 'key-pending') e.push(ext.passwordServer(true))
+    return e
+  }
+
+  /** The client's address as text (the peer, or behind trusted proxies the client the proxy saw), or a refusal. */
+  function clientIp(req: Request, srv: any): string | Response {
+    const peer = srv.requestIP(req)?.address || 'unknown'
+    if (w.proxy) {
+      const r = resolveClient(peer, req.headers.get(w.proxy.header), w.proxy.trusted, w.proxy.header)
+      if ('error' in r) return refuse(400, `${r.error}\n`, 'proxy header', { peer })
+      return r.ip
+    }
+    if (w.trustProxy) {
+      const xff = (req.headers.get('x-forwarded-for') || '').split(',').map(x => x.trim()).filter(Boolean)
+      if (xff.length) return xff[xff.length - 1]
+    }
+    return peer
+  }
+
+  /** A refusal body; on a hosted relay it always names the abuse contact. */
+  const reply = (body: string, status: number) => new Response(w.hosted ? body + w.hosted.contactLine : body, { status })
+
+  function refuse(status: number, body: string, why: string, fields: Record<string, unknown>) {
+    engine.refusedSession(why, { proto: 'wisp', ...fields })
+    return reply(body, status)
+  }
+
+  async function fetch(req: Request, srv: any, url: URL): Promise<Response | undefined> {
+    const ip = clientIp(req, srv)
+    if (typeof ip !== 'string') return ip
+    const addr = clientKey(ip)
+    const origin = req.headers.get('origin') || ''
+    // before any table or the log sees it: no real page origin is this long
+    if (origin.length > 256) return refuse(400, 'the Origin header is longer than 256 characters\n', 'origin too long', { addr })
+    if (w.hosted) {
+      const denied = w.hosted.deniedClient(ip, origin)
+      if (denied) return refuse(403, `${denied}\n`, 'denied', { addr, origin })
+      const closed = w.hosted.notAccepting()
+      if (closed) return refuse(503, `${closed}\n`, 'not accepting', { addr })
+    }
+    const t = failed.get(addr)
+    if (t && t.until > Date.now()) return refuse(429, 'too many wrong keys from this address; wait\n', 'key throttle', { addr }) // set only after ADDR_FAILS
+    if (open && w.checkHost && !LOOPBACK_HOST.test(req.headers.get('host') || '')) {
+      return refuse(403, 'this relay answers only to localhost, 127.0.0.1 or [::1] (a check against DNS rebinding)\n', 'host not loopback', { addr, host: req.headers.get('host') })
+    }
+    if (w.origins?.length && !w.origins.includes(origin)) return refuse(403, 'origin not allowed\n', 'origin not allowed', { addr, origin })
+    const header = req.headers.get('sec-websocket-protocol')
+    const protos = (header || '').split(',').map(x => x.trim()).filter(Boolean)
+    if (protos.includes('wmd-relay.v1') && !protos.includes(SUBPROTOCOL)) {
+      return reply(`this is the Wisp endpoint (${path}); wmd-relay.v1 is at /relay\n`, 400)
+    }
+    const v2 = header !== null // the spec: v2 only when the header is there
+    const rest = url.pathname.slice(path.length)
+    let mode: Mode
+    let key: OwnerKey | null = null
+    let sid = randomBytes(9).toString('base64url')
+    let uid = ''
+    let grp = ''
+    let exp = Infinity
+    let p: Principal | null = null
+    const tok = protos.find(x => x.startsWith('t.'))
+    if (tok && o.secret) {
+      const info = verifyToken(o.secret, tok.slice(2))
+      if (typeof info === 'string') return refuse(401, `${info}\n`, info, { origin })
+      if (engine.hasSession(info.sid)) {
+        stats.refusedSessions++
+        return reply('session already connected\n', 409)
+      }
+      mode = 'token'
+      sid = info.sid
+      uid = info.uid || info.sid
+      grp = info.grp || uid
+      exp = info.exp
+      const a = engine.admit(uid, grp, exp, { proto: 'wisp' })
+      if (!a.ok) return reply(a.body, a.status)
+      p = a.p
+    } else if (rest) {
+      // a key in the URL, for Wisp v1 clients (off unless the owner enables it)
+      const m = rest.match(/^([^./]{1,64})\.([^/]{1,256})\/$/)
+      if (!w.prefixKeys || !m) return reply('not found\n', 404)
+      if (keyThrottled(addr, m[1])) return refuse(429, 'too many wrong secrets for this key from this address; wait\n', 'key throttle', { addr, key: m[1] })
+      // a check costs a scrypt: at most preAuth of them at once per address, so a burst cannot test many secrets before
+      // the throttle (below) is set
+      const busy = inHandshake.get(addr) || 0
+      if (busy >= preAuth) return refuse(429, 'too many connections opening from this address; wait\n', 'pre-auth limit', { addr })
+      inHandshake.set(addr, busy + 1)
+      const k = keys.find(x => x.id === m[1])
+      let ok = false
+      try {
+        ok = await verifySecret(m[2], k?.hash ?? DUMMY_HASH)
+      } finally {
+        release({ pre: true, addr })
+      }
+      if (!ok || !k) {
+        noteFailure(addr, m[1])
+        return refuse(401, 'wrong key\n', 'wrong key', { addr, key: m[1] })
+      }
+      failed.delete(`${addr}|${m[1]}`)
+      if (k.origins?.length && !k.origins.includes(origin)) return refuse(403, 'origin not allowed for this key\n', 'origin not allowed for key', { addr, key: k.id, origin })
+      mode = 'key'
+      key = k
+    } else if (keys.length) {
+      if (!v2) return refuse(401, `this relay needs a key; a Wisp v1 client can put it in the URL (${path}<id>.<secret>/) when the owner allows it\n`, 'no key (v1)', { addr })
+      mode = 'key-pending'
+    } else if (open) {
+      mode = 'open'
+    } else {
+      return refuse(401, 'no token\n', 'no token', { origin })
+    }
+    const n = inHandshake.get(addr) || 0
+    if (n >= preAuth) return refuse(429, 'too many connections opening from this address; wait\n', 'pre-auth limit', { addr })
+    inHandshake.set(addr, n + 1)
+    const headers: Record<string, string> = {}
+    if (v2 && protos.length) headers['Sec-WebSocket-Protocol'] = protos.includes(SUBPROTOCOL) ? SUBPROTOCOL : protos[0]
+    const data = { kind: 'wisp', v2, mode, addr, ip, sid, uid, grp, exp, p, key, origin, hs: null as any, hsTimer: null as any, pre: true }
+    const ok = srv.upgrade(req, Object.keys(headers).length ? { data, headers } : { data }) // Bun refuses an empty headers object
+    if (!ok) {
+      release(data)
+      return reply('upgrade failed\n', 400)
+    }
+    return undefined
+  }
+
+  // Wrong keys are throttled per (address, key id), so one wrong guess does not lock out the right key from the same
+  // address (a NAT, a proxy); the whole address is throttled only after ADDR_FAILS wrong keys (guessing ids).
+  const ADDR_FAILS = 20
+  const KEY_FREE_FAILS = 3
+  function noteFailure(addr: string, id: string) {
+    const now = Date.now()
+    const f = failed.get(`${addr}|${id}`) || { fails: 0, until: 0, at: 0 }
+    f.fails++
+    f.at = now
+    // a typo or two goes through at once; from the fourth wrong secret on, 1 s doubling to 60 s
+    if (f.fails > KEY_FREE_FAILS) f.until = now + Math.min(60_000, 1000 * 2 ** (f.fails - KEY_FREE_FAILS - 1))
+    failed.set(`${addr}|${id}`, f)
+    const a = failed.get(addr) || { fails: 0, until: 0, at: 0 }
+    a.fails++
+    a.at = now
+    if (a.fails >= ADDR_FAILS) a.until = now + Math.min(60_000, 1000 * 2 ** (a.fails - ADDR_FAILS))
+    failed.set(addr, a)
+  }
+  const keyThrottled = (addr: string, id: string) => (failed.get(`${addr}|${id}`)?.until ?? 0) > Date.now()
+
+  /** The socket left its handshake (done or gone): it no longer counts against the pre-auth cap. */
+  function release(d: any) {
+    if (!d.pre) return
+    d.pre = false
+    const n = (inHandshake.get(d.addr) || 1) - 1
+    if (n > 0) inHandshake.set(d.addr, n)
+    else inHandshake.delete(d.addr)
+  }
+
+  function sendAll(ws: any, pkts: Uint8Array[]) {
+    for (const b of pkts) ws.send(b)
+  }
+
+  function open_(ws: any) {
+    const d = ws.data
+    d.hs = new ServerHandshake({ v2: d.v2, exts: serverExts(d.mode), buffer })
+    const r = d.hs.start()
+    sendAll(ws, r.send)
+    if (r.done) return finish(ws, null)
+    d.hsTimer = setTimeout(() => {
+      if (d.session) return
+      log({ ev: 'session-refused', proto: 'wisp', why: 'handshake timeout', addr: d.addr })
+      ws.close(1008, 'handshake timeout')
+    }, handshakeMs)
+  }
+
+  function rejectHs(ws: any, reason: number, why: string) {
+    const d = ws.data
+    log({ ev: 'session-refused', proto: 'wisp', why, addr: d.addr })
+    stats.refusedSessions++
+    sendAll(ws, d.hs.reject(reason))
+    ws.close(1008, closeWords(reason).slice(0, 120))
+  }
+
+  async function finish(ws: any, client: any) {
+    const d = ws.data
+    if (d.hsTimer) clearTimeout(d.hsTimer)
+    let share: Shared | undefined
+    let allow: AllowEntry[] | undefined
+    let fresh = false
+    const inst = client?.instance ? Buffer.from(client.instance).toString('hex') : randomBytes(8).toString('hex')
+    if (d.mode === 'key-pending') {
+      const pw = client?.password
+      if (pw && keyThrottled(d.addr, pw.user)) return rejectHs(ws, CLOSE.AUTH_BAD_PASSWORD, `key throttle ${String(pw.user).slice(0, 64)}`)
+      const k = pw ? keys.find(x => x.id === pw.user) : undefined
+      const ok = pw ? await verifySecret(pw.pass, k?.hash ?? DUMMY_HASH) : false
+      if (ws.readyState !== 1) return
+      if (!ok || !k) {
+        noteFailure(d.addr, pw ? String(pw.user) : '')
+        return rejectHs(ws, CLOSE.AUTH_BAD_PASSWORD, `wrong key${pw ? ` ${String(pw.user).slice(0, 64)}` : ''}`)
+      }
+      failed.delete(`${d.addr}|${pw.user}`)
+      if (k.origins?.length && !k.origins.includes(d.origin)) return rejectHs(ws, CLOSE.AUTH_BAD_PASSWORD, `origin not allowed for key ${k.id}`)
+      d.key = k
+      d.mode = 'key'
+    }
+    if (d.mode === 'key') {
+      const k: OwnerKey = d.key
+      d.grp = `key:${k.id}`
+      d.uid = `key:${k.id}/${inst}`
+      share = sharedFor(d.grp, k)
+      if (k.allowHosts?.length) allow = compileAllow(k.allowHosts)
+    } else if (d.mode === 'open') {
+      d.grp = d.addr
+      d.uid = `${d.addr}/${inst}`
+      share = sharedFor(d.grp)
+    }
+    if (d.mode !== 'token') {
+      fresh = !engine.principals.has(d.uid)
+      if (fresh && engine.principals.size >= maxPrincipals) {
+        // least recently admitted identity with no live session goes first (plan 5: LRU); refuse only when all are live
+        for (const [k, q] of engine.principals) if (!q.live) { engine.principals.delete(k); break }
+        if (engine.principals.size >= maxPrincipals) return rejectHs(ws, CLOSE.THROTTLED, 'too many identities remembered')
+      }
+      if (fresh) {
+        let win = newIds.get(d.grp)
+        if (!win) newIds.set(d.grp, (win = new Window(instancesPerHour, 60 * 60_000)))
+        if (!win.hit()) return rejectHs(ws, CLOSE.THROTTLED, `more than ${instancesPerHour} new instances this hour from ${d.grp}`)
+      }
+      const a = engine.admit(d.uid, d.grp, Date.now(), { proto: 'wisp' }, share)
+      if (!a.ok) return rejectHs(ws, CLOSE.THROTTLED, a.body.trim())
+      d.p = a.p
+    }
+    let adm: ReturnType<Governor['admitSession']> | null = null
+    if (w.hosted) {
+      const closed = w.hosted.notAccepting()
+      if (closed) return rejectHs(ws, CLOSE.THROTTLED, closed)
+      adm = w.hosted.admitSession({ ip: d.ip, grp: d.grp, origin: d.origin, fresh, end: words => ws.close(4011, words.slice(0, 120)) })
+      if (!adm.ok) return rejectHs(ws, CLOSE.THROTTLED, adm.why)
+      d.rel = adm.adm.release
+    }
+    const common: Set<number> = client?.common ?? new Set()
+    const window = common.has(EXT.WMD_CREDIT) ? client.window : Infinity
+    const s = engine.open(ws, d.sid, d.p, d.exp, wire, window, { proto: 'wisp', mode: d.mode, v: d.v2 ? 2 : 1, inst: client?.instance ? inst : undefined, addr: d.addr, ...(w.hosted ? { origin: d.origin } : {}) })
+    release(d)
+    if (!s) return d.rel?.()
+    if (adm?.ok) s.hx = adm.adm
+    s.allow = allow
+    const sw: SessionW = {
+      engine, v2: d.v2, confirm: common.has(EXT.CONFIRM), credit: common.has(EXT.WMD_CREDIT), halfclose: common.has(EXT.WMD_HALFCLOSE),
+      dns: common.has(EXT.WMD_DNS), buffer, idleTimer: null, unknownLogged: false,
+    }
+    s.w = sw
+    d.session = s
+    if (streamIdleMs > 0) sw.idleTimer = setInterval(() => idleSweep(s), Math.min(60_000, Math.max(20, streamIdleMs / 4)))
+    if (d.v2) sendAll(ws, d.hs.accept())
+  }
+
+  function sharedFor(k: string, key?: OwnerKey): Shared {
+    let sh = shared.get(k)
+    if (!sh) shared.set(k, (sh = newShared({ rateDown: key?.rateDown ?? o.rateDown, rateUp: key?.rateUp ?? o.rateUp })))
+    return sh
+  }
+
+  function idleSweep(s: Session) {
+    const t = performance.now()
+    for (const st of [...s.streams.values()]) {
+      const x = sw(st)
+      if (st.connected && t - x.last > streamIdleMs) {
+        x.idle = true
+        engine.fail(s, st, E.TIMEOUT, `no bytes for ${Math.round(streamIdleMs / 1000)} s`)
+      }
+    }
+  }
+
+  function sw(st: Stream): StreamW {
+    return (st.w ||= { pending: null, sizes: [], released: 0, held: 0, heldBytes: 0, drained: 0, last: performance.now(), idle: false, shutPending: false })
+  }
+
+  function send(s: Session, b: Uint8Array) {
+    if (!s.closed) s.ws.send(b)
+  }
+
+  /** Room in the stream's buffer, for a CONTINUE. */
+  const room = (s: Session, x: StreamW) => Math.max(0, (s.w as SessionW).buffer - x.held)
+
+  const wire: Wire = {
+    connected(s, st) {
+      const x = sw(st)
+      x.last = performance.now()
+      if ((s.w as SessionW).confirm) send(s, continuePacket(st.id, room(s, x)))
+      const q = x.pending
+      x.pending = null
+      if (q) for (const b of q) writeUp(s, st, x, b)
+      if (x.shutPending && !st.closed) engine.clientEnd(s, st.id)
+    },
+    refused: (s, id, code) => send(s, closePacket(id, reasonFor(code))),
+    data(s, st, bytes) {
+      sw(st).last = performance.now()
+      send(s, dataPacket(st.id, bytes))
+    },
+    end(s, st) {
+      if ((s.w as SessionW).halfclose) send(s, shutdownPacket(st.id))
+      else engine.clientEnd(s, st.id) // no half-close: the stream is over once the remote's bytes are all sent
+    },
+    abort: (s, st, code) => send(s, closePacket(st.id, st.w?.idle ? CLOSE.DATA_TIMEOUT : reasonFor(code))),
+    grant(s, st, n) {
+      const x = sw(st)
+      x.released += n
+      while (x.sizes.length && x.released >= x.sizes[0]) {
+        const k = x.sizes.shift()!
+        x.released -= k
+        x.held--
+        x.heldBytes -= k
+        x.drained++
+        // released bytes leave the relay's and the group's counts at once (not at the next recount), so a fast honest
+        // uploader whose bytes are sent as they arrive never meets a cap that its real held bytes are far from
+        heldSwept = Math.max(0, heldSwept - k)
+        const gh = (groupHeld.get(s.p.grp) || 0) - k
+        if (gh > 0) groupHeld.set(s.p.grp, gh)
+        else groupHeld.delete(s.p.grp)
+      }
+      maybeContinue(s, st, x)
+    },
+    dnsReply: (s, id, rcode, ttl, addrs, why) => send(s, answerPacket(id, rcode, ttl, addrs, why)),
+    done: (s, st) => send(s, closePacket(st.id, CLOSE.VOLUNTARY)),
+  }
+
+  function maybeContinue(s: Session, st: Stream, x: StreamW) {
+    const b = (s.w as SessionW).buffer
+    if (x.drained >= Math.max(1, b >> 1) && x.heldBytes <= maxHeld && !st.closed) {
+      x.drained = 0
+      send(s, continuePacket(st.id, room(s, x)))
+    }
+  }
+
+  function writeUp(s: Session, st: Stream, x: StreamW, b: Uint8Array) {
+    if (b.length === 0) {
+      // nothing to write: released at once (a zero-byte write would never be credited)
+      x.held--
+      x.drained++
+      return maybeContinue(s, st, x)
+    }
+    x.sizes.push(b.length)
+    engine.write(s, st, b)
+  }
+
+  function message(ws: any, raw: any) {
+    const d = ws.data
+    if (typeof raw === 'string') return ws.close(1003, 'binary packets only')
+    const u8: Uint8Array = raw instanceof Uint8Array ? raw : new Uint8Array(raw)
+    if (u8.length > maxPayload) return ws.close(1009, 'packet too large')
+    const m: any = parse(u8)
+    if (!d.session) {
+      if (!d.hs || d.hs.state !== 'wait-info') return // a packet while the key is being checked: dropped, the client waits for CONTINUE
+      const r = d.hs.step(m)
+      if (r.error) {
+        log({ ev: 'session-refused', proto: 'wisp', why: `handshake: ${r.error}`, addr: d.addr })
+        stats.refusedSessions++
+        sendAll(ws, r.send)
+        return ws.close(1008, 'handshake failed')
+      }
+      if (r.client) finish(ws, r.client).catch(e => {
+        log({ ev: 'error', proto: 'wisp', error: String(e) })
+        ws.close(1011, 'relay error')
+      })
+      return
+    }
+    const s: Session = d.session
+    const x = s.w as SessionW
+    if (m.error) return ws.close(1002, `malformed packet: ${m.error}`.slice(0, 120))
+    switch (m.type) {
+      case PT.CONNECT: {
+        const to = `${m.host}:${m.port}`
+        if (m.id === 0) {
+          log({ ev: 'refused', sid: s.sid, id: 0, to, code: 'bad', why: 'stream id 0 is reserved' })
+          return ws.close(1002, 'stream id 0 is reserved for the handshake')
+        }
+        if (m.streamType !== STREAM.TCP) return engine.refuse(s, m.id, E.BAD, m.streamType === STREAM.UDP ? 'UDP streams are not supported' : `stream type ${m.streamType}`, to)
+        const dup = s.streams.get(m.id)
+        if (dup) return engine.fail(s, dup, E.BAD, 'stream id in use') // the client must not keep believing in a stream the server dropped (or the reverse)
+        engine.connectSafe(s, m.id, m.host, m.port)
+        return
+      }
+      case PT.DATA: {
+        const st = s.streams.get(m.id)
+        if (!st || st.closed) return // gone: its CLOSE is on the way
+        const sx = sw(st)
+        if (st.clientEnded || st.w?.shutPending) return engine.fail(s, st, E.BAD, 'data after SHUTDOWN')
+        sx.held++
+        sx.heldBytes += m.payload.length
+        sx.last = performance.now()
+        if (sx.held > 2 * x.buffer) return engine.fail(s, st, E.LIMIT, `more than ${2 * x.buffer} packets past the CONTINUE window`)
+        let tot = 0
+        for (const t of s.streams.values()) tot += t.w?.heldBytes || 0
+        if (tot > maxSessHeld) return engine.fail(s, st, E.LIMIT, `more than ${maxSessHeld} bytes held for this session`)
+        heldSwept += m.payload.length
+        const gh = (groupHeld.get(s.p.grp) || 0) + m.payload.length
+        groupHeld.set(s.p.grp, gh)
+        if (gh > maxGroupHeld) return engine.fail(s, st, E.LIMIT, `more than ${maxGroupHeld} bytes held for this address or key`)
+        if (heldSwept > maxHeldAll && gh > maxHeldAll / Math.max(1, groupHeld.size)) {
+          return engine.fail(s, st, E.LIMIT, 'the relay is holding too much unsent data; try again shortly')
+        }
+        if (!st.connected || !st.sock) {
+          ;(sx.pending ||= []).push(m.payload.slice())
+          return
+        }
+        writeUp(s, st, sx, m.payload)
+        return
+      }
+      case PT.CLOSE:
+        engine.clientAbort(s, m.id)
+        return
+      case PT.SHUTDOWN: {
+        if (!x.halfclose) return unknown(s, m.type)
+        const st = s.streams.get(m.id)
+        if (!st) return
+        if (!st.connected) sw(st).shutPending = true
+        else engine.clientEnd(s, m.id)
+        return
+      }
+      case PT.CREDIT:
+        if (!x.credit) return unknown(s, m.type)
+        engine.credit(s, m.id, m.n)
+        return
+      case PT.LOOKUP:
+        if (!x.dns) return unknown(s, m.type)
+        engine.dns(s, m.id, m.name, m.qtype).catch(e => log({ ev: 'error', sid: s.sid, error: String(e) }))
+        return
+      default:
+        return unknown(s, m.type)
+    }
+  }
+
+  function unknown(s: Session, type: number) {
+    const x = s.w as SessionW
+    if (x.unknownLogged) return
+    x.unknownLogged = true
+    log({ ev: 'ignored', sid: s.sid, why: `packet type 0x${type.toString(16)} not used on this session` })
+  }
+
+  function close(ws: any, code: number, reason: string) {
+    const d = ws.data
+    if (d.hsTimer) clearTimeout(d.hsTimer)
+    release(d)
+    d.rel?.()
+    const s: Session | undefined = d.session
+    if (!s) return
+    const x = s.w as SessionW
+    if (x?.idleTimer) clearInterval(x.idleTimer)
+    engine.closeSession(s, `websocket closed ${code} ${reason || ''}`.trim())
+  }
+
+  return {
+    path,
+    maxPayload,
+    /** Maintenance: every stream gets CLOSE 0x01 (the spec has no maintenance code), then the socket closes 1001 in words. */
+    drain(ws: any) {
+      const s: Session | undefined = ws.data.session
+      if (s && !s.closed) for (const st of s.streams.values()) ws.send(closePacket(st.id, CLOSE.UNKNOWN))
+      ws.close(1001, DRAIN_WORDS)
+    },
+    fetch,
+    open: open_,
+    message,
+    close,
+    stop: () => {
+      clearInterval(sweep)
+      clearInterval(heldCount)
+    },
+  }
+}