@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/src/net/wisp.js

@@ -0,0 +1,511 @@
+// W59: the Wisp protocol (v2, github.com/MercuryWorkshop/wisp-protocol, CC-BY-4.0), shared by the
+// browser's network Worker (wisp-client.js) and the relay server (web/relay/wisp.ts).
+//
+// One WebSocket carries every TCP stream of a guest. Binary messages only:
+//
+//   type u8 | stream id u32 LE | payload            (all integers little-endian; stream 0 = handshake)
+//
+//   CONNECT  0x01  stream type u8 | port u16 | host utf8   client -> server, open a stream
+//   DATA     0x02  bytes                                   both ways
+//   CONTINUE 0x03  buffer u32                              server -> client: packets the server can
+//                                                          buffer for the stream; it RESETS the
+//                                                          client's counter (not added to it)
+//   CLOSE    0x04  reason u8                               both ways, the stream is gone
+//   INFO     0x05  major u8 | minor u8 | extensions        handshake, both ways (v2 only)
+//
+// An extension entry is id u8 | length u32 | metadata. A request without Sec-WebSocket-Protocol
+// is Wisp v1: the server skips INFO and sends CONTINUE on stream 0 at once.
+//
+// wmd's private extensions (docs/wisp-wmd-extensions.md), used only when both sides list them:
+//   0xE1 wmd-credit     packet 0xE0 CREDIT   n u32            client -> server: the server may send
+//                                                            n more bytes on the stream (download flow)
+//   0xE2 wmd-halfclose  packet 0xE3 SHUTDOWN -                either way: no more data from the sender
+//                                                            (a FIN), the other direction stays open
+//   0xE4 wmd-dns        packet 0xE5 LOOKUP   qtype u16 | name utf8                     client -> server
+//                       packet 0xE6 ANSWER   rcode u8 | ttl u32 | count u8 | addresses | reason utf8
+//   0xE7 wmd-instance   (no packet)          client metadata: a 16-byte instance id
+
+export const SUBPROTOCOL = 'wisp-v2'
+export const VERSION = { major: 2, minor: 0 }
+/** The wmd private extensions' own version, in each one's metadata byte 0. */
+export const WMD_EXT_VERSION = 1
+export const INSTANCE_BYTES = 16
+
+export const PT = {
+  CONNECT: 0x01, DATA: 0x02, CONTINUE: 0x03, CLOSE: 0x04, INFO: 0x05,
+  CREDIT: 0xe0, SHUTDOWN: 0xe3, LOOKUP: 0xe5, ANSWER: 0xe6,
+}
+
+export const EXT = {
+  UDP: 0x01, PASSWORD: 0x02, KEY: 0x03, MOTD: 0x04, CONFIRM: 0x05,
+  WMD_CREDIT: 0xe1, WMD_HALFCLOSE: 0xe2, WMD_DNS: 0xe4, WMD_INSTANCE: 0xe7,
+}
+
+export const STREAM = { TCP: 0x01, UDP: 0x02 }
+
+/** CLOSE reasons (spec, plus the extension-specified auth reasons). */
+export const CLOSE = {
+  UNKNOWN: 0x01, VOLUNTARY: 0x02, NETWORK: 0x03, INCOMPATIBLE: 0x04,
+  INVALID: 0x41, UNREACHABLE: 0x42, TIMEOUT: 0x43, REFUSED: 0x44,
+  DATA_TIMEOUT: 0x47, BLOCKED: 0x48, THROTTLED: 0x49,
+  CLIENT_ERROR: 0x81,
+  AUTH_BAD_PASSWORD: 0xc0, AUTH_BAD_SIGNATURE: 0xc1, AUTH_REQUIRED: 0xc2,
+}
+
+const CLOSE_WORDS = {
+  0x01: 'closed for an unknown reason',
+  0x02: 'closed by the other side',
+  0x03: 'closed by a network error',
+  0x04: 'the relay and this page support no common protocol extensions',
+  0x41: 'the relay refused the destination as invalid',
+  0x42: 'the destination is unreachable or its name did not resolve',
+  0x43: 'the destination did not answer in time',
+  0x44: 'the destination refused the connection',
+  0x47: 'the connection was idle too long',
+  0x48: 'the relay blocks this destination',
+  0x49: 'the relay limited this connection (too many, too fast or too much data)',
+  0x81: 'the page could not take more data',
+  0xc0: 'the relay refused the key (wrong id or secret)',
+  0xc1: 'the relay refused the key signature',
+  0xc2: 'the relay needs a key and none was given',
+}
+
+/** A close reason in words, for logs and the page's status. */
+export function closeWords(reason) {
+  return CLOSE_WORDS[reason] || `closed (reason 0x${(reason >>> 0).toString(16)})`
+}
+
+/** DNS rcodes in ANSWER (RFC 1035), the same as wmd-relay.v1. */
+export const RCODE = { NOERROR: 0, SERVFAIL: 2, NXDOMAIN: 3, REFUSED: 5 }
+
+const enc = new TextEncoder()
+const dec = new TextDecoder('utf-8', { fatal: true })
+
+export function packet(type, id, payload) {
+  const n = payload ? payload.length : 0
+  const b = new Uint8Array(5 + n)
+  b[0] = type
+  new DataView(b.buffer).setUint32(1, id >>> 0, true)
+  if (n) b.set(payload, 5)
+  return b
+}
+
+function u32(n) {
+  const p = new Uint8Array(4)
+  new DataView(p.buffer).setUint32(0, n >>> 0, true)
+  return p
+}
+
+export function connectPacket(id, host, port, type = STREAM.TCP) {
+  const h = enc.encode(host)
+  const p = new Uint8Array(3 + h.length)
+  p[0] = type
+  p[1] = port & 255
+  p[2] = (port >> 8) & 255
+  p.set(h, 3)
+  return packet(PT.CONNECT, id, p)
+}
+
+export const dataPacket = (id, bytes) => packet(PT.DATA, id, bytes)
+export const continuePacket = (id, buffer) => packet(PT.CONTINUE, id, u32(buffer))
+export const closePacket = (id, reason) => packet(PT.CLOSE, id, Uint8Array.of(reason & 255))
+export const creditPacket = (id, n) => packet(PT.CREDIT, id, u32(n))
+export const shutdownPacket = (id) => packet(PT.SHUTDOWN, id)
+
+export function lookupPacket(id, name, qtype) {
+  const h = enc.encode(name)
+  const p = new Uint8Array(2 + h.length)
+  p[0] = qtype & 255
+  p[1] = (qtype >> 8) & 255
+  p.set(h, 2)
+  return packet(PT.LOOKUP, id, p)
+}
+
+/** addrs: arrays of 4 (A) or 16 (AAAA) bytes. */
+export function answerPacket(id, rcode, ttl, addrs = [], reason = '') {
+  const d = enc.encode(reason)
+  const alen = addrs.reduce((s, a) => s + a.length, 0)
+  const p = new Uint8Array(6 + alen + d.length)
+  p[0] = rcode
+  new DataView(p.buffer).setUint32(1, ttl >>> 0, true)
+  p[5] = addrs.length
+  let o = 6
+  for (const a of addrs) {
+    p.set(a, o)
+    o += a.length
+  }
+  p.set(d, o)
+  return packet(PT.ANSWER, id, p)
+}
+
+/** exts: [{id, data?: Uint8Array}] */
+export function infoPacket(exts = [], version = VERSION) {
+  const len = exts.reduce((s, e) => s + 5 + (e.data ? e.data.length : 0), 0)
+  const p = new Uint8Array(2 + len)
+  const dv = new DataView(p.buffer)
+  p[0] = version.major
+  p[1] = version.minor
+  let o = 2
+  for (const e of exts) {
+    const d = e.data || new Uint8Array(0)
+    p[o] = e.id
+    dv.setUint32(o + 1, d.length, true)
+    p.set(d, o + 5)
+    o += 5 + d.length
+  }
+  return packet(PT.INFO, 0, p)
+}
+
+// Extension metadata ------------------------------------------------------------------------
+
+export const ext = {
+  passwordServer: (required) => ({ id: EXT.PASSWORD, data: Uint8Array.of(required ? 1 : 0) }),
+  passwordClient(user, pass) {
+    const u = enc.encode(user)
+    const w = enc.encode(pass)
+    if (u.length > 255) throw new RangeError('wisp: a key id is at most 255 bytes')
+    const d = new Uint8Array(1 + u.length + w.length)
+    d[0] = u.length
+    d.set(u, 1)
+    d.set(w, 1 + u.length)
+    return { id: EXT.PASSWORD, data: d }
+  },
+  motd: (text) => ({ id: EXT.MOTD, data: enc.encode(text) }),
+  confirm: () => ({ id: EXT.CONFIRM }),
+  /** window: the bytes the server may send on each new stream before the first CREDIT. */
+  wmdCredit(window) {
+    const d = new Uint8Array(5)
+    d[0] = WMD_EXT_VERSION
+    new DataView(d.buffer).setUint32(1, window >>> 0, true)
+    return { id: EXT.WMD_CREDIT, data: d }
+  },
+  wmdHalfclose: () => ({ id: EXT.WMD_HALFCLOSE, data: Uint8Array.of(WMD_EXT_VERSION) }),
+  wmdDns: () => ({ id: EXT.WMD_DNS, data: Uint8Array.of(WMD_EXT_VERSION) }),
+  /** The client sends its 16-byte id; the server lists the extension with no id. */
+  wmdInstance(idBytes) {
+    if (!idBytes) return { id: EXT.WMD_INSTANCE, data: Uint8Array.of(WMD_EXT_VERSION) }
+    if (idBytes.length !== INSTANCE_BYTES) throw new RangeError('wisp: an instance id is 16 bytes')
+    const d = new Uint8Array(1 + INSTANCE_BYTES)
+    d[0] = WMD_EXT_VERSION
+    d.set(idBytes, 1)
+    return { id: EXT.WMD_INSTANCE, data: d }
+  },
+}
+
+/**
+ * Read one extension's metadata into fields. Returns {error} when it is malformed.
+ * `from` is 'server' or 'client' (the password and instance formats differ by side).
+ */
+export function readExt(e, from) {
+  const d = e.data
+  switch (e.id) {
+    case EXT.PASSWORD:
+      if (from === 'server') {
+        if (d.length < 1) return { error: 'password extension without its flag' }
+        return { required: d[0] !== 0 }
+      } else {
+        if (d.length < 1 || d.length < 1 + d[0]) return { error: 'password extension too short' }
+        const user = text(d.subarray(1, 1 + d[0]))
+        const pass = text(d.subarray(1 + d[0]))
+        if (user === null || pass === null) return { error: 'password extension is not UTF-8' }
+        return { user, pass }
+      }
+    case EXT.KEY:
+      if (from === 'server') {
+        if (d.length < 2) return { error: 'key extension too short' }
+        return { required: d[0] !== 0, algorithms: d[1], challenge: d.subarray(2) }
+      }
+      return { raw: d }
+    case EXT.MOTD: {
+      const t = text(d)
+      return t === null ? { error: 'MOTD is not UTF-8' } : { motd: t }
+    }
+    case EXT.WMD_CREDIT:
+      if (d.length < 1) return { error: 'wmd-credit without a version' }
+      if (from === 'client') {
+        if (d.length < 5) return { error: 'wmd-credit without a window' }
+        return { version: d[0], window: new DataView(d.buffer, d.byteOffset, d.byteLength).getUint32(1, true) }
+      }
+      return { version: d[0] }
+    case EXT.WMD_HALFCLOSE:
+    case EXT.WMD_DNS:
+      if (d.length < 1) return { error: 'wmd extension without a version' }
+      return { version: d[0] }
+    case EXT.WMD_INSTANCE:
+      if (d.length < 1) return { error: 'wmd-instance without a version' }
+      if (from === 'client') {
+        // a later version may append fields: read the 16 bytes version 1 defines
+        if (d.length < 1 + INSTANCE_BYTES) return { error: 'wmd-instance id is shorter than 16 bytes' }
+        return { version: d[0], instance: d.slice(1, 1 + INSTANCE_BYTES) }
+      }
+      return { version: d[0] }
+    default:
+      return {}
+  }
+}
+
+function text(b) {
+  try {
+    return dec.decode(b)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse one packet (a Uint8Array or an ArrayBuffer). Never throws: returns {error, type?, id?}
+ * when the packet is malformed.
+ * Unknown packet types parse with just type, id and payload (the caller ignores or refuses them).
+ */
+export function parse(u8) {
+  if (u8 instanceof ArrayBuffer) u8 = new Uint8Array(u8)
+  if (!(u8 instanceof Uint8Array)) return { error: 'not a binary packet' }
+  if (u8.length < 5) return { error: 'packet shorter than 5 bytes' }
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength)
+  const type = u8[0]
+  const id = dv.getUint32(1, true)
+  const p = u8.subarray(5)
+  const m = { type, id, payload: p }
+  const bad = (error) => ({ error, type, id })
+  switch (type) {
+    case PT.CONNECT: {
+      if (p.length < 3) return bad('CONNECT too short')
+      m.streamType = p[0]
+      m.port = p[1] | (p[2] << 8)
+      const h = text(p.subarray(3))
+      if (h === null) return bad('CONNECT host is not UTF-8')
+      m.host = h
+      break
+    }
+    case PT.CONTINUE: // as wisp-mux: at least 4 bytes, the rest ignored
+      if (p.length < 4) return bad('CONTINUE payload shorter than 4 bytes')
+      m.n = dv.getUint32(5, true)
+      break
+    case PT.CREDIT:
+      if (p.length !== 4) return bad('CREDIT payload is not 4 bytes')
+      m.n = dv.getUint32(5, true)
+      break
+    case PT.CLOSE:
+      if (p.length < 1) return bad('CLOSE without a reason')
+      m.reason = p[0]
+      break
+    case PT.SHUTDOWN:
+      if (p.length !== 0) return bad('SHUTDOWN with a payload')
+      break
+    case PT.LOOKUP: {
+      if (p.length < 3) return bad('LOOKUP too short')
+      m.qtype = p[0] | (p[1] << 8)
+      const n = text(p.subarray(2))
+      if (n === null) return bad('LOOKUP name is not UTF-8')
+      m.name = n
+      break
+    }
+    case PT.ANSWER:
+      if (p.length < 6) return bad('ANSWER too short')
+      m.rcode = p[0]
+      m.ttl = dv.getUint32(6, true)
+      m.count = p[5]
+      m.rest = p.subarray(6) // the addresses (their size depends on the query), then the reason
+      break
+    case PT.INFO: {
+      if (p.length < 2) return bad('INFO too short')
+      m.version = { major: p[0], minor: p[1] }
+      m.exts = []
+      let o = 2
+      // as wisp-mux: fewer than 5 trailing bytes are ignored
+      while (p.length - o >= 5) {
+        const eid = p[o]
+        const len = dv.getUint32(5 + o + 1, true)
+        if (len > p.length - o - 5) return bad('INFO extension longer than the packet')
+        m.exts.push({ id: eid, data: p.subarray(o + 5, o + 5 + len) })
+        o += 5 + len
+      }
+      break
+    }
+  }
+  return m
+}
+
+/** The addresses of an ANSWER for a query of qtype (1: 4 bytes each, 28: 16). */
+export function answerAddrs(m, qtype) {
+  const size = qtype === 28 ? 16 : 4
+  const addrs = []
+  for (let i = 0; i < m.count; i++) {
+    const a = m.rest.subarray(i * size, (i + 1) * size)
+    if (a.length !== size) return { addrs, reason: 'short answer' }
+    addrs.push(a)
+  }
+  return { addrs, reason: text(m.rest.subarray(m.count * size)) ?? '' }
+}
+
+// Handshakes -------------------------------------------------------------------------------
+//
+// Both machines are pure: feed packets in, get packets to send and an outcome out. The caller
+// owns the WebSocket and the timers.
+
+const WMD_EXTS = new Set([EXT.WMD_CREDIT, EXT.WMD_HALFCLOSE, EXT.WMD_DNS, EXT.WMD_INSTANCE])
+
+/**
+ * The client side. `exts` are the extensions the client offers (built with `ext.*`, without
+ * password auth); `password` is {user, pass} or null.
+ *
+ * step(pkt) returns {send: Uint8Array[], done?: {version: 1|2, buffer, server: Map, common: Set,
+ * motd}, fail?: {reason, words, state}}. state is one of 'auth-required', 'auth-refused',
+ * 'incompatible', 'protocol'.
+ */
+export class ClientHandshake {
+  constructor({ exts = [], password = null } = {}) {
+    this.exts = exts
+    this.password = password
+    this.state = 'wait-info'
+    this.server = null
+    this.version = 1
+  }
+
+  step(m) {
+    const fail = (state, reason, words, send = []) => {
+      this.state = 'failed'
+      return { send, fail: { state, reason, words } }
+    }
+    if (m.error) return fail('protocol', CLOSE.UNKNOWN, `the relay sent a malformed packet: ${m.error}`)
+    if (this.state === 'wait-info') {
+      if (m.type === PT.CONTINUE && m.id === 0) {
+        this.state = 'done'
+        return { send: [], done: { version: 1, buffer: m.n, server: new Map(), common: new Set(), motd: '' } }
+      }
+      if (m.type === PT.CLOSE && m.id === 0) return fail(closeState(m.reason), m.reason, closeWords(m.reason))
+      if (m.type !== PT.INFO || m.id !== 0) return fail('protocol', CLOSE.UNKNOWN, 'the relay did not start with INFO or CONTINUE')
+      // A newer relay is asked for v2 (the INFO reply carries the lower version); an older one fails.
+      if (m.version.major < 2) {
+        const words = `the relay speaks Wisp ${m.version.major}.${m.version.minor}; this page speaks Wisp 2`
+        return fail('version', CLOSE.INCOMPATIBLE, words, [closePacket(0, CLOSE.INCOMPATIBLE)])
+      }
+      this.server = new Map()
+      for (const e of m.exts) {
+        const r = readExt(e, 'server')
+        if (r.error) return fail('protocol', CLOSE.UNKNOWN, `the relay sent a malformed extension: ${r.error}`)
+        this.server.set(e.id, r)
+      }
+      const pw = this.server.get(EXT.PASSWORD)
+      const keyx = this.server.get(EXT.KEY)
+      // Only password auth is supported: it satisfies the relay when the relay lists it and does
+      // not require a signature key alone (both required: the client may choose, per the spec).
+      const keyOnly = keyx && keyx.required && !(pw && pw.required)
+      if (keyOnly) {
+        return fail('auth-required', CLOSE.AUTH_REQUIRED, 'the relay needs a signature key, which this page does not support', [closePacket(0, CLOSE.AUTH_REQUIRED)])
+      }
+      if (pw && pw.required && !this.password) {
+        return fail('auth-required', CLOSE.AUTH_REQUIRED, closeWords(CLOSE.AUTH_REQUIRED), [closePacket(0, CLOSE.AUTH_REQUIRED)])
+      }
+      if (pw && this.password) {
+        const { user, pass } = this.password
+        if (typeof user !== 'string' || typeof pass !== 'string' || enc.encode(user).length > 255) {
+          return fail('auth-refused', CLOSE.AUTH_BAD_PASSWORD, 'the key is malformed (its id must be text of at most 255 bytes)', [closePacket(0, CLOSE.AUTH_BAD_PASSWORD)])
+        }
+      }
+      const mine = this.exts.filter((e) => this.server.has(e.id))
+      if (pw && this.password) mine.push(ext.passwordClient(this.password.user, this.password.pass))
+      this.state = 'wait-continue'
+      this.version = 2
+      const minor = m.version.major === 2 ? Math.min(m.version.minor, VERSION.minor) : VERSION.minor
+      return { send: [infoPacket(mine, { major: 2, minor })] }
+    }
+    if (this.state === 'wait-continue') {
+      if (m.id !== 0) return fail('protocol', CLOSE.UNKNOWN, 'the relay sent a stream packet before the handshake ended')
+      if (m.type === PT.CLOSE) return fail(closeState(m.reason), m.reason, closeWords(m.reason))
+      if (m.type !== PT.CONTINUE) return fail('protocol', CLOSE.UNKNOWN, 'the relay did not answer INFO with CONTINUE')
+      this.state = 'done'
+      const common = new Set(this.exts.filter((e) => this.server.has(e.id)).map((e) => e.id))
+      const motd = this.server.get(EXT.MOTD)?.motd || ''
+      return { send: [], done: { version: 2, buffer: m.n, server: this.server, common, motd } }
+    }
+    return fail('protocol', CLOSE.UNKNOWN, 'handshake packet after the handshake')
+  }
+}
+
+function closeState(reason) {
+  if (reason === CLOSE.AUTH_REQUIRED) return 'auth-required'
+  if (reason === CLOSE.AUTH_BAD_PASSWORD || reason === CLOSE.AUTH_BAD_SIGNATURE) return 'auth-refused'
+  if (reason === CLOSE.INCOMPATIBLE) return 'incompatible'
+  return 'protocol'
+}
+
+/**
+ * The server side. v2 is whether the request carried Sec-WebSocket-Protocol. `exts` are the
+ * extensions the server lists (built with `ext.*`, including `ext.passwordServer` when keys are
+ * on). start() returns the first packets; step(pkt) returns {send, client?} where `client` is the
+ * parsed client INFO ({exts: Map, common: Set, password, instance, version}) for the caller to
+ * accept() or reject(reason). For v1 the handshake is done after start().
+ */
+export class ServerHandshake {
+  constructor({ v2 = true, exts = [], buffer = 32 } = {}) {
+    this.v2 = v2
+    this.exts = exts
+    this.buffer = buffer
+    this.state = 'new'
+  }
+
+  start() {
+    if (!this.v2) {
+      this.state = 'done'
+      return { send: [continuePacket(0, this.buffer)], done: { version: 1, common: new Set() } }
+    }
+    this.state = 'wait-info'
+    return { send: [infoPacket(this.exts)] }
+  }
+
+  step(m) {
+    if (this.state !== 'wait-info') return { send: [], error: 'packet out of handshake order' }
+    if (m.error) return this.#reject(CLOSE.UNKNOWN, `malformed packet: ${m.error}`)
+    if (m.id !== 0) return this.#reject(CLOSE.UNKNOWN, 'stream packet before the handshake ended')
+    if (m.type === PT.CLOSE) {
+      this.state = 'failed'
+      return { send: [], error: `the client closed the handshake: ${closeWords(m.reason)}`, reason: m.reason }
+    }
+    if (m.type !== PT.INFO) return this.#reject(CLOSE.UNKNOWN, 'expected the client INFO')
+    if (m.version.major < 2) return this.#reject(CLOSE.INCOMPATIBLE, `the client speaks Wisp ${m.version.major}`)
+    const mine = new Set(this.exts.map((e) => e.id))
+    const exts = new Map()
+    for (const e of m.exts) {
+      const r = readExt(e, 'client')
+      if (r.error) return this.#reject(CLOSE.UNKNOWN, `malformed client extension 0x${e.id.toString(16)}: ${r.error}`)
+      exts.set(e.id, r)
+    }
+    const common = new Set([...exts.keys()].filter((id) => mine.has(id) && id !== EXT.PASSWORD))
+    const pw = exts.get(EXT.PASSWORD)
+    const pwRequired = this.exts.some((e) => e.id === EXT.PASSWORD && e.data && e.data[0])
+    const keyRequired = this.exts.some((e) => e.id === EXT.KEY && e.data && e.data[0])
+    // a required method the client did not use is refused here, never left to the caller
+    if ((pwRequired || keyRequired) && !(pw && mine.has(EXT.PASSWORD))) return this.#reject(CLOSE.AUTH_REQUIRED, 'the client sent no key')
+    this.state = 'decide'
+    return {
+      send: [],
+      client: {
+        version: m.version,
+        exts,
+        common,
+        password: pw && mine.has(EXT.PASSWORD) ? { user: pw.user, pass: pw.pass } : null,
+        instance: common.has(EXT.WMD_INSTANCE) ? exts.get(EXT.WMD_INSTANCE).instance : null,
+        window: common.has(EXT.WMD_CREDIT) ? exts.get(EXT.WMD_CREDIT).window : 0,
+      },
+    }
+  }
+
+  accept() {
+    this.state = 'done'
+    return [continuePacket(0, this.buffer)]
+  }
+
+  reject(reason) {
+    this.state = 'failed'
+    return [closePacket(0, reason)]
+  }
+
+  #reject(reason, error) {
+    this.state = 'failed'
+    return { send: [closePacket(0, reason)], error }
+  }
+}
+
+/** True for the wmd private extension ids (a peer that did not list one never gets its packets). */
+export const isWmdExt = (id) => WMD_EXTS.has(id)

package/src/registry/client.js

@@ -0,0 +1,176 @@
+// P-B7: the page's side of the pack host and the registry proxy.
+//
+//   const idx = await getImage('busybox', {pull: 'auto', onEvent})   // the image's index
+//   const packs = await fetchPacks(idx)                              // its packs, verified
+//
+// getImage asks the host for the image's index (/idx/...; through the service worker, so a
+// cached index answers when the host is gone). When the host has none (404) and `pull`
+// allows it, it asks the proxy to pull it (POST /pull, NDJSON events) and uses the index the
+// pull ends with. fetchPacks downloads each pack (/blobs/sha256/<hex>) and checks that its
+// bytes hash to its name.
+
+import { blobPath, checkImageIndex, DEFAULT_PLATFORM, indexPath, parseRef } from './ref.js'
+
+export class PullError extends Error {
+  constructor(message, kind) {
+    super(message)
+    this.name = 'PullError'
+    this.kind = kind // 'unreachable' | 'interrupted' | 'refused' | 'registry' | 'not-found' | 'verify'
+  }
+}
+
+const hex = buf => [...new Uint8Array(buf)].map(b => b.toString(16).padStart(2, '0')).join('')
+
+/** The image's index for a platform: from the host, else (pull 'auto'/'always') through the proxy. */
+export async function getImage(ref, { platform = DEFAULT_PLATFORM, pull = 'auto', base = '', onEvent = () => {}, signal } = {}) {
+  const r = parseRef(ref)
+  if (pull !== 'always') {
+    let res = null
+    try {
+      res = await fetch(`${base}/${indexPath(r, platform)}`, { cache: 'no-store', signal })
+    } catch (e) {
+      if (pull === 'never') throw new PullError(`${r.ref}: the host is unreachable and the index is not cached (${e.message})`, 'unreachable')
+    }
+    if (res?.ok) {
+      onEvent({ t: 'index', from: 'host' })
+      return checkImageIndex(await res.json())
+    }
+    if (res && res.status !== 404 && res.status !== 504) throw new PullError(`${r.ref}: the host answered ${res.status} for its index`, 'registry')
+    if (pull === 'never') throw new PullError(`${r.ref} (${platform}): not on this host`, 'not-found')
+  }
+  return pullThroughProxy(r.ref, { platform, base, onEvent, signal })
+}
+
+/** POST /pull and follow its events to the index (or a PullError). */
+export async function pullThroughProxy(ref, { platform = DEFAULT_PLATFORM, base = '', onEvent = () => {}, signal } = {}) {
+  let res
+  try {
+    res = await fetch(`${base}/pull?ref=${encodeURIComponent(ref)}&platform=${encodeURIComponent(platform)}`, { method: 'POST', cache: 'no-store', signal })
+  } catch (e) {
+    throw new PullError(`${ref}: the registry proxy is unreachable (${e.message}); try again when it is back`, 'unreachable')
+  }
+  if (!res.ok) {
+    const j = await res.json().catch(() => ({}))
+    throw new PullError(`${ref}: the proxy refused the pull: ${j.error || res.status}`, res.status === 503 ? 'unreachable' : 'refused')
+  }
+  const reader = res.body.getReader()
+  const dec = new TextDecoder()
+  let buf = ''
+  let events = 0
+  for (;;) {
+    let chunk
+    try {
+      chunk = await reader.read()
+    } catch (e) {
+      throw new PullError(`${ref}: the connection to the proxy broke during the pull (after ${events} events: ${e.message}); try again`, 'interrupted')
+    }
+    if (chunk.done) break
+    buf += dec.decode(chunk.value, { stream: true })
+    let nl
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl)
+      buf = buf.slice(nl + 1)
+      if (!line.trim()) continue
+      const e = JSON.parse(line)
+      events++
+      onEvent(e)
+      if (e.t === 'done') return checkImageIndex(e.index)
+      // the proxy's messages name the image already
+      if (e.t === 'error') throw new PullError(e.message.includes(ref) ? e.message : `${ref}: ${e.message}`, e.status === 404 ? 'not-found' : 'registry')
+    }
+  }
+  throw new PullError(`${ref}: the proxy ended the pull without a result (after ${events} events); try again`, 'interrupted')
+}
+
+/**
+ * Downloads the image's packs (top first, as the index lists them) and checks each against
+ * its digest (verify: false skips the hash; the service worker checks before it caches).
+ * @returns {Promise<{packs: Uint8Array[], sources: string[], bytes: number, fetchMs: number, hashMs: number}>}
+ * (sources: 'cache' when the service worker answered from its cache, else 'network')
+ */
+export async function fetchPacks(index, { base = '', verify = true, signal, onPack = () => {} } = {}) {
+  const t0 = performance.now()
+  let hashMs = 0
+  const sources = []
+  const packs = await Promise.all(
+    index.layers.map(async (l, i) => {
+      let res
+      try {
+        res = await fetch(`${base}/${blobPath(l.pack)}`, { cache: 'no-store', signal })
+      } catch (e) {
+        throw new PullError(`pack ${i} (${l.pack.slice(7, 19)}): unreachable (${e.message})`, 'unreachable')
+      }
+      if (!res.ok) throw new PullError(`pack ${i} (${l.pack.slice(7, 19)}): ${res.status} ${(await res.text().catch(() => '')).trim()}`, res.status === 502 ? 'verify' : 'unreachable')
+      let buf
+      try {
+        buf = await res.arrayBuffer()
+      } catch (e) {
+        throw new PullError(`pack ${i} (${l.pack.slice(7, 19)}): the transfer broke (${e.message})`, 'interrupted')
+      }
+      if (buf.byteLength !== l.size) throw new PullError(`pack ${i} (${l.pack.slice(7, 19)}): ${buf.byteLength} bytes, the index says ${l.size}`, 'verify')
+      if (verify) {
+        const h0 = performance.now()
+        const got = hex(await crypto.subtle.digest('SHA-256', buf))
+        hashMs += performance.now() - h0
+        if (`sha256:${got}` !== l.pack) throw new PullError(`pack ${i}: bytes hash to sha256:${got.slice(0, 12)}, not ${l.pack.slice(0, 19)}; refused`, 'verify')
+      }
+      sources[i] = res.headers.get('X-Wmd-Source') || 'network'
+      onPack(i, buf.byteLength)
+      return new Uint8Array(buf)
+    }),
+  )
+  return { packs, sources, bytes: packs.reduce((a, p) => a + p.length, 0), fetchMs: Math.round(performance.now() - t0), hashMs: Math.round(hashMs) }
+}
+
+/**
+ * Registers the service worker (scope /) and waits until it controls this page, then asks it
+ * to cache the page's own files (they loaded before it was in control).
+ */
+export async function useServiceWorker({ url = '/sw.js', timeoutMs = 30_000 } = {}) {
+  if (!('serviceWorker' in navigator)) throw new Error('no service worker support in this browser')
+  const reg = await navigator.serviceWorker.register(url, { scope: '/' })
+  if (!navigator.serviceWorker.controller) {
+    await new Promise((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error(`the service worker did not take control within ${timeoutMs} ms`)), timeoutMs)
+      navigator.serviceWorker.addEventListener('controllerchange', () => {
+        clearTimeout(t)
+        resolve()
+      }, { once: true })
+    })
+  }
+  const urls = [location.href, ...performance.getEntriesByType('resource').map(e => e.name)].filter(u => {
+    const p = new URL(u, location.href)
+    return p.origin === location.origin && !p.pathname.startsWith('/blobs/') && p.pathname !== '/pull' && !p.pathname.startsWith('/idx/')
+  })
+  const warmed = await swCall({ t: 'warm', urls })
+  // Ask the browser not to evict the caches (Safari deletes a site's script-writable storage
+  // after 7 days without a visit unless the site is installed or persistent; Chromium and Firefox
+  // may evict under disk pressure). The answer is recorded; the app works either way (a first
+  // visit online fills the caches again).
+  // Firefox may show a permission prompt and not answer until the user does: never wait for it
+  // for long (2 s), and let the answer come on its own.
+  let persisted = null
+  try {
+    persisted = await Promise.race([navigator.storage?.persist?.() ?? null, new Promise(r => setTimeout(() => r('pending'), 2000))])
+  } catch {}
+  return { reg, warmed: warmed.n, persisted }
+}
+
+let swSeq = 0
+/** A request to the controlling service worker, answered by id. */
+export function swCall(msg, timeoutMs = 120_000) {
+  const sw = navigator.serviceWorker.controller
+  if (!sw) return Promise.reject(new Error('no controlling service worker'))
+  const id = ++swSeq
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(`service worker: no answer to ${msg.t}`)), timeoutMs)
+    const f = e => {
+      if (e.data?.id !== id) return
+      clearTimeout(t)
+      navigator.serviceWorker.removeEventListener('message', f)
+      resolve(e.data)
+    }
+    navigator.serviceWorker.addEventListener('message', f)
+    sw.postMessage({ ...msg, id })
+  })
+}