@factoidal/core 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+## 0.20.0 (2026-10-27)
+
+- **Breaking:** in a checked pipeline (`node`, `pipe`, `run`), each node now puts a value of its output wire on the wire: text after a writer, the rows after SELECT, a boolean after ASK, the report after `shaclValidator`, `[canonical, sha256]` after `rdfcStage`, the result after `rdfsExplainGraphStage`. Before, such a node left its input Dataset on the wire, so a well-typed reader → writer → reader pipeline failed at run time. `run()` rejects a runner value that is not of the node's `wireOut`. `rdfcStage` as a node takes a Dataset only (https://github.com/danbri/factoidal-core/pull/155).
+- `node()` keeps its own copy of its settings (frozen at every depth; a Dataset is cloned). A change to the caller's objects after `node()` no longer changes what runs while the evidence keeps the old `settingsDigest`. `run()` rejects a node whose settings changed through `node.params` (https://github.com/danbri/factoidal-core/pull/155).
+- **Breaking:** `canonicalHash(dataset)` keeps graph names: it is the SHA-256 of the text `canonicalize()` answers. 0.17.0 to 0.19.0 dropped graph names, so datasets that differ only in graph names got one hash. New `asDefaultGraph(dataset)`; `canonicalHash(asDefaultGraph(g))` gives a graph's hash whatever its name (https://github.com/danbri/factoidal-core/pull/155).
+- SBM11 stores opened with `openSbm11` (and the wasm ops `sbm11Open` / `sbm11Query`) are checked against their Merkle roots by default: the open admits each file's `.merkle` sidecar against `manifest.sbm11`, and every byte a query decodes comes from a 65,536-byte chunk checked by its Merkle proof. A changed data file, sidecar or Merkle reference in the manifest fails the open or the query with an error that names the file (before, a changed `dict.gdv1` was answered as data). `openSbm11(source, { verify: 'none' })` keeps the earlier length-only check; `store.verify` says which mode is in use. Measured cost: within run-to-run noise on stores of 1 to 6 MB (https://github.com/danbri/factoidal-core/pull/157).
+- Parse is faster again after the IRI check of 0.19.0 (https://github.com/danbri/factoidal/issues/1057): the check tests bytes, and a repeated IRI is not checked again. Parse of 100,000 triples is now about 3% slower than 0.18.0 (it was 10% to 19%). The IRIs that are accepted and refused do not change (https://github.com/danbri/factoidal-core/pull/158).
+- CID 1.0 (Controlled Identifiers, W3C Recommendation 2025-05-15): new Lean module `L4Factoidal/CID/` with the section 2 data model (one named error per MUST), Multikey and JsonWebKey material, the five verification relationships, Fragment Resolution, Retrieve Verification Method and the section 3.5 processing errors. The CID context is vendored. Authorization server, CID suite (lws10-authn-ssi-cid): the subject document is checked as a whole and the method is found by Retrieve Verification Method with `authentication`; `expires`/`revoked` need a time zone; `Accept` starts with `application/cid`. VC Data Integrity (Lean): `verificationMethod` can be a method in a controlled identifier document (not only an Ed25519 did:key), and it must be in the relationship that `proofPurpose` names. No npm functions yet (https://github.com/danbri/factoidal/issues/1100, https://github.com/danbri/factoidal-core/pull/161).
+- `parse` takes the option `rdfstar` for JSON-LD, as the 0.18.0 changelog says: `parse(text, { format: 'jsonld', rdfstar: true })` reads `@triple`, `@reifies` and `@annotation` as RDF 1.2 triple terms and reifiers, as `jsonldToRdf` does. 0.18.0 and 0.19.0 refused the option with `option.unknown`. `rdfstar` with another format, or with `lenient`, is refused with `option.conflict` (https://github.com/danbri/factoidal/issues/1091, https://github.com/danbri/factoidal-core/pull/152).
+- Docs: hub page "JSON-LD-star and JSON-LD 1.3" (`docs/web/hub/jsonld-star.md`), with live cells on 0.19.0; the hub pages load 0.19.0 (were 0.16.0).
+- Value matching (https://github.com/danbri/factoidal/issues/1052): new `sameValue(a, b)` is SPARQL 1.1 `=` on two terms (sections 17.3, 17.4.1.7), decided by the engine (Lean `SPARQL/SameValue.lean`). It answers `true`, `false`, or `null` for incomparable (the type error of `=`). `Dataset.has`, `match` and `delete` take `{match: 'value'}`: a literal object then matches each object literal of the same value (`"1"^^xsd:int` finds `"01"^^xsd:integer` and `"1.0"^^xsd:decimal`), through an index of the literals by value. Term matching stays the default. New wasm op `sameValue`; `datasetMatch`, `datasetMatchCount` and `datasetDeleteQuadsJson` take an optional options argument.
+- Syntax names (https://github.com/danbri/factoidal/issues/1053): new `syntaxFor(fileName)` and `syntaxFor({fileName, mediaType})` give the syntax of a document from the W3C registrations (Lean `RDF/MediaType.lean`), or `null`. Each row of `formats()` has `mediaTypes` and `extensions` from the same table (README format table: two new columns). New wasm op `syntaxFor`.
+- IRIs, vocabularies, lists and containers (https://github.com/danbri/factoidal/issues/1051 items 4 to 6): new `splitIri(iri)` (namespace and the longest XML NCName suffix), `isNCName(text)`, `vocabularies()` (rdf, rdfs, xsd and owl with their terms; foaf, dcterms, dc and schema namespaces), `memberIri(n)` and `memberOrdinal(iri)` (`rdf:_n`). Dataset methods `listItems(head, graph?)` (refuses a list that is not well formed, with the reason), `containerItems(node, graph?)` and `addList(items, graph?)`. Lean `RDF/IriSplit.lean`, `RDF/VocabularyTable.lean`, `RDF/Collections.lean`. New wasm ops `splitIri`, `isNCName`, `vocabularies`, `memberIri`, `memberOrdinal`, `datasetListItems`, `datasetContainerItems`, `datasetAddList`. These need a wasm built from this source.
+- Literal values (https://github.com/danbri/factoidal/issues/1051 items 1 to 3). New functions `literalValue(term)`, `isValidLiteral(term)`, `canonicalLiteral(term)` and `literalFromValue(value, {datatype?})`, synchronous after `ready()` (API.md "Literal values"). `literalValue` gives the XSD 1.1 lexical-to-value mapping of a literal for every XSD built-in the engine has (numeric types and the derived integer types with their bounds, boolean, the string types, date/time and `g*` types, durations, binary, lists) and for `rdf:langString`, `rdf:dirLangString`, `rdf:XMLLiteral`, `rdf:JSON`: `{datatype, recognized, valid, value?, canonical?}`, with the value as JSON-safe data (a number that a JavaScript number does not hold exactly is a decimal string). `valid: false` is an ill-typed literal; `recognized: false` is a datatype the engine does not have. `literalFromValue` maps a boolean, number, bigint, string or Date to a typed literal with one engine table (safe integer `xsd:integer`, other number `xsd:double`, bigint `xsd:integer`, Date `xsd:dateTime` in UTC), or to a named datatype (`{datatype: 'int'}`) when the value is in its value space, else a `FactoidalError` with the new code `literal.value`. New wasm ops `literalValue` and `literalFromValue` (Lean `L4Factoidal/RDF/LiteralValue.lean`, `Wasm/Ops/LiteralValue.lean`). An extension function may now answer a `Date` (an `xsd:dateTime`).
+- The canonical form of an `xsd:float` or `xsd:double` value is now the XSD 1.1 Part 2 §3.3.4.2/§3.3.5.2 form (algorithm §E.1): the fewest significant digits that map back to the value. `"0.1"^^xsd:double` has the canonical form `1.0E-1`; before, it was the exact binary expansion `1.000000000000000055511151231257827021181583404541015625E-1`. It is the `canonical` member of `literalValue` and RML's canonical form of a double (RML-Core natural mapping). SPARQL casts do not change (`xsd:double("0.1")` is still `"0.1"^^xsd:double`). Theorems `double_canonical_roundTrip`, `float_canonical_roundTrip`, `integer_canonical_roundTrip` (`XSD/CanonicalTheorems.lean`).
+
+## 0.19.0 (2026-10-27)
+
+- Notice (owner decision, 2026-10-27): "EXPERIMENTAL UNREVIEWED CODE - USE WITH CARE - DO NOT CREATE PUBLIC SERVICES USING THIS WITHOUT CAREFUL INDEPENDENT EXPERT REVIEW." It is at the top of both READMEs and the hub, in the package description, in every `factoidal` help text, and on standard error when `serve`, `lws-serve`, `solid-serve`, `solid-client`, `lws-client`, `authz-serve`, `authz-keys`, `xmpp-serve` or `webdav-serve` starts.
+- Authorization server (https://github.com/danbri/factoidal-core/pull/150): SAML 2.0 subject tokens (lws10-authn-saml, token type `urn:ietf:params:oauth:token-type:saml2`) from the identity providers the configuration trusts: `authz-serve --saml-idp FILE` (repeatable; also `lws-serve --authz`), config member `samlIdps` (`[{ entityId, jwk }]`, an RSA public JWK of 2048 bits or more). The assertion needs one enveloped XML Signature in the SAML Core §5 profile (Exclusive XML Canonicalization 1.0, rsa-sha256, SHA-256 digest, the reference `#` + the assertion's `ID`), verified under the configured key, never a key from `ds:KeyInfo`; a document type declaration, comments, processing instructions, a second signature or a wrapped assertion are refused. `saml:NameID` is the subject, the bearer `Recipient` the client; `Conditions` times and every `AudienceRestriction` must name this server. Encrypted assertions are refused (https://github.com/danbri/factoidal/issues/1073). The token type is advertised only when a provider is configured (https://github.com/danbri/factoidal/issues/926). Lean: `XML/ExcC14n.lean`, `XML/DSig.lean`, `SAML/Assertion.lean`; record `docs/designissues/2026-10-27-saml-xml-signature.md`.
+
+Fixes for defects found by the echo test ports (https://github.com/danbri/echochamber: Jena-, RDFLib-, N3.js- and RDF4J-style test suites run against this package).
+
+- SPARQL (https://github.com/danbri/factoidal-core/pull/146): blank nodes written by SPARQL Update get valid N-Triples labels, so CONSTRUCT, DESCRIBE and `shaclValidate` on that Dataset no longer fail (https://github.com/danbri/factoidal/issues/1074); IN and NOT IN raise an error when a comparison errs and no other element decides, so `2 IN (3, 1/0)` is an error, not false (§17.4.1.9, https://github.com/danbri/factoidal/issues/1049); ORDER BY an aggregate (`ORDER BY DESC(COUNT(?s))`) orders the groups of a grouped query (https://github.com/danbri/factoidal/issues/1050); SUBSTR takes start and length of types derived from xsd:integer, such as xsd:int (https://github.com/danbri/factoidal/issues/1060); no XSD constructor function casts a language-tagged literal: `xsd:string("foo"@en)` and `xsd:byte("1"@en)` are errors, use `STR` (§17.5, https://github.com/danbri/factoidal/issues/1062); `true.` and `false.` read as the keyword and the triple terminator (https://github.com/danbri/factoidal/issues/1075); a variable used only inside MINUS is not in scope, so `(1 AS ?z)` is allowed (§18.2.1, https://github.com/danbri/factoidal/issues/1069).
+- Readers and writers (https://github.com/danbri/factoidal-core/pull/147): N-Triples 1.2 and N-Quads 1.2 read the VERSION directive (https://github.com/danbri/factoidal/issues/1055); TriG refuses a top-level triple with no final '.' (https://github.com/danbri/factoidal/issues/1056); Turtle and TriG read white space or a comment after `^^`, and a prefix named `true` or `false` (https://github.com/danbri/factoidal/issues/1063); one RFC 3987 IRI check: the readers, `fromQuads`/`Dataset.add`, the SPARQL parser and the writers refuse a string that is not an IRI, such as `<a_b:c>`, `<http://www:example.org/>` or `<http://a/%zz>`, with `term.invalid-iri`, so no writer writes text that no reader reads (https://github.com/danbri/factoidal/issues/1057); RDF/XML writer: CR in a literal is written `&#xD;` (https://github.com/danbri/factoidal/issues/1047), a predicate such as `urn:example:p` is written with namespace `urn:example:` (https://github.com/danbri/factoidal/issues/1048); RDF/JS: `dataFactory.literal` gives the language tag in lowercase, and the `Literal` type has `direction` (https://github.com/danbri/factoidal/issues/1054); JSON-LD: a `"@foo"` key in a value object is ignored with or without a base (https://github.com/danbri/factoidal/issues/1064); `parse()` with no format: JSON-LD only for JSON text, N-Quads when a statement names a graph; the rules are in API.md (https://github.com/danbri/factoidal/issues/1058).
+- Cost: the IRI check makes parsing slower: 100,000 triples, median of 3, 0.18 → 0.19: N-Triples 581 → 646 ms (+11%), Turtle 606 → 718 ms (+19%), N-Quads 1.2 616 → 681 ms (+10%). Work to recover it is in progress.
+
 ## 0.18.0 (2026-10-27)
 
 - XSD constructor functions for datatypes outside the SPARQL 1.1 §17.5 table (`xsd:byte`, `xsd:int`, `xsd:unsignedInt`, `xsd:date`, `xsd:time`, `xsd:gYear` and the other `xsd:g*` types, the duration types, `xsd:token`, …) now cast as XPath F&O 3.1 §19 says. Before, they changed only the datatype and gave ill-typed literals such as `"HaHa"^^xsd:byte`. An invalid value or a cast that F&O does not allow is now an error (the variable is unbound) (https://github.com/danbri/factoidal/issues/1041, https://github.com/danbri/factoidal-core/pull/142).

package/README.md

@@ -1,5 +1,13 @@
 # @factoidal/core
 
+> ⚠️ **EXPERIMENTAL UNREVIEWED CODE - USE WITH CARE - DO NOT CREATE PUBLIC SERVICES USING THIS WITHOUT CAREFUL INDEPENDENT EXPERT REVIEW.**
+>
+> This covers the whole core library and every command line tool, and in
+> particular all protocol, authentication and security code (the LWS, Solid,
+> SPARQL Protocol, WebDAV and XMPP servers and clients, the authorization
+> server, JOSE, XML Signature and SAML, the crypto bindings). Owner decision,
+> 2026-10-27.
+
 RDF, SPARQL, reasoning, validation and Linked Data servers in one package.
 Runs in Node 22.12+, Deno 2 and browsers. No dependencies.
 
@@ -30,10 +38,14 @@ every consumer accepts one, so a pipeline does not re-parse between steps.
 An unknown option key throws. With no `format`, the format is inferred and
 reported in `dataset.format`; an explicit `format` is never overridden.
 RDF 1.2 input uses `turtle12`, `ntriples12`, `nquads12` or `trig12`.
+RDF 1.2 in JSON-LD (JSON-LD-star: `@triple`, `@reifies`, `@annotation`,
+`@direction`) needs the option `rdfstar`: `jsonldToRdf(text, { rdfstar: true })`
+and `dataset.serialize({ format: 'jsonld', rdfstar: true })`.
 
 ## What it does
 
 - Syntaxes: N-Triples, N-Quads, Turtle, TriG, RDF/XML, JSON-LD; RDF 1.1 and 1.2
+  (RDF 1.2 in JSON-LD through the JSON-LD-star draft, option `rdfstar`)
 - SPARQL 1.1 and 1.2 query and update; GeoSPARQL functions, text search,
   JavaScript extension functions, SERVICE
 - Reasoning: RDFS, OWL 2 RL closure, restricted checked OWL consistency,
@@ -43,7 +55,13 @@ RDF 1.2 input uses `turtle12`, `ntriples12`, `nquads12` or `trig12`.
 - Canonicalization: RDFC-1.0; Verifiable Credentials Data Integrity (eddsa-rdfc-2022), did:key
 - XML: XML 1.0, XPath 1.0, XSLT 1.0, XForms
 - Servers: SPARQL 1.1 Protocol and Graph Store (Fuseki-compatible paths,
-  Jena TDB2 read only), Linked Web Storage 1.0, Solid
+  Jena TDB2 read only), Linked Web Storage 1.0, Solid, an OAuth 2.0
+  authorization server (token exchange for OpenID Connect ID tokens,
+  self-issued CID credentials and SAML 2.0 assertions)
+- Security: JWS/JWT (ES256, RS256, EdDSA), XML Signature verification in the
+  SAML Core profile (Exclusive XML Canonicalization 1.0, rsa-sha256), with
+  HACL\* primitives. XML Encryption and JWE are not implemented yet:
+  https://github.com/danbri/factoidal/issues/1081
 - A persisted store with a delta log for updates (early stage)
 - Terms: a JavaScript extension function can answer with an exact term
   (`{value: "007", datatype: XSD + "integer"}`, an RDF/JS term, a triple
@@ -104,19 +122,19 @@ and marks those steps in the evidence. Details: API.md, "Stages as nodes" and
 Formats (generated from `formats()`):
 
 <!-- formats-table:start (generated by test/formats-table.test.mjs) -->
-| format | read RDF 1.1 | read RDF 1.2 | write RDF 1.1 | write RDF 1.2 | engine |
-|---|---|---|---|---|---|
-| nquads | yes | yes | yes | yes | core |
-| ntriples | yes | yes | yes | yes | core |
-| turtle | yes | yes | yes | yes | core |
-| trig | yes | yes | yes | yes | core |
-| rdfxml | yes | no | yes | no | core |
-| jsonld | yes | no | yes | no | full |
-| rdfc | no | no | yes | no | core |
-| sparql-results-json | no | no | yes | yes | core |
-| sparql-results-xml | no | no | yes | yes | core |
-| sparql-results-csv | no | no | yes | yes | core |
-| sparql-results-tsv | no | no | yes | yes | core |
+| format | read RDF 1.1 | read RDF 1.2 | write RDF 1.1 | write RDF 1.2 | engine | media type | extension |
+|---|---|---|---|---|---|---|---|
+| nquads | yes | yes | yes | yes | core | `application/n-quads` | `.nq` |
+| ntriples | yes | yes | yes | yes | core | `application/n-triples` | `.nt` |
+| turtle | yes | yes | yes | yes | core | `text/turtle` | `.ttl` |
+| trig | yes | yes | yes | yes | core | `application/trig` | `.trig` |
+| rdfxml | yes | no | yes | no | core | `application/rdf+xml` | `.rdf` |
+| jsonld | yes | no | yes | no | full | `application/ld+json` | `.jsonld` |
+| rdfc | no | no | yes | no | core |  |  |
+| sparql-results-json | no | no | yes | yes | core |  |  |
+| sparql-results-xml | no | no | yes | yes | core |  |  |
+| sparql-results-csv | no | no | yes | yes | core |  |  |
+| sparql-results-tsv | no | no | yes | yes | core |  |  |
 <!-- formats-table:end -->
 
 Missing writers (HDT, N3, RDFa): https://github.com/danbri/factoidal/issues/883.
@@ -146,6 +164,7 @@ Codes (generated from `engineTables().errorCodes`):
 | `term.invalid-iri` | <https://www.w3.org/TR/rdf12-concepts/#section-IRIs> | A term that must be an IRI is not one. |
 | `term.invalid-langtag` | <https://www.w3.org/TR/rdf12-concepts/#section-Graph-Literal> | A language tag is not well-formed (BCP 47). |
 | `term.invalid` | <https://www.w3.org/TR/sparql11-results-json/#select-encode-terms> | A term or quad given as JSON is not an RDF term or quad. |
+| `literal.value` | <https://www.w3.org/TR/xmlschema11-2/#value-space> | The value is not in the value space of the named datatype, or the datatype is not one the engine has. |
 | `query.syntax` | <https://www.w3.org/TR/sparql11-query/#grammar> | The SPARQL query does not match the SPARQL grammar. |
 | `query.failed` | <https://www.w3.org/TR/sparql11-query/#sparqlDefinition> | The SPARQL query parsed but its evaluation was refused. |
 | `update.syntax` | <https://www.w3.org/TR/sparql11-update/#grammar> | The SPARQL update does not match the SPARQL Update grammar. |
@@ -189,6 +208,7 @@ $ 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
 $ npx factoidal solid-serve DIR                    # Solid Protocol
+$ npx factoidal authz-serve DIR --resource IRI --saml-idp idp.json   # OAuth 2.0 authorization server
 ```
 
 `npx factoidal --help` lists every command. Replacing Apache Jena Fuseki:
@@ -224,6 +244,8 @@ and the [assurance record](https://github.com/danbri/factoidal-core/blob/main/do
 | JSON-LD 1.1 toRdf, expand, flatten | 910 / 0 / 910 |
 | JSON-LD 1.1 compact, fromRdf | 298 / 0 / 300 (2 not run) |
 | JSON-LD 1.1 Framing | 29 / 63 / 92 |
+| JSON-LD-star draft (RDF 1.2), option `rdfstar` | 168 / 1 / 171 (2 local override; 170 of 171 with them) [J] |
+| RDF 1.2 eval tests written as JSON-LD-star and read back | 140 / 0 / 140 [J] |
 | RDFC-1.0 | 86 / 0 / 86 |
 | OWL 2 RL | 126 / 0 / 126 |
 | OWL 2 DL type-inconsistency | 116 / 11 / 128 (1 other) |
@@ -247,6 +269,7 @@ and the [assurance record](https://github.com/danbri/factoidal-core/blob/main/do
 [L] 2026-10-22, https://github.com/danbri/factoidal-core/blob/2b9d2e39af53be31ed92463b58d3e132e65c4fe4/docs/designissues/2026-10-21-lws-touchstone-run.md (with server options, 220 of 221 pass in at least one configuration)
 [S] 2026-10-21, the current W3C manifest (29 active tests), https://github.com/danbri/factoidal-core/blob/2b9d2e39af53be31ed92463b58d3e132e65c4fe4/docs/claude-rules/current-state.md
 [C] 2026-10-21, validation test308, https://github.com/danbri/factoidal/issues/700
+[J] 2026-10-27, tests of https://github.com/json-ld/json-ld-star/pull/61; the fail is a defective fixture (fromRdf tst07), https://github.com/danbri/factoidal-core/blob/2a656d7bfb4af329d77669afb5e62eb00625bd15/docs/designissues/2026-10-26-jsonld-star.md
 
 ## Limits
 

package/authz/server.mjs

@@ -169,6 +169,8 @@ async function fetchFrom (url, accept, address) {
  * @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 {{entityId: string, jwk: object}[]} [options.samlIdps] the SAML 2.0 identity providers
+ *   whose signed assertions are accepted, each with its RSA public JWK (issue 926)
  * @param {object} [options.engine] an engine to reuse
  */
 export async function openAuthorizationServer (options = {}) {
@@ -192,6 +194,9 @@ export async function openAuthorizationServer (options = {}) {
   // 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
+  // SAML 2.0 identity providers (issue 926): [{ entityId, jwk }], passed
+  // unread; the engine checks each (Wasm/Ops/Authz.lean samlIdpsOf?).
+  if (options.samlIdps !== undefined) config.samlIdps = options.samlIdps
   const key = storageKeyText(options.storageKey)
   if (key !== undefined) config.storageKey = key
   if (dir !== null) {

package/bin/factoidal.mjs

@@ -90,6 +90,15 @@ function err (line) { console.error(line) }
 
 // ---------------------------------------------------------------- usage
 
+// Owner, 2026-10-27: every protocol, authentication and security component,
+// the CLIs and the core library carry this notice. It is printed with every
+// help text and on standard error when a server, client or key command starts.
+const REVIEW_WARNING = 'EXPERIMENTAL UNREVIEWED CODE - USE WITH CARE - DO NOT CREATE PUBLIC SERVICES USING THIS WITHOUT CAREFUL INDEPENDENT EXPERT REVIEW.'
+
+/** The commands that serve, speak a protocol, or handle keys and tokens. */
+const WARNED_COMMANDS = new Set(['serve', 'lws-serve', 'solid-serve', 'solid-client', 'lws-client',
+  'authz-serve', 'authz-keys', 'xmpp-serve', 'webdav-serve'])
+
 const USAGE = `factoidal - the Factoidal persisted store, from Node or Deno
 
 usage: factoidal <command> [options]
@@ -355,6 +364,7 @@ usage: factoidal authz-serve DIR --resource IRI[,IRI...] [--issuer IRI]
                            [--token-lifetime SECONDS] [--rotate-after SECONDS]
                            [--allow-http] [--allow-private-fetch]
                            [--cors-origin ORIGIN]... [--no-cors]
+                           [--saml-idp FILE]...
 
 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:
@@ -363,8 +373,17 @@ for lws-serve and any resource server that reads RFC 8414 metadata:
   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).
+self-issued JWTs for https and did:key subjects (lws10-authn-ssi-cid), and
+SAML 2.0 assertions (lws10-authn-saml) from the identity providers --saml-idp
+names (https://github.com/danbri/factoidal/issues/926).
+
+--saml-idp FILE (repeatable) trusts one SAML 2.0 identity provider. FILE is
+JSON: {"entityId": "<the saml:Issuer value>", "jwk": <its RSA public JWK>}.
+An assertion must carry one enveloped XML Signature (exclusive
+canonicalization, rsa-sha256) that verifies under that key, an audience that
+names the issuer of this server, and bearer subject confirmation; its NameID
+is the subject and its Recipient the client. Encrypted assertions are
+refused. Without --saml-idp the token type is refused and not advertised.
 
 --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.
@@ -520,7 +539,8 @@ is required):
                         BASE.well-known/lws-token, the JWK Set at
                         BASE.well-known/lws-jwks, signing keys in DIR (as
                         authz-serve; --alg, --token-lifetime, --rotate-after,
-                        --allow-http and --allow-private-fetch as there). The
+                        --allow-http, --allow-private-fetch and --saml-idp as
+                        there). The
                         storage trusts it, and any --issuer too. Each request
                         is the authorization server's when the engine says so
                         (L4Factoidal/Authz/Mount.lean); every other is the
@@ -807,7 +827,7 @@ 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 REPEATABLE_OPTIONS = new Set(['cors-origin', 'saml-idp'])
 
 const VALUE_OPTIONS = {
   version: new Set([]),
@@ -821,7 +841,8 @@ const VALUE_OPTIONS = {
   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', 'page-size', 'moves', 'controller-inbox', 'delivery-limit', 'delivery-window',
-    'redirects-max', 'storage', 'cors-origin', 'authz', 'alg', 'token-lifetime', 'rotate-after']),
+    'redirects-max', 'storage', 'cors-origin', 'authz', 'alg', 'token-lifetime', 'rotate-after',
+    'saml-idp']),
   'solid-serve': new Set(['port', 'host', 'base', 'owner', 'issuer', 'auth-config']),
   'solid-client': new Set(['body', 'file', 'content-type', 'interpret']),
   'lws-client': new Set(['body', 'file', 'content-type', 'slug', 'type', 'link', 'if-match',
@@ -829,7 +850,7 @@ const VALUE_OPTIONS = {
     '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']),
+    'cors-origin', 'saml-idp']),
   'authz-keys': new Set([]),
   'xmpp-serve': new Set(['port', 'host', 'domain', 'accounts', 'cert', 'key']),
   'webdav-serve': new Set(['port', 'host'])
@@ -1744,6 +1765,16 @@ function corsConfig (options) {
   return {}
 }
 
+// --saml-idp FILE (repeatable): a SAML 2.0 identity provider whose signed
+// assertions the authorization server accepts, as the config member
+// `samlIdps`. FILE is JSON {"entityId": ID, "jwk": RSA public JWK}; passed
+// unread, the engine checks it (Wasm/Ops/Authz.lean, issue 926).
+function samlConfig (options) {
+  const files = options['saml-idp']
+  if (!Array.isArray(files)) return {}
+  return { samlIdps: files.map((f) => readJsonFile(f)) }
+}
+
 function serveHost (options) {
   if (options.host === undefined) return '127.0.0.1'
   if (typeof options.host !== 'string' || options.host.length === 0) {
@@ -1877,7 +1908,8 @@ async function commandLwsServe (positional, options) {
     ...(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)
+    ...corsConfig(options),
+    ...samlConfig(options)
   }
   let auth
   if (authFile !== null) {
@@ -1964,7 +1996,8 @@ async function commandAuthzServe (positional, options) {
       ...(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)
+      ...corsConfig(options),
+      ...samlConfig(options)
     })
   } catch (error) {
     if (error !== null && typeof error === 'object' && error.envelope !== undefined) {
@@ -2287,12 +2320,14 @@ const COMMANDS = {
 
 async function main () {
   if (argv.length === 0) {
+    out(REVIEW_WARNING + '\n')
     out(USAGE)
     return EXIT_USAGE
   }
   const command = argv[0]
   if (command === '--help' || command === '-h' || command === 'help') {
     const topic = argv[1]
+    out(REVIEW_WARNING + '\n')
     if (typeof topic === 'string' && Object.prototype.hasOwnProperty.call(COMMAND_USAGE, topic)) {
       out(COMMAND_USAGE[topic])
     } else {
@@ -2317,9 +2352,13 @@ async function main () {
     throw error
   }
   if (parsed.options.help) {
+    out(REVIEW_WARNING + '\n')
     out(COMMAND_USAGE[command])
     return EXIT_OK
   }
+  if (WARNED_COMMANDS.has(command)) {
+    err(`factoidal ${command}: WARNING: ${REVIEW_WARNING}`)
+  }
   try {
     return await COMMANDS[command](parsed.positional, parsed.options)
   } catch (error) {

package/browser.d.ts

@@ -12,6 +12,7 @@ export type {
   QueryOptions, SerializeOptions, StoreReader, OpenStoreOptions,
   DeltaLogHandle, DeltaLogInspection,
   Sbm11Reader, Sbm11Answer, Sbm11Store, Sbm11ReadEvidence, Sbm11Transport,
+  LiteralValueData, LiteralValueResult,
   ExplainResult, StageInfo, EvidenceRecord, Wire, FactoidalNode, Pipeline, RunResult, RunOptions,
 } from './index';
 
@@ -23,10 +24,22 @@ export {
   canonicalize,
   graphs,
   canonicalHash,
+  asDefaultGraph,
   isomorphic,
   fromQuads,
+  literalValue,
+  isValidLiteral,
+  canonicalLiteral,
+  literalFromValue,
   ready,
   engineTables,
+  sameValue,
+  syntaxFor,
+  splitIri,
+  isNCName,
+  vocabularies,
+  memberIri,
+  memberOrdinal,
   openDataset,
   closure,
   formats,

package/browser.js

@@ -83,10 +83,24 @@ export const serialize = api.serialize;
 export const canonicalize = api.canonicalize;
 export const graphs = api.graphs;
 export const canonicalHash = api.canonicalHash;
+export const asDefaultGraph = api.asDefaultGraph;
 export const isomorphic = api.isomorphic;
 export const fromQuads = api.fromQuads;
+// Literal values (https://github.com/danbri/factoidal/issues/1051): synchronous
+// after the engine is loaded.
+export const literalValue = api.literalValue;
+export const isValidLiteral = api.isValidLiteral;
+export const canonicalLiteral = api.canonicalLiteral;
+export const literalFromValue = api.literalFromValue;
 export const ready = api.ready;
 export const engineTables = api.engineTables;
+export const sameValue = api.sameValue;
+export const syntaxFor = api.syntaxFor;
+export const splitIri = api.splitIri;
+export const isNCName = api.isNCName;
+export const vocabularies = api.vocabularies;
+export const memberIri = api.memberIri;
+export const memberOrdinal = api.memberOrdinal;
 export const openDataset = api.openDataset;
 export const closure = api.closure;
 export const formats = api.formats;