@factoidal/core 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,203 @@
 # Changelog
 
+## 0.14.0
+
+**Checked pipelines.** Each component (reader, store, query evaluator, writer, reasoner, validator, proof checker) has one interface type whose contract against the W3C specifications is part of the type. A component cannot be added without a contract; a contract that is not proved yet is a named assumption, listed and counted in CI. A theorem states that the SPARQL answer agrees with the SPARQL 1.1 semantics for data from any source (a parsed document, a Dataset after edits, an update, a reasoner's output, a union of stores), given the listed assumptions. Status and gaps: https://github.com/danbri/factoidal/issues/975.
+
+- `explain(sources, description, { profile: "rdfs" })`: whether the sources RDFS-entail a description graph (its blank nodes are variables), with a checked derivation (`bundle`) when it does and the reason (`rejection`) when not (https://github.com/danbri/factoidal/issues/1002).
+- `run(pipeline, input, { unchecked: true })`: runs nodes whose stage is not proved; each evidence record has `checked`, and the result has `proved` and `uncheckedSteps`. Without the option a stage with no contract does not run.
+- `Dataset.warnings`: a language tag that is not well-formed BCP 47 is kept and reported with its line, column and offset; the writers write it unchanged (https://github.com/danbri/factoidal/issues/1004).
+- SPARQL `SELECT *` on the store path returns the variables in query order, the same header as the in-memory path (https://github.com/danbri/factoidal/issues/1014).
+- SBM11 in npm (`openSbm11`) is **not** in this release. Its wasm op `sbm11Open` traps (`unreachable`) in the release build, so the ops are not dispatched and the functions are not exported; the native `l4sbm11` commands are unchanged (https://github.com/danbri/factoidal/issues/1009).
+- `factoidal pack`, `factoidal sample-store` and `sampleStorePath()` write the IBK5 layout (wire version 10, manifest layout `quad-ibk5-ptd2-lgi4-gbi1-merkle-v0`) when no `--layout` is given; the default was IBK3. Owner, 2026-10-25: "yes IBK5 not IBK3 as default sounds sensible, assuming no major downside" (https://github.com/danbri/factoidal/issues/1009). `factoidal serve` over such a store takes changes to every graph; over an IBK3 store a change to a named graph answered 501. `--layout ibk3` still writes IBK3. `sampleStoreFacts.layout` is now `'ibk5'`.
+- `stages()`, `node()`, `pipe()`, `run()`: the registered Lean stages as nodes (https://github.com/danbri/factoidal/issues/1002, step 2). `stages()` is the engine's op `stageList`, read from the Lean stage registry: name, interface type, wire types, status, contract and named assumptions of each stage. A value on a wire is `{graph, evidence}`; each node adds one evidence record `{stage, status, contract, assumptions, artefact}`, and `run()` reports the union of the named assumptions of the nodes. A stage with status `missing` does not run. Needs a wasm build with the op `stageList`.
+- `factoidal pack` writes a set of rows in every layout (https://github.com/danbri/factoidal/issues/1006). Correction to 0.13.0: its entry says that the stores keep one copy of a repeated triple, but in 0.13.0 that was true for the IBK4 and IBK5 layouts only, and only on read. The default layout (IBK3) kept a repeated triple, and kept `"a"@en` and `"a"@EN` as two rows, so `COUNT(*)` counted both; the IBK4 and IBK5 packers also wrote the repeated rows. Now each packer keeps the distinct triples it has written and writes a triple only once (per graph on the quad layouts). A source with no repeated triple gives the same generation as before. The packer's memory now grows with the number of distinct triples of the source. Proved: `Dataflow.packedRows_keyNodup`; tests: `test/pack-is-a-set-1006.test.mjs`.
+- The N-Triples, N-Quads, Turtle and TriG writers give a fresh valid label to a blank-node label outside BLANK_NODE_LABEL (the same label for each occurrence, never a label of another blank node), and refuse a language tag outside LANGTAG with an error that names the tag (https://github.com/danbri/factoidal/issues/986).
+- A language tag is kept in lower case (RDF 1.2 Concepts §3.4: `"x"@en` and `"x"@EN` are one RDF term). Every reader, `STRLANG`, `STRLANGDIR` and the term constructors write the tag in lower case, so `LANG()` returns it in lower case, and a SPARQL answer no longer depends on the order of the triple patterns when the data spells one tag in two ways (https://github.com/danbri/factoidal/issues/1001).
+
+## 0.13.0
+
+**A parsed document is a set of quads** (RDF 1.1 Concepts §3 and §4;
+https://github.com/danbri/factoidal/issues/972). Up to 0.12.0 a document
+that stated the same triple twice gave a graph with two copies: `size`
+counted 2 and `SELECT (COUNT(*) AS ?n)` answered 2. Every parser, the
+streamed parse, the command's `query` and the stores now keep one copy.
+Language tags compare case-insensitively (RDF 1.2 Concepts §3.4), so
+`"a"@en` and `"a"@EN` are one term in a graph and in a store dictionary
+(https://github.com/danbri/factoidal/issues/977).
+
+SPARQL and RDF semantics fixes:
+
+- `=` and `!=` follow RDFterm-equal (SPARQL 1.1 §17.4.1.7). Terms of
+  different kinds (IRI, blank node, literal, triple term) give `=` false.
+  Two literals that are different terms give a type error, except where
+  the §17.3.1 extension of the W3C tests gives false: `rdf:langString`
+  against another datatype, and `xsd:dateTime` against `xsd:date`. The
+  SPARQL 1.0 open-world tests: 18 pass, 0 fail (out of 18); were 13 pass,
+  5 fail.
+- `rdf:XMLLiteral` values compare by RDF term equality; SPARQL `=` on two
+  different XMLLiteral terms is a type error
+  (https://github.com/danbri/factoidal/issues/963). The RDF/XML parser's
+  exclusive XML canonicalization is repaired.
+- A query with `FROM` clauses queries the RDF merge of those graphs
+  (SPARQL 1.1 §13.2.1): blank nodes from different `FROM` graphs are no
+  longer joined (https://github.com/danbri/factoidal/issues/979).
+- RDFS closure rule rdfs9 accepts a blank node as the sub-class
+  (RDF 1.1 Semantics §9.2; https://github.com/danbri/factoidal/issues/982).
+- The RDF/XML writer keeps the base direction of a directional language
+  string (`its:dir` with `rdf:version="1.2"`). The JSON-LD writer still
+  drops it: https://github.com/danbri/factoidal/issues/984.
+- Opening a dataset renames blank nodes inside triple terms as well as at
+  the top level.
+- `factoidal sample-store` under Deno printed its path three times: the
+  pack and the activate each re-executed the whole command. It now
+  re-executes once, before any work.
+
+**`proofCheck` no longer joins blank nodes across artifacts**
+(https://github.com/danbri/factoidal/issues/976). Up to 0.12.0 a bundle
+could take `:A rdfs:subClassOf _:x` from one graph artifact and
+`_:x rdfs:subClassOf :C` from another with the same RDFC-1.0 digest, and
+conclude `:A rdfs:subClassOf :C` with `valid: true`. Blank nodes are now
+scoped to the artifact or assumption they come from (RDF 1.1 Semantics
+section 5.2), so that bundle is refused. A chain inside one artifact, and
+a chain across artifacts through triples with no blank node, are still
+accepted. The report has a new member `rejection`: `null` for a valid
+bundle, else the first failed check in words. The bundle format and the
+profile `fpp0/1` are unchanged.
+
+**XMPP server from wasm.** `factoidal xmpp-serve DIR` and
+`@factoidal/core/xmpp/server` run the Lean XMPP server
+(`L4Factoidal.XMPP.Server` — RFC 6120 negotiation, SASL PLAIN and
+SCRAM-SHA-256, binding, RFC 6121 roster/presence/messages) in the
+WebAssembly engine, one engine session per TCP or direct-TLS (XEP-0368)
+connection. New engine ops `xmppOpen`, `xmppSessionOpen`,
+`xmppSessionFeed`, `xmppSessionDeliver`, `xmppSessionClose`,
+`xmppRosterGet`, `xmppRosterSet`, `xmppClose`
+(`formal/lean4/Wasm/Ops/XmppSession.lean`). The state directory is the
+native carrier's layout (`accounts`, `roster/`, `spool/`), so a stanza
+written as a file under `spool/<bare jid>/` is delivered to that
+account. See `xmpp/README.md`.
+
+Linked Web Storage kept in files, stage 2 (https://github.com/danbri/factoidal/issues/918;
+design record `docs/designissues/2026-10-22-lws-storage-on-disk.md`):
+
+- Stage 2 (`L4Factoidal/LWS/Bodies.lean`): with `--storage files` the bodies
+  stay in their body files. An entry keeps its length, its FNV-1a and SHA-256
+  digests and the types of a Turtle body, and no bytes (ACL resources keep
+  theirs). A step that needs bytes (GET body or range, JSON Patch, a PUT a
+  subscription may hear of, a move of a Turtle resource) answers
+  `read: [PATH, ...]`; the host reads those files and gives them to the new op
+  `lwsRead` (byte-region entry only), which checks them, and steps again. A
+  start reads no body file unless the metadata lacks a fact; the peak RSS of a
+  start and one GET of 1,000 and 4,000 resources of 16 KiB is 230 and 211 MiB
+  (stage 1: 258 and 515 MiB). A changed body file is refused when it is read
+  (the request answers 500), no longer at start.
+- The LWS handles run a tree store (`TreeStore`, theorem `treeStoreLaws`) and
+  a type index in persistent trees: the engine's step and persist of a PUT
+  take 0.30, 0.27, 0.28 and 0.29 ms in a storage of 1,000, 2,000, 4,000 and
+  16,000 resources (stage 1: 0.21 ms at 1,000, about 3 ms at 16,000). A POST
+  no longer lists every path; a DELETE lists paths only for a container.
+- The order of the entries of a snapshot and of `lws-files.json`, and of the
+  activities of a recursive DELETE in one notification, is path order (was
+  newest first). `lwsSnapshot` of a storage kept in files is refused.
+- `solid-serve` keeps the snapshot: an expected failure naming issue 918.
+
+An authorization server as a component (https://github.com/danbri/factoidal/issues/916;
+design record `docs/designissues/2026-10-22-authorization-server.md`; skill
+`skills/authz-server/SKILL.md`), decided in Lean (`L4Factoidal/Authz/`):
+
+- `factoidal authz-serve DIR --resource IRI[,IRI...]` and
+  `import { listen } from '@factoidal/core/authz'`: RFC 8414 metadata at
+  `/.well-known/lws-configuration` (and `/.well-known/oauth-authorization-server`),
+  a JWK Set, and an RFC 8693 token endpoint that exchanges a subject token for
+  an RFC 9068 access token whose `aud` is exactly the requested resource
+  (lws10-core "Authorization"). `lws-serve --issuer <its issuer>` accepts its
+  tokens with no other setting. `factoidal authz-keys DIR` prints the JWK Set.
+- Subject tokens: OpenID Connect ID tokens (lws10-authn-openid) and
+  self-issued JWTs for https and did:key subjects (lws10-authn-ssi-cid; P-256
+  and Ed25519 did:keys). SAML 2.0 is refused and not advertised: there is no
+  XML Signature verifier (https://github.com/danbri/factoidal/issues/926).
+  solid-serve does not accept these tokens yet
+  (https://github.com/danbri/factoidal/issues/928).
+- Documents the server fetches for a subject token: `https` only (`--allow-http`
+  for tests), never from a loopback, link-local or private address
+  (`--allow-private-fetch` for tests), from the address the engine checked,
+  with no redirect.
+- Keys: ES256 by default (`--alg EdDSA`), signed by HACL\* through three new
+  P-256 externs (sign, secret-to-public, point decompression; RFC 6979 and
+  Wycheproof vectors in `lake exe l4crypto-probe`); `kid` is the RFC 7638
+  thumbprint; `--rotate-after` rotates and keeps the old key published until
+  its tokens expire; `DIR/authz-keys.json` (mode 0600) is sealed under
+  `FACTOIDAL_LWS_KEY` when it is set.
+- New ops `authzOpen`, `authzStep`, `authzFetched`, `authzKeys`, `authzRotate`,
+  `authzClose`.
+- Theorems: `issueToken_verifies_published` and `issueToken_audience_exact`
+  hold because of a run-time check of every issued token (the proof that
+  removes the check: https://github.com/danbri/factoidal/issues/927);
+  `exchange_refused_no_token` (a subject token that fails validation never
+  yields an access token), `cid_valid_verified`, `didKey_valid_verified`,
+  `oidc_valid_named_provider`, `chooseAddress_refuses_private` and others.
+- Touchstone with this server in place of its reference one
+  (`tools/lws-touchstone.sh --config auth --authz factoidal`, 2026-10-22):
+  212 passed, 0 failed, 9 inapplicable (out of 221); of these
+  core/authorization_server 9 pass, 0 fail (out of 9), auth/oidc 6 pass,
+  0 fail (out of 6), auth/cid 22 pass, 0 fail (out of 22), auth/saml 3
+  inapplicable (issue 926).
+
+CORS in the LWS HTTP binding (https://github.com/danbri/factoidal/issues/923),
+decided in Lean (`L4Factoidal/HTTP/Cors.lean`, `L4Factoidal/LWS/Cors.lean`), so
+a page on another origin (for example GitHub Pages) can call `lws-serve`:
+
+- A CORS-preflight request (`OPTIONS` with `Access-Control-Request-Method`
+  and `Origin`) is answered 204 before any other decision, with no token and
+  no access check: `Access-Control-Allow-Methods` (with `QUERY` and `PATCH`),
+  `-Allow-Headers` (`Authorization`, `Content-Type`, `If-Match`,
+  `If-None-Match`, `If-Modified-Since`, `If-Unmodified-Since`, `Link`,
+  `Prefer`, `Slug`, `Range`, `DPoP`, `Accept`), `-Max-Age` 7200. An `OPTIONS`
+  without `Access-Control-Request-Method` is answered as before.
+- Every answer carries `Vary: Origin` (one `Vary` field with the answer's
+  own), and, for an answered origin, `Access-Control-Allow-Origin` and
+  `Access-Control-Expose-Headers` (`ETag`, `Link`, `Location`, `Allow`,
+  `Accept-Patch`, `Accept-Post`, `Accept-Put`, `Accept-Query`,
+  `Accept-Ranges`, `Content-Location`, `Content-Range`, `WWW-Authenticate`,
+  `Preference-Applied`, `Repr-Digest`, `Last-Modified`,
+  `Factoidal-Merkle-Root`). No `Access-Control-Allow-Credentials`: the token
+  goes in `Authorization`.
+- Default: echo a valid request `Origin` (Solid Protocol §8.1), never `null`.
+  `lws-serve --cors-origin ORIGIN` (repeatable) answers only those origins;
+  `--no-cors` sends no CORS field; config member `cors` (`false` or a list).
+  A malformed origin stops the start.
+- `authz-serve` gets the same (`Authz.stepCors`; methods `GET, HEAD, OPTIONS,
+  POST`), with the same flags. `solid-serve` keeps its own Solid §8.1 CORS;
+  its preflight is now answered before Web Access Control (it was 401 for a
+  resource that is not public).
+
+An LWS client (https://github.com/danbri/factoidal/issues/917; design record
+`docs/designissues/2026-10-22-lws-client.md`):
+
+- `@factoidal/core/lws/client`: `createLwsClient({ fetch, subjectToken,
+  subjectTokenType })` with `discover`, `read`, `head`, `create`, `update`,
+  `patch`, `delete`, `readLinkset`, `updateLinkset`, `move`, `list`,
+  `typeIndex`, `search`, `subscribe`, `unsubscribe`, `requestAccess`,
+  `grantAccess`, `getAccess`, `revokeAccess`, `verifyNotification`; and
+  `createNotificationReceiver`, a webhook receiver that answers each delivery
+  with the engine's verdict. `fetch` is injected (Node, a browser, or a
+  transport such as XMPP).
+- Every decision is in Lean (`L4Factoidal/LWS/Client/`, wasm ops
+  `lwsClientStart` and `lwsClientStep`): the 401 flow with the three checks of
+  lws10-core "Discovery Validation by a Client", RFC 8414 metadata and RFC 8693
+  token exchange; conditional writes (the current ETag by default for
+  `update`, `patch`, `updateLinkset`, `move`); no repeat after 405 or 415, no
+  POST again after a 5xx or a lost answer; paging by `rel="next"` only;
+  linkset writes only in advertised methods and formats; the RFC 9421 check of
+  a notification. Theorems: `walk_concat`, `walk_members_once`,
+  `step_write_precondition`, `step_no_token_request_without_validation`,
+  `step_no_blind_create_retry`, `step_no_repeat_after_refusal`.
+- CLI `factoidal lws-client <op> URL`.
+- Self-issued credentials (lws10-authn-ssi-cid): `createLwsClient({ selfIssued:
+  { subject, keyId, jwk } })`; the engine signs the ES256 JWT with HACL*.
+- Expected failure: OpenID sign-in is not built (row names issue 917).
+
 ## 0.12.0 — 2026-10-22
 
 One error model for the whole package

package/README.md

@@ -35,7 +35,8 @@ RDF 1.2 input uses `turtle12`, `ntriples12`, `nquads12` or `trig12`.
 - Syntaxes: N-Triples, N-Quads, Turtle, TriG, RDF/XML, JSON-LD; RDF 1.1 and 1.2
 - SPARQL 1.1 and 1.2 query and update; GeoSPARQL functions, text search,
   JavaScript extension functions, SERVICE
-- Reasoning: RDFS, OWL 2 RL closure, OWL 2 DL consistency and entailment, RIF Core
+- Reasoning: RDFS, OWL 2 RL closure, restricted checked OWL consistency,
+  experimental OWL entailment, RIF Core
 - Validation: SHACL, ShEx, JSON Schema, Schematron
 - Mapping: CSVW, RML, JSON-LD
 - Canonicalization: RDFC-1.0; Verifiable Credentials Data Integrity (eddsa-rdfc-2022), did:key
@@ -51,6 +52,50 @@ RDF 1.2 input uses `turtle12`, `ntriples12`, `nquads12` or `trig12`.
   "Terms given as strings".
 - RDF/JS DataFactory and DatasetCore (`/rdfjs`), a functional API (`/fn`)
 
+## Checked pipelines
+
+Each component kind has one interface type whose contract against the W3C
+specifications is part of the type: readers, stores, the SPARQL evaluator,
+writers, reasoners, validators and the proof checker. A contract that is not
+proved yet is a named assumption; CI fails when the list of assumptions grows
+without a stated reason. A theorem states that the SPARQL answer agrees with
+the SPARQL 1.1 semantics for data from any source (a parsed document, an
+edited Dataset, an update, a reasoner's output, a union of stores), given the
+listed assumptions. No new command-line verbs. Status:
+https://github.com/danbri/factoidal/issues/975.
+
+The same components are nodes you can compose. A value on a wire is
+`{graph, evidence}`; each node adds one evidence record; the result lists the
+union of the named assumptions of the nodes, so a pipeline says exactly what
+its answer depends on.
+
+```js
+import { stages, node, pipe, run } from "@factoidal/core";
+
+const sources = `@prefix ex: <http://example.org/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+ex:alice ex:worksFor ex:acme .
+ex:worksFor rdfs:domain ex:Employee .
+ex:Employee rdfs:subClassOf ex:Person .`;
+const description = `@prefix ex: <http://example.org/> .
+_:x a ex:Person . _:x ex:worksFor ex:acme .`;
+
+console.log((await stages()).length);  // registered components, each with status and contract
+const p = pipe(
+  await node("turtleDocumentReader"),
+  await node("rdfsReasoner"),
+  await node("rdfsExplainGraphStage", { description }),
+);
+const r = await run(p, sources);
+console.log(r.evidence.map((e) => e.stage)); // one record per node
+console.log(r.evidence[2].artefact.entailed); // true, with a checked derivation
+console.log(r.assumptions, r.proved);       // what the answer depends on
+```
+
+`run(p, input, { unchecked: true })` also runs components that are not proved,
+and marks those steps in the evidence. Details: API.md, "Stages as nodes" and
+"Explaining an entailment" (`explain()` is the same check as one call).
+
 Formats (generated from `formats()`):
 
 <!-- formats-table:start (generated by test/formats-table.test.mjs) -->
@@ -134,7 +179,7 @@ Changes: [CHANGELOG.md](CHANGELOG.md).
 ```console
 $ npx factoidal serve --file data.ttl /ds          # SPARQL endpoint at /ds/sparql
 $ npx factoidal serve --tdb2 DIR /ds               # serve a Jena TDB2 database
-$ npx factoidal pack data.ttl store/gen-1 && npx factoidal activate store gen-1
+$ npx factoidal pack data.ttl store/gen-1 && npx factoidal activate store gen-1   # IBK5 quad blocks
 $ npx factoidal query store 'SELECT * WHERE { ?s ?p ?o } LIMIT 5'
 $ npx factoidal query "$(npx factoidal sample-store)" 'SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }'
 $ npx factoidal lws-serve DIR --issuer IRI         # Linked Web Storage
@@ -148,6 +193,19 @@ $ npx factoidal solid-serve DIR                    # Solid Protocol
 
 Official test suites, pass / fail / total, 2026-10-09 [B] unless marked.
 
+The OWL DL rows below are historical measurements of the legacy harness;
+they do not measure the current `owlIsConsistent` API. That API checks only
+an admitted fragment of the default graph (atomic classes,
+`owl:someValuesFrom`, `owl:TransitiveProperty`, and annotations, axiom
+annotations included). It returns `true` for a checked finite model, `false`
+for a checked contradiction and `null` for unsupported input, exhausted
+`fuel` or an incomplete check. Other restrictions, negative property
+assertions, imports and equivalentClass are unsupported. `owlEntails`
+answers `false` only with a checked countermodel; its positive verdicts use a
+separate legacy path that does not have this source-to-verdict proof. See the
+[OWL API contract](https://github.com/danbri/factoidal-core/blob/main/npm/factoidal/API.md)
+and the [assurance record](https://github.com/danbri/factoidal-core/blob/main/docs/20261022-owl-pr-reconciliation.md).
+
 | Suite | Result |
 |---|---|
 | SPARQL 1.1 Query, Update, Protocol | 631 / 0 / 631 |

package/authz/server.mjs

@@ -0,0 +1,331 @@
+// A Node HTTP host for the authorization server component.
+// https://github.com/danbri/factoidal/issues/916
+// Design record: docs/designissues/2026-10-22-authorization-server.md
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Accept a socket, turn one HTTP request into the JSON request record,
+// call the engine's `authzStep` on a handle, and write the JSON response
+// record back. Read the clock, draw random bytes, resolve host names, fetch
+// the documents the engine names, and read and write the key file. That is
+// the whole contract (iron rule 7 of CLAUDE.md, anti-pattern 36).
+//
+// It makes NO protocol or token decision: no status code, no OAuth error
+// code, no claim, no key choice, no address check. Every one of those lives
+// in `formal/lean4/L4Factoidal/Authz/`. The one status code written here is
+// 500, for a failure of this host itself.
+//
+// THE WASM CONTRACT (Wasm/Ops/Authz.lean)
+//   authzOpen    [configJson]              -> { ok, handle, issuer, kid, changed }
+//   authzStep    [handle, requestJson]     -> { ok, response, changed }
+//                                            | { ok, resolve: { host }, changed }
+//                                            | { ok, fetch: { url, accept, address }, changed }
+//   authzFetched [handle, { url, status, body, now } | { host, addresses, now }] -> { ok }
+//   authzKeys    [handle, { nonce?, private? }] -> { ok, keys } | { ok, jwks }
+//   authzRotate  [handle, { now, random }]  -> { ok, changed, kid }
+//   authzClose   [handle]                   -> { ok }
+//
+// FETCHES. `resolve` names a host: this host resolves it (`dns.lookup`, every
+// address) and passes the addresses back; the engine decides whether they may
+// be reached (loopback, link-local and private addresses are refused unless
+// the configuration says `allowPrivateFetch`). `fetch` names a URL and the
+// address to connect to: this host connects to exactly that address (the name
+// is not resolved again), sends no cookie or credential, follows no redirect,
+// reads at most MAX_DOCUMENT_BYTES, and passes the status and the text back.
+
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { loadEngine } from '../bin/engine.mjs'
+import { storageKeyText } from '../lws/persist.mjs'
+
+/** The ops this host needs from the engine. */
+export const AUTHZ_OPS = ['authzOpen', 'authzStep', 'authzFetched', 'authzKeys', 'authzRotate', 'authzClose']
+
+/** The key file in DIR. */
+export const KEY_FILE = 'authz-keys.json'
+
+/** Bounds on what one request may make this host do. */
+const MAX_NEEDS = 16
+const FETCH_TIMEOUT_MS = 10000
+const MAX_DOCUMENT_BYTES = 1048576
+
+/** Random bytes for the engine, base64. Pure I/O. */
+function randomBase64 (size) {
+  const bytes = new Uint8Array(size)
+  globalThis.crypto.getRandomValues(bytes)
+  return Buffer.from(bytes).toString('base64')
+}
+
+function nowSeconds () {
+  return Math.floor(Date.now() / 1000)
+}
+
+/** An error raised by this host, as opposed to one the engine reported. */
+export class AuthzHostError extends Error {
+  constructor (message) {
+    super(message)
+    this.name = 'AuthzHostError'
+  }
+}
+
+/** Read the key file of DIR, or null. */
+export function readKeyFile (dir) {
+  const file = join(resolve(dir), KEY_FILE)
+  if (!existsSync(file)) return null
+  const text = readFileSync(file, 'utf8')
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new AuthzHostError(`${file} is not JSON: ${error.message}`)
+  }
+}
+
+/** Write the key file of DIR: temporary file, fsync, rename, mode 0600. */
+export function writeKeyFile (dir, doc) {
+  const root = resolve(dir)
+  mkdirSync(root, { recursive: true })
+  const file = join(root, KEY_FILE)
+  const temporary = join(root, `.${KEY_FILE}.${process.pid}.tmp`)
+  const fd = openSync(temporary, 'w', 0o600)
+  try {
+    writeSync(fd, JSON.stringify(doc))
+    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.
+  }
+}
+
+/** Every address of a host name. Pure I/O. */
+async function resolveHost (host) {
+  try {
+    const dns = await import('node:dns')
+    const found = await dns.promises.lookup(host, { all: true, verbatim: true })
+    return found.map((a) => a.address)
+  } catch (_error) {
+    return []
+  }
+}
+
+/** GET one URL from the address the engine named. Pure I/O: status 0 and a
+ *  message when there is no answer. */
+async function fetchFrom (url, accept, address) {
+  let target
+  try {
+    target = new URL(url)
+  } catch (error) {
+    return { status: 0, body: `not a URL: ${url}` }
+  }
+  const module = target.protocol === 'https:' ? await import('node:https') : await import('node:http')
+  const family = address.indexOf(':') >= 0 ? 6 : 4
+  return new Promise((done) => {
+    const request = module.request(target, {
+      method: 'GET',
+      headers: { accept },
+      lookup: (_host, options, callback) => {
+        if (options && options.all) callback(null, [{ address, family }])
+        else callback(null, address, family)
+      },
+      timeout: FETCH_TIMEOUT_MS
+    }, (response) => {
+      const chunks = []
+      let size = 0
+      response.on('data', (chunk) => {
+        size += chunk.length
+        if (size > MAX_DOCUMENT_BYTES) {
+          response.destroy()
+          done({ status: 0, body: `the document at ${url} is larger than ${MAX_DOCUMENT_BYTES} bytes` })
+          return
+        }
+        chunks.push(chunk)
+      })
+      response.on('end', () => done({ status: response.statusCode, body: Buffer.concat(chunks).toString('utf8') }))
+      response.on('error', (error) => done({ status: 0, body: String(error.message) }))
+    })
+    request.on('timeout', () => request.destroy(new Error('timeout')))
+    request.on('error', (error) => done({ status: 0, body: String(error.message) }))
+    request.end()
+  })
+}
+
+/**
+ * Open one authorization server on the engine.
+ *
+ * @param {object} options
+ * @param {string} options.issuer the issuer identifier (http or https, no query)
+ * @param {string[]} options.resources the resource IRIs tokens may be issued for
+ * @param {string} [options.dir] the directory of the key file
+ * @param {string} [options.alg] "ES256" (default) or "EdDSA"
+ * @param {number} [options.tokenLifetime] seconds, 1 to 300 (default 300)
+ * @param {number} [options.rotateAfter] seconds; 0 (default) never
+ * @param {boolean} [options.allowHttp] accept http subjects (default false)
+ * @param {boolean} [options.allowPrivateFetch] fetch from loopback, link-local and private addresses (default false)
+ * @param {string|null} [options.storageKey] the key text; default FACTOIDAL_LWS_KEY; null reads none
+ * @param {boolean|string[]} [options.cors] false for no CORS fields, or the origins to answer;
+ *   default: echo any valid request Origin (issue 923)
+ * @param {object} [options.engine] an engine to reuse
+ */
+export async function openAuthorizationServer (options = {}) {
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const dir = typeof options.dir === 'string' ? options.dir : null
+  const config = {
+    issuer: options.issuer,
+    resources: Array.isArray(options.resources) ? options.resources : [],
+    now: nowSeconds(),
+    entropy: randomBase64(64)
+  }
+  for (const name of ['alg', 'tokenLifetime', 'leeway', 'rotateAfter', 'docTtl']) {
+    if (options[name] !== undefined) config[name] = options[name]
+  }
+  if (options.allowHttp === true) config.allowHttp = true
+  if (options.allowPrivateFetch === true) config.allowPrivateFetch = true
+  // CORS (issue 923): false or a list of origins, passed unread; absent, the
+  // engine echoes the request Origin (L4Factoidal/Authz/Server.lean stepCors).
+  if (options.cors !== undefined) config.cors = options.cors
+  const key = storageKeyText(options.storageKey)
+  if (key !== undefined) config.storageKey = key
+  if (dir !== null) {
+    const keys = readKeyFile(dir)
+    if (keys !== null) config.keys = keys
+  }
+  const opened = engine.call('authzOpen', [JSON.stringify(config)])
+  const handle = opened.handle
+  if (typeof handle !== 'string') throw new AuthzHostError('authzOpen answered with no handle')
+
+  const persist = (envelope) => {
+    if (dir === null || envelope === null || typeof envelope !== 'object' || envelope.changed !== true) return
+    const told = engine.call('authzKeys', [handle, JSON.stringify({ nonce: randomBase64(12) })])
+    writeKeyFile(dir, told.keys)
+  }
+  persist(opened)
+
+  return {
+    engine,
+    handle,
+    issuer: opened.issuer,
+    /**
+     * One request.
+     * @param {{method: string, target: string, headers: Array<[string, string]>, body: string}} request
+     * @returns {Promise<{status: number, headers: Array<[string, string]>, body: string}>}
+     */
+    async step (request) {
+      let needs = 0
+      for (;;) {
+        const now = nowSeconds()
+        const record = { ...request, now, random: randomBase64(112) }
+        const envelope = engine.call('authzStep', [handle, JSON.stringify(record)])
+        persist(envelope)
+        if (envelope.response !== undefined && envelope.response !== null) {
+          const r = envelope.response
+          return { status: r.status, headers: Array.isArray(r.headers) ? r.headers : [], body: typeof r.body === 'string' ? r.body : '' }
+        }
+        needs += 1
+        if (needs > MAX_NEEDS) throw new AuthzHostError('the engine asked for more than one request may fetch')
+        if (envelope.resolve !== undefined && envelope.resolve !== null) {
+          const host = String(envelope.resolve.host)
+          const addresses = await resolveHost(host)
+          engine.call('authzFetched', [handle, JSON.stringify({ host, addresses, now: nowSeconds() })])
+        } else if (envelope.fetch !== undefined && envelope.fetch !== null) {
+          const f = envelope.fetch
+          const got = await fetchFrom(String(f.url), String(f.accept), String(f.address))
+          engine.call('authzFetched', [handle, JSON.stringify({ url: f.url, status: got.status, body: got.body, now: nowSeconds() })])
+        } else {
+          throw new AuthzHostError('authzStep answered with no response, resolve or fetch')
+        }
+      }
+    },
+    /** Make a new signing key now (the old one stays published). Returns
+     *  the engine's envelope unread. */
+    rotate () {
+      const told = engine.call('authzRotate', [handle, JSON.stringify({ now: nowSeconds(), random: randomBase64(64) })])
+      persist(told)
+      return told
+    },
+    /** The private JWKs of the published keys: for a test harness only. */
+    privateJwks () {
+      return engine.call('authzKeys', [handle, JSON.stringify({ private: true })]).jwks
+    },
+    close () {
+      try { engine.call('authzClose', [handle]) } catch (_error) { /* already gone */ }
+    }
+  }
+}
+
+function headerPairs (raw) {
+  const pairs = []
+  for (let index = 0; index + 1 < raw.length; index += 2) pairs.push([raw[index], raw[index + 1]])
+  return pairs
+}
+
+function readBody (request) {
+  return new Promise((resolveBody, reject) => {
+    const chunks = []
+    request.on('data', (chunk) => chunks.push(chunk))
+    request.on('error', reject)
+    request.on('end', () => resolveBody(Buffer.concat(chunks).toString('utf8')))
+  })
+}
+
+/**
+ * Start an authorization server: listen, then open the engine handle. With
+ * no `issuer` the issuer is the bound origin.
+ *
+ * @param {object} options as `openAuthorizationServer`, plus `port`, `host`
+ * @returns {Promise<{server: object, port: number, origin: string, issuer: string,
+ *                    authz: object, close: Function}>}
+ */
+export async function listen (options = {}) {
+  const http = await import('node:http')
+  const port = typeof options.port === 'number' ? options.port : 0
+  const host = typeof options.host === 'string' ? options.host : '127.0.0.1'
+  let authz = null
+  const server = http.createServer(async (request, response) => {
+    let answer
+    try {
+      const record = {
+        method: request.method,
+        target: request.url,
+        headers: headerPairs(request.rawHeaders),
+        body: await readBody(request)
+      }
+      answer = await authz.step(record)
+    } catch (error) {
+      console.error(`authz-serve: ${error && error.message ? error.message : error}`)
+      response.writeHead(500, { 'content-type': 'text/plain' })
+      response.end('authz-serve: host failure\n')
+      return
+    }
+    for (const [name, value] of answer.headers) response.setHeader(name, String(value))
+    response.statusCode = answer.status
+    response.end(request.method === 'HEAD' ? undefined : answer.body)
+  })
+  await new Promise((resolveListen, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, resolveListen)
+  })
+  const bound = server.address()
+  const origin = `http://${host.indexOf(':') >= 0 ? `[${host}]` : host}:${bound.port}`
+  try {
+    authz = await openAuthorizationServer({ ...options, issuer: typeof options.issuer === 'string' ? options.issuer : origin })
+  } catch (error) {
+    await new Promise((resolveClose) => server.close(resolveClose))
+    throw error
+  }
+  return {
+    server,
+    port: bound.port,
+    origin,
+    issuer: authz.issuer,
+    authz,
+    close () {
+      return new Promise((resolveClose) => {
+        server.close(() => { authz.close(); resolveClose() })
+      })
+    }
+  }
+}