@factoidal/core 0.12.0 → 0.14.0

package/lws/client.mjs

@@ -0,0 +1,319 @@
+// A `fetch` host for the Linked Web Storage 1.0 client.
+// https://github.com/danbri/factoidal/issues/917
+// Design record: docs/designissues/2026-10-22-lws-client.md
+// Drafts: https://w3c.github.io/lws-protocol/lws10-core/ (and lws10-index,
+// lws10-notifications-webhook)
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Call `lwsClientStart` with the caller's operation, then loop: when the
+// engine's action is `fetch`, send exactly that request with the `fetch`
+// it was given and pass the answer to `lwsClientStep`; when it is `done` or
+// `fail`, return or throw. It is a socket and nothing else.
+//
+// Every decision is in formal/lean4/L4Factoidal/LWS/Client/ (iron rule 7
+// of CLAUDE.md, anti-pattern 36): which request comes next, every header
+// field, every URL, every media type, the authorization flow and its
+// discovery checks, preconditions, retries, paging, and whether a
+// notification's signature verifies. This file reads no header, composes no
+// URL and chooses no media type. A reviewer who finds a header name, a
+// status code, a media type or a link relation here has found a rule
+// violation.
+//
+// THE WASM CONTRACT (docs/lws-solid-conformance.md, section "wasm ABI")
+//   lwsClientStart [opJson, sessionJson] -> { ok, state, action }
+//   lwsClientStep  [stateJson, eventJson] -> { ok, state, action }
+//
+//   action  { fetch: { method, url, headers: [[name, value]], bodyBase64? } }
+//         | { done: RESULT, session } | { fail: { code, ... }, session }
+//   event   { status, headers: [[name, value]], bodyBase64 } | { error }
+//
+// `state` is passed back unread. `session` (access tokens, the subject
+// token) is kept here and given to the next operation's start, unread.
+//
+// `fetch` is any function with the WHATWG fetch signature: Node's, a
+// browser's, or one that carries each request as a message over another
+// transport (XMPP, a worker port). The client needs no global fetch.
+
+import { loadEngine } from '../bin/engine.mjs'
+import { FactoidalError } from '../lib/errors.mjs'
+
+/** The ops this host needs from the engine. */
+export const LWS_CLIENT_OPS = ['lwsClientStart', 'lwsClientStep']
+
+/** The operation kinds of the ABI. Listed so a caller can be checked
+ *  against the contract; this host attaches no meaning to any of them. */
+export const LWS_CLIENT_KINDS = [
+  'discover', 'read', 'head', 'create', 'update', 'patch', 'delete', 'readLinkset',
+  'updateLinkset', 'move', 'list', 'typeIndex', 'search', 'subscribe', 'unsubscribe',
+  'requestAccess', 'grantAccess', 'getAccess', 'revokeAccess', 'verifyNotification'
+]
+
+/** The error an operation ends with. `reason` is the engine's code
+ *  (`discoveryValidation`, `preconditionFailed`, ...); `detail` is the
+ *  engine's whole `fail` document. */
+export class LwsClientError extends FactoidalError {
+  constructor (fail, extra = {}) {
+    const reason = fail && typeof fail.code === 'string' ? fail.code : 'unknown'
+    super(`lws client: ${reason}`, { code: 'lws.client' })
+    this.name = 'LwsClientError'
+    this.reason = reason
+    this.detail = fail
+    this.unknownOp = extra.unknownOp === true
+  }
+}
+
+function isUnknownOp (error) {
+  const text = error && error.message ? String(error.message) : String(error)
+  return text.indexOf('unknown op') >= 0
+}
+
+/** Bytes as base64 (RFC 4648 section 4): the transport encoding of the
+ *  string ABI, not a reading of the bytes. */
+function base64OfBytes (bytes) {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64')
+  }
+  let text = ''
+  for (let index = 0; index < bytes.length; index += 1) text += String.fromCharCode(bytes[index])
+  return btoa(text)
+}
+
+function bytesOfBase64 (text) {
+  if (typeof Buffer !== 'undefined') return new Uint8Array(Buffer.from(text, 'base64'))
+  const raw = atob(text)
+  const out = new Uint8Array(raw.length)
+  for (let index = 0; index < raw.length; index += 1) out[index] = raw.charCodeAt(index)
+  return out
+}
+
+/** A caller's body (string, Uint8Array, ArrayBuffer) as bytes. */
+function bytesOf (body) {
+  if (body === undefined || body === null) return null
+  if (typeof body === 'string') return new TextEncoder().encode(body)
+  if (body instanceof Uint8Array) return body
+  if (body instanceof ArrayBuffer) return new Uint8Array(body)
+  throw new TypeError('a body is a string, a Uint8Array or an ArrayBuffer')
+}
+
+/** An operation document: the caller's members, with a body carried as
+ *  base64. */
+function opDocument (op) {
+  const doc = { ...op }
+  if (doc.body !== undefined) {
+    const bytes = bytesOf(doc.body)
+    delete doc.body
+    if (bytes !== null) doc.bodyBase64 = base64OfBytes(bytes)
+  }
+  return doc
+}
+
+/**
+ * Whether the loaded engine carries the client operations.
+ *
+ * @param {object} engine the handle from `loadEngine()`
+ * @returns {Promise<{available: boolean, reason: string}>}
+ */
+export async function lwsClientOpsAvailable (engine) {
+  try {
+    engine.call('lwsClientStart', [JSON.stringify({ kind: 'head', url: 'http://localhost/' }), ''])
+    return { available: true, reason: 'lwsClientStart answered' }
+  } catch (error) {
+    if (isUnknownOp(error)) {
+      return {
+        available: false,
+        reason: 'the loaded l4factoidal WebAssembly module does not carry the LWS client ops ' +
+          '(rebuild formal/lean4/Wasm)'
+      }
+    }
+    return { available: true, reason: 'lwsClientStart answered with an engine error' }
+  }
+}
+
+/**
+ * An LWS client bound to one engine and one `fetch`.
+ *
+ * @param {object} [options]
+ * @param {object} [options.engine] an engine handle to reuse
+ * @param {Function} [options.fetch] the fetch to use (default `globalThis.fetch`)
+ * @param {string} [options.subjectToken] the authentication credential to
+ *   exchange for access tokens (RFC 8693 subject_token)
+ * @param {string} [options.subjectTokenType] its token type URI
+ * @param {object} [options.selfIssued] `{ subject, keyId, jwk }`: a P-256 key
+ *   to sign self-issued credentials with, instead of a subject token
+ * @param {object} [options.session] a session from an earlier client
+ * @param {number} [options.maxSteps] the loop cap of one operation
+ * @returns {Promise<object>} the client
+ */
+export async function createLwsClient (options = {}) {
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const wire = typeof options.fetch === 'function' ? options.fetch : globalThis.fetch
+  if (typeof wire !== 'function') throw new TypeError('no fetch is available in this runtime')
+  const maxSteps = typeof options.maxSteps === 'number' ? options.maxSteps : 1024
+  let session = options.session !== undefined && options.session !== null
+    ? { ...options.session }
+    : {}
+  if (typeof options.subjectToken === 'string') session.subjectToken = options.subjectToken
+  if (typeof options.subjectTokenType === 'string') session.subjectTokenType = options.subjectTokenType
+  // `{ subject, keyId, jwk }`: a P-256 key the engine signs self-issued
+  // credentials with (lws10-authn-ssi-cid), passed through unread.
+  if (options.selfIssued !== undefined) session.selfIssued = options.selfIssued
+
+  function call (op, args) {
+    try {
+      return engine.call(op, args)
+    } catch (error) {
+      if (isUnknownOp(error)) {
+        throw new LwsClientError({ code: 'unknownOp', op }, { unknownOp: true })
+      }
+      throw error
+    }
+  }
+
+  /** Send one request exactly as the engine wrote it; the answer as an
+   *  event document. */
+  async function exchange (request) {
+    const init = {
+      method: request.method,
+      headers: Array.isArray(request.headers) ? request.headers : [],
+      redirect: 'manual'
+    }
+    if (typeof request.bodyBase64 === 'string') init.body = bytesOfBase64(request.bodyBase64)
+    let reply
+    try {
+      reply = await wire(request.url, init)
+    } catch (error) {
+      return { error: error && error.message ? String(error.message) : String(error) }
+    }
+    const headers = []
+    reply.headers.forEach((value, name) => { headers.push([name, value]) })
+    const bytes = new Uint8Array(await reply.arrayBuffer())
+    // The host's clock and random source, which the engine cannot reach: the
+    // iat, exp, nonce and jti of a self-issued credential.
+    const random = new Uint8Array(48)
+    globalThis.crypto.getRandomValues(random)
+    return {
+      status: reply.status,
+      headers,
+      bodyBase64: base64OfBytes(bytes),
+      now: Math.floor(Date.now() / 1000),
+      randomBase64: base64OfBytes(random)
+    }
+  }
+
+  /**
+   * Run one operation to its end.
+   *
+   * @param {object} op `{ kind, url, ... }`; `body` may be a string or bytes
+   * @returns {Promise<object>} the engine's `done` document
+   */
+  async function run (op) {
+    let envelope = call('lwsClientStart', [JSON.stringify(opDocument(op)), JSON.stringify(session)])
+    for (let step = 0; step < maxSteps; step += 1) {
+      const action = envelope.action || {}
+      if (action.fetch !== undefined) {
+        const event = await exchange(action.fetch)
+        envelope = call('lwsClientStep', [JSON.stringify(envelope.state), JSON.stringify(event)])
+        continue
+      }
+      if (action.session !== undefined) session = action.session
+      if (action.done !== undefined) return action.done
+      throw new LwsClientError(action.fail)
+    }
+    throw new LwsClientError({ code: 'hostStepLimit', steps: maxSteps })
+  }
+
+  const with_ = (kind) => (url, args = {}) => run({ ...args, kind, url })
+
+  return {
+    engine,
+    run,
+    /** The session (access tokens and subject token), for a later client. */
+    session: () => ({ ...session }),
+    discover: with_('discover'),
+    read: with_('read'),
+    head: with_('head'),
+    /** `create(containerUrl, { body, mediaType, slug, container, types, links })` */
+    create: with_('create'),
+    /** `update(url, { body, mediaType, precondition, tag, retry412, links })` */
+    update: with_('update'),
+    patch: with_('patch'),
+    /** `delete(url, { recursive, precondition, tag })` */
+    delete: with_('delete'),
+    readLinkset: with_('readLinkset'),
+    updateLinkset: with_('updateLinkset'),
+    /** `move(url, { destination })` */
+    move: with_('move'),
+    list: with_('list'),
+    typeIndex: with_('typeIndex'),
+    /** `search(anyUrlInTheStorage, { query })` */
+    search: with_('search'),
+    subscribe: with_('subscribe'),
+    unsubscribe: with_('unsubscribe'),
+    requestAccess: with_('requestAccess'),
+    grantAccess: with_('grantAccess'),
+    getAccess: with_('getAccess'),
+    revokeAccess: with_('revokeAccess'),
+    /** `verifyNotification(baseUrl, { requestTarget, method, headers, body })`:
+     *  the engine's verdict `{ accept, status, reason? }`. */
+    verifyNotification: with_('verifyNotification')
+  }
+}
+
+/**
+ * An HTTP receiver for webhook notifications. For each request it asks the
+ * engine (`verifyNotification`) and answers with the status of the
+ * verdict; an accepted notification goes to `onNotification`. The receiver
+ * reads no header and decides nothing.
+ *
+ * @param {object} options
+ * @param {object} options.client a client from `createLwsClient`
+ * @param {Function} [options.onNotification] `(verdict, bodyBytes, request)`
+ * @param {number} [options.port] default 0 (an ephemeral port)
+ * @param {string} [options.host] default 127.0.0.1
+ * @returns {Promise<{ url: string, close: Function, received: Function }>}
+ *   `url` is the receiver's base URL; any path under it receives
+ */
+export async function createNotificationReceiver (options) {
+  const { createServer } = await import('node:http')
+  const client = options.client
+  const host = typeof options.host === 'string' ? options.host : '127.0.0.1'
+  let base = ''
+  const verdicts = []
+  const server = createServer((request, response) => {
+    const chunks = []
+    request.on('data', (chunk) => chunks.push(chunk))
+    request.on('end', async () => {
+      const body = new Uint8Array(Buffer.concat(chunks))
+      const headers = []
+      for (let index = 0; index + 1 < request.rawHeaders.length; index += 2) {
+        headers.push([request.rawHeaders[index], request.rawHeaders[index + 1]])
+      }
+      let verdict
+      try {
+        verdict = await client.verifyNotification(base, {
+          requestTarget: request.url, method: request.method, headers, body
+        })
+      } catch (error) {
+        response.statusCode = 500
+        response.end()
+        return
+      }
+      verdicts.push(verdict)
+      if (verdict.accept === true && typeof options.onNotification === 'function') {
+        try { options.onNotification(verdict, body, { target: request.url, headers }) } catch (_e) { /* the caller's */ }
+      }
+      response.statusCode = verdict.status
+      response.end()
+    })
+  })
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(typeof options.port === 'number' ? options.port : 0, host, resolve)
+  })
+  base = `http://${host}:${server.address().port}/`
+  return {
+    url: base,
+    received: () => verdicts.slice(),
+    close: () => new Promise((resolve) => server.close(resolve))
+  }
+}

package/lws/persist.mjs

@@ -155,7 +155,9 @@ export function persistIfChanged (engine, snapshotOp, handle, envelope, dir) {
 // part of the file only performs what the engine names:
 //
 //   * reads: the engine names files (paths relative to DIR); each is read
-//     whole, or reported absent;
+//     whole, or reported absent. At start (`lwsLoad`) and before a step that
+//     needs the bytes of a resource (a `read` answer of `lwsStep`, given to
+//     `lwsRead`, stage 2 of issue 918);
 //   * a plan of file operations, in order, with their bytes in one region:
 //       write  {path, temp, offset, length}  parent directory, temp file,
 //                                            fsync, rename, fsync directory
@@ -297,6 +299,20 @@ export function loadFiles (engine, handle, opened, dir) {
   throw new Error('lwsLoad asked for more reads than one start may make')
 }
 
+/**
+ * Before one step of a storage kept in files (stage 2): read the body files
+ * the engine named in a `read` answer and give them to `lwsRead`. The engine
+ * checks each one (seal, length, digests); a refusal is thrown as its error.
+ */
+export function readStepBodies (engine, handle, names, dir) {
+  const { files, region } = readNamedFiles(dir, Array.isArray(names) ? names : [])
+  const answered = engine.callBlobIO('lwsRead', [handle, JSON.stringify({ files })], region)
+  const envelope = answered.envelope
+  if (envelope === null || typeof envelope !== 'object' || envelope.ok !== true) {
+    throw new Error(`lwsRead: ${envelope !== null && typeof envelope === 'object' ? envelope.error : 'no answer'}`)
+  }
+}
+
 /**
  * After one step of a storage kept in files: when the engine says the
  * storage changed, ask it for the write plan (`lwsPersist`) and perform it.

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 } from './persist.mjs'
+import { readSnapshot, persistIfChanged, storageKeyText, storageModeText, loadFiles, persistFilesIfChanged, readStepBodies } from './persist.mjs'
 
 /** The ops this host needs from the engine. */
 export const LWS_OPS = ['lwsOpen', 'lwsStep', 'lwsClose', 'lwsSnapshot', 'lwsFetched', 'lwsDelivered',
-  'lwsLoad', 'lwsPersist']
+  'lwsLoad', 'lwsPersist', 'lwsRead']
 
 /** How long this host waits for the answer to one delivery request before
  *  it reports "no answer" (status 0) to the engine. */
@@ -252,6 +252,8 @@ function contentBytes (request) {
  *   default the environment variable FACTOIDAL_LWS_KEY; `null` reads no key
  * @param {string} [options.storage] where DIR keeps the storage: "snapshot" (default, one
  *   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 {object} [options.engine] an engine handle to reuse
  * @returns {Promise<{step: Function, close: Function, handle: string, engine: object}>}
  */
@@ -311,6 +313,10 @@ export async function openLwsStorage (options = {}) {
   if (typeof options.deliveryWindow === 'number') config.deliveryWindow = options.deliveryWindow
   if (typeof options.redirectsMax === 'number') config.redirectsMax = options.redirectsMax
   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.
+  if (options.cors !== undefined) config.cors = options.cors
   // 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()
@@ -460,7 +466,23 @@ export async function openLwsStorage (options = {}) {
       // The engine may ask for the addresses of a host name first
       // (`resolve`); this host resolves it and steps the request again.
       let resolves = 0
-      const callStep = () => engine.callBlobIO('lwsStep', [handle, JSON.stringify(record)], content)
+      // A storage kept in files (https://github.com/danbri/factoidal/issues/918,
+      // stage 2) may answer `read: [NAME, ...]` first: the body files the step
+      // needs. This host reads exactly those files, passes them to `lwsRead`
+      // (the engine checks them), and steps the same request again.
+      const callStep = () => {
+        let got = engine.callBlobIO('lwsStep', [handle, JSON.stringify(record)], content)
+        let reads = 0
+        while (got.envelope !== null && typeof got.envelope === 'object' && Array.isArray(got.envelope.read)) {
+          reads += 1
+          if (reads > 2 || dir === null) {
+            throw new LwsHostError('the engine asked for body files this host cannot read')
+          }
+          readStepBodies(engine, handle, got.envelope.read, dir)
+          got = engine.callBlobIO('lwsStep', [handle, JSON.stringify(record)], content)
+        }
+        return got
+      }
       let answered = callStep()
       let envelope = answered.envelope
       while (envelope !== null && typeof envelope === 'object' &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factoidal/core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "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",
@@ -69,6 +69,7 @@
     "./store-host": "./store-host/index.mjs",
     "./store-host/paths": "./store-host/paths.mjs",
     "./xmpp": "./xmpp/index.mjs",
+    "./xmpp/server": "./xmpp/server.mjs",
     "./store": {
       "default": "./bin/store.mjs"
     },
@@ -87,6 +88,12 @@
     "./lws": {
       "default": "./lws/server.mjs"
     },
+    "./lws/client": {
+      "default": "./lws/client.mjs"
+    },
+    "./authz": {
+      "default": "./authz/server.mjs"
+    },
     "./solid/server": {
       "default": "./solid/server/index.mjs"
     },
@@ -116,6 +123,7 @@
     "lib/",
     "bin/",
     "lws/",
+    "authz/",
     "solid/",
     "store-host/",
     "xmpp/",

package/sample-store.mjs

@@ -27,7 +27,7 @@ ex:c3 a skos:Concept ; skos:inScheme ex:scheme ; skos:prefLabel "SECAM"@en ; sko
 export const sampleStoreFacts = Object.freeze({
   triples: 15,
   source: 'SAMPLE_TURTLE in sample-store.mjs (written for this package)',
-  layout: 'ibk3'
+  layout: 'ibk5'
 })
 
 /**

package/xmpp/README.md

@@ -59,6 +59,85 @@ carries these ops at all, so a caller (or a test) can skip gracefully
 against an older committed bundle instead of getting a confusing
 "unknown op" error.
 
+## The server: `@factoidal/core/xmpp/server` and `factoidal xmpp-serve`
+
+```sh
+mkdir -p state && printf 'juliet:r0m30\nromeo:juli3t\n' > state/accounts
+npx factoidal xmpp-serve state --domain localhost            # plaintext on 5222
+npx factoidal xmpp-serve state --cert fullchain.pem --key privkey.pem   # XEP-0368 direct TLS on 5223
+```
+
+```js
+import { listen } from '@factoidal/core/xmpp/server'
+const running = await listen({ dir: 'state', domain: 'localhost', port: 0 })
+console.log(running.origin)        // xmpp://127.0.0.1:<port>
+await running.close()
+```
+
+`server.mjs` is a socket, a UTF-8 decoder and a routing table. It runs
+one engine session per connection and answers every byte through the
+engine's `xmppSessionFeed` operation; `L4Factoidal.XMPP.Server.step`
+(Lean, `formal/lean4/L4Factoidal/XMPP/Server.lean`) makes every
+protocol decision and the host performs what comes back. It is the same
+library the native carrier (`deploy/fly/xmpp/`, one `l4xmpp-serve`
+process per connection behind socat) serves; the wasm session ops are
+`formal/lean4/Wasm/Ops/XmppSession.lean`.
+
+| op | arguments | answer |
+|---|---|---|
+| `xmppOpen` | `[configJson]` | `{ ok, handle, domain, accounts }` |
+| `xmppSessionOpen` | `[server, optionsJson]` | `{ ok, handle }` — `streamId` and `nonce` are required and come from the host's random source |
+| `xmppSessionFeed` | `[session, text]` | `{ ok, send: [...], route: [{to, text}], presence: [...], rostersSaved: [...], close, stage, bare, full, bufferedBytes }` |
+| `xmppSessionDeliver` | `[session, text]` | `{ ok, delivered, send }` — `delivered:false` for an unbound session; nothing is lost |
+| `xmppSessionClose` | `[session]` | `{ ok, send }` |
+| `xmppRosterGet` / `xmppRosterSet` | `[server, bare]` / `[server, bare, encoded]` | the roster in the engine's own on-disk encoding |
+| `xmppClose` | `[server]` | `{ ok, sessions }` |
+
+The state directory is laid out as the native carrier's, so the two
+hosts can share one: `DIR/accounts` (one `user:password` per line),
+`DIR/roster/<bare jid>.tsv` (persisted on every `rostersSaved`, loaded
+on start), and `DIR/spool/<bare jid>/<file>` — a stanza written there
+by any process is delivered to that account's bound session and
+unlinked. That last one is how a program that is not an XMPP client (a
+web application, say) hands a user a message: write a file.
+
+Roster snapshots are written in order through temporary-file replacement.
+`await running.close()` waits for queued writes and rejects if persistence
+failed. This protects against overlapping writes within one host; it does
+not coordinate concurrent processes or promise recovery after a power loss.
+The spool file is removed when the engine accepts delivery, before any
+remote acknowledgement. Stanzas queued for offline accounts in this Node
+host are held in memory and disappear on process exit.
+
+`maxBuffered` (default 1 MiB) limits the engine's residual UTF-8 input after
+each feed, reported by `bufferedBytes`. A decoder can separately hold up to
+three bytes of an incomplete UTF-8 sequence. This is not a bound on complete
+stanza size, output queues, offline queues, connection count or idle time.
+The host requires this field; an older engine without it closes the affected
+connection with an error. Rebuild the host and engine together.
+
+What it speaks: RFC 6120 stream negotiation, stream errors, SASL PLAIN
+and SCRAM-SHA-256, resource binding; RFC 6121 roster, presence
+subscription and broadcast, message delivery with the server-stamped
+`from`; XEP-0030 `disco#info`; XEP-0368 direct TLS with `--cert`/`--key`.
+Not: STARTTLS, server-to-server federation, MUC/MIX/GC3 rooms, PRECIS.
+Known limitation shared with the native harness: one SCRAM salt per
+server (`saltB64` in the config), not one per account.
+
+The shared engine currently reduces routed destinations to bare JIDs and
+the Node host delivers to every bound resource. It does not implement full
+resource-selection/priority semantics. Binding alone permits delivery; this
+is not a complete presence-availability policy. The plaintext test listener
+also offers SASL PLAIN and has no transport confidentiality. Supplying only
+one of `cert`/`key` is rejected; supplying both selects direct TLS.
+
+Tests: `node --test test/xmpp-serve.test.mjs` drives the host over real
+TCP sockets, including an independent SCRAM-SHA-256 computed with
+`node:crypto`; `tools/xmpp-interop.sh wasm` drives it with
+`@xmpp/client`, a third-party implementation.
+`node --test test/xmpp-host.test.mjs` separately checks IO cleanup and
+persistence with a mock engine; passing it makes no protocol-conformance claim.
+
 ## What this does not cover yet, on purpose
 
 - **Stanza construction from JSON.** `parseStanza` has no inverse: building
@@ -66,10 +145,9 @@ against an older committed bundle instead of getting a confusing
   sibling-node XML constructor the Lean side doesn't have yet.
 - **GC3 itself.** Still an unfinished, early-stage upstream XSF spec —
   see the design record.
-- **SASL/SCRAM computation.** The message *format* exists on the Lean
-  side (`L4Factoidal.XMPP.Sasl`); the actual hash/HMAC computation
-  doesn't yet (no HACL* HMAC-SHA-256 binding — see the design record's
-  crypto section).
+- **SASL/SCRAM computation as a pure function.** The server ops above
+  do SCRAM-SHA-256 (via `L4Factoidal.XMPP.Scram` and the HACL* SHA-256
+  binding); there is no standalone pure op for it in this module.
 - **MUC/MIX interop modules.**
 
 ## Upstream limit found via this module's tests (2026-09-07), repaired 2026-10-10