@factoidal/core 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 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.
 
@@ -43,7 +51,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
@@ -189,6 +203,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:

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/index.d.ts

@@ -27,8 +27,11 @@ export interface BlankNode {
 export interface Literal {
   termType: 'Literal';
   value: string;
-  /** Language tag ('' when none). */
+  /** Language tag, lowercase ('' when none). */
   language: string;
+  /** Base direction of a directional language-tagged string (RDF 1.2):
+   *  'ltr' or 'rtl'; '' when none. RDF/JS Data Model, Literal.direction. */
+  direction: '' | 'ltr' | 'rtl';
   /** Datatype IRI term (xsd:string for plain literals). */
   datatype: NamedNode;
   equals(other: Term | null | undefined): boolean;

package/l4-assets/l4factoidal.js

@@ -37,7 +37,7 @@
 // bytes change.
 
 // Stamped by formal/lean4/Wasm/build-wasm.sh step 9 -- do not hand-edit.
-const WASM_VERSION = "925f357453db";
+const WASM_VERSION = "6dbf38660cb9";
 
 import createModule from './l4factoidal.mjs';
 

package/l4-assets/version.json

@@ -2,17 +2,17 @@
   "engine": "lean4",
   "note": "The Lean 4 (L4Factoidal) engine build provenance and claims: the only engine of @factoidal/core since 0.9.0 (issue 713). This committed file is a placeholder. tools/fetch-builds.sh --set web (through tools/stamp-l4-version.mjs) writes the provenance members from the danbri/factoidal-builds release that built the wasm; formal/lean4/Wasm/build-wasm.sh step 9 writes them for a local build. Do not commit a stamped copy.",
   "stamped": true,
-  "release": "danbri/factoidal-builds build-788ee43aec79-web",
-  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/40457275423",
-  "gitSha": "788ee43aec79c4d29592c5e82cc7ab350f0d05dd",
-  "builtAt": "2026-10-27T06:36:59Z",
+  "release": "danbri/factoidal-builds build-b8c6b64b8dc1-web",
+  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/40525043015",
+  "gitSha": "b8c6b64b8dc18a6daa2151a61e28dbb9a4707ade",
+  "builtAt": "2026-10-27T15:28:08Z",
   "leanToolchain": "leanprover/lean4:v4.33.1",
   "emscripten": "6.0.8",
   "abiVersion": "1",
   "engineVersion": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
   "version": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
-  "wasmSha256": "925f357453dbb71d087bef70fd428b054999756d7c967a806403d3d8ee875a57",
-  "wasmBytes": 17565361,
+  "wasmSha256": "6dbf38660cb9966ae7c65ecdb68a38e83d09c1283415c1486b618f203f3f2f39",
+  "wasmBytes": 17694204,
   "claims": {
     "source": "formal/lean4 (L4Factoidal): no sorry, no user axioms, no native_decide; W3C behaviour pinned by build-time #guard",
     "suitesAtBuildSha": "see docs/test-results and formal/lean4/PORT_NOTES.md at gitSha"

package/lib/version.mjs

@@ -2,4 +2,4 @@
 // needs import attributes, which not every runtime this package targets
 // reads). test/dts-drift.test.js checks that it equals package.json's
 // `version`.
-export const version = '0.18.0';
+export const version = '0.19.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@factoidal/core",
-  "version": "0.18.0",
-  "description": "RDF parsing and writing (Turtle, TriG, N-Triples, N-Quads, RDF/XML, JSON-LD), SPARQL 1.1 and 1.2, RDFS and OWL reasoning, SHACL and ShEx validation, CSVW and RML mapping, RDFC-1.0, and SPARQL, LWS and Solid servers, for Node, Deno and browsers.",
+  "version": "0.19.0",
+  "description": "EXPERIMENTAL UNREVIEWED CODE: do not run public services on it without careful independent expert review. RDF parsing and writing (Turtle, TriG, N-Triples, N-Quads, RDF/XML, JSON-LD), SPARQL 1.1 and 1.2, RDFS and OWL reasoning, SHACL and ShEx validation, CSVW and RML mapping, RDFC-1.0, and SPARQL, LWS and Solid servers, for Node, Deno and browsers.",
   "keywords": [
     "sparql",
     "rdf",

package/rdfjs.mjs

@@ -52,11 +52,20 @@ class BlankNode {
   }
 }
 
+// RDF/JS Data Model, interface Literal: "language the language as lowercase
+// [BCP47] string (examples: "en", "en-gb")". A BCP 47 tag is ASCII (RFC 5646
+// section 2.1), and the engine's readers lowercase its ASCII letters (Lean
+// String.toLower), so a factory term equals the same term read from text
+// (https://github.com/danbri/factoidal/issues/1054).
+function lowerAscii(s) {
+  return s.replace(/[A-Z]+/g, (m) => m.toLowerCase());
+}
+
 class Literal {
   constructor(value, language, datatype, direction) {
     this.termType = 'Literal';
     this.value = value;
-    this.language = language || '';
+    this.language = language ? lowerAscii(String(language)) : '';
     // RDF/JS Data Model DataFactory.literal: no datatype argument means
     // xsd:string, a language means rdf:langString, a language and a
     // direction mean rdf:dirLangString.