@factoidal/core 0.20.0 → 0.22.0

package/lib/cid-node.mjs

@@ -0,0 +1,77 @@
+// The Node and Deno host of cidRetrieveVerificationMethod (lib/cid.mjs,
+// https://github.com/danbri/factoidal/issues/1100 item 9): name resolution,
+// and a GET that connects to the one address the engine chose, so a second
+// answer of a name server cannot move the request (the authorization
+// server's fetch, authz/server.mjs). Pure I/O: the engine decides which
+// URL, which address, and what the answer means
+// (formal/lean4/L4Factoidal/CID/Fetch.lean). No redirect is followed.
+
+const FETCH_TIMEOUT_MS = 10000;
+const MAX_DOCUMENT_BYTES = 1048576;
+
+/** Every address of a name, as the system resolver gives them. */
+async function resolve(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 [];
+  }
+}
+
+// A Response-like answer: status, headers.get, text().
+function answer(status, contentType, body) {
+  return {
+    status,
+    headers: { get: (name) => (String(name).toLowerCase() === 'content-type' ? contentType : null) },
+    text: async () => body,
+  };
+}
+
+/**
+ * GET `url` from `init.address`, sending `init.headers`. With no address
+ * (the engine named none), the system resolver connects.
+ */
+async function fetch(url, init) {
+  let target;
+  try {
+    target = new URL(url);
+  } catch (_error) {
+    return answer(0, '', '');
+  }
+  const mod = target.protocol === 'https:' ? await import('node:https') : await import('node:http');
+  const address = init && typeof init.address === 'string' ? init.address : null;
+  const family = address && address.indexOf(':') >= 0 ? 6 : 4;
+  const options = { method: 'GET', headers: (init && init.headers) || {}, timeout: FETCH_TIMEOUT_MS };
+  if (address) {
+    options.lookup = (_host, opts, callback) => {
+      if (opts && opts.all) callback(null, [{ address, family }]);
+      else callback(null, address, family);
+    };
+  }
+  return new Promise((done) => {
+    const request = mod.request(target, options, (response) => {
+      const chunks = [];
+      let size = 0;
+      response.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > MAX_DOCUMENT_BYTES) {
+          response.destroy();
+          done(answer(0, '', ''));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on('end', () => done(answer(response.statusCode || 0,
+        String(response.headers['content-type'] || ''), Buffer.concat(chunks).toString('utf8'))));
+      response.on('error', () => done(answer(0, '', '')));
+    });
+    request.on('timeout', () => request.destroy(new Error('timeout')));
+    request.on('error', () => done(answer(0, '', '')));
+    request.end();
+  });
+}
+
+/** The host index.mjs passes to the API. */
+export const nodeCidHost = Object.freeze({ resolve, fetch });

package/lib/cid.mjs

@@ -0,0 +1,146 @@
+// Controlled Identifiers v1.0 (https://www.w3.org/TR/cid-1.0/):
+// cidValidate and cidRetrieveVerificationMethod
+// (https://github.com/danbri/factoidal/issues/1100, items 7 and 9).
+//
+// The engine decides everything (formal/lean4/L4Factoidal/CID/Validate.lean,
+// CID/Fetch.lean, over the ops cidValidate and cidRetrieve of
+// formal/lean4/Wasm/Ops/Cid.lean): the §2 checks; which URL to fetch; whether
+// its scheme and addresses may be fetched (the private-address guard of the
+// authorization server); whether the status and the Content-Type of the
+// answer are accepted; §3.3; expiry and revocation with `now`. This file
+// moves bytes: it resolves the host name the engine names, GETs the URL the
+// engine names from the address the engine names, and passes the status,
+// the Content-Type and the body back.
+//
+// ES module, no Node built-ins: the browser loads this file as it is. The
+// Node and Deno host functions (name resolution, a GET pinned to one
+// address) are lib/cid-node.mjs, which index.mjs passes in.
+
+import { FactoidalError } from './errors.mjs';
+
+// The engine names at most one resolution and one fetch; a longer loop is
+// a defect, not a document.
+const MAX_STEPS = 4;
+
+/**
+ * The browser host: no name resolution (a page cannot resolve names; the
+ * engine then checks only IP literals and localhost names), and the page's
+ * fetch, which does not follow redirects and sends no credentials.
+ */
+export const browserCidHost = Object.freeze({
+  resolve: null,
+  fetch: (url, init) => globalThis.fetch(url, {
+    method: 'GET',
+    headers: init.headers,
+    redirect: 'manual',
+    credentials: 'omit',
+  }),
+});
+
+// The status, Content-Type and body of a fetch answer: a WHATWG Response,
+// or an object of the same shape.
+async function answerOf(url, response) {
+  const status = Number(response && response.status) || 0;
+  const headers = response && response.headers;
+  const contentType = headers && typeof headers.get === 'function'
+    ? (headers.get('content-type') || '') : '';
+  const body = response && typeof response.text === 'function' ? String(await response.text()) : '';
+  return { url, status, contentType, body };
+}
+
+function nowSeconds(now) {
+  if (now === undefined || now === null) return undefined;
+  if (now instanceof Date) return Math.floor(now.getTime() / 1000);
+  if (typeof now === 'number' && Number.isFinite(now)) return Math.floor(now);
+  throw new TypeError('cidRetrieveVerificationMethod: options.now must be a Date or a number of seconds');
+}
+
+/**
+ * The two functions over an entry (lib/lean-entry.mjs) and a host.
+ * @param {object} deps
+ * @param {() => Promise<object>} deps.entry
+ * @param {(jsonText: string, what: string) => object} deps.entryResult
+ * @param {(e: object, fn: string, what: string) => void} deps.requireEntryFn
+ * @param {{resolve: ((host: string) => Promise<string[]>)|null, fetch: Function}} [deps.host]
+ */
+export function cidFunctions({ entry, entryResult, requireEntryFn, host }) {
+  const defaults = host || browserCidHost;
+
+  /**
+   * CID 1.0 §2: check a controlled identifier document.
+   * @param {string|object} doc JSON text, or a value JSON.stringify writes
+   * @returns {Promise<{valid: boolean, errors: Array<{code: string, message: string, path: string}>}>}
+   */
+  async function cidValidate(doc) {
+    const text = typeof doc === 'string' ? doc : JSON.stringify(doc);
+    if (typeof text !== 'string') throw new TypeError('cidValidate: doc must be JSON text or a JSON value');
+    const e = await entry();
+    requireEntryFn(e, 'cidValidate', 'CID 1.0 document check');
+    const r = entryResult(e.cidValidate(text), 'cidValidate');
+    return { valid: r.valid === true, errors: Array.isArray(r.errors) ? r.errors : [] };
+  }
+
+  /**
+   * CID 1.0 §3.3 Retrieve Verification Method, with the fetch done here.
+   * @param {string} url the verification method URL
+   * @param {string} relationship a verification relationship of §2.3
+   * @param {object} [options]
+   * @returns {Promise<{ok: true, verificationMethod: object, controllerDocument: string}
+   *                  | {ok: false, code: string, problem: {type: string, title: string, detail: string}}>}
+   */
+  async function cidRetrieveVerificationMethod(url, relationship, options) {
+    if (typeof url !== 'string' || typeof relationship !== 'string') {
+      throw new TypeError('cidRetrieveVerificationMethod: url and relationship must be strings');
+    }
+    const o = options || {};
+    const fetchFn = typeof o.fetch === 'function' ? o.fetch : defaults.fetch;
+    // `resolve: null` says the caller cannot resolve names.
+    const resolveFn = 'resolve' in o ? o.resolve : defaults.resolve;
+    const request = {
+      vm: url,
+      relationship,
+      allowHttp: o.allowHttp === true,
+      allowPrivateFetch: o.allowPrivateFetch === true,
+      resolver: typeof resolveFn === 'function',
+      resolved: [],
+      fetched: [],
+    };
+    const now = nowSeconds(o.now);
+    if (now !== undefined) request.now = now;
+    const e = await entry();
+    requireEntryFn(e, 'cidRetrieve', 'CID 1.0 Retrieve Verification Method');
+    for (let i = 0; i < MAX_STEPS; i += 1) {
+      const r = entryResult(e.cidRetrieve(JSON.stringify(request)), 'cidRetrieve');
+      if (r.step === 'method') {
+        return { ok: true, verificationMethod: r.verificationMethod, controllerDocument: r.controllerDocument };
+      }
+      if (r.step === 'error') return { ok: false, code: r.code, problem: r.problem };
+      if (r.step === 'resolve') {
+        let addresses = [];
+        try {
+          const got = await resolveFn(r.host);
+          addresses = Array.isArray(got) ? got.map(String) : [];
+        } catch (_error) {
+          addresses = [];
+        }
+        request.resolved.push({ host: r.host, addresses });
+      } else if (r.step === 'fetch') {
+        let answer;
+        try {
+          const init = { method: 'GET', headers: { accept: r.accept }, redirect: 'manual' };
+          if (r.address !== null && r.address !== undefined) init.address = r.address;
+          answer = await answerOf(r.url, await fetchFn(r.url, init));
+        } catch (_error) {
+          answer = { url: r.url, status: 0, contentType: '', body: '' };
+        }
+        request.fetched.push(answer);
+      } else {
+        break;
+      }
+    }
+    throw new FactoidalError('cidRetrieveVerificationMethod: the engine asked for more steps than one retrieval needs',
+      { code: 'op.failed' });
+  }
+
+  return { cidValidate, cidRetrieveVerificationMethod };
+}

package/lib/cipher-host.mjs

@@ -0,0 +1,126 @@
+// cipher-host.mjs — the JavaScript host side of the AES call-out
+// (https://github.com/danbri/factoidal/issues/1081,
+// https://github.com/danbri/factoidal/issues/677; design record
+// docs/designissues/2026-10-27-xml-encryption-and-jwe.md, section "The AES
+// call-out on JavaScript hosts"; request format
+// formal/lean4/L4Factoidal/Crypto/CipherCall.lean).
+//
+// The engine (Lean, in the wasm) makes every decision: the algorithm, the key,
+// the IV, the lengths (`Req.wellFormed`), the document structure. When it needs
+// AES it answers `{need: {op, key, iv, aad, data}}` (bytes as base64). This
+// module runs exactly that one WebCrypto operation and gives back
+// `{ok: base64}` or `{refused: true}`. It reads no document, chooses no
+// algorithm and checks no length. Every failure becomes the same refusal with
+// no message, so no error text of the host's crypto library reaches the caller
+// (padding oracle, Jager and Somorovsky 2011).
+//
+// Only `globalThis.crypto.subtle` is used, so the same code runs in Node 22,
+// Deno and browsers (Node: OpenSSL; Chromium: BoringSSL; Firefox: NSS).
+//
+// PBKDF2 (https://github.com/danbri/factoidal/issues/1108, the login of
+// `factoidal webdav-serve` and `factoidal webdav-user`; owner, 2026-10-28:
+// PBKDF2-HMAC-SHA256 from WebCrypto, as AES): the engine answers
+// `{need: {op: 'pbkdf2-hmac-sha256', key, data, iterations, bits}}` with the
+// password as `key` and the salt as `data`. This module runs exactly that
+// `deriveBits` call; Lean chose the salt, the count and the output size
+// (formal/lean4/L4Factoidal/WebDAV/Login.lean) and compares the result.
+//
+// Key Wrap: WebCrypto wraps a CryptoKey, not bytes. The bytes to wrap are
+// imported as an extractable raw HMAC key (any byte length), wrapped with
+// `wrapKey('raw', ...)`; an unwrap gives an HMAC key whose raw export is the
+// unwrapped bytes.
+
+const subtle = () => globalThis.crypto.subtle;
+
+/** The most requests one engine operation may make (CipherCall.maxRequests). */
+export const MAX_CIPHER_REQUESTS = 64;
+
+function fromBase64(s) {
+  const bin = atob(s ?? '');
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function toBase64(buf) {
+  const b = new Uint8Array(buf);
+  let bin = '';
+  for (let i = 0; i < b.length; i += 0x8000) {
+    bin += String.fromCharCode.apply(null, b.subarray(i, i + 0x8000));
+  }
+  return btoa(bin);
+}
+
+const HMAC = { name: 'HMAC', hash: 'SHA-256' };
+
+// One entry per op name of CipherCall.Op.name: the WebCrypto call, nothing more.
+const OPS = {
+  'aes-gcm-encrypt': async (k, iv, aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-GCM', false, ['encrypt']);
+    return subtle().encrypt({ name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, key, d);
+  },
+  'aes-gcm-decrypt': async (k, iv, aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-GCM', false, ['decrypt']);
+    return subtle().decrypt({ name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, key, d);
+  },
+  'aes-kw-wrap': async (k, _iv, _aad, d) => {
+    const kek = await subtle().importKey('raw', k, 'AES-KW', false, ['wrapKey']);
+    const inner = await subtle().importKey('raw', d, HMAC, true, ['sign']);
+    return subtle().wrapKey('raw', inner, kek, 'AES-KW');
+  },
+  'aes-kw-unwrap': async (k, _iv, _aad, d) => {
+    const kek = await subtle().importKey('raw', k, 'AES-KW', false, ['unwrapKey']);
+    const inner = await subtle().unwrapKey('raw', d, kek, 'AES-KW', HMAC, true, ['sign']);
+    return subtle().exportKey('raw', inner);
+  },
+  'aes-cbc-encrypt': async (k, iv, _aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-CBC', false, ['encrypt']);
+    return subtle().encrypt({ name: 'AES-CBC', iv }, key, d);
+  },
+  'aes-cbc-decrypt': async (k, iv, _aad, d) => {
+    const key = await subtle().importKey('raw', k, 'AES-CBC', false, ['decrypt']);
+    return subtle().decrypt({ name: 'AES-CBC', iv }, key, d);
+  },
+  'pbkdf2-hmac-sha256': async (k, _iv, _aad, d, req) => {
+    const key = await subtle().importKey('raw', k, 'PBKDF2', false, ['deriveBits']);
+    return subtle().deriveBits({ name: 'PBKDF2', hash: 'SHA-256', salt: d, iterations: req.iterations }, key, req.bits);
+  },
+};
+
+/**
+ * Answer one cipher request of the engine (AES, or the PBKDF2 of a login).
+ * @param {{op: string, key: string, iv?: string, aad?: string, data: string, iterations?: number, bits?: number}} req  bytes as base64
+ * @returns {Promise<{ok: string} | {refused: true}>}
+ */
+export async function answerCipherRequest(req) {
+  try {
+    const run = Object.prototype.hasOwnProperty.call(OPS, req?.op) ? OPS[req.op] : null;
+    if (!run) return { refused: true };
+    const out = await run(fromBase64(req.key), fromBase64(req.iv), fromBase64(req.aad), fromBase64(req.data), req);
+    return { ok: toBase64(out) };
+  } catch {
+    return { refused: true };
+  }
+}
+
+/**
+ * Run an engine operation that may ask for AES. `callOp(args)` calls the wasm
+ * op (sync or async) with `args` plus `answers`; while its result has `need`,
+ * the request is answered and the op is called again with the same inputs and
+ * the answer list extended by `{request, answer}`. The engine's format code is
+ * deterministic, so each call gets one request further.
+ * @param {(args: object) => any} callOp
+ * @param {object} args
+ */
+export async function runWithCipher(callOp, args) {
+  const answers = [];
+  for (let asked = 0; ; asked++) {
+    const res = await callOp({ ...args, answers: answers.slice() });
+    if (!res || res.need === undefined) return res;
+    // The request bound is the one check the host makes (design record step 4).
+    if (asked === MAX_CIPHER_REQUESTS) {
+      throw new Error(`runWithCipher: more than ${MAX_CIPHER_REQUESTS} cipher requests`);
+    }
+    answers.push({ request: res.need, answer: await answerCipherRequest(res.need) });
+  }
+}

package/lib/engine-integrity.mjs

@@ -0,0 +1,56 @@
+// The load-time check of the engine against its release stamp
+// (https://github.com/danbri/factoidal/issues/1106, layer 1).
+//
+// A release stamps l4-assets/version.json with the SHA-256 and the size of
+// l4factoidal.wasm (tools/stamp-l4-version.mjs). Before an engine is
+// instantiated, its bytes are hashed and compared with the stamp: a stamped
+// copy whose bytes differ does not load. An unstamped copy (a source
+// checkout, a local build that did not stamp) loads as before.
+//
+// This catches accidents (a stale wasm next to a new loader, a partial
+// upgrade, a hand edit). It is not a defence against someone who can edit
+// the package: they can edit this file too. See issue 1106 for the checks
+// made from outside the package.
+//
+// ES module, no Node built-ins: Node, Deno and the browser load it as it is.
+// The digest is Web Crypto's SHA-256 (globalThis.crypto.subtle).
+
+/** Lowercase hex SHA-256 of `bytes` (a Uint8Array or an ArrayBuffer). */
+export async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto && globalThis.crypto.subtle;
+  if (!subtle) throw new Error('factoidal: no Web Crypto SHA-256 to check the engine with');
+  const digest = new Uint8Array(await subtle.digest('SHA-256', bytes));
+  let hex = '';
+  for (const b of digest) hex += b.toString(16).padStart(2, '0');
+  return hex;
+}
+
+/**
+ * Check engine bytes against a version.json stamp.
+ * @param {Uint8Array|ArrayBuffer} bytes the wasm
+ * @param {object|null} stamp the parsed version.json, or null when absent
+ * @param {{where?: string, allowModified?: boolean, warn?: (msg: string) => void}} [opts]
+ * @returns {Promise<{checked: boolean, sha256?: string}>} `checked` false for
+ *   an absent or unstamped version.json
+ */
+export async function checkEngineStamp(bytes, stamp, opts = {}) {
+  if (!stamp || stamp.stamped !== true || typeof stamp.wasmSha256 !== 'string') {
+    return { checked: false };
+  }
+  const size = bytes.byteLength;
+  const sha256 = await sha256Hex(bytes);
+  const sizeOk = !Number.isInteger(stamp.wasmBytes) || stamp.wasmBytes === size;
+  if (sha256 === stamp.wasmSha256.toLowerCase() && sizeOk) return { checked: true, sha256 };
+  const where = opts.where || 'l4factoidal.wasm';
+  const msg = `factoidal: ${where} is not the engine of this release: version.json ` +
+    `(build ${stamp.release ?? stamp.gitSha ?? '?'}) says sha256 ${stamp.wasmSha256}, ${stamp.wasmBytes ?? '?'} bytes; ` +
+    `the file has sha256 ${sha256}, ${size} bytes. Reinstall @factoidal/core, ` +
+    'or set FACTOIDAL_ALLOW_MODIFIED_ENGINE=1 to load a changed engine on purpose.';
+  if (opts.allowModified) {
+    (opts.warn || (() => {}))(`${msg} Loading it because FACTOIDAL_ALLOW_MODIFIED_ENGINE is set.`);
+    return { checked: false, sha256 };
+  }
+  const err = new Error(msg);
+  err.code = 'engine.modified';
+  throw err;
+}

package/lib/errors.mjs

@@ -24,6 +24,10 @@
  * - `cause`: the underlying error, when there is one.
  * - `format`, `formatInferred`: for a parse failure of text, the syntax it
  *   was read as and whether that syntax was inferred.
+ * - `qtError`: for xpath4Eval, xqueryEval and xslt4Transform, the error the
+ *   XPath, XQuery or XSLT 4.0 specification names: `{code, namespace,
+ *   message}` (for example code `XPST0003` in
+ *   http://www.w3.org/2005/xqt-errors).
  */
 export class FactoidalError extends Error {
   constructor(message, info) {
@@ -35,6 +39,7 @@ export class FactoidalError extends Error {
     this.spec = i.spec || null;
     if (i.format !== undefined) this.format = i.format;
     if (i.formatInferred !== undefined) this.formatInferred = i.formatInferred;
+    if (i.qtError !== undefined) this.qtError = i.qtError;
     if (typeof Error.captureStackTrace === 'function') {
       Error.captureStackTrace(this, FactoidalError);
     }
@@ -81,6 +86,7 @@ export function errorFromEnvelope(env, text) {
     spec: env && env.spec,
     position,
     format: env && env.format,
+    qtError: env && env.qtError && typeof env.qtError === 'object' ? env.qtError : undefined,
   });
 }