@factoidal/core 0.11.0 → 0.13.0

package/bin/factoidal.mjs

@@ -101,6 +101,11 @@ commands:
   lws-serve DIR               serve Linked Web Storage 1.0 over HTTP
   solid-serve DIR             serve the Solid Protocol over HTTP
   solid-client OP URL         run one Solid client operation
+  lws-client OP URL           run one Linked Web Storage client operation
+  authz-serve DIR             serve an OAuth 2.0 authorization server for LWS
+                              (RFC 8414 metadata, JWK Set, RFC 8693 token exchange)
+  authz-keys DIR              print the public JWK Set of an authorization server
+  xmpp-serve DIR              serve XMPP (RFC 6120/6121) over TCP or direct TLS
 
 global options:
   -h, --help                  print this text, or a command's own help
@@ -328,11 +333,61 @@ Specifications: https://www.w3.org/TR/sparql11-protocol/
 https://www.w3.org/TR/sparql11-http-rdf-update/
 https://www.w3.org/TR/sparql11-service-description/`,
 
+  'authz-serve': `factoidal authz-serve - serve an OAuth 2.0 authorization server
+
+usage: factoidal authz-serve DIR --resource IRI[,IRI...] [--issuer IRI]
+                           [--port N] [--host ADDRESS] [--alg ES256|EdDSA]
+                           [--token-lifetime SECONDS] [--rotate-after SECONDS]
+                           [--allow-http] [--allow-private-fetch]
+                           [--cors-origin ORIGIN]... [--no-cors]
+
+An authorization server as a component (https://github.com/danbri/factoidal/issues/916),
+for lws-serve and any resource server that reads RFC 8414 metadata:
+  GET  /.well-known/lws-configuration (also /.well-known/oauth-authorization-server)
+  GET  /jwks                          the JWK Set (public keys only)
+  POST /token                         RFC 8693 token exchange for an RFC 9068
+                                      access token whose aud is the resource
+Subject tokens: OpenID Connect ID tokens (lws10-authn-openid) and
+self-issued JWTs for https and did:key subjects (lws10-authn-ssi-cid). SAML
+2.0 is not accepted (https://github.com/danbri/factoidal/issues/926).
+
+--resource names the resource IRIs (for lws-serve: BASE.well-known/lws-storage)
+tokens may be issued for; any other is refused with invalid_target.
+--issuer defaults to the bound origin. Give lws-serve --issuer the same IRI.
+DIR holds the signing keys (DIR/authz-keys.json, mode 0600), sealed with
+FACTOIDAL_LWS_KEY when it is set. --rotate-after makes a new key when the
+current one is that old; the old key stays published until its tokens expire.
+--allow-http accepts http subject identifiers; --allow-private-fetch lets the
+server fetch documents from loopback, link-local and private addresses. Both
+are off by default and are for tests.
+CORS (https://github.com/danbri/factoidal/issues/923): by default every answer
+echoes a valid request Origin in Access-Control-Allow-Origin, so a page on
+another origin can read the metadata and keys and exchange a token; a
+preflight is answered 204 first. --cors-origin ORIGIN (repeatable) answers
+only those origins; --no-cors sends no CORS fields.
+
+Every decision is made in formal/lean4/L4Factoidal/Authz/; this command only
+carries sockets, the clock, random bytes, DNS answers and files.`,
+
+  'authz-keys': `factoidal authz-keys - print the JWK Set of an authorization server
+
+usage: factoidal authz-keys DIR [--private]
+
+Prints the published JWK Set of the key file in DIR. --private prints the
+private keys (with d): for a conformance harness that mints test tokens
+(tools/lws-touchstone.sh --authz factoidal). Never publish that output.`,
+
   'lws-serve': `factoidal lws-serve - serve Linked Web Storage 1.0 over HTTP
 
 usage: factoidal lws-serve DIR (--issuer IRI | --auth-config FILE | --insecure-no-auth)
                          [--owner WEBID] [--root-acl FILE] [--audience IRI]
-                         [--port N] [--host ADDRESS] [--base IRI]
+                         [--port N] [--host ADDRESS] [--base IRI] [--page-size N]
+                         [--paginate-always] [--moves all|data|off]
+                         [--no-linkset-put] [--unstable-search-results] [--merkle]
+                         [--controller-inbox URL] [--delivery-limit N]
+                         [--delivery-window SECONDS] [--redirects-max N]
+                         [--storage snapshot|files]
+                         [--cors-origin ORIGIN]... [--no-cors]
 
 Starts a Node HTTP server that answers every request through the engine's
 lwsStep operation.
@@ -344,10 +399,100 @@ start. The engine decides the snapshot format and refuses a snapshot
 path with a dot segment or other traversal form
 (formal/lean4/L4Factoidal/LWS/Snapshot.lean).
 
+With --storage files (off by default) a write costs the same whatever the
+size of the storage: DIR holds one file per resource body (DIR/bodies/),
+a journal of metadata changes (DIR/lws-journal) and a metadata file
+(DIR/lws-files.json) that the journal is folded into from time to time.
+A journal record is valid only when it is complete and its SHA-256
+matches; a torn last record is ignored at start. An existing
+DIR/lws-state.json is migrated at the first start and renamed to
+lws-state.json.migrated. The engine decides every file name and every
+byte (formal/lean4/L4Factoidal/LWS/FileLayout.lean); the storage is still
+held in memory while the server runs
+(docs/designissues/2026-10-22-lws-storage-on-disk.md).
+
+Encryption at rest (off by default): when the environment variable
+FACTOIDAL_LWS_KEY holds a 32-byte key (64 hex digits, or 43 characters of
+base64url), the snapshot is sealed with ChaCha20-Poly1305 (HACL*) under a
+new random nonce for every write, and authenticated when the storage is
+opened. A wrong key, a changed or truncated file, a clear-text file with the
+variable set, or a sealed file without it stops the start with a message.
+It protects the file on disk only (formal/lean4/L4Factoidal/LWS/SnapshotSeal.lean).
+
   --port N        the port to bind; 0 takes an ephemeral one (default 3000)
   --host ADDRESS  the address to bind (default 127.0.0.1)
   --base IRI      the absolute IRI the storage root maps to
                   (default: the bound origin)
+  --page-size N   the engine's container page size (config member pageSize;
+                  default 100, 0 turns pagination off)
+  --paginate-always
+                  present every container listing as paginated, also one
+                  that fits on one page (config member paginateAlways;
+                  default off): rel="first" and rel="last", no rel="next"
+  --moves all|data|off
+                  which resources a client may move by changing their up
+                  link (config member moves; default all): data resources
+                  and containers, data resources only (the MoveResource
+                  capability's appliesTo is [DataResource]), or none (no
+                  MoveResource capability; a change of up answers 409)
+  --no-linkset-put
+                  a linkset resource does not accept PUT (config member
+                  linksetPut false): its Allow leaves PUT out and a PUT
+                  answers 405 Method Not Allowed; PATCH still applies
+  --unstable-search-results
+                  ANTICIPATORY AND UNSTABLE, off by default: a QUERY answer
+                  of the type search names a results resource with
+                  Content-Location (RFC 10008 section 2.3). lws10-index
+                  defines no such resource; this is likely to change.
+                  https://github.com/danbri/factoidal/issues/922
+  --merkle        off by default: keep a SHA-256 digest of every resource
+                  and a Merkle root of every container, and show them: an
+                  RFC 9530 Repr-Digest field on GET of a resource, a
+                  Factoidal-Merkle-Root field and listing member on a
+                  container, and the storage root's digest in the storage
+                  description (roots to the storage controller only under
+                  authorization). Entity tags do not change. The hashes are
+                  rebuilt when the storage is opened, not stored.
+                  https://github.com/danbri/factoidal/issues/919
+  --controller-inbox URL
+                  the storage controller's inbox (config member
+                  controllerInbox; default none): each new access request
+                  is announced there with a Create notification. The LWS
+                  draft names no such inbox; this is a server choice.
+                  https://github.com/danbri/factoidal/issues/920
+  --delivery-limit N
+                  the most webhook deliveries one subscription gets in one
+                  window (config member deliveryLimit; default 10, 0 turns
+                  the limit off); the changes over it wait and go in one
+                  batched notification when the window ends
+                  https://github.com/danbri/factoidal/issues/915
+  --delivery-window SECONDS
+                  the length of that window (config member deliveryWindow;
+                  default 60)
+  --redirects-max N
+                  the most previous identifiers of moved resources kept to
+                  answer 301 Moved Permanently (config member redirectsMax;
+                  default 256)
+                  https://github.com/danbri/factoidal/issues/914
+  --storage snapshot|files
+                  how DIR keeps the storage (config member storage;
+                  default the environment variable FACTOIDAL_LWS_STORAGE,
+                  else snapshot): one snapshot file written whole after
+                  each change, or one file per body with a journal, so a
+                  write costs the same whatever the storage size
+                  https://github.com/danbri/factoidal/issues/918
+  --cors-origin ORIGIN
+                  answer CORS (Fetch Standard) only for this origin, written
+                  scheme://host[:port] (for example https://danbri.github.io);
+                  give it once per origin. Default: echo any valid request
+                  Origin, as the Solid Protocol section 8.1 requires of Solid
+                  servers. Never Access-Control-Allow-Credentials: the token
+                  travels in Authorization. A preflight (OPTIONS with
+                  Access-Control-Request-Method) is answered 204 before any
+                  authorization decision.
+                  https://github.com/danbri/factoidal/issues/923
+  --no-cors       send no CORS fields; a page on another origin cannot read
+                  any answer
 
 Authorization (LWS editor's draft, section Authorization; one of the three
 is required):
@@ -365,7 +510,8 @@ is required):
                         that gives this agent Read, Write and Control
   --root-acl FILE       a Turtle root ACL for a new storage instead
   --audience IRI        the aud value tokens must carry (default: the
-                        storage root IRI)
+                        storage IRI, BASE.well-known/lws-storage, which
+                        every lws#storage link names)
 
 Requests carry an access token as "Authorization: Bearer TOKEN" (RFC 6750).
 The engine verifies its JWS signature (ES256, RS256 or EdDSA, with the
@@ -397,6 +543,14 @@ start. The engine decides the snapshot format and refuses a snapshot
 path with a dot segment or other traversal form
 (formal/lean4/L4Factoidal/LWS/Snapshot.lean).
 
+Encryption at rest (off by default): when the environment variable
+FACTOIDAL_LWS_KEY holds a 32-byte key (64 hex digits, or 43 characters of
+base64url), the snapshot is sealed with ChaCha20-Poly1305 (HACL*) under a
+new random nonce for every write, and authenticated when the storage is
+opened. A wrong key, a changed or truncated file, a clear-text file with the
+variable set, or a sealed file without it stops the start with a message.
+It protects the file on disk only (formal/lean4/L4Factoidal/LWS/SnapshotSeal.lean).
+
   --port N        the port to bind; 0 takes an ephemeral one (default 3000)
   --host ADDRESS  the address to bind (default 127.0.0.1)
   --base IRI      the absolute IRI the storage root maps to
@@ -426,6 +580,42 @@ those operations landed makes this command exit 3 and say so.
 
 Specification: https://solidproject.org/TR/protocol`,
 
+  'xmpp-serve': `factoidal xmpp-serve - serve XMPP (RFC 6120 and RFC 6121) over TCP or direct TLS
+
+usage: factoidal xmpp-serve DIR [--domain NAME] [--port N] [--host ADDRESS]
+                            [--accounts FILE] [--cert FILE --key FILE]
+
+Starts a Node TCP server that runs one engine session per connection and
+answers every byte through the engine's xmppSessionFeed operation.
+
+DIR is the state directory, laid out as the native carrier's
+(formal/lean4/Harness/XmppServe.lean): DIR/accounts holds one
+user:password per line (unless --accounts names another file), rosters
+are persisted under DIR/roster/, and a stanza written as a file under
+DIR/spool/<bare jid>/ is delivered to that account's bound session.
+
+  --domain NAME    the domain the server is authoritative for (default localhost);
+                   a stream for any other domain is answered host-unknown
+  --port N         the port to bind; 0 takes an ephemeral one
+                   (default 5222, or 5223 with --cert and --key)
+  --host ADDRESS   the address to bind (default 127.0.0.1)
+  --accounts FILE  the accounts file (default DIR/accounts)
+  --cert FILE      PEM certificate chain: XEP-0368 direct TLS, no STARTTLS
+  --key FILE       PEM private key for --cert
+
+The server makes no protocol decision. Stream negotiation, SASL PLAIN and
+SCRAM-SHA-256, resource binding, the roster, presence subscription and
+broadcast, message routing with the server-stamped from, stream errors and
+disco#info are answered by formal/lean4/L4Factoidal/XMPP/. A WebAssembly
+module built before the session operations landed makes this command
+exit 3 and say so.
+
+Not implemented: STARTTLS (use --cert/--key), server-to-server federation,
+MUC/MIX/GC3 rooms.
+
+Specifications: https://www.rfc-editor.org/rfc/rfc6120 and
+https://www.rfc-editor.org/rfc/rfc6121`,
+
   'solid-client': `factoidal solid-client - run one Solid client operation
 
 usage: factoidal solid-client <get|put|post|delete|discover> URL [options]
@@ -447,7 +637,50 @@ kind names are accepted directly as well.
   --interpret KIND  one of storage, containment, auxiliaries, profile,
                     wacAllow, used when the engine names none
 
-Specification: https://solidproject.org/TR/protocol`
+Specification: https://solidproject.org/TR/protocol`,
+
+  'lws-client': `factoidal lws-client - run one Linked Web Storage client operation
+
+usage: factoidal lws-client <op> URL [options]
+
+Every request is chosen and built by the engine (lwsClientStart,
+lwsClientStep; formal/lean4/L4Factoidal/LWS/Client/): the authorization
+flow with its discovery checks, preconditions, retries, paging and linksets.
+This command supplies a socket and prints the engine's result as JSON. It
+exits 1 when the operation fails, and prints the failure document.
+
+operations:
+  discover URL        read the storage description of the storage of URL
+  read URL | head URL | getAccess URL
+  create CONTAINER    --body/--file, --content-type, --slug, --container,
+                      --type IRI, --link VALUE
+  update URL          --body/--file, --content-type, --link VALUE
+  patch URL           --body/--file (JSON Patch unless --content-type)
+  delete URL          --recursive
+  readLinkset URL | updateLinkset URL (--body/--file, --content-type)
+  move URL            --destination CONTAINER
+  list CONTAINER      every page, following rel="next"
+  typeIndex URL | search URL --query JSON
+  subscribe URL       --inbox URL [--topic URL]
+  unsubscribe URL | revokeAccess URL
+  requestAccess URL | grantAccess URL
+                      --action A[,A] --assignee URI [--target URL[,URL]]
+                      [--inbox URL]
+
+preconditions (update, patch, delete, updateLinkset, move):
+  --if-match TAG | --if-match-current | --if-none-match-star |
+  --if-unmodified-since DATE | --no-precondition
+  (default: --if-match-current for update, patch, updateLinkset and move)
+  --retry-412 N       read the tag again and resend, at most N times
+
+authorization:
+  --subject-token-file FILE   the credential to exchange (RFC 8693)
+  --subject-token-type URI    its type, for example
+                              urn:ietf:params:oauth:token-type:saml2
+  --access-token TOKEN        a token to present to the storage of URL
+                              (with --storage IRI and --root URL)
+
+Draft: https://w3c.github.io/lws-protocol/lws10-core/`
 }
 
 // ------------------------------------------------------------- arguments
@@ -475,8 +708,16 @@ function parseArguments (args, valueOptions) {
     }
     const equals = argument.indexOf('=')
     const name = equals < 0 ? argument.slice(2) : argument.slice(2, equals)
+    // An option named in REPEATABLE_OPTIONS keeps every value, in order.
+    const keep = (value) => {
+      if (REPEATABLE_OPTIONS.has(name)) {
+        options[name] = Array.isArray(options[name]) ? [...options[name], value] : [value]
+      } else {
+        options[name] = value
+      }
+    }
     if (equals >= 0) {
-      options[name] = argument.slice(equals + 1)
+      keep(argument.slice(equals + 1))
       continue
     }
     if (valueOptions.has(name)) {
@@ -484,7 +725,7 @@ function parseArguments (args, valueOptions) {
       if (index >= args.length) {
         throw new UsageError(`option --${name} needs a value`)
       }
-      options[name] = args[index]
+      keep(args[index])
       continue
     }
     options[name] = true
@@ -494,6 +735,9 @@ function parseArguments (args, valueOptions) {
 
 class UsageError extends Error {}
 
+/** Options that may be given more than once; their value is the list. */
+const REPEATABLE_OPTIONS = new Set(['cors-origin'])
+
 const VALUE_OPTIONS = {
   version: new Set([]),
   'sample-store': new Set([]),
@@ -505,9 +749,18 @@ const VALUE_OPTIONS = {
   compact: new Set([]),
   serve: new Set(['port', 'host', 'query-path', 'gsp-path', 'file', 'layout', 'tdb2']),
   'lws-serve': new Set(['port', 'host', 'base', 'issuer', 'auth-config', 'owner', 'root-acl',
-    'audience']),
+    'audience', 'page-size', 'moves', 'controller-inbox', 'delivery-limit', 'delivery-window',
+    'redirects-max', 'storage', 'cors-origin']),
   'solid-serve': new Set(['port', 'host', 'base', 'owner', 'issuer', 'auth-config']),
-  'solid-client': new Set(['body', 'file', 'content-type', 'interpret'])
+  'solid-client': new Set(['body', 'file', 'content-type', 'interpret']),
+  'lws-client': new Set(['body', 'file', 'content-type', 'slug', 'type', 'link', 'if-match',
+    'if-unmodified-since', 'retry-412', 'destination', 'query', 'topic', 'action', 'assignee',
+    'target', 'subject-token-file', 'subject-token-type', 'access-token', 'storage', 'root',
+    'inbox']),
+  'authz-serve': new Set(['port', 'host', 'issuer', 'resource', 'alg', 'token-lifetime', 'rotate-after',
+    'cors-origin']),
+  'authz-keys': new Set([]),
+  'xmpp-serve': new Set(['port', 'host', 'domain', 'accounts', 'cert', 'key'])
 }
 
 // ------------------------------------------------------------- commands
@@ -1086,6 +1339,11 @@ async function commandPack (positional, options) {
 
 async function commandSampleStore (positional, options) {
   if (positional.length > 1) throw new UsageError('sample-store takes at most one DIR')
+  // Re-execute here, once, before any work. The pack and the activate
+  // below would each re-execute the whole command line under Deno, and
+  // each child printed the path again (three lines, 2026-10-24).
+  const reexec = await denoReexec({ worker: options['no-worker'] !== true })
+  if (reexec !== null) return reexec
   const { mkdtempSync, writeFileSync, existsSync } = await import('node:fs')
   const { tmpdir } = await import('node:os')
   const root = positional.length === 1
@@ -1198,6 +1456,35 @@ function servePort (options, fallback) {
   return port
 }
 
+// --page-size N: a CLI number, passed unchanged as the engine config member
+// `pageSize`; what a page holds is decided in L4Factoidal/LWS/Pagination.lean.
+function pageSizeOption (value) {
+  return natOption('page-size', value)
+}
+
+function natOption (flag, value) {
+  const n = Number(value)
+  if (!Number.isInteger(n) || n < 0) {
+    throw new UsageError(`--${flag} must be a non-negative integer, not "${value}"`)
+  }
+  return n
+}
+
+// --cors-origin ORIGIN (repeatable) and --no-cors, as the config member
+// `cors`: a list of origins, or false. Passed unread; the engine checks each
+// origin and decides every CORS field (L4Factoidal/HTTP/Cors.lean). With
+// neither option the member is absent and the engine echoes the request
+// Origin (Solid Protocol section 8.1).
+function corsConfig (options) {
+  const origins = options['cors-origin']
+  if (options['no-cors'] === true && origins !== undefined) {
+    throw new UsageError('--no-cors cannot be combined with --cors-origin')
+  }
+  if (options['no-cors'] === true) return { cors: false }
+  if (Array.isArray(origins)) return { cors: origins }
+  return {}
+}
+
 function serveHost (options) {
   if (options.host === undefined) return '127.0.0.1'
   if (typeof options.host !== 'string' || options.host.length === 0) {
@@ -1326,6 +1613,20 @@ async function commandLwsServe (positional, options) {
       port: servePort(options, 3000),
       host: serveHost(options),
       ...(typeof options.base === 'string' ? { baseIri: options.base } : {}),
+      ...(options['page-size'] !== undefined ? { pageSize: pageSizeOption(options['page-size']) } : {}),
+      ...(options['unstable-search-results'] === true ? { searchResults: true } : {}),
+      ...(options.merkle === true ? { merkle: true } : {}),
+      // Passed unread as config members; the engine decides what they mean
+      // and refuses a value it does not know (Wasm/Ops/Lws.lean).
+      ...(options['paginate-always'] === true ? { paginateAlways: true } : {}),
+      ...(typeof options.moves === 'string' ? { moves: options.moves } : {}),
+      ...(options['no-linkset-put'] === true ? { linksetPut: false } : {}),
+      ...(typeof options['controller-inbox'] === 'string' ? { controllerInbox: options['controller-inbox'] } : {}),
+      ...(options['delivery-limit'] !== undefined ? { deliveryLimit: natOption('delivery-limit', options['delivery-limit']) } : {}),
+      ...(options['delivery-window'] !== undefined ? { deliveryWindow: natOption('delivery-window', options['delivery-window']) } : {}),
+      ...(options['redirects-max'] !== undefined ? { redirectsMax: natOption('redirects-max', options['redirects-max']) } : {}),
+      ...(typeof options.storage === 'string' ? { storage: options.storage } : {}),
+      ...corsConfig(options),
       ...(insecure ? { insecureNoAuth: true } : { auth }),
       ...(typeof options.owner === 'string' ? { owner: options.owner } : {}),
       ...(typeof options['root-acl'] === 'string'
@@ -1338,6 +1639,14 @@ async function commandLwsServe (positional, options) {
     if (error instanceof LwsHostError && error.unknownOp) {
       return notWired('lws-serve', error.message)
     }
+    // The engine refused to open the storage (a bad configuration, or a
+    // snapshot it could not read or authenticate, issue 921), or the state
+    // file is not JSON: the message is the whole answer.
+    if (error !== null && typeof error === 'object' &&
+        (error.envelope !== undefined || error.stateFile === true)) {
+      err(`factoidal lws-serve: ${error.envelope !== undefined ? error.envelope.error : error.message}`)
+      return EXIT_FAILURE
+    }
     throw error
   }
   if (!quiet) {
@@ -1348,6 +1657,79 @@ async function commandLwsServe (positional, options) {
   return untilInterrupted(running, quiet)
 }
 
+async function commandAuthzServe (positional, options) {
+  if (positional.length !== 1) throw new UsageError('authz-serve needs one DIR')
+  if (typeof options.resource !== 'string') {
+    throw new UsageError('authz-serve needs --resource IRI[,IRI...]: the resources tokens may be issued for')
+  }
+  const quiet = options.quiet === true
+  const { listen } = await import('../authz/server.mjs')
+  let running
+  try {
+    running = await listen({
+      port: servePort(options, 3001),
+      host: serveHost(options),
+      dir: positional[0],
+      resources: options.resource.split(',').filter((v) => v !== ''),
+      ...(typeof options.issuer === 'string' ? { issuer: options.issuer } : {}),
+      // Passed unread; the engine checks them (Wasm/Ops/Authz.lean).
+      ...(typeof options.alg === 'string' ? { alg: options.alg } : {}),
+      ...(options['token-lifetime'] !== undefined ? { tokenLifetime: natOption('token-lifetime', options['token-lifetime']) } : {}),
+      ...(options['rotate-after'] !== undefined ? { rotateAfter: natOption('rotate-after', options['rotate-after']) } : {}),
+      ...(options['allow-http'] === true ? { allowHttp: true } : {}),
+      ...(options['allow-private-fetch'] === true ? { allowPrivateFetch: true } : {}),
+      ...corsConfig(options)
+    })
+  } catch (error) {
+    if (error !== null && typeof error === 'object' && error.envelope !== undefined) {
+      err(`factoidal authz-serve: ${error.envelope.error}`)
+      return EXIT_FAILURE
+    }
+    if (error !== null && typeof error === 'object' && /unknown op/.test(String(error.message))) {
+      return notWired('authz-serve', error.message)
+    }
+    throw error
+  }
+  if (!quiet) {
+    err(`authz-serve: listening on ${running.origin}, issuer ${running.issuer}`)
+    if (options['allow-http'] === true) err('authz-serve: WARNING: --allow-http: http subject identifiers are accepted')
+    if (options['allow-private-fetch'] === true) err('authz-serve: WARNING: --allow-private-fetch: private addresses may be fetched')
+  }
+  out(running.origin)
+  return untilInterrupted(running, quiet)
+}
+
+async function commandAuthzKeys (positional, options) {
+  if (positional.length !== 1) throw new UsageError('authz-keys needs one DIR')
+  const { openAuthorizationServer, readKeyFile } = await import('../authz/server.mjs')
+  if (readKeyFile(positional[0]) === null) {
+    err(`factoidal authz-keys: ${positional[0]} holds no key file`)
+    return EXIT_FAILURE
+  }
+  let authz
+  try {
+    // The issuer and resources do not matter for reading the keys.
+    authz = await openAuthorizationServer({ dir: positional[0], issuer: 'https://authz.invalid', resources: [] })
+  } catch (error) {
+    if (error !== null && typeof error === 'object' && error.envelope !== undefined) {
+      err(`factoidal authz-keys: ${error.envelope.error}`)
+      return EXIT_FAILURE
+    }
+    throw error
+  }
+  try {
+    if (options.private === true) {
+      out(JSON.stringify(authz.privateJwks()))
+    } else {
+      const answer = await authz.step({ method: 'GET', target: '/jwks', headers: [], body: '' })
+      out(answer.body)
+    }
+  } finally {
+    authz.close()
+  }
+  return EXIT_OK
+}
+
 async function commandSolidServe (positional, options) {
   if (positional.length !== 1) throw new UsageError('solid-serve needs one DIR')
   const quiet = options.quiet === true
@@ -1385,6 +1767,14 @@ async function commandSolidServe (positional, options) {
     if (error instanceof SolidServerHostError && error.unknownOp) {
       return notWired('solid-serve', error.message)
     }
+    // The engine refused to open the storage (a bad configuration, or a
+    // snapshot it could not read or authenticate, issue 921), or the state
+    // file is not JSON: the message is the whole answer.
+    if (error !== null && typeof error === 'object' &&
+        (error.envelope !== undefined || error.stateFile === true)) {
+      err(`factoidal solid-serve: ${error.envelope !== undefined ? error.envelope.error : error.message}`)
+      return EXIT_FAILURE
+    }
     throw error
   }
   if (!quiet) {
@@ -1395,6 +1785,45 @@ async function commandSolidServe (positional, options) {
   return untilInterrupted(running, quiet)
 }
 
+async function commandXmppServe (positional, options) {
+  if (positional.length !== 1) throw new UsageError('xmpp-serve needs one DIR')
+  const quiet = options.quiet === true
+  const { listen, XmppHostError } = await import('../xmpp/server.mjs')
+  const fs = await import('node:fs/promises')
+  const useTls = options.cert !== undefined || options.key !== undefined
+  if (useTls && (typeof options.cert !== 'string' || typeof options.key !== 'string')) {
+    throw new UsageError('--cert and --key go together')
+  }
+  const settings = {
+    dir: positional[0],
+    port: servePort(options, useTls ? 5223 : 5222),
+    host: serveHost(options),
+    onError: (error) => { if (!quiet) err(`xmpp-serve: ${error.message}`) }
+  }
+  if (typeof options.domain === 'string') settings.domain = options.domain
+  if (typeof options.accounts === 'string') settings.accountsText = await fs.readFile(options.accounts, 'utf8')
+  if (useTls) {
+    settings.cert = await fs.readFile(options.cert)
+    settings.key = await fs.readFile(options.key)
+  }
+  let running
+  try {
+    running = await listen(settings)
+  } catch (error) {
+    if (error instanceof XmppHostError && error.unknownOp) {
+      return notWired('xmpp-serve', error.message)
+    }
+    throw error
+  }
+  if (!quiet) {
+    err(`xmpp-serve: listening on ${running.origin} for domain ${running.xmpp.domain}` +
+        ` (${running.xmpp.accounts} accounts, state ${positional[0]}` +
+        (useTls ? ', direct TLS)' : ', PLAINTEXT: no TLS on this listener)'))
+  }
+  out(running.origin)
+  return untilInterrupted(running, quiet)
+}
+
 // The command's verbs, as aliases for the wasm ABI's request kinds. A
 // kind name is accepted directly too, so this table adds a spelling and
 // hides nothing.
@@ -1451,6 +1880,75 @@ async function commandSolidClient (positional, options) {
   return EXIT_OK
 }
 
+// `factoidal lws-client`: the caller's options become the members of one
+// operation document; the engine decides everything else.
+async function commandLwsClient (positional, options) {
+  if (positional.length !== 2) {
+    throw new UsageError('lws-client needs an operation and a URL')
+  }
+  const [kind, url] = positional
+  const { createLwsClient, LwsClientError, LWS_CLIENT_KINDS } = await import('../lws/client.mjs')
+  if (!LWS_CLIENT_KINDS.includes(kind) || kind === 'verifyNotification') {
+    throw new UsageError(`unknown operation "${kind}"; one of ` +
+      LWS_CLIENT_KINDS.filter((k) => k !== 'verifyNotification').join(', '))
+  }
+  const list = (v) => String(v).split(',').filter((x) => x !== '')
+  const op = { kind, url }
+  if (typeof options.file === 'string') op.body = readWhole(options.file)
+  else if (typeof options.body === 'string') op.body = options.body
+  if (typeof options['content-type'] === 'string') op.mediaType = options['content-type']
+  if (typeof options.slug === 'string') op.slug = options.slug
+  if (options.container === true) op.container = true
+  if (options.recursive === true) op.recursive = true
+  if (typeof options.type === 'string') op.types = list(options.type)
+  if (typeof options.link === 'string') op.links = [options.link]
+  if (typeof options['if-match'] === 'string') { op.precondition = 'ifMatch'; op.tag = options['if-match'] }
+  if (options['if-match-current'] === true) op.precondition = 'ifMatchCurrent'
+  if (options['if-none-match-star'] === true) op.precondition = 'ifNoneMatchStar'
+  if (typeof options['if-unmodified-since'] === 'string') {
+    op.precondition = 'ifUnmodifiedSince'; op.tag = options['if-unmodified-since']
+  }
+  if (options['no-precondition'] === true) op.precondition = 'none'
+  if (typeof options['retry-412'] === 'string') op.retry412 = Number(options['retry-412'])
+  if (typeof options.destination === 'string') op.destination = options.destination
+  if (typeof options.query === 'string') op.query = JSON.parse(options.query)
+  if (typeof options.topic === 'string') op.topics = list(options.topic)
+  if (typeof options.inbox === 'string') op.inbox = options.inbox
+  if (typeof options.action === 'string') op.actions = list(options.action)
+  if (typeof options.assignee === 'string') op.assignee = options.assignee
+  if (typeof options.target === 'string') op.targets = list(options.target)
+  const clientOptions = {}
+  if (typeof options['subject-token-file'] === 'string') {
+    clientOptions.subjectToken = new TextDecoder('utf-8', { fatal: true })
+      .decode(readWhole(options['subject-token-file'])).trim()
+  }
+  if (typeof options['subject-token-type'] === 'string') {
+    clientOptions.subjectTokenType = options['subject-token-type']
+  }
+  if (typeof options['access-token'] === 'string') {
+    if (typeof options.storage !== 'string' || typeof options.root !== 'string') {
+      throw new UsageError('--access-token needs --storage IRI and --root URL')
+    }
+    clientOptions.session = {
+      tokens: [{ storage: options.storage, root: options.root, token: options['access-token'] }]
+    }
+  }
+  let answer
+  try {
+    const client = await createLwsClient(clientOptions)
+    answer = await client.run(op)
+  } catch (error) {
+    if (error instanceof LwsClientError) {
+      if (error.unknownOp) return notWired('lws-client', error.message)
+      out(JSON.stringify({ fail: error.detail }, null, 2))
+      return EXIT_FAILURE
+    }
+    throw error
+  }
+  out(JSON.stringify(answer, null, 2))
+  return EXIT_OK
+}
+
 const COMMANDS = {
   version: (positional, options) => commandVersion(options),
   'sample-store': (positional, options) => commandSampleStore(positional, options),
@@ -1463,7 +1961,11 @@ const COMMANDS = {
   serve: commandServe,
   'lws-serve': commandLwsServe,
   'solid-serve': commandSolidServe,
-  'solid-client': commandSolidClient
+  'solid-client': commandSolidClient,
+  'lws-client': commandLwsClient,
+  'authz-serve': commandAuthzServe,
+  'authz-keys': commandAuthzKeys,
+  'xmpp-serve': commandXmppServe
 }
 
 // ----------------------------------------------------------------- main