@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/relay/hosted.ts

@@ -0,0 +1,660 @@
+// W59 S7: the `--hosted` profile (plan §15): what a public relay we run adds to the engine.
+//
+// The governor holds every hosted-only limit and list, and nothing else: it does not touch sockets. The engine
+// (engine.ts, its `guard` hook) and the Wisp adapter (wisp.ts) ask it, at the points where a session is admitted,
+// a stream is opened or bytes move, and the relay (relay.ts) asks it for the state shown at /healthz and set by the
+// control socket. Clocks are injectable, so every limit is tested without waiting.
+//
+// Keys: an "address group" is wisp.ts's `grp` (an IPv4 address, or an IPv6 /64: token.ts clientKey); a "coarse
+// group" is the IPv4 /24 or IPv6 /48 around it. Page origins are a fairness control for cooperating browsers only: any
+// script can send any Origin, so every origin budget is also bounded by the address's own share and caps.
+
+import { readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { Bucket, type Session, type Shared, type Stream } from './engine.ts'
+import { type Addr, type Cidr, addrString, cidrContains, hostedBlockedReason, parseCidr, parseIP } from './policy.ts'
+
+const MIB = 1 << 20
+const GIB = 2 ** 30
+
+export type HostedOptions = {
+  abuseContact: string
+  version?: string
+  startStopped?: boolean // begin in stop-new: nothing is taken until `ctl resume` (a stop does not persist a restart otherwise)
+  now?: () => number // ms since the epoch (tests)
+  // per address group
+  groupStreams?: number // streams open at once, all its sessions (128)
+  groupConnectsPerMin?: number // (300)
+  groupBytesPerHour?: number // both ways (2 GiB)
+  groupDnsPerMin?: number // (600)
+  // per coarse group (IPv4 /24, IPv6 /48)
+  coarseSessions?: number // (64)
+  coarseInstancesPerHour?: number // new instances (240)
+  coarseRateDown?: number // bytes/s, all its addresses together (16 MiB/s)
+  coarseRateUp?: number // (4 MiB/s)
+  // per page origin
+  originTable?: number // origins remembered (1000, LRU)
+  originSessions?: number // sessions of one origin (400)
+  originShare?: number // the most of an origin one address group may use, 0-1 (0.25)
+  otherOriginSessions?: number // "other origins" and `Origin: null`: one shared budget (200)
+  noOriginSessions?: number // requests without an Origin (16)
+  originsPerAddrPerHour?: number // distinct origins one address group may use before it falls into "other" (8)
+  originRateDown?: number // bytes/s of one origin (32 MiB/s)
+  originRateUp?: number // (8 MiB/s)
+  // the whole relay
+  maxStreams?: number // streams open at once, all sessions: a file-descriptor budget below the host's limit (20,000)
+  maxRateDown?: number // bytes/s (64 MiB/s)
+  maxRateUp?: number // (16 MiB/s)
+  maxBytesPerDay?: number // both ways; 0 = no ceiling
+  maxBytesPerMonth?: number
+  usageFile?: string // the day and month counters survive a restart here
+  ceilingGraceMs?: number // after a ceiling is reached, streams already open may run this long, then they end (60 s)
+  onCeilingGrace?: (words: string) => void // called when the grace is over and the ceiling is still in force: end the open streams
+  warn?: (line: string) => void // one-line operator notices (stderr)
+  // against third parties
+  destConnectsPerMin?: number // per destination (host:port) per coarse group (600)
+  destStreams?: number // streams to one destination at once per coarse group (200)
+  distinctDests?: number // distinct destinations per address group per 10 minutes (100)
+  failedConnects?: number // refused, unreachable or timed-out dials per address group before it cools off (20)
+  failedWindowMs?: number // (5 min)
+  failedCoolMs?: number // (5 min)
+  denyCidrs?: string[] // dialled addresses refused besides the built-in ranges (the fleet's own neighbours)
+  tableMax?: number // address and coarse groups remembered per table (50000)
+}
+
+export type DenySpec = {
+  addresses?: string[] // client addresses or CIDRs ("203.0.113.0/24", "2001:db8:1:2::/64")
+  origins?: string[]
+  destinations?: string[] // "name", "name:port", ".suffix" (and its apex), or a literal address
+}
+
+export type Refusal = { status: number; body: string }
+
+/** A live session, as the deny lists see it. */
+export type Handle = { ip: string; origin: string; end: (words: string) => void }
+
+/** What a session holds from the governor until it ends. */
+export type Admission = {
+  grp: string
+  coarse: string
+  budget: OriginBudget
+  addrBucket: Shared
+  down: Bucket[]
+  up: Bucket[]
+  handle: Handle
+  release: () => void
+}
+
+type OriginBudget = {
+  key: string
+  cap: number
+  sessions: number
+  perAddr: Map<string, { n: number; shared: Shared }>
+  shared: Shared
+}
+
+/** A sliding window of event times on an injectable clock. */
+class Hits {
+  times: number[] = []
+  constructor(public max: number, public ms: number) {}
+  prune(t: number) {
+    let i = 0
+    while (i < this.times.length && t - this.times[i] > this.ms) i++
+    if (i) this.times.splice(0, i)
+  }
+  hit(t: number): boolean {
+    this.prune(t)
+    if (this.times.length >= this.max) return false
+    this.times.push(t)
+    return true
+  }
+  last(): number {
+    return this.times.length ? this.times[this.times.length - 1] : 0
+  }
+}
+
+/** A table that forgets its least recently used entry past `max`. */
+class Lru<V> {
+  m = new Map<string, V>()
+  constructor(public max: number) {}
+  get(k: string): V | undefined {
+    const v = this.m.get(k)
+    if (v !== undefined) {
+      this.m.delete(k)
+      this.m.set(k, v)
+    }
+    return v
+  }
+  set(k: string, v: V) {
+    this.m.delete(k)
+    this.m.set(k, v)
+    while (this.m.size > this.max) this.m.delete(this.m.keys().next().value as string)
+  }
+  delete(k: string) {
+    this.m.delete(k)
+  }
+  get size() {
+    return this.m.size
+  }
+}
+
+const ipv4Group = /^\d+\.\d+\.\d+\.\d+$/
+
+/** The coarse group of an address group key (token.ts clientKey form): IPv4 /24, IPv6 /48. */
+export function coarseKey(grp: string): string {
+  if (ipv4Group.test(grp)) return `c4:${grp.split('.').slice(0, 3).join('.')}`
+  if (grp.startsWith('v6:')) return `c6:${grp.slice(3).split(':').slice(0, 3).join(':')}`
+  return `c:${grp}`
+}
+
+export type ClientAddr = { ip: string } | { error: string }
+
+/**
+ * The client address of a request behind trusted proxies (plan §15, H2). A peer that is not a trusted proxy is keyed on
+ * its own address and the header is ignored. A trusted proxy must send the header; its entries are walked from the right
+ * and the first one that is not itself a trusted proxy is the client.
+ */
+export function resolveClient(peer: string, header: string | null, trusted: Cidr[], headerName: string): ClientAddr {
+  const norm = (s: string): Addr | null => {
+    s = s.trim().replace(/^\[|\](:\d+)?$/g, '')
+    if (/^\d+\.\d+\.\d+\.\d+:\d+$/.test(s)) s = s.slice(0, s.lastIndexOf(':'))
+    return parseIP(s)
+  }
+  const isTrusted = (a: Addr) => trusted.some(c => cidrHas(c, a))
+  const p = norm(peer)
+  if (!p) return { ip: peer }
+  const peerIp = unmap(p)
+  if (!isTrusted(peerIp)) return { ip: addrText(peerIp) }
+  const entries = (header || '').split(',').map(x => x.trim()).filter(Boolean)
+  if (!entries.length) return { error: `this relay sits behind a proxy that must send ${headerName}; the request had none` }
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const a = norm(entries[i])
+    if (!a) return { error: `${headerName} has an entry that is not an address` }
+    const u = unmap(a)
+    if (!isTrusted(u)) return { ip: addrText(u) }
+  }
+  return { error: `${headerName} names only proxies, no client` }
+}
+
+const cidrHas = cidrContains
+const unmap = (a: Addr): Addr => (a.v === 6 && a.b.slice(0, 10).every(x => x === 0) && a.b[10] === 255 && a.b[11] === 255 ? { v: 4, b: a.b.slice(12) } : a)
+const addrText = (a: Addr) => (a.v === 4 ? addrString(a) : compact6(a))
+/** IPv6 in the compressed form the clients' own text uses ("2001:db8::1"), so clientKey groups it. */
+function compact6(a: Addr): string {
+  const w: number[] = []
+  for (let i = 0; i < 16; i += 2) w.push((a.b[i] << 8) | a.b[i + 1])
+  let best = -1
+  let bestLen = 0
+  for (let i = 0; i < 8; ) {
+    if (w[i]) { i++; continue }
+    let j = i
+    while (j < 8 && !w[j]) j++
+    if (j - i > bestLen && j - i > 1) [best, bestLen] = [i, j - i]
+    i = j
+  }
+  const h = (x: number[]) => x.map(n => n.toString(16)).join(':')
+  return best < 0 ? h(w) : `${h(w.slice(0, best))}::${h(w.slice(best + bestLen))}`
+}
+
+type Dest = { name: string; port: number; suffix: boolean }
+
+export function createGovernor(o: HostedOptions) {
+  const now = o.now ?? Date.now
+  const tableMax = o.tableMax ?? 50_000
+  const c = {
+    groupStreams: o.groupStreams ?? 128,
+    groupConnectsPerMin: o.groupConnectsPerMin ?? 300,
+    groupBytesPerHour: o.groupBytesPerHour ?? 2 * GIB,
+    groupDnsPerMin: o.groupDnsPerMin ?? 600,
+    coarseSessions: o.coarseSessions ?? 64,
+    coarseInstancesPerHour: o.coarseInstancesPerHour ?? 240,
+    coarseRateDown: o.coarseRateDown ?? 16 * MIB,
+    coarseRateUp: o.coarseRateUp ?? 4 * MIB,
+    originTable: o.originTable ?? 1000,
+    originSessions: o.originSessions ?? 400,
+    originShare: o.originShare ?? 0.25,
+    otherOriginSessions: o.otherOriginSessions ?? 200,
+    noOriginSessions: o.noOriginSessions ?? 16,
+    originsPerAddrPerHour: o.originsPerAddrPerHour ?? 8,
+    originRateDown: o.originRateDown ?? 32 * MIB,
+    originRateUp: o.originRateUp ?? 8 * MIB,
+    maxStreams: o.maxStreams ?? 20_000,
+    maxRateDown: o.maxRateDown ?? 64 * MIB,
+    maxRateUp: o.maxRateUp ?? 16 * MIB,
+    maxBytesPerDay: o.maxBytesPerDay ?? 0,
+    maxBytesPerMonth: o.maxBytesPerMonth ?? 0,
+    destConnectsPerMin: o.destConnectsPerMin ?? 600,
+    destStreams: o.destStreams ?? 200,
+    distinctDests: o.distinctDests ?? 100,
+    failedConnects: o.failedConnects ?? 20,
+    failedWindowMs: o.failedWindowMs ?? 5 * 60_000,
+    failedCoolMs: o.failedCoolMs ?? 5 * 60_000,
+    ceilingGraceMs: o.ceilingGraceMs ?? 60_000,
+  }
+  const denyCidrs = (o.denyCidrs ?? []).map(s => {
+    const x = parseCidr(s)
+    if (!x) throw new Error(`deny-cidr '${s}' is not an address or CIDR`)
+    return x
+  })
+  const contact = o.abuseContact
+  const contactLine = `abuse contact: ${contact}\n`
+
+  // ---- state set by the operator (control socket) and by the ceilings
+  let stopped = !!o.startStopped
+  let draining = false
+
+  // ---- tables
+  const groupStreams = new Map<string, number>()
+  const groupConnects = new Lru<Hits>(tableMax)
+  const groupDns = new Lru<Hits>(tableMax)
+  const groupBytes = new Lru<{ hour: number; n: number }>(tableMax)
+  const groupDests = new Lru<Map<string, number>>(tableMax)
+  const groupFails = new Lru<{ hits: Hits; cool: number }>(tableMax)
+  const coarseSessions = new Map<string, number>()
+  const coarseInstances = new Lru<Hits>(tableMax)
+  const coarseShared = new Lru<Shared>(tableMax)
+  const destConnects = new Lru<Hits>(tableMax)
+  const destLive = new Map<string, number>()
+  const addrOrigins = new Lru<Map<string, number>>(tableMax) // per address group: origin -> first seen (this hour)
+  const origins = new Lru<OriginBudget>(c.originTable) // by origin; entries with live sessions are never evicted
+  const mk = (key: string, cap: number): OriginBudget => ({
+    key, cap, sessions: 0, perAddr: new Map(),
+    shared: { down: new Bucket(c.originRateDown), up: new Bucket(c.originRateUp) },
+  })
+  const other = mk('other', c.otherOriginSessions)
+  const none = mk('none', c.noOriginSessions)
+  const globalShared: Shared = { down: new Bucket(c.maxRateDown), up: new Bucket(c.maxRateUp) }
+  const live = new Set<Handle>()
+  let liveStreams = 0
+
+  // ---- deny lists
+  let denyAddr: Cidr[] = []
+  let denyOrigin = new Set<string>()
+  let denyDest: Dest[] = []
+
+  function reloadDeny(spec: DenySpec): { ended: number } {
+    const addrs: Cidr[] = []
+    for (const a of spec.addresses ?? []) {
+      const x = parseCidr(a)
+      if (!x) throw new Error(`deny list: '${a}' is not an address or CIDR`)
+      addrs.push(x)
+    }
+    const dests: Dest[] = []
+    for (const d of spec.destinations ?? []) {
+      const m = String(d).toLowerCase().trim().match(/^(\.?[^:]+)(?::(\d{1,5}))?$/)
+      if (!m) throw new Error(`deny list: '${d}' is not a destination (name, name:port or .suffix)`)
+      dests.push({ name: m[1].replace(/^\./, ''), port: m[2] ? Number(m[2]) : 0, suffix: m[1].startsWith('.') })
+    }
+    denyAddr = addrs
+    denyOrigin = new Set((spec.origins ?? []).map(String))
+    denyDest = dests
+    let ended = 0
+    for (const h of [...live]) {
+      const why = deniedClient(h.ip, h.origin)
+      if (why) {
+        ended++
+        h.end(why)
+      }
+    }
+    return { ended }
+  }
+
+  function deniedClient(ip: string, origin: string): string | null {
+    const a = parseIP(ip)
+    if (a && denyAddr.some(x => cidrHas(x, unmap(a)))) return 'this address is blocked by the operator'
+    if (origin && denyOrigin.has(origin)) return 'this page origin is blocked by the operator'
+    return null
+  }
+
+  const deniedDestination = (host: string, port: number): boolean => {
+    const h = host.toLowerCase().replace(/\.$/, '')
+    return denyDest.some(d => (!d.port || d.port === port) && (h === d.name || (d.suffix && h.endsWith(`.${d.name}`))))
+  }
+
+  // ---- ceilings
+  const day = (t: number) => new Date(t).toISOString().slice(0, 10)
+  const month = (t: number) => new Date(t).toISOString().slice(0, 7)
+  const warn = o.warn ?? ((m: string) => void process.stderr.write(`${m}\n`))
+  let usage = { day: day(now()), dayBytes: 0, month: month(now()), monthBytes: 0 }
+  if (o.usageFile) {
+    let raw: string | null = null
+    try { raw = readFileSync(o.usageFile, 'utf8') } catch {}
+    if (raw !== null) {
+      let u: any = null
+      try { u = JSON.parse(raw) } catch {}
+      const t = now()
+      const dayOk = (v: unknown) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v) && Number.isFinite(Date.parse(`${v}T00:00:00Z`)) && day(Date.parse(`${v}T00:00:00Z`)) === v && v <= day(t + 86_400_000)
+      const next = new Date(t)
+      const monthMax = month(Date.UTC(next.getUTCFullYear(), next.getUTCMonth() + 1, 1))
+      const monthOk = (v: unknown) => typeof v === 'string' && /^\d{4}-\d{2}$/.test(v) && Number.isFinite(Date.parse(`${v}-01T00:00:00Z`)) && month(Date.parse(`${v}-01T00:00:00Z`)) === v && v <= monthMax
+      // a counter that is not a finite, safe, non-negative number, or is far past its own ceiling, is corrupt
+      const sane = (v: unknown, ceil?: number) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= Number.MAX_SAFE_INTEGER && (!ceil || v <= ceil * 2)
+      const problems: string[] = []
+      if (!u || typeof u !== 'object') problems.push('not a JSON object')
+      else {
+        usage.day = dayOk(u.day) ? u.day : (u.day !== undefined && problems.push('day'), usage.day)
+        usage.month = monthOk(u.month) ? u.month : (u.month !== undefined && problems.push('month'), usage.month)
+        if (sane(u.dayBytes, c.maxBytesPerDay)) usage.dayBytes = u.dayBytes
+        else problems.push('dayBytes')
+        if (sane(u.monthBytes, c.maxBytesPerMonth)) usage.monthBytes = u.monthBytes
+        else problems.push('monthBytes')
+        // a date that was reset starts its counter at 0 too
+        if (usage.day !== u.day) usage.dayBytes = 0
+        if (usage.month !== u.month) usage.monthBytes = 0
+      }
+      if (problems.length) warn(`wmd-relay: ${o.usageFile} is damaged (${problems.join(', ')}); the affected counters and dates start again from 0 and today`)
+    }
+  }
+  /** The counters restart only when the date moves forward: a clock set back must not zero them. */
+  function roll() {
+    const t = now()
+    if (day(t) > usage.day) {
+      usage.day = day(t)
+      usage.dayBytes = 0
+    }
+    if (month(t) > usage.month) {
+      usage.month = month(t)
+      usage.monthBytes = 0
+    }
+  }
+  /** The ceiling in force, or null. The rollover lifts it: the counters restart with the day and the month. */
+  function ceiling(): 'day' | 'month' | null {
+    roll()
+    const k = c.maxBytesPerMonth && usage.monthBytes >= c.maxBytesPerMonth ? 'month' : c.maxBytesPerDay && usage.dayBytes >= c.maxBytesPerDay ? 'day' : null
+    if (!k) {
+      ceilingSince = 0
+      if (graceTimer) clearTimeout(graceTimer)
+      graceTimer = null
+    } else if (!ceilingSince) {
+      ceilingSince = now()
+      graceTimer = setTimeout(() => {
+        graceTimer = null
+        const w = ceiling()
+        if (w) o.onCeilingGrace?.(ceilingWords(w))
+      }, c.ceilingGraceMs)
+      ;(graceTimer as any).unref?.()
+    }
+    return k
+  }
+  let ceilingSince = 0
+  let graceTimer: ReturnType<typeof setTimeout> | null = null
+  /** True once a ceiling has been in force longer than the grace: even streams that are open end. */
+  const pastGrace = () => !!ceiling() && now() - ceilingSince >= c.ceilingGraceMs
+  const ceilingWords = (k: 'day' | 'month') => `the relay has reached its traffic limit for ${k === 'day' ? 'today' : 'this month'}`
+  function saveUsage() {
+    if (!o.usageFile) return
+    try {
+      const tmp = `${o.usageFile}.new`
+      writeFileSync(tmp, JSON.stringify(usage), { mode: 0o600 })
+      renameSync(tmp, o.usageFile)
+    } catch {}
+  }
+  const saver = o.usageFile ? setInterval(saveUsage, 15_000) : null
+  saver?.unref?.()
+
+  function accepting(): boolean {
+    return !stopped && !draining && !ceiling()
+  }
+
+  /** Why new sessions are not taken now, or null. */
+  function notAccepting(): string | null {
+    if (draining) return 'the relay is closed for maintenance'
+    if (stopped) return 'the relay is not taking new connections now'
+    const k = ceiling()
+    return k ? ceilingWords(k) : null
+  }
+
+  // ---- sessions
+  function pickBudget(grp: string, origin: string): OriginBudget {
+    if (!origin) return none
+    if (origin === 'null') return other
+    const t = now()
+    let seen = addrOrigins.get(grp)
+    if (!seen) addrOrigins.set(grp, (seen = new Map()))
+    for (const [k, at] of seen) if (t - at > 3_600_000) seen.delete(k)
+    if (!seen.has(origin)) {
+      if (seen.size >= c.originsPerAddrPerHour) return other // a ninth distinct origin from one address
+      seen.set(origin, t)
+    }
+    let b = origins.get(origin)
+    if (b) return b
+    if (origins.size >= c.originTable) {
+      // evict the least recently used origin that has no live session; none free: this one is "other"
+      let victim: string | null = null
+      for (const [k, v] of origins.m) if (!v.sessions) { victim = k; break }
+      if (victim === null) return other
+      origins.delete(victim)
+    }
+    b = mk(origin, c.originSessions)
+    origins.set(origin, b)
+    return b
+  }
+
+  /** A session of an address group from `ip` with this page origin is about to open. */
+  function admitSession(i: { ip: string; grp: string; origin: string; fresh: boolean; end: (words: string) => void }): { ok: true; adm: Admission } | { ok: false; why: string } {
+    const coarse = coarseKey(i.grp)
+    const t = now()
+    if ((coarseSessions.get(coarse) || 0) >= c.coarseSessions) return { ok: false, why: `more than ${c.coarseSessions} sessions from this network` }
+    if (i.fresh) {
+      let w = coarseInstances.get(coarse)
+      if (!w) coarseInstances.set(coarse, (w = new Hits(c.coarseInstancesPerHour, 3_600_000)))
+      if (!w.hit(t)) return { ok: false, why: `more than ${c.coarseInstancesPerHour} new instances an hour from this network` }
+    }
+    const budget = pickBudget(i.grp, i.origin)
+    const share = Math.max(1, Math.floor(budget.cap * c.originShare))
+    const mine = budget.perAddr.get(i.grp)
+    if (budget.sessions >= budget.cap) return { ok: false, why: `this page origin has no room for more sessions (${budget.cap})` }
+    if ((mine?.n ?? 0) >= share) return { ok: false, why: `more than ${share} sessions of this page origin from one address` }
+    let cs = coarseShared.get(coarse)
+    if (!cs) coarseShared.set(coarse, (cs = { down: new Bucket(c.coarseRateDown), up: new Bucket(c.coarseRateUp) }))
+    const entry = mine ?? { n: 0, shared: { down: new Bucket(Math.max(1, c.originRateDown * c.originShare)), up: new Bucket(Math.max(1, c.originRateUp * c.originShare)) } }
+    entry.n++
+    budget.perAddr.set(i.grp, entry)
+    budget.sessions++
+    coarseSessions.set(coarse, (coarseSessions.get(coarse) || 0) + 1)
+    const handle: Handle = { ip: i.ip, origin: i.origin, end: i.end }
+    live.add(handle)
+    let done = false
+    const adm: Admission = {
+      grp: i.grp, coarse, budget, addrBucket: entry.shared,
+      down: [cs.down, entry.shared.down, budget.shared.down, globalShared.down],
+      up: [cs.up, entry.shared.up, budget.shared.up, globalShared.up],
+      handle,
+      release() {
+        if (done) return
+        done = true
+        live.delete(handle)
+        budget.sessions--
+        const e = budget.perAddr.get(i.grp)
+        if (e && --e.n <= 0) budget.perAddr.delete(i.grp)
+        const n = (coarseSessions.get(coarse) || 1) - 1
+        if (n > 0) coarseSessions.set(coarse, n)
+        else coarseSessions.delete(coarse)
+      },
+    }
+    return { ok: true, adm }
+  }
+
+  // ---- streams (engine guard)
+  const grpOf = (s: Session): string => s.hx?.grp ?? s.p.grp
+  const destKey = (host: string, port: number) => `${host.toLowerCase().replace(/\.$/, '')}:${port}`
+
+  /** Before a connect is resolved: the cooling-off, the group's rate, the scan shape and the destination's rate. Null, or the words. */
+  function admitConnect(s: Session, host: string, port: number): string | null {
+    const t = now()
+    const grp = grpOf(s)
+    const closed = notAccepting() // stop-new, drain and a ceiling end new streams too: open streams run to their end
+    if (closed) return closed
+    const f = groupFails.get(grp)
+    if (f && f.cool > t) return `too many failed connections from this address; new connections wait ${Math.ceil((f.cool - t) / 1000)} s`
+    const h = bytesHour(grp)
+    if (h.n >= c.groupBytesPerHour) return 'this address has used its bytes for this hour'
+    let w = groupConnects.get(grp)
+    if (!w) groupConnects.set(grp, (w = new Hits(c.groupConnectsPerMin, 60_000)))
+    if (!w.hit(t)) return `more than ${c.groupConnectsPerMin} connections a minute from this address`
+    const key = destKey(host, port)
+    let seen = groupDests.get(grp)
+    if (!seen) groupDests.set(grp, (seen = new Map()))
+    for (const [k, at] of seen) if (t - at > 600_000) seen.delete(k)
+    if (!seen.has(key) && seen.size >= c.distinctDests) return `more than ${c.distinctDests} different destinations in 10 minutes from this address`
+    seen.set(key, t)
+    const ck = `${coarseKey(grp)}|${key}`
+    let dw = destConnects.get(ck)
+    if (!dw) destConnects.set(ck, (dw = new Hits(c.destConnectsPerMin, 60_000)))
+    if (!dw.hit(t)) return `more than ${c.destConnectsPerMin} connections a minute to ${key} from this network`
+    return null
+  }
+
+  /** Just before the dial: the concurrent counts. Sets `st.rel`, which the engine calls once when the stream is gone. */
+  function openStream(s: Session, st: Stream, host: string, port: number): string | null {
+    const grp = grpOf(s)
+    const ck = `${coarseKey(grp)}|${destKey(host, port)}`
+    if (liveStreams >= c.maxStreams) return `the relay has ${c.maxStreams} streams open; try again shortly`
+    if ((groupStreams.get(grp) || 0) >= c.groupStreams) return `more than ${c.groupStreams} streams open from this address`
+    if ((destLive.get(ck) || 0) >= c.destStreams) return `more than ${c.destStreams} streams open to ${destKey(host, port)} from this network`
+    liveStreams++
+    groupStreams.set(grp, (groupStreams.get(grp) || 0) + 1)
+    destLive.set(ck, (destLive.get(ck) || 0) + 1)
+    st.rel = () => {
+      liveStreams--
+      for (const [m, k] of [[groupStreams, grp], [destLive, ck]] as const) {
+        const n = (m.get(k) || 1) - 1
+        if (n > 0) m.set(k, n)
+        else m.delete(k)
+      }
+    }
+    return null
+  }
+
+  /** A dial the remote refused, that found no route or that timed out (or a name that did not resolve). */
+  function dialFailed(s: Session) {
+    const t = now()
+    const grp = grpOf(s)
+    let f = groupFails.get(grp)
+    if (!f) groupFails.set(grp, (f = { hits: new Hits(Infinity, c.failedWindowMs), cool: 0 }))
+    f.hits.prune(t)
+    f.hits.times.push(t)
+    if (f.hits.times.length >= c.failedConnects) {
+      f.cool = t + c.failedCoolMs
+      f.hits.times = []
+    }
+  }
+
+  /** DNS answers stop with new connections: stop-new, a drain and a ceiling (the same words). */
+  const dnsClosed = (): string | null => notAccepting()
+
+  function dnsAllowed(s: Session): boolean {
+    const grp = grpOf(s)
+    let w = groupDns.get(grp)
+    if (!w) groupDns.set(grp, (w = new Hits(c.groupDnsPerMin, 60_000)))
+    return w.hit(now())
+  }
+
+  function bytesHour(grp: string) {
+    const hour = Math.floor(now() / 3_600_000)
+    let b = groupBytes.get(grp)
+    if (!b || b.hour !== hour) groupBytes.set(grp, (b = { hour, n: 0 }))
+    return b
+  }
+
+  /** Bytes relayed for a session (either way). True while the group is within its hourly bytes. */
+  function bytes(s: Session, n: number): boolean {
+    roll()
+    usage.dayBytes += n
+    usage.monthBytes += n
+    const b = bytesHour(grpOf(s))
+    b.n += n
+    ceiling() // starts the grace clock the moment the counter crosses
+    return b.n <= c.groupBytesPerHour && !pastGrace()
+  }
+
+  /** Why `bytes` just said no. */
+  function limitWhy(): string {
+    const k = ceiling()
+    return k && pastGrace() ? ceilingWords(k) : 'this address has used its bytes for this hour'
+  }
+
+  /** Up to n bytes from the coarse, origin and relay-wide buckets of the session (what the group's own bucket let through). */
+  function take(s: Session, dir: 'down' | 'up', n: number): number {
+    const list: Bucket[] | undefined = s.hx?.[dir]
+    if (!list) return n
+    const got: number[] = []
+    let k = n
+    for (const b of list) {
+      k = b.take(k)
+      got.push(k)
+      if (!k) break
+    }
+    const last = got[got.length - 1]
+    for (let i = 0; i < got.length; i++) if (got[i] > last) list[i].tokens = Math.min(list[i].rate, list[i].tokens + got[i] - last)
+    return last
+  }
+  function waitMs(s: Session, dir: 'down' | 'up', n: number): number {
+    const list: Bucket[] | undefined = s.hx?.[dir]
+    return list ? Math.max(1, ...list.map(b => b.waitMs(n))) : 1
+  }
+
+  function blockedAddr(a: Addr): string | null {
+    return hostedBlockedReason(a, denyCidrs)
+  }
+
+  // ---- housekeeping
+  const sweep = setInterval(() => {
+    const t = now()
+    for (const m of [groupConnects, groupDns, coarseInstances]) for (const [k, w] of m.m) { w.prune(t); if (!w.times.length) m.delete(k) }
+    for (const [k, w] of destConnects.m) { w.prune(t); if (!w.times.length && !destLive.has(k)) destConnects.delete(k) }
+    for (const [k, f] of groupFails.m) { f.hits.prune(t); if (!f.hits.times.length && f.cool < t) groupFails.delete(k) }
+    for (const [k, b] of groupBytes.m) if (b.hour !== Math.floor(t / 3_600_000)) groupBytes.delete(k)
+  }, 60_000)
+  sweep.unref?.()
+
+  return {
+    options: c,
+    contact,
+    contactLine,
+    version: o.version,
+    // operator state
+    stopNew: () => void (stopped = true),
+    resume() {
+      stopped = false
+      draining = false
+    },
+    startDrain: () => void ((draining = true), (stopped = true)),
+    isStopped: () => stopped,
+    isDraining: () => draining,
+    accepting,
+    notAccepting,
+    ceiling,
+    ceilingWords,
+    usage: () => (roll(), { ...usage }),
+    saveUsage,
+    // deny lists
+    reloadDeny,
+    deniedClient,
+    isDeniedDest: deniedDestination,
+    // admission
+    admitSession,
+    admitConnect,
+    openStream,
+    dialFailed,
+    dnsAllowed,
+    dnsClosed,
+    bytes,
+    limitWhy,
+    take,
+    waitMs,
+    blockedAddr,
+    /** Sessions per origin class, for tests and status (counts only). */
+    liveStreams: () => liveStreams,
+    originStats: () => ({ table: origins.size, other: other.sessions, none: none.sessions }),
+    limitsLine: () =>
+      `${c.groupStreams} streams, ${c.groupConnectsPerMin} connects a minute, ${Math.round(c.groupBytesPerHour / MIB)} MiB an hour per address`,
+    stop() {
+      if (graceTimer) clearTimeout(graceTimer)
+      clearInterval(sweep)
+      if (saver) clearInterval(saver)
+      saveUsage()
+    },
+  }
+}
+
+export type Governor = ReturnType<typeof createGovernor>