@factoidal/core 0.7.1 → 0.11.0

package/lws/README.md

@@ -0,0 +1,137 @@
+# `@factoidal/core/lws` — a Node host for Linked Web Storage 1.0
+
+The W3C Linked Web Storage Protocol 1.0 core
+(<https://w3c.github.io/lws-protocol/lws10-core/>, Linked Web Storage
+Working Group editor's draft) served over Node's `http` module.
+
+Tracking issue: <https://github.com/danbri/factoidal/issues/659>.
+Design record:
+[`docs/designissues/2026-09-06-lws-and-solid-protocols.md`](../../../docs/designissues/2026-09-06-lws-and-solid-protocols.md).
+Conformance ledger:
+[`docs/lws-solid-conformance.md`](../../../docs/lws-solid-conformance.md).
+
+## What is here and what is not
+
+`server.mjs` is a socket, a body reader and a header writer. Every
+protocol decision — status codes, `Link` relations, `Last-Modified`,
+containment, the blank-node refusal in PATCH — is made by
+`formal/lean4/L4Factoidal/LWS/` and reaches this file only as a
+`{status, headers, body}` record. Iron rule 7 of `CLAUDE.md`: no
+protocol logic in a host.
+
+The one status code this file writes itself is `500`, and only when the
+host or the engine failed rather than answered.
+
+## The wasm contract
+
+| op | arguments | answer |
+| --- | --- | --- |
+| `lwsOpen` | `[configJson]` | `{ ok, handle, root }` |
+| `lwsStep` | `[handle, requestJson]` | `{ ok, response }` |
+| `lwsClose` | `[handle]` | `{ ok }` |
+| `lwsSnapshot` | `[handle]` | `{ ok, snapshot }` |
+| `lwsFetched` | `[handle, documentJson]` | `{ ok, fetch? , installed?, refused? }` |
+
+```
+request  { method, target, headers: [[name, value]] } + the content as bytes
+response { status, headers: [[name, value]], bodyBytes } + the content as bytes
+(through callBlobIO; https://github.com/danbri/factoidal/issues/889)
+```
+
+`headers` is a list of pairs, not an object: HTTP allows a field name to
+repeat and the order of repeated fields carries meaning. `target` is a
+path within the storage, so Node's `request.url` is passed through
+unchanged and this host composes no IRI.
+
+`configJson` members, all optional: `baseIri` (the absolute IRI the
+storage root maps to), `now` (the engine clock in seconds, which advances
+by one second per mutation so a write sequence has increasing
+`Last-Modified` values with no real clock), `owner`, `agent`, `rootAcl`,
+`auth` and `insecureNoAuth` (below). A request
+may carry `now` and `agent` of its own to override the handle's for one
+step; `listen({realClock: true})` is how a server with a real clock feeds
+one in, and a test leaves it off to keep the engine's deterministic
+clock. The full contract is `docs/lws-solid-conformance.md`, section
+"wasm ABI".
+
+A WebAssembly module built before these ops landed answers `unknown op`.
+`lwsOpsAvailable(engine)` reports that as `{available: false, reason}`,
+and every test in `tests/lws/` skips with the reason printed rather than
+passing on an engine that cannot answer.
+
+## Authorization
+
+Authorization follows the draft's "Authorization" section
+(https://github.com/danbri/factoidal/issues/886) and is decided by
+`formal/lean4/L4Factoidal/LWS/Authorization.lean`. It is ON by default.
+
+```js
+const running = await listen({
+  port: 3000,
+  owner: 'https://id.example/alice',          // root ACL: Read, Write, Control
+  auth: { issuers: [{ issuer: 'https://as.example' }] },
+  realClock: true
+})
+```
+
+* Clients send `Authorization: Bearer <access token>` (RFC 6750). The
+  token is a JWT (RFC 9068) signed with ES256, RS256 or EdDSA by a trusted
+  issuer; `aud` must contain the storage IRI (`baseIri`, or `auth.audience`).
+* Without a valid token the answer is 401 with
+  `WWW-Authenticate: Bearer resource_metadata="…"`; the RFC 9728 metadata
+  document is served at `/.well-known/oauth-protected-resource<path>`.
+* The host fetches the issuer's `/.well-known/lws-configuration` and its
+  `jwks_uri` when the engine asks (`lwsStep` answers `{ fetch }`), passes
+  the bytes to `lwsFetched`, and steps again. `auth.issuers[].jwks` gives
+  the keys inline instead.
+* `insecureNoAuth: true` serves every request with no authorization. It is
+  for development only, and must be asked for.
+
+## Use
+
+```js
+import { listen } from '@factoidal/core/lws'
+
+const running = await listen({ port: 3000, baseIri: 'https://storage.example/',
+  insecureNoAuth: true })   // development only; see Authorization
+console.log(running.origin)
+await running.close()
+```
+
+From the command:
+
+```
+factoidal lws-serve /var/lib/lws --port 3000 --issuer https://as.example --owner https://id.example/alice
+factoidal lws-serve /tmp/dev --port 3000 --insecure-no-auth
+```
+
+One of `--issuer`, `--auth-config FILE` or `--insecure-no-auth` is
+required.
+
+`--port 0` takes an ephemeral port and the command prints the one it got;
+`--base IRI` sets `baseIri`, which defaults to the bound origin. `DIR`
+names the storage directory, but the first slice keeps the resource tree
+in the engine handle, so nothing is read from it or written to it yet
+(design record, section 2).
+
+## Exports
+
+| name | what it is |
+| --- | --- |
+| `listen(options)` | start a server, resolve when it is listening |
+| `createLwsServer(options)` | build the server without listening |
+| `openLwsStorage(options)` | open a handle and get `step` / `close` |
+| `createLwsServer(...).setBaseIri(iri)` | set `baseIri` before the first request |
+| `lwsOpsAvailable(engine)` | probe the loaded module for the ops |
+| `LWS_OPS` | the op names |
+| `LwsHostError` | a host failure, with `unknownOp` set when the op is absent |
+
+## Tests
+
+```
+node tests/lws/server.mjs
+node tests/lws/draft-binding.mjs
+node tests/lws/binary-bodies.mjs
+node tests/lws/authorization.mjs
+deno run --allow-read --allow-net --allow-write --allow-env tests/lws/server.mjs
+```

package/lws/persist.mjs

@@ -0,0 +1,78 @@
+// Durable storage for `factoidal lws-serve DIR` and `solid-serve DIR`.
+// https://github.com/danbri/factoidal/issues/659
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Move bytes between one file and the engine. The engine decides what
+// the bytes are (`L4Factoidal/LWS/Snapshot.lean`): the snapshot document,
+// which paths it may hold (no `..`, no absolute or encoded traversal), and
+// when the storage changed (the `changed` member of the step envelope).
+// This file decides only where the one file lives and how it is written:
+//
+//   DIR/lws-state.json      the snapshot, replaced atomically
+//
+// No request target ever becomes a file name here, so a request cannot
+// address a file outside DIR. The write is: a temporary file in DIR,
+// fsync, rename over the state file, fsync of DIR. A crash leaves the old
+// snapshot or the new one, never a torn one.
+
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+export const STATE_FILE = 'lws-state.json'
+
+/** The absolute path of the state file of a storage directory. */
+export function stateFileOf (dir) {
+  return join(resolve(dir), STATE_FILE)
+}
+
+/**
+ * The parsed snapshot in DIR, or `null` when DIR holds none yet. The
+ * engine checks the document; a file that does not parse as JSON is an
+ * error of this host, reported as such.
+ */
+export function readSnapshot (dir) {
+  const file = stateFileOf(dir)
+  if (!existsSync(file)) return null
+  const text = readFileSync(file, 'utf8')
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new Error(`${file} is not JSON: ${error.message}`)
+  }
+}
+
+/** Write a snapshot document to DIR, atomically. */
+export function writeSnapshot (dir, snapshot) {
+  const root = resolve(dir)
+  mkdirSync(root, { recursive: true })
+  const file = stateFileOf(root)
+  const temporary = join(root, `.${STATE_FILE}.${process.pid}.tmp`)
+  const fd = openSync(temporary, 'w', 0o600)
+  try {
+    writeSync(fd, JSON.stringify(snapshot))
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  renameSync(temporary, file)
+  try {
+    const dirFd = openSync(root, 'r')
+    try { fsyncSync(dirFd) } finally { closeSync(dirFd) }
+  } catch (_error) {
+    // Some platforms cannot fsync a directory; the rename stands.
+  }
+}
+
+/**
+ * After one step: when the engine says the storage changed, ask it for
+ * the snapshot (`snapshotOp`) and write it.
+ */
+export function persistIfChanged (engine, snapshotOp, handle, envelope, dir) {
+  if (typeof dir !== 'string' || envelope === null || typeof envelope !== 'object') return
+  if (envelope.changed !== true) return
+  const answer = engine.call(snapshotOp, [handle])
+  if (answer === null || typeof answer !== 'object' || answer.snapshot === undefined) {
+    throw new Error(`${snapshotOp} answered with no snapshot`)
+  }
+  writeSnapshot(dir, answer.snapshot)
+}

package/lws/server.mjs

@@ -0,0 +1,416 @@
+// A Node HTTP host for the Linked Web Storage Protocol 1.0 core.
+// https://github.com/danbri/factoidal/issues/659
+// Design record: docs/designissues/2026-09-06-lws-and-solid-protocols.md
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Accept a socket, turn one HTTP request into the JSON request record,
+// call the engine's `lwsStep` on a handle, and write the JSON response
+// record back onto the socket. That is the whole contract.
+//
+// It makes NO protocol decision. It does not choose a status code, does
+// not build a `Link` header, does not read or write a resource, does not
+// decide whether a PATCH is refused, and does not know what a container
+// is. Every one of those lives in `formal/lean4/L4Factoidal/LWS/`
+// (iron rule 7 of CLAUDE.md). A reviewer who finds a status code, a
+// media type decision or an RDF term in this file has found a rule
+// violation. The one status code written here is 500, and only for a
+// failure of this host itself.
+//
+// THE WASM CONTRACT
+// Fixed in docs/lws-solid-conformance.md, section "wasm ABI".
+//   lwsOpen  [configJson]            -> { ok, handle, root }
+//   lwsStep  [handle, requestJson]   -> { ok, response }
+//   lwsClose [handle]                -> { ok }
+//   lwsFetched [handle, documentJson] -> { ok, fetch? | installed? | refused? }
+//
+// `lwsStep` may answer `{ ok, fetch: { issuer, url } }` instead of a
+// response: the engine needs an authorization server's metadata or key
+// set before it can decide. This host fetches that URL, passes
+// `{ issuer, url, status, body, now }` to `lwsFetched`, follows any
+// further `fetch` it names, and steps the request again.
+//
+//   request  { method, target, headers: [[name, value]] } + content bytes
+//   response { status, headers: [[name, value]], bodyBytes } + content bytes
+//
+// Bodies are BYTES (https://github.com/danbri/factoidal/issues/889). The
+// step goes through the engine's byte-region entry, `callBlobIO`: the
+// request content is the IN region and the response content is the OUT
+// region, with no encoding and no decoding here. This host never reads a
+// body as text.
+//
+// The config members are `baseIri`, `now`, `owner`, `agent`, `rootAcl`,
+// `auth` and `insecureNoAuth`, all optional. `target` is a path within the storage, so this host passes
+// Node's `request.url` through unchanged and never composes an absolute
+// IRI: `baseIri` tells the engine what the root maps to.
+//
+// A request may carry `now` and `agent` beside `method` to override the
+// handle's clock and agent for one step. That is how a host with a real
+// clock and a real token verifier feeds both in; this host sets `now`
+// from its own clock only when the caller asked for it, so a test can
+// keep the engine's deterministic clock.
+//
+// `headers` is a list of pairs rather than an object because HTTP allows
+// a field name to repeat and the order of repeated fields is
+// significant; an object would lose both.
+//
+// The reader of the response envelope accepts the response record either
+// under `response` or spread onto the envelope itself, and the handle
+// either as `handle` or as `id`. This is deliberate tolerance while the
+// Lean side of the contract lands, not two supported shapes: when
+// `docs/lws-solid-conformance.md` fixes one, the other stops being
+// produced and this code keeps working unchanged.
+
+import { loadEngine } from '../bin/engine.mjs'
+import { readSnapshot, persistIfChanged } from './persist.mjs'
+
+/** The ops this host needs from the engine. */
+export const LWS_OPS = ['lwsOpen', 'lwsStep', 'lwsClose', 'lwsSnapshot', 'lwsFetched']
+
+/** The most documents one request may make this host fetch before the
+ *  engine has answered it. The engine names at most two per issuer (its
+ *  metadata, then its key set); this bound only stops a defective module
+ *  from looping the host. */
+const MAX_FETCHES = 8
+
+/**
+ * Fetch one document the engine named, for `lwsFetched`. Pure I/O: the
+ * engine decides what the bytes mean. A network failure is reported as
+ * status 0, which the engine refuses like any other failed fetch.
+ */
+async function fetchDocument (url) {
+  try {
+    const answer = await fetch(url, { redirect: 'error' })
+    return { status: answer.status, body: await answer.text() }
+  } catch (error) {
+    return { status: 0, body: String(error && error.message ? error.message : error) }
+  }
+}
+
+/** An error raised by the LWS host, as opposed to one the engine
+ *  reported. `unknownOp` is set when the loaded WebAssembly module does
+ *  not carry the operation at all, which is what a test skips on. */
+export class LwsHostError extends Error {
+  constructor (message, detail = {}) {
+    super(message)
+    this.name = 'LwsHostError'
+    this.unknownOp = detail.unknownOp === true
+  }
+}
+
+function isUnknownOp (error) {
+  const text = error && error.message ? String(error.message) : String(error)
+  return text.indexOf('unknown op') >= 0
+}
+
+/**
+ * Whether the loaded engine carries the LWS operations.
+ *
+ * One call is made and its refusal read. A module built before the LWS
+ * ops landed answers "unknown op"; anything else -- including an engine
+ * complaint about the configuration -- means the op is present.
+ *
+ * @param {object} engine the handle from `loadEngine()`
+ * @returns {Promise<{available: boolean, reason: string}>}
+ */
+export async function lwsOpsAvailable (engine) {
+  try {
+    const opened = engine.call('lwsOpen', [JSON.stringify({ probe: true })])
+    const handle = handleOf(opened)
+    if (handle !== null) {
+      try { engine.call('lwsClose', [handle]) } catch (_error) { /* probe only */ }
+    }
+    return { available: true, reason: 'lwsOpen answered' }
+  } catch (error) {
+    if (isUnknownOp(error)) {
+      return {
+        available: false,
+        reason: 'the loaded l4factoidal WebAssembly module does not carry ' +
+          'the lws ops (rebuild formal/lean4/Wasm)'
+      }
+    }
+    return { available: true, reason: 'lwsOpen answered with an engine error' }
+  }
+}
+
+function handleOf (envelope) {
+  if (envelope === null || typeof envelope !== 'object') return null
+  for (const name of ['handle', 'id']) {
+    const value = envelope[name]
+    if (typeof value === 'string' && value.length > 0) return value
+    if (typeof value === 'number') return String(value)
+  }
+  return null
+}
+
+function responseOf (envelope, bytes) {
+  if (envelope === null || typeof envelope !== 'object') {
+    throw new LwsHostError('lwsStep answered with no envelope')
+  }
+  const record = (envelope.response !== null && typeof envelope.response === 'object')
+    ? envelope.response
+    : envelope
+  if (typeof record.status !== 'number') {
+    throw new LwsHostError('lwsStep answered with no status in its response record')
+  }
+  const headers = Array.isArray(record.headers) ? record.headers : []
+  const body = bytes instanceof Uint8Array ? bytes : new Uint8Array(0)
+  return { status: record.status, headers, body }
+}
+
+/** The request content as bytes: a byte array is passed as it is, and a
+ *  string (a JavaScript caller's convenience) as its UTF-8 bytes. */
+function contentBytes (request) {
+  if (request.body instanceof Uint8Array) return request.body
+  if (typeof request.body === 'string') return new TextEncoder().encode(request.body)
+  return new Uint8Array(0)
+}
+
+/**
+ * Open one LWS storage on the engine and return the handle plus the two
+ * calls a host makes against it.
+ *
+ * The config members are the ABI's own: `baseIri`, `now`, `owner`,
+ * `agent`. Nothing else is sent.
+ *
+ * @param {object} options
+ * @param {string} [options.baseIri] the absolute IRI the storage root maps to
+ * @param {number} [options.now] the engine clock, seconds since the epoch
+ * @param {string} [options.owner] the WebID the storage advertises
+ * @param {string} [options.agent] the WebID of the requesting agent
+ * @param {boolean} [options.realClock] stamp each request with this host's clock
+ * @param {object} [options.engine] an engine handle to reuse
+ * @returns {Promise<{step: Function, close: Function, handle: string, engine: object}>}
+ */
+export async function openLwsStorage (options = {}) {
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const config = {}
+  if (typeof options.baseIri === 'string') config.baseIri = options.baseIri
+  if (typeof options.now === 'number') config.now = options.now
+  if (typeof options.owner === 'string') config.owner = options.owner
+  if (typeof options.agent === 'string') config.agent = options.agent
+  // Authorization (L4Factoidal/LWS/Authorization.lean). `auth` is passed
+  // through unread; `insecureNoAuth` is the explicit development mode.
+  // With neither, the engine enforces authorization with no trusted
+  // issuer.
+  if (options.auth !== undefined && options.auth !== null) config.auth = options.auth
+  if (options.insecureNoAuth === true) config.insecureNoAuth = true
+  if (typeof options.rootAcl === 'string') config.rootAcl = options.rootAcl
+  // `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
+  if (dir !== null) {
+    const snapshot = readSnapshot(dir)
+    if (snapshot !== null) config.snapshot = snapshot
+  }
+  let opened
+  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
+  }
+  const handle = handleOf(opened)
+  if (handle === null) {
+    throw new LwsHostError('lwsOpen answered with no handle')
+  }
+  return {
+    engine,
+    handle,
+    /**
+     * One protocol step.
+     * @param {{method: string, target: string,
+     *          headers: Array<[string, string]>, body: Uint8Array|string}} request
+     * @returns {{status: number, headers: Array<[string, string]>, body: Uint8Array}}
+     */
+    async step (request) {
+      const content = contentBytes(request)
+      const { body: _body, ...fields } = request
+      const record = options.realClock === true
+        ? { ...fields, now: Math.floor(Date.now() / 1000) }
+        : fields
+      const callStep = () => engine.callBlobIO('lwsStep', [handle, JSON.stringify(record)], content)
+      let answered = callStep()
+      let envelope = answered.envelope
+      // The engine may answer "fetch this document first" (an issuer's
+      // metadata or key set). The host fetches exactly what it is told,
+      // hands the bytes back, and steps the request again.
+      let fetches = 0
+      while (envelope !== null && typeof envelope === 'object' &&
+             envelope.fetch !== undefined && envelope.fetch !== null) {
+        let wanted = envelope.fetch
+        while (wanted !== undefined && wanted !== null) {
+          fetches += 1
+          if (fetches > MAX_FETCHES) {
+            throw new LwsHostError('the engine asked for more documents than one request may fetch')
+          }
+          const got = await fetchDocument(wanted.url)
+          const told = engine.call('lwsFetched', [handle, JSON.stringify({
+            issuer: wanted.issuer, url: wanted.url, status: got.status, body: got.body,
+            ...(typeof record.now === 'number' ? { now: record.now } : {})
+          })])
+          wanted = told !== null && typeof told === 'object' ? told.fetch : null
+        }
+        answered = callStep()
+        envelope = answered.envelope
+      }
+      const answer = responseOf(envelope, answered.bytes)
+      if (dir !== null) persistIfChanged(engine, 'lwsSnapshot', handle, envelope, dir)
+      return answer
+    },
+    close () {
+      try { engine.call('lwsClose', [handle]) } catch (_error) { /* already gone */ }
+    }
+  }
+}
+
+/** Read a Node request body as its bytes. */
+function readBody (request) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    request.on('data', (chunk) => chunks.push(chunk))
+    request.on('error', reject)
+    request.on('end', () => resolve(new Uint8Array(Buffer.concat(chunks))))
+  })
+}
+
+/** Node's flat `rawHeaders` array as the pairs the contract wants. */
+function headerPairs (raw) {
+  const pairs = []
+  for (let index = 0; index + 1 < raw.length; index += 2) {
+    pairs.push([raw[index], raw[index + 1]])
+  }
+  return pairs
+}
+
+/**
+ * A Node `http.Server` that answers every request through `lwsStep`.
+ *
+ * The server is returned unlistened: the caller chooses the port, which
+ * is what lets a test take an ephemeral one. The storage handle is
+ * opened on demand rather than here, because with an ephemeral port the
+ * origin `baseIri` maps the storage root to is not known until the
+ * socket is bound.
+ *
+ * @param {object} options as `openLwsStorage`, plus `onError`
+ * @returns {Promise<{server: import('node:http').Server,
+ *                    storage: Function, close: Function,
+ *                    setBaseIri: Function}>}
+ */
+export async function createLwsServer (options = {}) {
+  const http = await import('node:http')
+  const onError = typeof options.onError === 'function'
+    ? options.onError
+    : (error) => { console.error(`lws-serve: ${error.message}`) }
+
+  let settings = { ...options }
+  let opening = null
+  let opened = null
+
+  /** The storage handle, opened once. */
+  function storage () {
+    if (opening === null) {
+      opening = openLwsStorage(settings).then((value) => { opened = value; return value })
+    }
+    return opening
+  }
+
+  const server = http.createServer(async (request, response) => {
+    let record
+    try {
+      record = {
+        method: request.method,
+        target: request.url,
+        headers: headerPairs(request.rawHeaders),
+        body: await readBody(request)
+      }
+    } catch (error) {
+      onError(error)
+      response.writeHead(500, { 'content-type': 'text/plain' })
+      response.end('lws-serve: could not read the request body\n')
+      return
+    }
+    let answer
+    try {
+      answer = await (await storage()).step(record)
+    } catch (error) {
+      // A failure of this host or of the engine, not a protocol answer.
+      // The engine's own words are kept; nothing is invented.
+      onError(error)
+      response.writeHead(500, { 'content-type': 'text/plain' })
+      response.end(`lws-serve: ${error.message}\n`)
+      return
+    }
+    writeHeaders(response, answer.headers)
+    response.statusCode = answer.status
+    response.end(answer.body)
+  })
+
+  return {
+    server,
+    storage,
+    /** Set the storage root's absolute IRI, before the first request. */
+    setBaseIri (value) {
+      if (opening !== null) {
+        throw new LwsHostError('the storage is already open; set baseIri first')
+      }
+      settings = { ...settings, baseIri: value }
+    },
+    close () {
+      return new Promise((resolve) => {
+        server.close(() => {
+          if (opened !== null) opened.close()
+          resolve()
+        })
+      })
+    }
+  }
+}
+
+/** Write one response record's header pairs, keeping repeats. */
+function writeHeaders (response, pairs) {
+  for (const pair of pairs) {
+    if (!Array.isArray(pair) || pair.length < 2) continue
+    const existing = response.getHeader(pair[0])
+    if (existing === undefined) {
+      response.setHeader(pair[0], String(pair[1]))
+    } else if (Array.isArray(existing)) {
+      response.setHeader(pair[0], existing.concat([String(pair[1])]))
+    } else {
+      response.setHeader(pair[0], [String(existing), String(pair[1])])
+    }
+  }
+}
+
+/**
+ * Start a server and resolve once it is listening and the storage is
+ * open. The storage is opened here rather than on the first request so
+ * that a module without the LWS ops is reported by the command that
+ * started the server, not by a later request.
+ *
+ * @param {object} options as `createLwsServer`, plus `port` and `host`
+ * @returns {Promise<{server: object, storage: Function, port: number,
+ *                    origin: string, close: Function}>}
+ */
+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'
+  const created = await createLwsServer(options)
+  await new Promise((resolve, reject) => {
+    created.server.once('error', reject)
+    created.server.listen(port, host, resolve)
+  })
+  const bound = created.server.address()
+  const origin = `http://${host}:${bound.port}`
+  if (typeof options.baseIri !== 'string') created.setBaseIri(`${origin}/`)
+  try {
+    await created.storage()
+  } catch (error) {
+    await new Promise((resolve) => created.server.close(resolve))
+    throw error
+  }
+  return { ...created, port: bound.port, origin }
+}