@factoidal/core 0.10.0 → 0.11.0

package/lib/lean-entry.mjs

@@ -22,12 +22,12 @@
 // None of them makes a semantic decision: which IRIs reach the host, what
 // an absent answer means, which artifact a query reads, are decided in Lean.
 
-const XSD = 'http://www.w3.org/2001/XMLSchema#';
 
 // The two npm entries and the engine each loads (issue 713 stage 4). The
 // core engine's `ops` reflection lists what only the full engine serves
 // (`fullOnlyOps`, `fullOnlyFormats`); a call to one of those names the
 // entry that has it.
+import { appTermToJson, termToJson } from '../rdfjs.mjs';
 export const FULL_ENTRY = '@factoidal/core';
 // The core profile is built for the hub pages only; the package ships the
 // full engine (owner, 2026-10-20).
@@ -64,22 +64,22 @@ function failEnvelope(err) {
   return JSON.stringify({ ok: false, error: String((err && err.message) || err) });
 }
 
-// One SPARQL Results JSON term object per answer, the wire form
-// Wasm/ExtHost.lean reads; '' means "no value" (the section 17.6 error).
+// One answer for Wasm/Ops/ExtFns.lean: the JavaScript value tagged with its
+// JavaScript type ({js, v}; a number as its Number::toString text), or a term
+// object. The engine chooses the datatype and the lexical form
+// (L4Factoidal.XSD.JsValue.jsLiteral, issue 894 item 3). '' means "no
+// value" (the section 17.6 error).
 function encodeExtAnswer(out) {
   if (out === null || out === undefined || out === EXT_PENDING_MARKER) return '';
-  if (typeof out === 'boolean') {
-    return JSON.stringify({ type: 'literal', value: out ? 'true' : 'false', datatype: XSD + 'boolean' });
+  switch (typeof out) {
+    case 'boolean': return JSON.stringify({ js: 'boolean', v: out });
+    case 'number': return JSON.stringify({ js: 'number', v: Object.is(out, -0) ? '-0' : String(out) });
+    case 'bigint': return JSON.stringify({ js: 'bigint', v: out.toString() });
+    case 'string': return JSON.stringify({ js: 'string', v: out });
+    case 'object':
+      try { return JSON.stringify(appTermToJson(out)); } catch (_error) { return ''; }
+    default: return '';
   }
-  if (typeof out === 'number') {
-    if (!Number.isFinite(out)) return '';
-    return Number.isInteger(out)
-      ? JSON.stringify({ type: 'literal', value: String(out), datatype: XSD + 'integer' })
-      : JSON.stringify({ type: 'literal', value: String(out), datatype: XSD + 'double' });
-  }
-  if (typeof out === 'string') return JSON.stringify({ type: 'literal', value: out });
-  if (typeof out === 'object' && typeof out.type === 'string') return JSON.stringify(out);
-  return '';
 }
 
 // The Lean module asks its host through ONE global,
@@ -200,5 +200,14 @@ export function entryFromEngine(eng) {
       }
     };
   }
+  // datasetQuadsBin answers a byte region (formal/lean4/L4Factoidal/RDF/QuadsBin.lean):
+  // this method answers {envelope, bytes} and throws on a refusal.
+  const blobIoOps = Array.isArray(reflection.blobIoOps) ? reflection.blobIoOps : [];
+  if (typeof eng.callBlobIO === 'function' && blobIoOps.includes('datasetQuadsBin')) {
+    entry.datasetQuadsBin = (handle, optsJson) =>
+      eng.callBlobIO('datasetQuadsBin', [String(handle), String(optsJson ?? '')], new Uint8Array(0));
+  } else {
+    delete entry.datasetQuadsBin;
+  }
   return entry;
 }

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.10.0';
+export const version = '0.11.0';

package/lws/README.md

@@ -29,10 +29,13 @@ host or the engine failed rather than answered.
 | `lwsOpen` | `[configJson]` | `{ ok, handle, root }` |
 | `lwsStep` | `[handle, requestJson]` | `{ ok, response }` |
 | `lwsClose` | `[handle]` | `{ ok }` |
+| `lwsSnapshot` | `[handle]` | `{ ok, snapshot }` |
+| `lwsFetched` | `[handle, documentJson]` | `{ ok, fetch? , installed?, refused? }` |
 
 ```
-request  { method, target, headers: [[name, value]], body }
-response { status, headers: [[name, value]], body }
+request  { method, target, headers: [[name, value]] } + the content as bytes
+response { status, headers: [[name, value]], bodyBytes } + the content as bytes
+(through callBlobIO; https://github.com/danbri/factoidal/issues/889)
 ```
 
 `headers` is a list of pairs, not an object: HTTP allows a field name to
@@ -43,7 +46,8 @@ unchanged and this host composes no IRI.
 `configJson` members, all optional: `baseIri` (the absolute IRI the
 storage root maps to), `now` (the engine clock in seconds, which advances
 by one second per mutation so a write sequence has increasing
-`Last-Modified` values with no real clock), `owner`, `agent`. A request
+`Last-Modified` values with no real clock), `owner`, `agent`, `rootAcl`,
+`auth` and `insecureNoAuth` (below). A request
 may carry `now` and `agent` of its own to override the handle's for one
 step; `listen({realClock: true})` is how a server with a real clock feeds
 one in, and a test leaves it off to keep the engine's deterministic
@@ -55,12 +59,41 @@ A WebAssembly module built before these ops landed answers `unknown op`.
 and every test in `tests/lws/` skips with the reason printed rather than
 passing on an engine that cannot answer.
 
+## Authorization
+
+Authorization follows the draft's "Authorization" section
+(https://github.com/danbri/factoidal/issues/886) and is decided by
+`formal/lean4/L4Factoidal/LWS/Authorization.lean`. It is ON by default.
+
+```js
+const running = await listen({
+  port: 3000,
+  owner: 'https://id.example/alice',          // root ACL: Read, Write, Control
+  auth: { issuers: [{ issuer: 'https://as.example' }] },
+  realClock: true
+})
+```
+
+* Clients send `Authorization: Bearer <access token>` (RFC 6750). The
+  token is a JWT (RFC 9068) signed with ES256, RS256 or EdDSA by a trusted
+  issuer; `aud` must contain the storage IRI (`baseIri`, or `auth.audience`).
+* Without a valid token the answer is 401 with
+  `WWW-Authenticate: Bearer resource_metadata="…"`; the RFC 9728 metadata
+  document is served at `/.well-known/oauth-protected-resource<path>`.
+* The host fetches the issuer's `/.well-known/lws-configuration` and its
+  `jwks_uri` when the engine asks (`lwsStep` answers `{ fetch }`), passes
+  the bytes to `lwsFetched`, and steps again. `auth.issuers[].jwks` gives
+  the keys inline instead.
+* `insecureNoAuth: true` serves every request with no authorization. It is
+  for development only, and must be asked for.
+
 ## Use
 
 ```js
 import { listen } from '@factoidal/core/lws'
 
-const running = await listen({ port: 3000, baseIri: 'https://storage.example/' })
+const running = await listen({ port: 3000, baseIri: 'https://storage.example/',
+  insecureNoAuth: true })   // development only; see Authorization
 console.log(running.origin)
 await running.close()
 ```
@@ -68,9 +101,13 @@ await running.close()
 From the command:
 
 ```
-factoidal lws-serve /var/lib/lws --port 3000
+factoidal lws-serve /var/lib/lws --port 3000 --issuer https://as.example --owner https://id.example/alice
+factoidal lws-serve /tmp/dev --port 3000 --insecure-no-auth
 ```
 
+One of `--issuer`, `--auth-config FILE` or `--insecure-no-auth` is
+required.
+
 `--port 0` takes an ephemeral port and the command prints the one it got;
 `--base IRI` sets `baseIri`, which defaults to the bound origin. `DIR`
 names the storage directory, but the first slice keeps the resource tree
@@ -86,12 +123,15 @@ in the engine handle, so nothing is read from it or written to it yet
 | `openLwsStorage(options)` | open a handle and get `step` / `close` |
 | `createLwsServer(...).setBaseIri(iri)` | set `baseIri` before the first request |
 | `lwsOpsAvailable(engine)` | probe the loaded module for the ops |
-| `LWS_OPS` | the three op names |
+| `LWS_OPS` | the op names |
 | `LwsHostError` | a host failure, with `unknownOp` set when the op is absent |
 
 ## Tests
 
 ```
 node tests/lws/server.mjs
+node tests/lws/draft-binding.mjs
+node tests/lws/binary-bodies.mjs
+node tests/lws/authorization.mjs
 deno run --allow-read --allow-net --allow-write --allow-env tests/lws/server.mjs
 ```

package/lws/persist.mjs

@@ -0,0 +1,78 @@
+// Durable storage for `factoidal lws-serve DIR` and `solid-serve DIR`.
+// https://github.com/danbri/factoidal/issues/659
+//
+// WHAT THIS FILE IS ALLOWED TO DO
+// Move bytes between one file and the engine. The engine decides what
+// the bytes are (`L4Factoidal/LWS/Snapshot.lean`): the snapshot document,
+// which paths it may hold (no `..`, no absolute or encoded traversal), and
+// when the storage changed (the `changed` member of the step envelope).
+// This file decides only where the one file lives and how it is written:
+//
+//   DIR/lws-state.json      the snapshot, replaced atomically
+//
+// No request target ever becomes a file name here, so a request cannot
+// address a file outside DIR. The write is: a temporary file in DIR,
+// fsync, rename over the state file, fsync of DIR. A crash leaves the old
+// snapshot or the new one, never a torn one.
+
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+export const STATE_FILE = 'lws-state.json'
+
+/** The absolute path of the state file of a storage directory. */
+export function stateFileOf (dir) {
+  return join(resolve(dir), STATE_FILE)
+}
+
+/**
+ * The parsed snapshot in DIR, or `null` when DIR holds none yet. The
+ * engine checks the document; a file that does not parse as JSON is an
+ * error of this host, reported as such.
+ */
+export function readSnapshot (dir) {
+  const file = stateFileOf(dir)
+  if (!existsSync(file)) return null
+  const text = readFileSync(file, 'utf8')
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new Error(`${file} is not JSON: ${error.message}`)
+  }
+}
+
+/** Write a snapshot document to DIR, atomically. */
+export function writeSnapshot (dir, snapshot) {
+  const root = resolve(dir)
+  mkdirSync(root, { recursive: true })
+  const file = stateFileOf(root)
+  const temporary = join(root, `.${STATE_FILE}.${process.pid}.tmp`)
+  const fd = openSync(temporary, 'w', 0o600)
+  try {
+    writeSync(fd, JSON.stringify(snapshot))
+    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.
+  }
+}
+
+/**
+ * After one step: when the engine says the storage changed, ask it for
+ * the snapshot (`snapshotOp`) and write it.
+ */
+export function persistIfChanged (engine, snapshotOp, handle, envelope, dir) {
+  if (typeof dir !== 'string' || envelope === null || typeof envelope !== 'object') return
+  if (envelope.changed !== true) return
+  const answer = engine.call(snapshotOp, [handle])
+  if (answer === null || typeof answer !== 'object' || answer.snapshot === undefined) {
+    throw new Error(`${snapshotOp} answered with no snapshot`)
+  }
+  writeSnapshot(dir, answer.snapshot)
+}

package/lws/server.mjs

@@ -21,12 +21,25 @@
 //   lwsOpen  [configJson]            -> { ok, handle, root }
 //   lwsStep  [handle, requestJson]   -> { ok, response }
 //   lwsClose [handle]                -> { ok }
+//   lwsFetched [handle, documentJson] -> { ok, fetch? | installed? | refused? }
 //
-//   request  { method, target, headers: [[name, value]], body }
-//   response { status, headers: [[name, value]], body }
+// `lwsStep` may answer `{ ok, fetch: { issuer, url } }` instead of a
+// response: the engine needs an authorization server's metadata or key
+// set before it can decide. This host fetches that URL, passes
+// `{ issuer, url, status, body, now }` to `lwsFetched`, follows any
+// further `fetch` it names, and steps the request again.
 //
-// The config members are `baseIri`, `now`, `owner` and `agent`, all
-// optional. `target` is a path within the storage, so this host passes
+//   request  { method, target, headers: [[name, value]] } + content bytes
+//   response { status, headers: [[name, value]], bodyBytes } + content bytes
+//
+// Bodies are BYTES (https://github.com/danbri/factoidal/issues/889). The
+// step goes through the engine's byte-region entry, `callBlobIO`: the
+// request content is the IN region and the response content is the OUT
+// region, with no encoding and no decoding here. This host never reads a
+// body as text.
+//
+// The config members are `baseIri`, `now`, `owner`, `agent`, `rootAcl`,
+// `auth` and `insecureNoAuth`, all optional. `target` is a path within the storage, so this host passes
 // Node's `request.url` through unchanged and never composes an absolute
 // IRI: `baseIri` tells the engine what the root maps to.
 //
@@ -48,9 +61,30 @@
 // produced and this code keeps working unchanged.
 
 import { loadEngine } from '../bin/engine.mjs'
+import { readSnapshot, persistIfChanged } from './persist.mjs'
 
 /** The ops this host needs from the engine. */
-export const LWS_OPS = ['lwsOpen', 'lwsStep', 'lwsClose']
+export const LWS_OPS = ['lwsOpen', 'lwsStep', 'lwsClose', 'lwsSnapshot', 'lwsFetched']
+
+/** The most documents one request may make this host fetch before the
+ *  engine has answered it. The engine names at most two per issuer (its
+ *  metadata, then its key set); this bound only stops a defective module
+ *  from looping the host. */
+const MAX_FETCHES = 8
+
+/**
+ * Fetch one document the engine named, for `lwsFetched`. Pure I/O: the
+ * engine decides what the bytes mean. A network failure is reported as
+ * status 0, which the engine refuses like any other failed fetch.
+ */
+async function fetchDocument (url) {
+  try {
+    const answer = await fetch(url, { redirect: 'error' })
+    return { status: answer.status, body: await answer.text() }
+  } catch (error) {
+    return { status: 0, body: String(error && error.message ? error.message : error) }
+  }
+}
 
 /** An error raised by the LWS host, as opposed to one the engine
  *  reported. `unknownOp` is set when the loaded WebAssembly module does
@@ -108,7 +142,7 @@ function handleOf (envelope) {
   return null
 }
 
-function responseOf (envelope) {
+function responseOf (envelope, bytes) {
   if (envelope === null || typeof envelope !== 'object') {
     throw new LwsHostError('lwsStep answered with no envelope')
   }
@@ -119,10 +153,18 @@ function responseOf (envelope) {
     throw new LwsHostError('lwsStep answered with no status in its response record')
   }
   const headers = Array.isArray(record.headers) ? record.headers : []
-  const body = typeof record.body === 'string' ? record.body : ''
+  const body = bytes instanceof Uint8Array ? bytes : new Uint8Array(0)
   return { status: record.status, headers, body }
 }
 
+/** The request content as bytes: a byte array is passed as it is, and a
+ *  string (a JavaScript caller's convenience) as its UTF-8 bytes. */
+function contentBytes (request) {
+  if (request.body instanceof Uint8Array) return request.body
+  if (typeof request.body === 'string') return new TextEncoder().encode(request.body)
+  return new Uint8Array(0)
+}
+
 /**
  * Open one LWS storage on the engine and return the handle plus the two
  * calls a host makes against it.
@@ -146,6 +188,20 @@ export async function openLwsStorage (options = {}) {
   if (typeof options.now === 'number') config.now = options.now
   if (typeof options.owner === 'string') config.owner = options.owner
   if (typeof options.agent === 'string') config.agent = options.agent
+  // Authorization (L4Factoidal/LWS/Authorization.lean). `auth` is passed
+  // through unread; `insecureNoAuth` is the explicit development mode.
+  // With neither, the engine enforces authorization with no trusted
+  // issuer.
+  if (options.auth !== undefined && options.auth !== null) config.auth = options.auth
+  if (options.insecureNoAuth === true) config.insecureNoAuth = true
+  if (typeof options.rootAcl === 'string') config.rootAcl = options.rootAcl
+  // `dir` names the storage directory. The snapshot found there, if any,
+  // is the storage to continue from; the engine checks it.
+  const dir = typeof options.dir === 'string' ? options.dir : null
+  if (dir !== null) {
+    const snapshot = readSnapshot(dir)
+    if (snapshot !== null) config.snapshot = snapshot
+  }
   let opened
   try {
     opened = engine.call('lwsOpen', [JSON.stringify(config)])
@@ -167,14 +223,43 @@ export async function openLwsStorage (options = {}) {
     /**
      * One protocol step.
      * @param {{method: string, target: string,
-     *          headers: Array<[string, string]>, body: string}} request
-     * @returns {{status: number, headers: Array<[string, string]>, body: string}}
+     *          headers: Array<[string, string]>, body: Uint8Array|string}} request
+     * @returns {{status: number, headers: Array<[string, string]>, body: Uint8Array}}
      */
-    step (request) {
+    async step (request) {
+      const content = contentBytes(request)
+      const { body: _body, ...fields } = request
       const record = options.realClock === true
-        ? { ...request, now: Math.floor(Date.now() / 1000) }
-        : request
-      return responseOf(engine.call('lwsStep', [handle, JSON.stringify(record)]))
+        ? { ...fields, now: Math.floor(Date.now() / 1000) }
+        : fields
+      const callStep = () => engine.callBlobIO('lwsStep', [handle, JSON.stringify(record)], content)
+      let answered = callStep()
+      let envelope = answered.envelope
+      // The engine may answer "fetch this document first" (an issuer's
+      // metadata or key set). The host fetches exactly what it is told,
+      // hands the bytes back, and steps the request again.
+      let fetches = 0
+      while (envelope !== null && typeof envelope === 'object' &&
+             envelope.fetch !== undefined && envelope.fetch !== null) {
+        let wanted = envelope.fetch
+        while (wanted !== undefined && wanted !== null) {
+          fetches += 1
+          if (fetches > MAX_FETCHES) {
+            throw new LwsHostError('the engine asked for more documents than one request may fetch')
+          }
+          const got = await fetchDocument(wanted.url)
+          const told = engine.call('lwsFetched', [handle, JSON.stringify({
+            issuer: wanted.issuer, url: wanted.url, status: got.status, body: got.body,
+            ...(typeof record.now === 'number' ? { now: record.now } : {})
+          })])
+          wanted = told !== null && typeof told === 'object' ? told.fetch : null
+        }
+        answered = callStep()
+        envelope = answered.envelope
+      }
+      const answer = responseOf(envelope, answered.bytes)
+      if (dir !== null) persistIfChanged(engine, 'lwsSnapshot', handle, envelope, dir)
+      return answer
     },
     close () {
       try { engine.call('lwsClose', [handle]) } catch (_error) { /* already gone */ }
@@ -182,13 +267,13 @@ export async function openLwsStorage (options = {}) {
   }
 }
 
-/** Read a Node request body as one UTF-8 string. */
+/** Read a Node request body as its bytes. */
 function readBody (request) {
   return new Promise((resolve, reject) => {
     const chunks = []
     request.on('data', (chunk) => chunks.push(chunk))
     request.on('error', reject)
-    request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    request.on('end', () => resolve(new Uint8Array(Buffer.concat(chunks))))
   })
 }
 
@@ -250,7 +335,7 @@ export async function createLwsServer (options = {}) {
     }
     let answer
     try {
-      answer = (await storage()).step(record)
+      answer = await (await storage()).step(record)
     } catch (error) {
       // A failure of this host or of the engine, not a protocol answer.
       // The engine's own words are kept; nothing is invented.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factoidal/core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "RDF parsing and writing (Turtle, TriG, N-Triples, N-Quads, RDF/XML, JSON-LD), SPARQL 1.1 and 1.2, RDFS and OWL reasoning, SHACL and ShEx validation, CSVW and RML mapping, RDFC-1.0, and SPARQL, LWS and Solid servers, for Node, Deno and browsers.",
   "keywords": [
     "sparql",