@factoidal/core 0.32.0 → 0.34.0

package/xmpp/server.mjs

@@ -37,13 +37,26 @@
 // server-to-server federation, and any limit on how many bytes
 // a client may send without completing a unit beyond `maxBuffered`,
 // which is a transport limit this host applies by closing the socket.
-// The other transport limits are `maxConnections`, `loginTimeoutMs` and
-// `maxQueuedBytes`. There is no limit per address: behind a proxy, every
-// client has the same one.
+// The other transport limits are `maxConnections`, `loginTimeoutMs`,
+// `maxQueuedBytes`, and `pingIntervalMs` with `pingTimeoutMs`: a bound session
+// silent for the interval gets a ping from the engine (`xmppSessionPing`, or
+// `xmppWsPing` on a WebSocket), and one that sends no byte in the timeout after
+// that is closed. There is no connection limit per address: behind a
+// proxy, every client has the same one.
+//
+// Client addresses (the failed-login limit): the engine keeps a tag of each,
+// HMAC-SHA-256 under `addressKey`, a random key made here at start and kept in
+// memory only (`L4Factoidal/Net/LoginLimit.lean`, `addressTag`). Logs show the
+// first 12 digits of the tag, never the address. With `proxyProtocol` each
+// connection must start with a PROXY protocol v2 header, which names the client
+// behind a proxy; the engine decides on it (`proxyHeaderParse`,
+// `L4Factoidal/Net/ProxyProtocol.lean`) and this file only buffers the bytes,
+// then hands what follows the header to TLS or to the XMPP session.
 
-import { randomBytes } from 'node:crypto'
+import { createHash, randomBytes } from 'node:crypto'
 import { StringDecoder } from 'node:string_decoder'
-import { mkdir, readFile, writeFile, readdir, unlink, rename } from 'node:fs/promises'
+import { Duplex } from 'node:stream'
+import { mkdir, readFile, writeFile, readdir, unlink, rename, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import { loadEngine } from '../bin/engine.mjs'
 import { createXmppRouter } from './router.mjs'
@@ -51,8 +64,8 @@ import { createXmppRouter } from './router.mjs'
 /** The ops this host needs from the engine. */
 export const XMPP_SERVER_OPS = [
   'xmppOpen', 'xmppClose',
-  'xmppSessionOpen', 'xmppSessionFeed', 'xmppSessionDeliver', 'xmppSessionClose',
-  'xmppSessionTlsUp', 'xmppRosterGet', 'xmppRosterSet', 'xmppWsOpen', 'xmppStateLoad'
+  'xmppSessionOpen', 'xmppSessionFeed', 'xmppSessionDeliver', 'xmppSessionPing', 'xmppSessionClose',
+  'xmppSessionTlsUp', 'xmppRosterGet', 'xmppRosterSet', 'xmppWsOpen', 'xmppStateLoad', 'xmppClock'
 ]
 
 /** An error raised by this host, as opposed to one the engine reported.
@@ -119,10 +132,19 @@ function randomToken (bytes = 18) {
  * @param {object} options
  * @param {string} [options.domain] the domain the server is authoritative for (default `localhost`)
  * @param {Array<{username: string, password: string}>} [options.accounts]
- * @param {string} [options.accountsText] `user:password` lines, the harness's accounts-file format
- * @param {string} [options.saltB64] the SCRAM salt, base64
+ * @param {string} [options.accountsText] the accounts file's text, one account per line:
+ *   `name:password`, or the keys `factoidal xmpp-serve --verifier NAME` writes. A line that is
+ *   neither stops the start (`Server.accountsOfText`)
+ * @param {string} [options.saltB64] one SCRAM salt for every name, base64; absent, each name has its own
+ * @param {string} [options.saltSeed] the seed of the salts; absent, a random one for this process
+ * @param {string} [options.occupantSeed] the key of the rooms' occupant ids; absent, a random one
  * @param {number} [options.iterationCount] the SCRAM iteration count
  * @param {boolean} [options.tlsCarrier] whether the carrier terminates TLS
+ * @param {boolean} [options.disableRateLimits] no failed SASL login limit and no sender rate on
+ *   held stanzas (`--dangerously-disable-ratelimits`)
+ * @param {object} [options.heldLimits] caps of the stanzas held for offline accounts, each a
+ *   number: `perAccount`, `perAccountBytes`, `total`, `totalBytes`, `senderPerWindow`,
+ *   `senderWindow` (seconds); what is absent keeps the engine's default
  * @param {object} [options.engine] an engine handle to reuse
  * @returns {Promise<{engine: object, handle: string, domain: string,
  *   openSession: Function, roster: Function, setRoster: Function, close: Function}>}
@@ -133,13 +155,23 @@ export async function openXmppServer (options = {}) {
   if (typeof options.domain === 'string') config.domain = options.domain
   if (Array.isArray(options.accounts)) config.accounts = options.accounts
   if (typeof options.accountsText === 'string') config.accountsText = options.accountsText
+  // One salt per name, from a seed the engine cannot make; a fixed `saltB64`
+  // (a transcript that must replay) is one salt for all.
   if (typeof options.saltB64 === 'string') config.saltB64 = options.saltB64
+  else config.saltSeed = typeof options.saltSeed === 'string' ? options.saltSeed : randomToken(32)
+  // The key of the XEP-0421 occupant ids of the rooms.
+  config.occupantSeed = typeof options.occupantSeed === 'string' ? options.occupantSeed : randomToken(32)
   if (typeof options.iterationCount === 'number') config.iterationCount = options.iterationCount
   if (typeof options.tlsCarrier === 'boolean') config.tlsCarrier = options.tlsCarrier
   // XEP-0045 room service (L4Factoidal/XMPP/Muc.lean); off unless named.
   if (typeof options.mucDomain === 'string') config.mucDomain = options.mucDomain
   // Members-only rooms: [{room, members: [bare JID]}]; no list, an open room.
   if (Array.isArray(options.mucMembers)) config.mucMembers = options.mucMembers
+  // Owners: [{room, owners: [bare JID]}], room '*' for every room. Present, also empty: nobody
+  // becomes an owner by being first in a room. Absent: the first occupant is the owner.
+  if (Array.isArray(options.mucOwners)) config.mucOwners = options.mucOwners
+  // Nicks reserved for a JID: [{nick, jid}]. Each account's name is reserved for it anyway.
+  if (Array.isArray(options.mucReservedNicks)) config.mucReservedNicks = options.mucReservedNicks
   // XEP-0369 channels (L4Factoidal/XMPP/Mix.lean), joined through MIX-PAM; off unless named.
   if (typeof options.mixDomain === 'string') config.mixDomain = options.mixDomain
   // GC3 prototype groups (L4Factoidal/XMPP/Gc3.lean; no published spec); off unless named.
@@ -147,6 +179,13 @@ export async function openXmppServer (options = {}) {
   // The host keeps the state across restarts (a state key and a DIR): only
   // then does the engine produce `store`/`unstore`.
   if (options.persist === true) config.persist = true
+  // The failed SASL login limit is on unless the operator turns it off
+  // (https://github.com/danbri/factoidal/issues/1128); the engine decides.
+  if (options.disableRateLimits === true) config.disableRateLimits = true
+  if (options.heldLimits && typeof options.heldLimits === 'object') config.heldLimits = options.heldLimits
+  // The key of the client address tags: random, in memory only, new at each start.
+  // A tag is no use to anyone who does not hold it, so it never goes to a log or a file.
+  config.addressKey = typeof options.addressKey === 'string' ? options.addressKey : randomToken(32)
   let opened
   try {
     opened = engine.call('xmppOpen', [JSON.stringify(config)])
@@ -162,25 +201,50 @@ export async function openXmppServer (options = {}) {
     throw new XmppHostError('xmppOpen answered with no handle')
   }
   const handle = opened.handle
+  // The rate limits read the host's clock: tell the engine when the second changes.
+  let lastSecond = 0
+  const tick = () => {
+    const now = Math.floor(Date.now() / 1000)
+    if (now === lastSecond) return
+    lastSecond = now
+    try {
+      engine.call('xmppClock', [handle, String(now)])
+    } catch (error) {
+      // An older engine has no such op, and no limit that reads it.
+      if (!isUnknownOp(error)) throw error
+    }
+  }
   // An older engine ignores the list, and the rooms would be open: do not start.
   if (Array.isArray(options.mucMembers) && opened.mucMembers !== options.mucMembers.length) {
     engine.call('xmppClose', [handle])
     throw new XmppHostError('this engine does not carry members-only rooms; rebuild the engine')
   }
+  // The same for owners: an older engine would make the first occupant the owner.
+  if (Array.isArray(options.mucOwners) && opened.mucOwners !== options.mucOwners.length) {
+    engine.call('xmppClose', [handle])
+    throw new XmppHostError('this engine does not carry configured room owners; rebuild the engine')
+  }
   return {
     engine,
     handle,
     domain: typeof opened.domain === 'string' ? opened.domain : (config.domain || 'localhost'),
     accounts: typeof opened.accounts === 'number' ? opened.accounts : undefined,
+    /** The engine's start warnings (--dangerously-disable-ratelimits). */
+    warnings: Array.isArray(opened.warnings) ? opened.warnings : [],
+    tick,
     /**
      * One client connection.
-     * @param {{streamId?: string, nonce?: string, tlsCarrier?: boolean, startTls?: boolean, maxUnits?: number}} [sessionOptions]
+     * `remoteAddress` (the socket's) and the clock go to the engine for the
+     * failed SASL login limit (https://github.com/danbri/factoidal/issues/1128).
+     * @param {{streamId?: string, nonce?: string, tlsCarrier?: boolean, startTls?: boolean, maxUnits?: number, remoteAddress?: string}} [sessionOptions]
      */
     openSession (sessionOptions = {}) {
       const record = {
         streamId: typeof sessionOptions.streamId === 'string' ? sessionOptions.streamId : randomToken(),
-        nonce: typeof sessionOptions.nonce === 'string' ? sessionOptions.nonce : randomToken()
+        nonce: typeof sessionOptions.nonce === 'string' ? sessionOptions.nonce : randomToken(),
+        now: Math.floor(Date.now() / 1000)
       }
+      if (typeof sessionOptions.remoteAddress === 'string') record.remoteAddress = sessionOptions.remoteAddress
       if (typeof sessionOptions.tlsCarrier === 'boolean') record.tlsCarrier = sessionOptions.tlsCarrier
       if (typeof sessionOptions.startTls === 'boolean') record.startTls = sessionOptions.startTls
       if (typeof sessionOptions.maxUnits === 'number') record.maxUnits = sessionOptions.maxUnits
@@ -190,8 +254,11 @@ export async function openXmppServer (options = {}) {
       let open = true
       return {
         handle: session,
+        /** The first digits of the client's address tag, for a log line ('' for no address). */
+        addressTag: typeof answer.addressTag === 'string' ? answer.addressTag : '',
         /** Feed received text; returns the engine's answer document. */
         feed (text) {
+          tick()
           return engine.call('xmppSessionFeed', [session, text])
         },
         /** The TLS handshake a feed asked for (`startTls: true`) finished. */
@@ -202,6 +269,10 @@ export async function openXmppServer (options = {}) {
         deliver (text) {
           return engine.call('xmppSessionDeliver', [session, text])
         },
+        /** This session has been silent: `{sent, send}`, an XEP-0199 ping when it is bound. */
+        ping (id) {
+          return engine.call('xmppSessionPing', [session, id])
+        },
         /** End of input: returns `{send: string[]}` and releases the handle. */
         close () {
           if (!open) return { send: [], routeFull: [] }
@@ -238,6 +309,14 @@ async function readAccountsFile (path) {
   }
 }
 
+/** A warning when the accounts file can be read by anyone but its owner. */
+async function accountsFileWarnings (path) {
+  if (process.platform === 'win32') return []
+  const { mode } = await stat(path)
+  if ((mode & 0o077) === 0) return []
+  return [`${path} can be read by other users of this machine: chmod 600 it`]
+}
+
 /**
  * A `net.Server` (or `tls.Server`, when `cert` and `key` are given —
  * XEP-0368 direct TLS) that runs one engine session per connection.
@@ -245,6 +324,7 @@ async function readAccountsFile (path) {
  * The server is returned unlistened: the caller chooses the port.
  *
  * @param {object} options as `openXmppServer`, plus:
+ * @param {string} [options.accountsFile] the path `accountsText` came from, to check its mode
  * @param {string} [options.dir] state directory: `accounts` is read from it when
  *   no accounts are given; rosters are persisted under `roster/`; `spool/` is
  *   polled for stanzas written by other processes
@@ -265,6 +345,18 @@ async function readAccountsFile (path) {
  *   without a bound resource before it is closed (default 30000; 0 disables)
  * @param {number} [options.maxQueuedBytes] bytes waiting to be written to a
  *   client that is not reading, before the socket is closed (default 8 MiB)
+ * @param {number} [options.pingIntervalMs] how long a bound session may be silent before it
+ *   gets a ping (default 30000; 0 disables pings and the timeout)
+ * @param {number} [options.pingTimeoutMs] how long after a ping a session that sends
+ *   no byte is closed, so that its resource is free again (default 20000)
+ * @param {boolean} [options.addressLimit] false: count failed logins per account name only
+ *   (default true). Behind a proxy that sends no PROXY header every client has the proxy's address
+ * @param {boolean} [options.proxyProtocol] every connection, on every listener, starts with a
+ *   PROXY protocol v2 header, read before TLS; the client address it names is the one the
+ *   failed-login limit counts. A connection without a valid header is closed. Without this option no
+ *   header is ever read, so a client cannot claim an address (default false)
+ * @param {number} [options.proxyHeaderTimeoutMs] with `proxyProtocol`, how long a connection has to
+ *   send its header and, on a TLS listener, finish the TLS handshake (default 10000)
  * @param {Function} [options.onError]
  * @param {Function} [options.onLog]
  * @returns {Promise<{server: object, xmpp: object, close: Function, sessions: Function}>}
@@ -285,6 +377,11 @@ export async function createXmppServer (options = {}) {
   const maxConnections = limit('maxConnections', 1024)
   const loginTimeoutMs = limit('loginTimeoutMs', 30000)
   const maxQueuedBytes = limit('maxQueuedBytes', 8 * 1024 * 1024)
+  const pingIntervalMs = limit('pingIntervalMs', 30000)
+  const pingTimeoutMs = limit('pingTimeoutMs', 20000)
+  const proxyProtocol = options.proxyProtocol === true
+  const proxyHeaderTimeoutMs = limit('proxyHeaderTimeoutMs', 10000)
+  if (pingIntervalMs > 0 && pingTimeoutMs === 0) throw new XmppHostError('pingTimeoutMs must be positive when pings are on')
   if (!Number.isSafeInteger(maxBuffered) || maxBuffered < 0) {
     throw new XmppHostError('maxBuffered must be a nonnegative safe integer')
   }
@@ -293,9 +390,19 @@ export async function createXmppServer (options = {}) {
   }
 
   const serverOptions = { ...options }
+  let accountsFile = typeof options.accountsFile === 'string' ? options.accountsFile : null
   if (dir !== null && !Array.isArray(options.accounts) && typeof options.accountsText !== 'string') {
     const text = await readAccountsFile(join(dir, 'accounts'))
-    if (text !== null) serverOptions.accountsText = text
+    if (text !== null) { serverOptions.accountsText = text; accountsFile = join(dir, 'accounts') }
+  }
+  // Salts that survive a restart when the state does: a client that keeps a
+  // salted password goes on working, and a name's salt does not change.
+  if (typeof options.saltSeed !== 'string' && typeof options.stateKey === 'string') {
+    serverOptions.saltSeed = createHash('sha256').update('xmpp salt seed\0' + options.stateKey).digest('base64url')
+  }
+  // Occupant ids that survive a restart, for the same reason.
+  if (typeof options.occupantSeed !== 'string' && typeof options.stateKey === 'string') {
+    serverOptions.occupantSeed = createHash('sha256').update('xmpp occupant seed\0' + options.stateKey).digest('base64url')
   }
   const haveKey = options.cert !== undefined && options.key !== undefined
   if (options.startTls === true && !haveKey) {
@@ -306,6 +413,18 @@ export async function createXmppServer (options = {}) {
   if (typeof serverOptions.tlsCarrier !== 'boolean') serverOptions.tlsCarrier = useTls
   if (dir !== null && options.stateKey !== undefined) serverOptions.persist = true
   const xmpp = await openXmppServer(serverOptions)
+  if (accountsFile !== null) xmpp.warnings.push(...await accountsFileWarnings(accountsFile))
+  if (proxyProtocol) {
+    try {
+      xmpp.engine.callBlobIO('proxyHeaderParse', [], new Uint8Array(0))
+    } catch (error) {
+      xmpp.close()
+      if (isUnknownOp(error)) {
+        throw new XmppHostError('the loaded l4factoidal WebAssembly module does not carry proxyHeaderParse', { unknownOp: true })
+      }
+      throw error
+    }
+  }
 
   // Rosters the previous run persisted.
   try {
@@ -352,7 +471,7 @@ export async function createXmppServer (options = {}) {
           '  acl:mode acl:Read, acl:Write, acl:Control .\n'
       })
       const get = (target, accept) => state.step({ method: 'GET', target, headers: accept ? [['Accept', accept]] : [], body: new Uint8Array(0) })
-      for (const kind of ['roster', 'held', 'mix', 'gc3']) {
+      for (const kind of ['roster', 'held', 'mix', 'gc3', 'muc']) {
         const listing = await get(`/xmpp/${kind}/`, 'application/lws+json')
         if (listing.status === 404) continue
         if (listing.status !== 200) throw new XmppHostError(`state: listing /xmpp/${kind}/ answered ${listing.status}`)
@@ -363,6 +482,10 @@ export async function createXmppServer (options = {}) {
           if (got.status !== 200) throw new XmppHostError(`state: ${path} answered ${got.status}`)
           const loaded = xmpp.engine.call('xmppStateLoad', [xmpp.handle, path, new TextDecoder().decode(got.body)])
           if (loaded === null || typeof loaded !== 'object') throw new XmppHostError(`state: ${path} was refused`)
+          if (loaded.stale === true) {
+            const gone = await state.step({ method: 'DELETE', target: path, headers: [], body: new Uint8Array(0) })
+            if (gone.status >= 300 && gone.status !== 404) throw new XmppHostError(`state: DELETE ${path} answered ${gone.status}`)
+          }
         }
       }
     } catch (error) {
@@ -411,6 +534,96 @@ export async function createXmppServer (options = {}) {
   // connection callback and therefore have no engine session yet.
   const transports = new Set()
 
+  // The client's address for the login limit: the socket's, or the one a PROXY
+  // header named. The engine keeps only its tag. `addressLimit: false` gives none.
+  const addressOf = (address) =>
+    options.addressLimit !== false && typeof address === 'string' ? address : ''
+
+  /** With `proxyProtocol`: buffer a new connection's bytes until the engine
+   *  decides on its PROXY v2 header, then `then(address, rest)` with the client
+   *  address and the bytes after the header. A refused header, or none in
+   *  `proxyHeaderTimeoutMs`, closes the connection. */
+  function readProxyHeader (socket, then) {
+    let buffered = Buffer.alloc(0)
+    const timer = setTimeout(() => {
+      onLog('closing a connection that sent no PROXY header in time')
+      finish()
+      socket.destroy()
+    }, proxyHeaderTimeoutMs)
+    timer.unref()
+    const finish = () => {
+      clearTimeout(timer)
+      socket.removeListener('data', onData)
+      socket.removeListener('error', onSocketError)
+    }
+    const onSocketError = () => { finish(); socket.destroy() }
+    const onData = (chunk) => {
+      buffered = buffered.length === 0 ? chunk : Buffer.concat([buffered, chunk])
+      let decision
+      try {
+        decision = xmpp.engine.callBlobIO('proxyHeaderParse', [],
+          new Uint8Array(buffered.buffer, buffered.byteOffset, buffered.byteLength)).envelope
+      } catch (error) {
+        onError(error)
+        finish()
+        socket.destroy()
+        return
+      }
+      if (decision.decision === 'more') return
+      finish()
+      if ((decision.decision !== 'proxy' && decision.decision !== 'local') ||
+          !Number.isSafeInteger(decision.consumed) || decision.consumed > buffered.length) {
+        onLog(`closing a connection: PROXY header refused (${decision.reason || decision.error || 'no decision'})`)
+        socket.destroy()
+        return
+      }
+      // LOCAL: the proxy's own connection (a health check); its address is the socket's.
+      const address = decision.decision === 'proxy' ? decision.address : socket.remoteAddress
+      then(address, buffered.subarray(decision.consumed))
+    }
+    socket.on('data', onData)
+    socket.on('error', onSocketError)
+  }
+
+  /** A stream that yields `head` and then what `socket` reads, and writes to
+   *  `socket`: TLS over a connection whose first bytes were a PROXY header. */
+  function prefixed (socket, head) {
+    const stream = new Duplex({
+      read () { socket.resume() },
+      write (chunk, _encoding, callback) { socket.write(chunk, callback) },
+      final (callback) { socket.end(); callback() },
+      destroy (error, callback) { socket.destroy(); callback(error) }
+    })
+    if (head.length > 0) stream.push(head)
+    socket.on('data', (chunk) => { if (!stream.push(chunk)) socket.pause() })
+    socket.on('end', () => stream.push(null))
+    socket.on('error', (error) => stream.destroy(error))
+    socket.on('close', () => stream.destroy())
+    return stream
+  }
+
+  /** With `proxyProtocol`, a TLS listener is a TCP listener: read the header,
+   *  then be the TLS server over the rest, within `proxyHeaderTimeoutMs`. */
+  function acceptTls (tls, socket, tlsOptions, then) {
+    readProxyHeader(socket, (address, rest) => {
+      const secure = new tls.TLSSocket(prefixed(socket, rest), { isServer: true, ...tlsOptions })
+      const timer = setTimeout(() => { secure.destroy(); socket.destroy() }, proxyHeaderTimeoutMs)
+      timer.unref()
+      const onHandshakeError = (error) => {
+        clearTimeout(timer)
+        if (error && error.code !== 'ECONNRESET') onError(new XmppHostError(`TLS handshake: ${error.message}`))
+        secure.destroy()
+        socket.destroy()
+      }
+      secure.once('error', onHandshakeError)
+      secure.once('secure', () => {
+        clearTimeout(timer)
+        secure.removeListener('error', onHandshakeError)
+        then(secure, address)
+      })
+    })
+  }
+
   // Transport limits, like `maxBuffered`: bytes and time, not protocol.
   function closeIfBacklogged (c) {
     if (c.socket.destroyed || !(c.socket.writableLength > maxQueuedBytes)) return
@@ -435,6 +648,35 @@ export async function createXmppServer (options = {}) {
     c.loginTimer.unref()
   }
 
+  /** Any byte from a peer shows it is alive, whatever the byte says. */
+  function heard (c) {
+    c.lastHeard = Date.now()
+    c.pingedAt = 0
+  }
+
+  /** Ping the bound sessions that have been silent, and close the ones that stayed silent.
+   *  A dead TCP connection sends no FIN, so without this it holds its resource for as long as
+   *  the operating system keeps retrying. */
+  function checkSilence () {
+    const now = Date.now()
+    for (const c of connections) {
+      if (c.full === null || c.closing || c.upgrading) continue
+      if (c.pingedAt !== 0) {
+        if (now - c.pingedAt >= pingTimeoutMs) {
+          onLog(`closing ${c.full}: no answer to a ping`)
+          c.socket.destroy()
+        }
+      } else if (now - c.lastHeard >= pingIntervalMs) {
+        c.pingedAt = now
+        try { c.ping() } catch (error) { onError(error) }
+      }
+    }
+  }
+  const pinger = pingIntervalMs > 0
+    ? setInterval(checkSilence, Math.ceil(Math.min(pingIntervalMs, pingTimeoutMs, 10000) / 2))
+    : null
+  if (pinger !== null) pinger.unref()
+
   /** Count a new socket, or close it at once if the server is full. */
   function admit (socket) {
     if (transports.size >= maxConnections) {
@@ -540,10 +782,10 @@ export async function createXmppServer (options = {}) {
     }
   }
 
-  function onConnection (socket, direct = false) {
+  function onConnection (socket, direct = false, address = socket.remoteAddress, rest = null) {
     let session
     try {
-      session = xmpp.openSession({ tlsCarrier: useTls || direct, startTls: startTls && !direct })
+      session = xmpp.openSession({ tlsCarrier: useTls || direct, startTls: startTls && !direct, remoteAddress: addressOf(address) })
     } catch (error) {
       onError(error)
       socket.destroy()
@@ -556,16 +798,25 @@ export async function createXmppServer (options = {}) {
       full: null,
       closing: false,
       decoder: new StringDecoder('utf8'),
+      lastHeard: Date.now(),
+      pingedAt: 0,
+      pings: 0,
       deliver (text) {
         const answer = c.session.deliver(text)
         if (answer.delivered === true) { writeAll(c, answer.send); return true }
         return false
+      },
+      ping () {
+        const answer = c.session.ping(`ping-${++c.pings}`)
+        if (answer.sent === true) writeAll(c, answer.send)
       }
     }
     connections.add(c)
     startLoginTimer(c)
-    onLog(`connection from ${socket.remoteAddress}:${socket.remotePort}`)
+    // The tag's first digits, never the address (the tag's key is in memory only).
+    onLog(`connection from ${session.addressTag === '' ? 'no address' : 'address ' + session.addressTag}`)
     c.onData = (chunk) => {
+      heard(c)
       if (!connections.has(c) || c.closing || c.upgrading) return
       const text = c.decoder.write(chunk)
       if (text.length === 0) return
@@ -597,6 +848,8 @@ export async function createXmppServer (options = {}) {
       if (error && error.code !== 'ECONNRESET') onError(error)
       endSession(c)
     })
+    // The bytes that came in one read with a PROXY header.
+    if (rest !== null && rest.length > 0) c.onData(rest)
   }
 
   // XMPP over WebSocket (RFC 7395): every byte goes to xmppWsFeed, which
@@ -607,17 +860,19 @@ export async function createXmppServer (options = {}) {
     const got = xmpp.engine.callBlobIO(op, args, bytes)
     return { envelope: got.envelope, bytes: got.bytes instanceof Uint8Array ? got.bytes : new Uint8Array(0) }
   }
-  function onWsConnection (socket) {
+  function onWsConnection (socket, address = socket.remoteAddress, rest = null) {
     let handle
+    let tag = ''
     try {
       const opened = xmpp.engine.call('xmppWsOpen', [xmpp.handle, JSON.stringify({
-        streamId: randomToken(), nonce: randomToken(),
+        streamId: randomToken(), nonce: randomToken(), remoteAddress: addressOf(address),
         path: typeof ws.path === 'string' ? ws.path : '/xmpp-websocket',
         allowedOrigins: Array.isArray(ws.allowedOrigins) ? ws.allowedOrigins : [],
         allowNoOrigin: ws.allowNoOrigin === true,
         tlsCarrier: ws.cert !== undefined && ws.key !== undefined
       })])
       handle = opened.handle
+      if (typeof opened.addressTag === 'string') tag = opened.addressTag
     } catch (error) {
       onError(error)
       socket.destroy()
@@ -628,6 +883,8 @@ export async function createXmppServer (options = {}) {
       bare: null,
       full: null,
       closing: false,
+      lastHeard: Date.now(),
+      pingedAt: 0,
       session: {
         close () {
           try {
@@ -640,14 +897,21 @@ export async function createXmppServer (options = {}) {
         const got = wsCall('xmppWsDeliver', [handle, text], new Uint8Array(0))
         if (got.envelope.delivered === true) { if (!socket.destroyed) socket.write(got.bytes); closeIfBacklogged(c); return true }
         return false
+      },
+      ping () {
+        const got = wsCall('xmppWsPing', [handle], new Uint8Array(0))
+        if (got.envelope.sent === true && !socket.destroyed) { socket.write(got.bytes); closeIfBacklogged(c) }
       }
     }
     connections.add(c)
     startLoginTimer(c)
-    socket.on('data', (chunk) => {
+    onLog(`WebSocket connection from ${tag === '' ? 'no address' : 'address ' + tag}`)
+    const onData = (chunk) => {
+      heard(c)
       if (!connections.has(c) || c.closing) return
       let got
       try {
+        xmpp.tick()
         got = wsCall('xmppWsFeed', [handle], new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength))
       } catch (error) {
         onError(error)
@@ -662,13 +926,16 @@ export async function createXmppServer (options = {}) {
         socket.destroy()
         endSession(c)
       }
-    })
+    }
+    socket.on('data', onData)
     socket.on('end', () => endSession(c))
     socket.on('close', () => endSession(c))
     socket.on('error', (error) => {
       if (error && error.code !== 'ECONNRESET') onError(error)
       endSession(c)
     })
+    // The bytes that came in one read with a PROXY header.
+    if (rest !== null && rest.length > 0) onData(rest)
   }
   let wsServer = null
   if (ws !== null) {
@@ -676,19 +943,34 @@ export async function createXmppServer (options = {}) {
       xmpp.close()
       throw new XmppHostError('the WebSocket listener needs both cert and key for TLS')
     }
-    if (ws.cert !== undefined) {
+    if (proxyProtocol) {
+      const net = await import('node:net')
+      const tls = ws.cert !== undefined ? await import('node:tls') : null
+      wsServer = net.createServer((socket) => {
+        if (tls === null) readProxyHeader(socket, (address, rest) => onWsConnection(socket, address, rest))
+        else acceptTls(tls, socket, { cert: ws.cert, key: ws.key }, (secure, address) => onWsConnection(secure, address))
+      })
+    } else if (ws.cert !== undefined) {
       const tls = await import('node:tls')
-      wsServer = tls.createServer({ cert: ws.cert, key: ws.key }, onWsConnection)
+      wsServer = tls.createServer({ cert: ws.cert, key: ws.key }, (socket) => onWsConnection(socket))
     } else {
       const net = await import('node:net')
-      wsServer = net.createServer(onWsConnection)
+      wsServer = net.createServer((socket) => onWsConnection(socket))
     }
     wsServer.on('connection', admit)
   }
 
   let server
   try {
-    if (useTls) {
+    if (proxyProtocol) {
+      // Every listener is TCP: the header comes before TLS.
+      const net = await import('node:net')
+      const tls = useTls ? await import('node:tls') : null
+      server = net.createServer((socket) => {
+        if (tls === null) readProxyHeader(socket, (address, rest) => onConnection(socket, false, address, rest))
+        else acceptTls(tls, socket, { cert: options.cert, key: options.key }, (secure, address) => onConnection(secure, false, address))
+      })
+    } else if (useTls) {
       const tls = await import('node:tls')
       server = tls.createServer({ cert: options.cert, key: options.key }, (socket) => onConnection(socket))
     } else {
@@ -706,7 +988,13 @@ export async function createXmppServer (options = {}) {
   let directServer = null
   if (startTls && options.directTlsPort !== undefined) {
     const tls = await import('node:tls')
-    directServer = tls.createServer({ cert: options.cert, key: options.key }, (socket) => onConnection(socket, true))
+    if (proxyProtocol) {
+      const net = await import('node:net')
+      directServer = net.createServer((socket) =>
+        acceptTls(tls, socket, { cert: options.cert, key: options.key }, (secure, address) => onConnection(secure, true, address)))
+    } else {
+      directServer = tls.createServer({ cert: options.cert, key: options.key }, (socket) => onConnection(socket, true))
+    }
     directServer.on('connection', admit)
   }
 
@@ -770,6 +1058,7 @@ export async function createXmppServer (options = {}) {
       if (closePromise !== null) return closePromise
       closePromise = (async () => {
         if (poller !== null) clearInterval(poller)
+        if (pinger !== null) clearInterval(pinger)
         for (const c of Array.from(connections)) {
           endSession(c)
           c.socket.destroy()