@factoidal/core 0.20.0 → 0.21.0

package/webdav/server.mjs

@@ -15,11 +15,31 @@
 //   `webdavStep`, then carry what the engine answers: an `lws` request to
 //   the local storage it names (no socket: the storage handle's own step),
 //   a `fetch` to the URL it names, until it answers a `response`, which
-//   this file writes back.
+//   this file writes back; when the response carries `write` (the state
+//   file `.webdav-state.json`: dead properties and locks), replace that file
+//   first (a new file in the same directory, mode 0600, then a rename);
+// * with a users file (`--users`, https://github.com/danbri/factoidal/issues/1108),
+//   give its path to `webdavOpen` and the bytes the engine names; when the
+//   engine answers `need` (a login: one PBKDF2-HMAC-SHA256 derivation), run
+//   exactly that WebCrypto call (`answerCipherRequest`, lib/cipher-host.mjs)
+//   and give the answer to `webdavResume`; give each request's client
+//   address (the socket's `remoteAddress`) to `webdavStep`, for the
+//   failed-login limit the engine keeps
+//   (https://github.com/danbri/factoidal/issues/1119); pass the limit
+//   options unread and print the `warnings` of `ready`;
+// * with `--cert` and `--key`, listen with Node `https` (TLS) instead of
+//   `http`;
+// * with `--guest NAME` (https://github.com/danbri/factoidal/issues/1147),
+//   pass the name unread: the engine decides that a request with no
+//   credentials acts as that user, and which mounts each user reaches.
+//
+// Expert review of the login: https://github.com/danbri/factoidal/issues/1117
 //
 // It makes NO protocol decision. Which files are mounts, what a mount file
 // says, every status code, header field, XML body, lock, property and path
-// mapping is decided in formal/lean4/L4Factoidal/WebDAV/ (iron rule 7 of
+// mapping, every login decision (which users file lines count, whether a
+// password matches, the login cache, whether Basic may run on this address)
+// is decided in formal/lean4/L4Factoidal/WebDAV/ (iron rule 7 of
 // CLAUDE.md). The one status code written here is 500, for a failure of
 // this host itself. Requests are served one at a time (a queue), because
 // the engine keeps one request in flight per handle.
@@ -27,14 +47,17 @@
 // THE WASM CONTRACT (formal/lean4/Wasm/Ops/WebDAV.lean)
 //   webdavOpen   [configJson]                 -> { ok, handle, need }
 //   webdavLoad   [handle, filesJson]          -> { ok, need } | { ok, ready }
-//   webdavStep   [handle, requestJson] + body -> { ok, response | lws | fetch } + body
-//   webdavResume [handle, answerJson]  + body -> { ok, response | lws | fetch } + body
+//   webdavStep   [handle, requestJson] + body -> { ok, response [+ write] | lws | fetch | need } + body
+//   webdavResume [handle, answerJson]  + body -> { ok, response | lws | fetch | need } + body
 //   webdavClose  [handle]                     -> { ok }
 
-import { readFileSync, readdirSync, writeFileSync, existsSync } from 'node:fs'
-import { resolve as resolvePath } from 'node:path'
+import {
+  readFileSync, readdirSync, writeFileSync, existsSync, openSync, writeSync, fsyncSync, closeSync, renameSync, unlinkSync
+} from 'node:fs'
+import { resolve as resolvePath, dirname, basename, join } from 'node:path'
 import { loadEngine } from '../bin/engine.mjs'
 import { openLwsStorage } from '../lws/server.mjs'
+import { answerCipherRequest } from '../lib/cipher-host.mjs'
 
 /** The ops this host needs from the engine. */
 export const WEBDAV_OPS = ['webdavOpen', 'webdavLoad', 'webdavStep', 'webdavResume', 'webdavClose']
@@ -107,12 +130,45 @@ function gather (configDir, need) {
   return { files, exists }
 }
 
+/**
+ * Replace a file the engine named (`write` on a response) atomically: write
+ * a new file in the same directory, flush it, then rename it over the old
+ * one, so a crash leaves the old text or the new text. Pure I/O.
+ */
+function replaceFile (configDir, write) {
+  const target = resolvePath(configDir, write.path)
+  const suffix = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(6))).toString('hex')
+  const temp = join(dirname(target), `.${basename(target)}.${process.pid}.${suffix}.tmp`)
+  const fd = openSync(temp, 'wx', parseInt(write.mode, 8))
+  try {
+    writeSync(fd, write.text)
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  try {
+    renameSync(temp, target)
+  } catch (error) {
+    try { unlinkSync(temp) } catch (_error) { /* already gone */ }
+    throw error
+  }
+}
+
 /**
  * Open a WebDAV server handle over the mount files of `configDir`.
  *
  * @param {object} options
  * @param {string} options.configDir the directory of mount files
  * @param {object} [options.engine] an engine handle to reuse
+ * @param {string} [options.users] the users file (an absolute path, or one
+ *   relative to configDir): the listener then needs a login
+ * @param {boolean} [options.tls] the listener uses TLS
+ * @param {string} [options.host] the address the listener binds
+ * @param {string} [options.loginLimit] `--login-limit`, passed unread
+ * @param {string} [options.loginWindow] `--login-window`, passed unread
+ * @param {boolean} [options.disableRateLimits] `--dangerously-disable-ratelimits`
+ * @param {string} [options.guest] `--guest NAME`: the user a request with no
+ *   credentials acts as (passed unread)
  * @returns {Promise<{handle: string, mounts: object[], step: Function, close: Function}>}
  */
 export async function openWebdav (options = {}) {
@@ -120,7 +176,22 @@ export async function openWebdav (options = {}) {
   const configDir = options.configDir
   const engine = options.engine !== undefined ? options.engine : await loadEngine()
   const listing = readdirSync(configDir)
-  let envelope = callEngine(engine, 'webdavOpen', [JSON.stringify({ listing, entropy: randomBase64(32) })])
+  const login = {
+    users: typeof options.users === 'string' ? options.users : null,
+    tls: options.tls === true,
+    host: typeof options.host === 'string' ? options.host : '127.0.0.1',
+    limit: typeof options.loginLimit === 'string' ? options.loginLimit : null,
+    window: typeof options.loginWindow === 'string' ? options.loginWindow : null,
+    disableRateLimits: options.disableRateLimits === true
+  }
+  // The guest user (issue 1147), passed unread; the engine checks it.
+  if (typeof options.guest === 'string') login.guest = options.guest
+  const config = { listing, entropy: randomBase64(32), now: nowSeconds(), login }
+  // The Host and Origin guard of the HTTP listener (issue 1124): the bound
+  // address and the operator's names and origins, passed unread
+  // (L4Factoidal/HTTP/LocalGuard.lean decides).
+  if (options.localGuard !== undefined && options.localGuard !== null) config.localGuard = options.localGuard
+  let envelope = callEngine(engine, 'webdavOpen', [JSON.stringify(config)])
   if (envelope.ok === false) throw new WebdavHostError(envelope.error, { envelope })
   const handle = envelope.handle
   let loads = 0
@@ -137,10 +208,25 @@ export async function openWebdav (options = {}) {
   }
   // Each local storage, opened as lws-serve opens it; the config is the
   // engine's, passed unread.
+  // Each takes the lock of its directory (one writing process per storage
+  // directory, https://github.com/danbri/factoidal/issues/1135): a directory
+  // that lws-serve or another webdav-serve holds stops the start, and the
+  // locks of the mounts opened before it are released.
   const storages = new Map()
-  for (const l of ready.local || []) {
-    const storage = await openLwsStorage({ engine, dir: resolvePath(configDir, l.dir), ...l.config, realClock: true })
-    storages.set(l.name, storage)
+  const storageNotices = []
+  try {
+    for (const l of ready.local || []) {
+      const storage = await openLwsStorage({ engine, dir: resolvePath(configDir, l.dir), ...l.config, realClock: true, lockCommand: 'webdav-serve' })
+      storages.set(l.name, storage)
+      for (const n of storage.notices || []) storageNotices.push(`mount ${l.name}: ${n}`)
+    }
+  } catch (error) {
+    for (const s of storages.values()) s.close()
+    try { engine.call('webdavClose', [handle]) } catch (_error) { /* already gone */ }
+    if (error !== null && typeof error === 'object' && error.envelope !== undefined && !(error instanceof WebdavHostError)) {
+      throw new WebdavHostError(error.envelope.error, { envelope: error.envelope })
+    }
+    throw error
   }
 
   /** Carry one `fetch` the engine named. Pure I/O. */
@@ -168,12 +254,14 @@ export async function openWebdav (options = {}) {
       target: request.target,
       headers: request.headers,
       now: nowSeconds(),
-      randomBase64: randomBase64(16)
+      randomBase64: randomBase64(16),
+      remoteAddress: typeof request.remoteAddress === 'string' ? request.remoteAddress : ''
     }
     let got = blobCall(engine, 'webdavStep', [handle, JSON.stringify(record)], request.body || new Uint8Array(0))
     for (let hop = 0; hop < MAX_HOPS; hop += 1) {
       const env = got.envelope
       if (env.response !== undefined) {
+        if (env.write !== undefined) replaceFile(configDir, env.write)
         return { status: env.response.status, headers: env.response.headers || [], body: got.bytes }
       }
       let answer
@@ -189,8 +277,12 @@ export async function openWebdav (options = {}) {
         const x = await exchange(env.fetch, got.bytes)
         answer = x.answer
         bytes = x.bytes
+      } else if (env.need !== undefined) {
+        // A login: the one WebCrypto derivation the engine named.
+        answer = await answerCipherRequest(env.need)
+        bytes = new Uint8Array(0)
       } else {
-        throw new WebdavHostError('the engine answered neither response, lws nor fetch')
+        throw new WebdavHostError('the engine answered neither response, lws, fetch nor need')
       }
       got = blobCall(engine, 'webdavResume', [handle, JSON.stringify(answer)], bytes)
     }
@@ -201,9 +293,13 @@ export async function openWebdav (options = {}) {
     handle,
     engine,
     mounts: ready.mounts || [],
+    warnings: ready.warnings || [],
+    /** The start notices of the local mounts (a stale lock taken over,
+     *  encryption at rest on or off), for standard error. */
+    storageNotices,
     /**
      * One request, served after the requests before it.
-     * @param {{method: string, target: string, headers: Array<[string, string]>, body: Uint8Array}} request
+     * @param {{method: string, target: string, headers: Array<[string, string]>, body: Uint8Array, remoteAddress?: string}} request
      */
     step (request) {
       const run = queue.then(() => serve(request))
@@ -217,6 +313,16 @@ export async function openWebdav (options = {}) {
   }
 }
 
+/** The addresses of this machine's interfaces. Pure I/O. */
+async function interfaceAddresses () {
+  try {
+    const os = await import('node:os')
+    return Object.values(os.networkInterfaces()).flat().filter(Boolean).map((i) => i.address)
+  } catch (_error) {
+    return []
+  }
+}
+
 function readBody (request) {
   return new Promise((resolve, reject) => {
     const chunks = []
@@ -246,20 +352,36 @@ function writeHeaders (response, pairs) {
  * Start the server: open the handle, then listen.
  *
  * @param {object} options `configDir`, `port` (default 8090), `host`
- *   (default 127.0.0.1), `engine`, `onError`
+ *   (default 127.0.0.1), `engine`, `onError`, `users` (a users file),
+ *   `cert` and `key` (PEM bytes: listen with TLS), `loginLimit`,
+ *   `loginWindow`, `disableRateLimits` (the failed-login limit)
  * @returns {Promise<{server: object, port: number, origin: string, mounts: object[], close: Function}>}
  */
 export async function listen (options = {}) {
-  const http = await import('node:http')
-  const dav = await openWebdav(options)
+  const tls = options.cert !== undefined && options.key !== undefined
+  const http = tls ? await import('node:https') : await import('node:http')
+  const host = typeof options.host === 'string' ? options.host : '127.0.0.1'
+  const localGuard = {
+    host,
+    addresses: await interfaceAddresses(),
+    ...(Array.isArray(options.allowHosts) ? { allowHosts: options.allowHosts } : {}),
+    ...(Array.isArray(options.allowOrigins) ? { allowOrigins: options.allowOrigins } : {})
+  }
+  const dav = await openWebdav({ ...options, tls, host, localGuard })
   const onError = typeof options.onError === 'function'
     ? options.onError
     : (error) => { console.error(`webdav-serve: ${error.message}`) }
-  const server = http.createServer(async (request, response) => {
+  const handler = async (request, response) => {
     let answer
     try {
       const body = await readBody(request)
-      answer = await dav.step({ method: request.method, target: request.url, headers: headerPairs(request.rawHeaders), body })
+      answer = await dav.step({
+        method: request.method,
+        target: request.url,
+        headers: headerPairs(request.rawHeaders),
+        body,
+        remoteAddress: request.socket.remoteAddress
+      })
     } catch (error) {
       onError(error)
       response.writeHead(500, { 'content-type': 'text/plain' })
@@ -269,20 +391,27 @@ export async function listen (options = {}) {
     writeHeaders(response, answer.headers)
     response.statusCode = answer.status
     response.end(answer.body)
-  })
+  }
+  const server = tls ? http.createServer({ cert: options.cert, key: options.key }, handler) : http.createServer(handler)
   const port = typeof options.port === 'number' ? options.port : 8090
-  const host = typeof options.host === 'string' ? options.host : '127.0.0.1'
-  await new Promise((resolve, reject) => {
-    server.once('error', reject)
-    server.listen(port, host, resolve)
-  })
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject)
+      server.listen(port, host, resolve)
+    })
+  } catch (error) {
+    dav.close()
+    throw error
+  }
   const bound = server.address()
-  const origin = `http://${host.includes(':') ? `[${host}]` : host}:${bound.port}`
+  const origin = `${tls ? 'https' : 'http'}://${host.includes(':') ? `[${host}]` : host}:${bound.port}`
   return {
     server,
     port: bound.port,
     origin,
     mounts: dav.mounts,
+    warnings: dav.warnings,
+    storageNotices: dav.storageNotices,
     close () {
       return new Promise((resolve) => {
         server.close(() => { dav.close(); resolve() })

package/xmpp/client.mjs

@@ -0,0 +1,332 @@
+// factoidal/xmpp/client.mjs — an OUTGOING XMPP client connection that
+// carries HTTP over XMPP (XEP-0332), in one of two modes.
+// https://github.com/danbri/factoidal/issues/1107. Design record:
+// docs/designissues/2026-10-28-http-over-xmpp.md.
+//
+//   connectHttpTarget     (step 1, `factoidal webdav-serve CONFIGDIR --xmpp JID`)
+//                         serves XEP-0332 requests with a local `step` function
+//   connectHttpRequester  (step 2, `factoidal xmpp-http-proxy`) sends XEP-0332
+//                         requests to ONE target JID and gives back responses
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Open one TCP socket, or one direct-TLS socket (XEP-0368), to an XMPP
+// server; give every text it reads to the engine (`xmppClientFeed`); write
+// every text the engine answers (`send`); carry each HTTP request the engine
+// names (`requests`) to the caller's `step` function and give the response
+// back (`xmppClientAnswer`); in requester mode, give each HTTP request to the
+// engine (`xmppClientRequest`), give it the clock (`xmppClientTick`) and
+// resolve each response the engine names (`responses`); close the socket when
+// the engine says `close`.
+//
+// It makes NO protocol decision. The stream negotiation, SASL SCRAM-SHA-256,
+// the check of the server signature, resource binding, which stanza is an
+// HTTP request or response, who may send one (the allow list), the target,
+// the refusals and limits, timeouts, chunked bodies and every status are
+// decided in formal/lean4/L4Factoidal/XMPP/ (ClientStream, HttpOverXmpp,
+// HttpRequester) and formal/lean4/Wasm/Ops/XmppClient.lean (iron rule 7 of
+// CLAUDE.md). The host supplies the SCRAM client nonce (random bytes) and the
+// clock, and moves bytes.
+//
+// THE WASM CONTRACT (formal/lean4/Wasm/Ops/XmppClient.lean)
+//   xmppClientOpen    [configJson]                 -> { ok, handle, send, ... }
+//   xmppClientFeed    [handle, text]               -> { ok, send, requests, responses, bound, close, reason, stage, bufferedBytes }
+//   xmppClientAnswer  [handle, id, responseJson]   -> { ok, send }
+//   xmppClientRequest [handle, nowMs, requestJson] -> { ok, id, send, responses }
+//   xmppClientTick    [handle, nowMs]              -> { ok, send, responses }
+//   xmppClientClose   [handle]                     -> { ok, send, responses }
+
+import { randomBytes } from 'node:crypto'
+import { StringDecoder } from 'node:string_decoder'
+import { loadEngine } from '../bin/engine.mjs'
+
+/** The ops this host needs from the engine. */
+export const XMPP_CLIENT_OPS = ['xmppClientOpen', 'xmppClientFeed', 'xmppClientAnswer', 'xmppClientClose',
+  'xmppClientRequest', 'xmppClientTick']
+
+/** An error of this host, as opposed to one the engine reported. */
+export class XmppClientError extends Error {
+  constructor (message, detail = {}) {
+    super(message)
+    this.name = 'XmppClientError'
+    this.unknownOp = detail.unknownOp === true
+  }
+}
+
+function call (engine, op, args) {
+  let envelope
+  try {
+    envelope = engine.call(op, args)
+  } catch (error) {
+    const text = error && error.message ? String(error.message) : String(error)
+    if (text.indexOf('unknown op') >= 0) {
+      throw new XmppClientError(`the loaded l4factoidal WebAssembly module does not carry ${op}`, { unknownOp: true })
+    }
+    throw error
+  }
+  if (envelope === null || typeof envelope !== 'object') throw new XmppClientError(`${op} answered with no envelope`)
+  if (envelope.ok === false) throw new XmppClientError(`${op}: ${envelope.error}`)
+  return envelope
+}
+
+/** The configuration fields both modes share; values go to the engine unread. */
+function baseConfig (options) {
+  const config = {
+    jid: options.jid,
+    password: typeof options.password === 'string' ? options.password : '',
+    clientNonce: randomBytes(24).toString('base64url'),
+    tls: options.tls === true
+  }
+  if (typeof options.host === 'string') config.host = options.host
+  if (typeof options.resource === 'string') config.resource = options.resource
+  if (typeof options.minIterations === 'number') config.minIterations = options.minIterations
+  return config
+}
+
+/**
+ * Open the engine handle and the socket; run the stream until it is bound.
+ * `onFeed(answer)` gets every `xmppClientFeed` envelope after the bytes it
+ * names are written. Pure byte moving.
+ */
+async function openStream (engine, config, options, onFeed, onClosed) {
+  const onError = typeof options.onError === 'function' ? options.onError : () => {}
+  const maxBuffered = typeof options.maxBuffered === 'number' ? options.maxBuffered : 16 * 1024 * 1024
+  const opened = call(engine, 'xmppClientOpen', [JSON.stringify(config)])
+  const handle = opened.handle
+  const domain = opened.domain
+  if (typeof domain !== 'string') throw new XmppClientError('xmppClientOpen answered with no domain; rebuild the engine')
+  const host = opened.host
+  const port = typeof options.port === 'number' ? options.port : (options.tls === true ? 5223 : 5222)
+
+  let socket
+  if (options.tls === true) {
+    const tls = await import('node:tls')
+    socket = tls.connect({ host, port, servername: domain, ...(options.tlsOptions || {}) })
+  } else {
+    const net = await import('node:net')
+    socket = net.connect({ host, port })
+  }
+
+  let open = true
+  let boundJid = null
+  let resolveBound
+  let rejectBound
+  const bound = new Promise((resolve, reject) => { resolveBound = resolve; rejectBound = reject })
+  let resolveClosed
+  const closed = new Promise((resolve) => { resolveClosed = resolve })
+
+  function write (texts) {
+    for (const t of texts || []) if (!socket.destroyed) socket.write(t)
+  }
+
+  function finish (reason) {
+    if (!open) return
+    open = false
+    let closing = null
+    try { closing = call(engine, 'xmppClientClose', [handle]) } catch (_error) { /* already gone */ }
+    if (!socket.destroyed) socket.end()
+    if (boundJid === null) rejectBound(new XmppClientError(reason || 'the XMPP connection closed before binding'))
+    if (closing !== null && typeof onClosed === 'function') onClosed(closing)
+    resolveClosed(reason || '')
+  }
+
+  const decoder = new StringDecoder('utf8')
+  socket.on('connect', () => write(opened.send))
+  socket.on('secureConnect', () => {})
+  socket.on('data', (chunk) => {
+    if (!open) return
+    const text = decoder.write(chunk)
+    if (text.length === 0) return
+    let answer
+    try {
+      answer = call(engine, 'xmppClientFeed', [handle, text])
+    } catch (error) {
+      onError(error)
+      socket.destroy()
+      finish(error.message)
+      return
+    }
+    write(answer.send)
+    if (typeof answer.bound === 'string' && boundJid === null) {
+      boundJid = answer.bound
+      resolveBound(boundJid)
+    }
+    onFeed(answer)
+    if (answer.close === true) finish(answer.reason)
+    else if (answer.bufferedBytes > maxBuffered) {
+      onError(new XmppClientError(`the server sent more than ${maxBuffered} bytes without completing a stanza`))
+      finish('buffer limit')
+    }
+  })
+  socket.on('error', (error) => { onError(error); finish(error.message) })
+  socket.on('close', () => finish('the server closed the connection'))
+
+  return {
+    opened,
+    handle,
+    bound,
+    closed,
+    write,
+    isOpen: () => open,
+    close () {
+      if (open && !socket.destroyed) {
+        try {
+          const closing = call(engine, 'xmppClientClose', [handle])
+          write(closing.send)
+          if (typeof onClosed === 'function') onClosed(closing)
+        } catch (_error) { /* gone */ }
+      }
+      finish('')
+      return closed
+    }
+  }
+}
+
+/**
+ * Connect to an XMPP server as `jid` and serve HTTP over XMPP with `step`.
+ * Resolves once the resource is bound (or rejects with the engine's reason).
+ *
+ * @param {object} options
+ * @param {string} options.jid the account, `user@domain` (a resource may follow `/`)
+ * @param {string} options.password
+ * @param {string} [options.host] the XMPP server's address (default: the JID's domain; no SRV lookup)
+ * @param {number} [options.port] default 5222, or 5223 with `tls`
+ * @param {boolean} [options.tls] direct TLS (XEP-0368); without it the engine allows plain TCP to a loopback address only
+ * @param {object} [options.tlsOptions] passed to `tls.connect` (for example `ca`)
+ * @param {string[]} [options.allow] bare JIDs that may send requests
+ * @param {string} [options.resource]
+ * @param {object[]} [options.mounts] the WebDAV handle's mounts, passed unread (the engine refuses writable local mounts without the opt-in)
+ * @param {boolean} [options.dangerouslyAllowWritableWithoutLogin]
+ * @param {Function} options.step `async ({method, target, headers, body}) => ({status, headers, body})`
+ * @param {object} [options.engine]
+ * @param {Function} [options.onError]
+ * @param {number} [options.maxBuffered] residual bytes the engine may hold before the socket is closed (default 16 MiB)
+ * @returns {Promise<{jid: string, closed: Promise<string>, close: Function}>}
+ */
+export async function connectHttpTarget (options = {}) {
+  if (typeof options.step !== 'function') throw new XmppClientError('connectHttpTarget needs step')
+  if (typeof options.jid !== 'string') throw new XmppClientError('connectHttpTarget needs jid')
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const onError = typeof options.onError === 'function' ? options.onError : () => {}
+  const config = baseConfig(options)
+  config.allow = Array.isArray(options.allow) ? options.allow : []
+  if (Array.isArray(options.mounts)) config.mounts = options.mounts
+  if (options.dangerouslyAllowWritableWithoutLogin === true) config.dangerouslyAllowWritableWithoutLogin = true
+
+  let stream = null
+  /** One request the engine named: carried to `step`, answered. */
+  async function carry (request) {
+    let answer
+    try {
+      const response = await options.step({
+        method: request.method,
+        target: request.target,
+        headers: request.headers || [],
+        body: new Uint8Array(Buffer.from(request.bodyBase64 || '', 'base64'))
+      })
+      answer = {
+        status: response.status,
+        headers: response.headers || [],
+        bodyBase64: Buffer.from(response.body || new Uint8Array(0)).toString('base64')
+      }
+    } catch (error) {
+      onError(error)
+      answer = { status: 500, headers: [['content-type', 'text/plain']], bodyBase64: Buffer.from(`host error: ${error.message}\n`).toString('base64') }
+    }
+    if (stream === null || !stream.isOpen()) return
+    try {
+      stream.write(call(engine, 'xmppClientAnswer', [stream.handle, String(request.id), JSON.stringify(answer)]).send)
+    } catch (error) {
+      onError(error)
+    }
+  }
+  stream = await openStream(engine, config, options, (answer) => {
+    for (const r of answer.requests || []) carry(r)
+  })
+  const jid = await stream.bound
+  return {
+    jid,
+    writableWithoutLogin: stream.opened.writableWithoutLogin || [],
+    closed: stream.closed,
+    close: () => stream.close()
+  }
+}
+
+/**
+ * Connect to an XMPP server as `jid` and send HTTP requests over XMPP to
+ * `target` (a full JID) and to no other entity. Resolves once the resource is
+ * bound. `request()` resolves with the response the engine names: from the
+ * target, or one the engine made (a refusal, 502, 504).
+ *
+ * @param {object} options the connection options of `connectHttpTarget`, without `allow`, `mounts` and `step`
+ * @param {string} options.target the full JID of the serving side
+ * @param {string} options.listenHost the address the caller will listen on (the engine accepts 127.0.0.1 only)
+ * @param {number} [options.timeoutSeconds] how long a request waits (the engine accepts 1 to 3600; default 60)
+ * @param {number} [options.tickMs] how often the clock is given to the engine (default 500)
+ * @returns {Promise<{jid: string, target: string, listenHost: string, maxBodyBytes: number,
+ *   request: Function, closed: Promise<string>, close: Function}>}
+ */
+export async function connectHttpRequester (options = {}) {
+  if (typeof options.jid !== 'string') throw new XmppClientError('connectHttpRequester needs jid')
+  if (typeof options.target !== 'string') throw new XmppClientError('connectHttpRequester needs target')
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const config = baseConfig(options)
+  config.proxyTarget = options.target
+  config.listenHost = typeof options.listenHost === 'string' ? options.listenHost : ''
+  if (typeof options.timeoutSeconds === 'number') config.timeoutSeconds = options.timeoutSeconds
+
+  const waiting = new Map()
+  function deliver (responses) {
+    for (const r of responses || []) {
+      const resolve = waiting.get(r.id)
+      if (resolve === undefined) continue
+      waiting.delete(r.id)
+      resolve({
+        status: r.status,
+        headers: r.headers || [],
+        body: new Uint8Array(Buffer.from(r.bodyBase64 || '', 'base64'))
+      })
+    }
+  }
+  const stream = await openStream(engine, config, options,
+    (answer) => deliver(answer.responses),
+    (closing) => deliver(closing.responses))
+  const jid = await stream.bound
+  const timer = setInterval(() => {
+    if (!stream.isOpen()) return
+    try {
+      const t = call(engine, 'xmppClientTick', [stream.handle, String(Date.now())])
+      stream.write(t.send)
+      deliver(t.responses)
+    } catch (_error) { /* handle gone */ }
+  }, typeof options.tickMs === 'number' ? options.tickMs : 500)
+  stream.closed.then(() => clearInterval(timer))
+
+  return {
+    jid,
+    target: stream.opened.target,
+    listenHost: stream.opened.listenHost,
+    maxBodyBytes: Number(stream.opened.maxBodyBytes),
+    closed: stream.closed,
+    /** `{method, target, headers: [[n, v]...], body: Uint8Array}` -> `{status, headers, body}` */
+    request (req) {
+      return new Promise((resolve, reject) => {
+        let answer
+        try {
+          answer = call(engine, 'xmppClientRequest', [stream.handle, String(Date.now()), JSON.stringify({
+            method: req.method,
+            target: req.target,
+            headers: req.headers || [],
+            bodyBase64: Buffer.from(req.body || new Uint8Array(0)).toString('base64')
+          })])
+        } catch (error) {
+          reject(error)
+          return
+        }
+        waiting.set(answer.id, resolve)
+        stream.write(answer.send)
+        deliver(answer.responses)
+      })
+    },
+    close: () => { clearInterval(timer); return stream.close() }
+  }
+}