@factoidal/core 0.20.0 → 0.22.0

package/lws/server.mjs

@@ -84,11 +84,11 @@
 // produced and this code keeps working unchanged.
 
 import { loadEngine } from '../bin/engine.mjs'
-import { readSnapshot, persistIfChanged, storageKeyText, storageModeText, loadFiles, persistFilesIfChanged, readStepBodies } from './persist.mjs'
+import { readSnapshot, persistIfChanged, storageKeyText, storageModeText, loadFiles, persistFilesIfChanged, readStepBodies, acquireDirLock, atRestNotice } from './persist.mjs'
 
 /** The ops this host needs from the engine. */
 export const LWS_OPS = ['lwsOpen', 'lwsStep', 'lwsClose', 'lwsSnapshot', 'lwsFetched', 'lwsDelivered',
-  'lwsLoad', 'lwsPersist', 'lwsRead']
+  'lwsLoad', 'lwsPersist', 'lwsRead', 'lwsDirLock', 'lwsAtRestNotice']
 
 /** How long this host waits for the answer to one delivery request before
  *  it reports "no answer" (status 0) to the engine. */
@@ -254,8 +254,11 @@ function contentBytes (request) {
  *   file) or "files" (one file per body and a journal, issue 918); passed unread
  * @param {boolean|string[]} [options.cors] CORS (issue 923): false for none, a list of
  *   origins to answer; default: echo any valid request Origin. Passed unread
+ * @param {string} [options.lockCommand] the command named in the lock file of DIR
+ *   (default "lws-serve"; https://github.com/danbri/factoidal/issues/1135)
  * @param {object} [options.engine] an engine handle to reuse
- * @returns {Promise<{step: Function, close: Function, handle: string, engine: object}>}
+ * @returns {Promise<{step: Function, close: Function, handle: string, engine: object,
+ *                    lockFile: string|null, notices: string[]}>}
  */
 export async function openLwsStorage (options = {}) {
   const engine = options.engine !== undefined ? options.engine : await loadEngine()
@@ -315,8 +318,14 @@ export async function openLwsStorage (options = {}) {
   if (typeof options.controllerInbox === 'string') config.controllerInbox = options.controllerInbox
   // CORS (https://github.com/danbri/factoidal/issues/923): `cors` is false or
   // a list of origins, passed unread; absent, the engine echoes the request
-  // Origin. L4Factoidal/LWS/Cors.lean decides every CORS field.
+  // Origin under authorization and sends no CORS field with insecureNoAuth
+  // (issue 1124). L4Factoidal/LWS/Cors.lean decides every CORS field.
   if (options.cors !== undefined) config.cors = options.cors
+  // The Host and Origin guard of a storage with insecureNoAuth
+  // (https://github.com/danbri/factoidal/issues/1124): extra host names and
+  // origins, passed unread; L4Factoidal/HTTP/LocalGuard.lean decides.
+  if (Array.isArray(options.allowHosts)) config.allowHosts = options.allowHosts
+  if (Array.isArray(options.allowOrigins)) config.allowOrigins = options.allowOrigins
   // What this host bound: data for the engine's inbox check (issue 915).
   if (options.listen !== undefined && options.listen !== null) config.listen = options.listen
   config.entropy = entropyBase64()
@@ -335,36 +344,69 @@ export async function openLwsStorage (options = {}) {
   const dir = typeof options.dir === 'string' ? options.dir : null
   const storage = dir !== null ? storageModeText(options.storage) : options.storage
   if (typeof storage === 'string') config.storage = storage
-  // `dir` names the storage directory. The snapshot found there, if any,
-  // is the storage to continue from; the engine checks it.
-  if (dir !== null && storage !== 'files') {
-    const snapshot = readSnapshot(dir)
-    if (snapshot !== null) config.snapshot = snapshot
+  // One writing process per storage directory
+  // (https://github.com/danbri/factoidal/issues/1135): the lock is taken
+  // before anything in DIR is read, and released by `close` and at process
+  // exit. The engine decides the file, its contents and every refusal
+  // (L4Factoidal/LWS/DirLock.lean); a refusal is thrown with its message.
+  let lock = null
+  if (dir !== null) {
+    try {
+      lock = acquireDirLock(engine, dir, typeof options.lockCommand === 'string' ? options.lockCommand : 'lws-serve')
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new LwsHostError(
+          'the loaded l4factoidal WebAssembly module does not carry lwsDirLock',
+          { unknownOp: true })
+      }
+      throw error
+    }
   }
   let opened
+  let handle
+  let filesMode
+  let notices = []
   try {
-    opened = engine.call('lwsOpen', [JSON.stringify(config)])
-  } catch (error) {
-    if (isUnknownOp(error)) {
-      throw new LwsHostError(
-        'the loaded l4factoidal WebAssembly module does not carry lwsOpen',
-        { unknownOp: true })
+    // `dir` names the storage directory. The snapshot found there, if any,
+    // is the storage to continue from; the engine checks it.
+    if (dir !== null && storage !== 'files') {
+      const snapshot = readSnapshot(dir)
+      if (snapshot !== null) config.snapshot = snapshot
     }
+    try {
+      opened = engine.call('lwsOpen', [JSON.stringify(config)])
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new LwsHostError(
+          'the loaded l4factoidal WebAssembly module does not carry lwsOpen',
+          { unknownOp: true })
+      }
+      throw error
+    }
+    handle = handleOf(opened)
+    if (handle === null) {
+      throw new LwsHostError('lwsOpen answered with no handle')
+    }
+    // A storage kept in files: read the files the engine names until it is
+    // ready, and perform the plan of the start. Without a DIR, there are no
+    // files: the engine is told none is present.
+    filesMode = opened !== null && typeof opened === 'object' &&
+      opened.load !== undefined && opened.load !== null
+    if (filesMode) {
+      if (dir === null) throw new LwsHostError('a storage kept in files needs a storage directory (dir)')
+      loadFiles(engine, handle, opened, dir)
+    }
+    // What a server prints at start, after the experimental code notice:
+    // a take-over of a stale lock, and whether the storage on disk is
+    // sealed (encryption at rest; the engine words both).
+    if (dir !== null) {
+      if (lock.warning !== null) notices.push(`WARNING: ${lock.warning}`)
+      notices.push(atRestNotice(engine, dir, storageKey).notice)
+    }
+  } catch (error) {
+    if (lock !== null) lock.release()
     throw error
   }
-  const handle = handleOf(opened)
-  if (handle === null) {
-    throw new LwsHostError('lwsOpen answered with no handle')
-  }
-  // A storage kept in files: read the files the engine names until it is
-  // ready, and perform the plan of the start. Without a DIR, there are no
-  // files: the engine is told none is present.
-  const filesMode = opened !== null && typeof opened === 'object' &&
-    opened.load !== undefined && opened.load !== null
-  if (filesMode) {
-    if (dir === null) throw new LwsHostError('a storage kept in files needs a storage directory (dir)')
-    loadFiles(engine, handle, opened, dir)
-  }
   /** After a call whose envelope may say `changed`: write what the engine
    *  gives (the snapshot, or the plan of a storage kept in files). */
   const persist = (envelope) => {
@@ -448,6 +490,10 @@ export async function openLwsStorage (options = {}) {
   return {
     engine,
     handle,
+    /** The lock file of the storage directory, or null with no DIR. */
+    lockFile: lock !== null ? lock.file : null,
+    /** The start notices, for the server to print on standard error. */
+    notices,
     /**
      * One protocol step.
      * @param {{method: string, target: string,
@@ -538,6 +584,7 @@ export async function openLwsStorage (options = {}) {
       closed = true
       if (flushTimer !== null) clearTimeout(flushTimer)
       try { engine.call('lwsClose', [handle]) } catch (_error) { /* already gone */ }
+      if (lock !== null) lock.release()
     }
   }
 }
@@ -593,6 +640,12 @@ export async function createLwsServer (options = {}) {
    *  (L4Factoidal/Authz/Mount.lean). */
   function storage () {
     if (opening === null) {
+      // What the socket bound, when the caller listened itself and did not
+      // say (data for the engine's Host check, issue 1124).
+      const bound = server.address()
+      if (settings.listen === undefined && bound !== null && typeof bound === 'object') {
+        settings = { ...settings, listen: { address: bound.address, port: bound.port, addresses: [] } }
+      }
       opening = (async () => {
         let storageSettings = settings
         if (settings.authz !== undefined && settings.authz !== null) {
@@ -720,7 +773,7 @@ export async function listen (options = {}) {
   const bound = created.server.address()
   const origin = `http://${host}:${bound.port}`
   if (typeof options.baseIri !== 'string') created.setBaseIri(`${origin}/`)
-  created.setListen({ address: bound.address, port: bound.port, addresses: await interfaceAddresses() })
+  created.setListen({ host, address: bound.address, port: bound.port, addresses: await interfaceAddresses() })
   try {
     await created.storage()
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factoidal/core",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "EXPERIMENTAL UNREVIEWED CODE: do not run public services on it without careful independent expert review. RDF parsing and writing (Turtle, TriG, N-Triples, N-Quads, RDF/XML, JSON-LD), SPARQL 1.1 and 1.2, RDFS and OWL reasoning, SHACL and ShEx validation, CSVW and RML mapping, RDFC-1.0, and SPARQL, LWS and Solid servers, for Node, Deno and browsers.",
   "keywords": [
     "sparql",
@@ -70,6 +70,7 @@
     "./store-host/paths": "./store-host/paths.mjs",
     "./xmpp": "./xmpp/index.mjs",
     "./xmpp/server": "./xmpp/server.mjs",
+    "./cipher-host": "./lib/cipher-host.mjs",
     "./store": {
       "default": "./bin/store.mjs"
     },

package/solid/server/index.mjs

@@ -55,8 +55,9 @@
 // loader, by the design record's rule that the two conformance classes
 // stay distinct.
 
+import { existsSync, readdirSync } from 'node:fs'
 import { loadEngine } from '../../bin/engine.mjs'
-import { readSnapshot, persistIfChanged, storageKeyText } from '../../lws/persist.mjs'
+import { readSnapshot, persistIfChanged, storageKeyText, acquireDirLock, atRestNotice } from '../../lws/persist.mjs'
 
 /** The ops this host needs from the engine. */
 export const SOLID_SERVER_OPS = ['solidOpen', 'solidStep', 'solidClose', 'solidSnapshot',
@@ -187,6 +188,11 @@ export async function openSolidStorage (options = {}) {
   if (options.auth !== undefined && options.auth !== null) config.auth = options.auth
   if (options.insecureNoAuth === true) config.insecureNoAuth = true
   if (typeof options.enforceWac === 'boolean') config.enforceWac = options.enforceWac
+  // The Host and Origin guard with insecureNoAuth (issue 1124): what the
+  // socket bound and the operator's names and origins, passed unread.
+  if (options.listen !== undefined && options.listen !== null) config.listen = options.listen
+  if (Array.isArray(options.allowHosts)) config.allowHosts = options.allowHosts
+  if (Array.isArray(options.allowOrigins)) config.allowOrigins = options.allowOrigins
   if (typeof options.rootAcl === 'string') config.rootAcl = options.rootAcl
   // Encryption at rest (issue 921), as the LWS host: the key text from
   // `storageKey` or FACTOIDAL_LWS_KEY, passed unread; the engine decides.
@@ -195,28 +201,65 @@ export async function openSolidStorage (options = {}) {
   // `dir` names the storage directory. The snapshot found there, if any,
   // is the storage to continue from; the engine checks it.
   const dir = typeof options.dir === 'string' ? options.dir : null
+  // One writing process per storage directory
+  // (https://github.com/danbri/factoidal/issues/1135), as the LWS host: the
+  // engine decides; the lock is taken before DIR is read.
+  let lock = null
   if (dir !== null) {
-    const snapshot = readSnapshot(dir)
-    if (snapshot !== null) config.snapshot = snapshot
+    try {
+      lock = acquireDirLock(engine, dir, 'solid-serve')
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new SolidServerHostError(
+          'the loaded l4factoidal WebAssembly module does not carry lwsDirLock',
+          { unknownOp: true })
+      }
+      throw error
+    }
   }
   let opened
+  let handle
+  const notices = []
   try {
-    opened = engine.call('solidOpen', [JSON.stringify(config)])
-  } catch (error) {
-    if (isUnknownOp(error)) {
-      throw new SolidServerHostError(
-        'the loaded l4factoidal WebAssembly module does not carry solidOpen',
-        { unknownOp: true })
+    if (dir !== null) {
+      const snapshot = readSnapshot(dir)
+      if (snapshot !== null) config.snapshot = snapshot
+      // The names in DIR, unread: the engine refuses a storage that LWS
+      // keeps there (`solidRefusesLws`, Wasm/Ops/Solid.lean); only lws-serve
+      // serves an LWS storage.
+      config.dirFiles = existsSync(dir) ? readdirSync(dir) : []
+    }
+    try {
+      opened = engine.call('solidOpen', [JSON.stringify(config)])
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new SolidServerHostError(
+          'the loaded l4factoidal WebAssembly module does not carry solidOpen',
+          { unknownOp: true })
+      }
+      throw error
+    }
+    handle = handleOf(opened)
+    if (handle === null) {
+      throw new SolidServerHostError('solidOpen answered with no handle')
     }
+    // The start notices: a take-over of a stale lock, and whether the
+    // storage on disk is sealed (encryption at rest).
+    if (dir !== null) {
+      if (lock.warning !== null) notices.push(`WARNING: ${lock.warning}`)
+      notices.push(atRestNotice(engine, dir, storageKey).notice)
+    }
+  } catch (error) {
+    if (lock !== null) lock.release()
     throw error
   }
-  const handle = handleOf(opened)
-  if (handle === null) {
-    throw new SolidServerHostError('solidOpen answered with no handle')
-  }
   return {
     engine,
     handle,
+    /** The lock file of the storage directory, or null with no DIR. */
+    lockFile: lock !== null ? lock.file : null,
+    /** The start notices, for the server to print on standard error. */
+    notices,
     storageIri: typeof opened.storage === 'string' ? opened.storage : null,
     /**
      * One protocol step.
@@ -258,6 +301,7 @@ export async function openSolidStorage (options = {}) {
     },
     close () {
       try { engine.call('solidClose', [handle]) } catch (_error) { /* already gone */ }
+      if (lock !== null) lock.release()
     }
   }
 }
@@ -302,6 +346,10 @@ export async function createSolidServer (options = {}) {
 
   function storage () {
     if (opening === null) {
+      const bound = server.address()
+      if (settings.listen === undefined && bound !== null && typeof bound === 'object') {
+        settings = { ...settings, listen: { address: bound.address, port: bound.port, addresses: [] } }
+      }
       opening = openSolidStorage(settings).then((value) => { opened = value; return value })
     }
     return opening
@@ -345,6 +393,13 @@ export async function createSolidServer (options = {}) {
       }
       settings = { ...settings, baseIri: value }
     },
+    /** Pass what the socket bound, before the first request (issue 1124). */
+    setListen (value) {
+      if (opening !== null) {
+        throw new SolidServerHostError('the storage is already open; set listen first')
+      }
+      settings = { ...settings, listen: value }
+    },
     close () {
       return new Promise((resolve) => {
         server.close(() => {
@@ -380,6 +435,16 @@ function writeHeaders (response, pairs) {
  * @returns {Promise<{server: object, storage: Function, port: number,
  *                    origin: string, close: Function}>}
  */
+/** 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 []
+  }
+}
+
 export async function listen (options = {}) {
   const port = typeof options.port === 'number' ? options.port : 0
   const host = typeof options.host === 'string' ? options.host : '127.0.0.1'
@@ -391,6 +456,7 @@ export async function listen (options = {}) {
   const bound = created.server.address()
   const origin = `http://${host}:${bound.port}`
   if (typeof options.baseIri !== 'string') created.setBaseIri(`${origin}/`)
+  created.setListen({ host, address: bound.address, port: bound.port, addresses: await interfaceAddresses() })
   try {
     await created.storage()
   } catch (error) {

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() })