@factoidal/core 0.20.0 → 0.21.0

package/lib/api.mjs

@@ -30,6 +30,8 @@ import { fullEngineMessage, encodeJsValue } from './lean-entry.mjs';
 import { memoryDeltaLogStore } from './delta-log-hosts.mjs';
 import { FactoidalError, errorFromEnvelope, envelopeResult } from './errors.mjs';
 import { buildNodes } from './nodes.mjs';
+import { runWithCipher } from './cipher-host.mjs';
+import { cidFunctions } from './cid.mjs';
 
 // The format names, regimes and query outputs are the engine's tables (op
 // engineTables, formal/lean4/Wasm/Ops/Handles.lean), read once per engine:
@@ -265,6 +267,10 @@ class Store {
  *        Where the deltaLog* functions keep their records
  *        (lib/delta-log-hosts.mjs): IndexedDB in the browser entries. The
  *        default keeps them in the memory of this process.
+ * @param {object} [driver.cidHost]
+ *        Name resolution and the GET of cidRetrieveVerificationMethod
+ *        (lib/cid-node.mjs under Node and Deno). The default is the browser
+ *        host of lib/cid.mjs: the page's fetch, no name resolution.
  */
 function buildApi(driver) {
   let entryPromise; // memoized; a failed load is retried on the next call
@@ -655,6 +661,17 @@ function buildApi(driver) {
     const entail = opts.entail || 'none';
     const sparql12 = opts.sparql12 === true || String(opts.version || '') === '1.2';
     const e = c.e;
+    if (sparql12 && entail !== 'none' && opts.output === undefined) {
+      // SPARQL 1.2 under an entailment regime: the engine closes the stored
+      // dataset and runs the SPARQL 1.2 evaluator (op datasetQuery12Entail,
+      // https://github.com/danbri/factoidal/issues/1109).
+      requireEntryFn(e, 'datasetQuery12Entail', 'query {sparql12, entail}');
+      const r = await withExtensionRounds(() => entryResult(
+        e.datasetQuery12Entail(ds.handle, sparql, entail), 'query', sparql));
+      if (r.kind === 'ask') return r.boolean;
+      if (r.kind === 'construct' || r.kind === 'describe') return c.fromNQuads(r.nquads, ds.prefixes);
+      return bindingsFromSrj(r.srj);
+    }
     if (entail !== 'none' || opts.output !== undefined) {
       // queryRaw over the stored dataset: an entailment regime, or a
       // results format (SPARQL 1.1 Query Results JSON, XML, CSV, TSV).
@@ -664,15 +681,18 @@ function buildApi(driver) {
       requireEntryFn(e, 'datasetQueryRaw', `query {entail/output}`);
       if (opts.output === undefined) {
         // An entailment regime with the default answer shape.
-        const r = entryResult(e.datasetQueryRaw(ds.handle, sparql, JSON.stringify({
-          entail, output: graphForm ? 'ntriples' : 'json' })), 'query', sparql);
+        // withExtensionRounds: a registered async extension function
+        // (SPARQL 1.1 §17.6) is resolved here as in datasetQuery
+        // (https://github.com/danbri/factoidal/issues/1090).
+        const r = await withExtensionRounds(() => entryResult(e.datasetQueryRaw(ds.handle, sparql,
+          JSON.stringify({ entail, output: graphForm ? 'ntriples' : 'json' })), 'query', sparql));
         if (graphForm) return c.fromNQuads(r.text, ds.prefixes);
         const srj = JSON.parse(r.text);
         if (typeof srj.boolean === 'boolean') return srj.boolean;
         return bindingsFromSrj(srj);
       }
-      const r = entryResult(e.datasetQueryRaw(ds.handle, sparql,
-        JSON.stringify({ entail, output })), 'query', sparql);
+      const r = await withExtensionRounds(() => entryResult(e.datasetQueryRaw(ds.handle, sparql,
+        JSON.stringify({ entail, output })), 'query', sparql));
       return output === 'json' && !graphForm ? JSON.parse(r.text) : r.text;
     }
     const fn = sparql12 ? e.datasetQuery12 : e.datasetQuery;
@@ -910,17 +930,28 @@ function buildApi(driver) {
    * name first, so datasets that differ only in their graph names got the
    * same hash. To hash a graph whatever its name, use
    * canonicalHash(asDefaultGraph(g)).
-   * @param {Dataset} dataset
+   *
+   * The input is what canonicalize() takes: a Dataset, or text (a string,
+   * or {text, format, baseIRI}), with the options {format, baseIRI}. Text is
+   * a JavaScript string: characters, not bytes. Decode bytes first (the RDF
+   * text syntaxes are UTF-8: `new TextDecoder('utf-8', { fatal: true })`);
+   * a Uint8Array is refused.
+   * @param {Dataset|string|{text: string, format?: string, baseIRI?: string}} data
+   * @param {{format?: string, baseIRI?: string}} [options]
    * @returns {Promise<string>}
    */
-  async function canonicalHash(dataset) {
-    if (!(dataset instanceof Dataset)) {
-      throw new TypeError('canonicalHash: expected a Dataset');
+  async function canonicalHash(data, options) {
+    const hashOf = (e, ds) => {
+      requireEntryFn(e, 'datasetCanonicalHash', 'canonicalHash');
+      return entryResult(e.datasetCanonicalHash(ds.handle), 'canonicalHash').hash;
+    };
+    if (data instanceof Dataset && options === undefined) {
+      data.size; // throws the disposed error
+      return hashOf(data._ctx.e, data);
     }
-    dataset.size; // throws the disposed error
-    const c = dataset._ctx;
-    requireEntryFn(c.e, 'datasetCanonicalHash', 'canonicalHash');
-    return entryResult(c.e.datasetCanonicalHash(dataset.handle), 'canonicalHash').hash;
+    // The options are canonicalize()'s, checked by the engine's table for it.
+    const opts = await checkedOptions('canonicalize', optionsOf('canonicalize', options));
+    return withDataset(data, opts, 'canonicalHash', (c, ds) => hashOf(c.e, ds));
   }
 
   /**
@@ -960,6 +991,30 @@ function buildApi(driver) {
       }));
   }
 
+  /**
+   * The RDF merge of two datasets (RDF 1.1 Semantics section 5.2): a new
+   * Dataset that holds the quads of both, with the blank nodes of each input
+   * kept apart, so `_:b` in `a` and `_:b` in `b` are two blank nodes. The
+   * engine computes it (op datasetMerge, formal/lean4/Wasm/Ops/GraphNodes.lean,
+   * theorem mergeDatasets_isMerge); the prefixes are those of `a`, then those
+   * of `b` whose label `a` does not declare. A text argument is read as by
+   * parse() (`options.format`, `options.baseIRI`), in its own blank-node
+   * scope. Since 0.21.0 (https://github.com/danbri/factoidal/issues/1130).
+   * @param {Dataset|string|Array} a
+   * @param {Dataset|string|Array} b
+   * @param {{format?: string, baseIRI?: string}} [options] read text arguments
+   * @returns {Promise<Dataset>}
+   */
+  async function datasetMerge(a, b, options) {
+    // An engine built before the op refuses with op.unknown before the
+    // options are read (its option table has no row for this function).
+    requireEntryFn((await ctx()).e, 'datasetMerge', 'datasetMerge');
+    const opts = await checkedOptions('datasetMerge', optionsOf('datasetMerge', options));
+    return withDataset(a, opts, 'datasetMerge', (c, da) =>
+      withDataset(b, opts, 'datasetMerge', (_c, db) =>
+        c.wrap(entryResult(c.e.datasetMerge(da.handle, db.handle), 'datasetMerge'))));
+  }
+
   /**
    * A Dataset holding RDF/JS quads (op datasetFromQuadsJson). Each term is
    * sent as its components; the engine reads no text.
@@ -1120,6 +1175,28 @@ function buildApi(driver) {
     return withDataset(data, opts, 'closure', (c, ds) => closureOnHandle(c, ds, regime));
   }
 
+  /**
+   * SPARQL 1.2 RL (SPARQL-RL) infer: apply a rule set to the default graph
+   * of `data` and answer the inference graph (the triples the rules derive,
+   * the rule set's DATA blocks included, that are not in `data`) as a new
+   * Dataset. The rule set is SPARQL-RL text (https://w3c.github.io/data-shapes/sparql12-rl/).
+   * A rule set that is not well-formed, not stratifiable, or has IMPORTS is
+   * refused. Engine op: datasetSparqlRlInfer.
+   * @param {Dataset|string|Array} data
+   * @param {string} rules
+   * @param {{format?: string, baseIRI?: string}} [options]
+   * @returns {Promise<Dataset>}
+   */
+  async function sparqlRlInfer(data, rules, options) {
+    const opts = await checkedOptions('sparqlRlInfer', optionsOf('sparqlRlInfer', options));
+    if (typeof rules !== 'string') throw new TypeError('sparqlRlInfer: rules must be a string');
+    return withDataset(data, opts, 'sparqlRlInfer(data)', (c, ds) => {
+      requireEntryFn(c.e, 'datasetSparqlRlInfer', 'sparqlRlInfer');
+      const r = entryResult(c.e.datasetSparqlRlInfer(ds.handle, rules), 'sparqlRlInfer');
+      return c.wrap(r, ds.prefixes);
+    });
+  }
+
   /**
    * RDFS or OWL 2 RL closure of the default graph, as a new Dataset.
    * @param {Dataset|string|Array} data
@@ -1652,6 +1729,136 @@ function buildApi(driver) {
       e.vcEd25519Verify(publicKeyHex, messageHex, signatureHex), 'vcEd25519Verify').valid;
   }
 
+  // -----------------------------------------------------------------
+  // XML Encryption 1.1 and JWE (https://github.com/danbri/factoidal/issues/1084,
+  // https://github.com/danbri/factoidal/issues/1085). Every decision is in
+  // Lean (formal/lean4/Wasm/Ops/XmlEnc.lean, Wasm/Ops/Jwe.lean); RSA, P-256
+  // and X25519 run in the wasm (HACL*). AES runs in this host's WebCrypto:
+  // runWithCipher (lib/cipher-host.mjs) answers each request the engine
+  // makes and calls the op again. This code converts bytes to base64 and
+  // draws random bytes; it reads no document and chooses nothing.
+  // -----------------------------------------------------------------
+
+  // The most random octets any of these ops reads (Jwe.randomBytesNeeded is
+  // at most 112; xmlEncrypt reads at most 76).
+  const CIPHER_RANDOM_BYTES = 112;
+
+  function bytesToBase64(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+      bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(bin);
+  }
+
+  function base64ToBytes(text) {
+    const bin = atob(text);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+
+  function randomBase64(n) {
+    const b = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(b);
+    return bytesToBase64(b);
+  }
+
+  // One op that may ask for AES: the engine's envelope after every request
+  // is answered; a refusal throws a FactoidalError.
+  async function cipherOp(fnName, what, args) {
+    const e = await entry();
+    requireEntryFn(e, fnName, what);
+    const res = await runWithCipher((a) => JSON.parse(e[fnName](JSON.stringify(a))), args);
+    return entryResult(JSON.stringify(res), fnName);
+  }
+
+  function checkKeys(fnName, keys) {
+    if (!Array.isArray(keys) || !keys.every((k) => k !== null && typeof k === 'object')) {
+      throw new TypeError(`${fnName}: keys must be an array of JWK objects`);
+    }
+  }
+
+  /**
+   * Decrypt every xenc:EncryptedData of an XML document (XML Encryption 1.1).
+   * Allowlist and key forms: API.md "XML Encryption and JWE".
+   * @param {string} document the XML document
+   * @param {{keys: object[], allowCbc?: boolean}} options private JWKs
+   *   (`kid` is the ds:KeyName); `allowCbc` admits aes128-cbc and aes256-cbc
+   * @returns {Promise<{document: string, canonical: string}>}
+   */
+  async function xmlDecrypt(document, options) {
+    if (typeof document !== 'string') throw new TypeError('xmlDecrypt: document must be a string');
+    const o = options || {};
+    checkKeys('xmlDecrypt', o.keys);
+    const r = await cipherOp('xmlDecrypt', 'XML decryption',
+      { document, keys: o.keys, allowCbc: o.allowCbc === true });
+    return { document: r.document, canonical: r.canonical };
+  }
+
+  /**
+   * Encrypt the document element (or, with `content`, its content) of an XML
+   * document for one recipient (XML Encryption 1.1, AES-GCM content).
+   * @param {string} document the XML document
+   * @param {{recipient: object, algorithm?: 'aes128-gcm'|'aes256-gcm',
+   *   keyTransport?: 'rsa-oaep-mgf1p'|'rsa-oaep-sha256', keyWrap?: 'kw-aes128'|'kw-aes256',
+   *   content?: boolean, saml?: boolean}} options `recipient` is a public JWK
+   *   (RSA, EC P-256, OKP X25519) or an `oct` key; `saml` wraps the result in
+   *   saml:EncryptedAssertion
+   * @returns {Promise<{document: string, canonical: string}>}
+   */
+  async function xmlEncrypt(document, options) {
+    if (typeof document !== 'string') throw new TypeError('xmlEncrypt: document must be a string');
+    const o = options || {};
+    if (o.recipient === null || typeof o.recipient !== 'object') {
+      throw new TypeError('xmlEncrypt: options.recipient must be a JWK object');
+    }
+    const args = { document, recipient: o.recipient, random: randomBase64(CIPHER_RANDOM_BYTES) };
+    for (const k of ['algorithm', 'keyTransport', 'keyWrap']) if (o[k] !== undefined) args[k] = o[k];
+    if (o.content === true) args.content = true;
+    if (o.saml === true) args.saml = true;
+    const r = await cipherOp('xmlEncrypt', 'XML encryption', args);
+    return { document: r.document, canonical: r.canonical };
+  }
+
+  /**
+   * Decrypt a JWE in the Compact Serialization (RFC 7516).
+   * @param {string} token the compact JWE
+   * @param {{jwk: object}} options the recipient's private JWK
+   * @returns {Promise<{header: object, plaintext: Uint8Array}>}
+   */
+  async function jweDecrypt(token, options) {
+    if (typeof token !== 'string') throw new TypeError('jweDecrypt: token must be a string');
+    const o = options || {};
+    if (o.jwk === null || typeof o.jwk !== 'object') throw new TypeError('jweDecrypt: options.jwk must be a JWK object');
+    const r = await cipherOp('jweDecrypt', 'JWE decryption', { token, jwk: o.jwk });
+    return { header: r.header, plaintext: base64ToBytes(r.plaintext) };
+  }
+
+  /**
+   * Encrypt to a JWE in the Compact Serialization (RFC 7516).
+   * @param {Uint8Array|string} plaintext bytes, or text written as UTF-8
+   * @param {{alg: string, enc: string, jwk: object, header?: object}} options
+   *   the recipient's public JWK (or the `oct` key for A128KW, A256KW, dir);
+   *   `header`: more protected header members
+   * @returns {Promise<string>} the compact JWE
+   */
+  async function jweEncrypt(plaintext, options) {
+    let bytes;
+    if (typeof plaintext === 'string') bytes = new TextEncoder().encode(plaintext);
+    else if (plaintext instanceof Uint8Array) bytes = plaintext;
+    else throw new TypeError('jweEncrypt: plaintext must be a Uint8Array or a string');
+    const o = options || {};
+    if (typeof o.alg !== 'string' || typeof o.enc !== 'string') {
+      throw new TypeError('jweEncrypt: options.alg and options.enc must be strings');
+    }
+    if (o.jwk === null || typeof o.jwk !== 'object') throw new TypeError('jweEncrypt: options.jwk must be a JWK object');
+    const args = { alg: o.alg, enc: o.enc, jwk: o.jwk, plaintext: bytesToBase64(bytes),
+      random: randomBase64(CIPHER_RANDOM_BYTES) };
+    if (o.header !== undefined) args.header = o.header;
+    return (await cipherOp('jweEncrypt', 'JWE encryption', args)).token;
+  }
+
   /**
    * Create an eddsa-rdfc-2022 Data Integrity proofValue over an
    * already-canonicalized document + proof config (entry_jsoo.ml's
@@ -2282,11 +2489,14 @@ function buildApi(driver) {
       // ops it actually has.
       shacl: has('shaclValidate'),
       shex: has('shexValidate'),
+      sparqlRl: has('datasetSparqlRlInfer'),
       owlClosure: has('owlClosure'),
       explain: has('explainGraph'),
       stages: has('stageList'),
       pipelineCheck: has('pipelineCheck'),
       pipelineCheckNodes: has('pipelineCheckNodes'),
+      graphCheck: has('graphCheckNodes'),
+      datasetMerge: has('datasetMerge'),
       entailment: has('queryRaw'),
       tableau: has('tableauMaterialise') && has('tableauDlInconsistent'),
       rml: has('rmlMap'),
@@ -2318,6 +2528,7 @@ function buildApi(driver) {
       store: has('storeOpen') && has('storeHandleQuery'),
       deltaLog: has('deltaLogEncode') && has('deltaLogDecode') && has('deltaLogMerge'),
       literalValues: has('literalValue') && has('literalFromValue'),
+      cid: has('cidValidate') && has('cidRetrieve'),
     };
   }
 
@@ -2421,8 +2632,12 @@ function buildApi(driver) {
   const nodeApi = buildNodes({
     entry, entryResult, requireEntryFn, Dataset,
     parse, closure, shaclValidate, query, serialize, canonicalize, canonicalHash, explain, csvwToRdf,
+    datasetMerge,
   });
 
+  // Controlled Identifiers v1.0 (lib/cid.mjs, issue 1100 items 7 and 9).
+  const cid = cidFunctions({ entry, entryResult, requireEntryFn, host: driver.cidHost });
+
   return {
     parse,
     query,
@@ -2443,6 +2658,7 @@ function buildApi(driver) {
     asDefaultGraph,
     shaclValidate,
     shexValidate,
+    sparqlRlInfer,
     owlClosure,
     coreRdfsClosure,
     coreRdfsCheck,
@@ -2450,6 +2666,7 @@ function buildApi(driver) {
     stages: nodeApi.stages,
     node: nodeApi.node,
     pipe: nodeApi.pipe,
+    graph: nodeApi.graph,
     run: nodeApi.run,
     rdfsPlusClosure,
     rhoDfClosure,
@@ -2484,12 +2701,18 @@ function buildApi(driver) {
     vcEd25519SecretToPublic,
     vcEd25519Sign,
     vcEd25519Verify,
+    xmlDecrypt,
+    xmlEncrypt,
+    jweDecrypt,
+    jweEncrypt,
     vcEddsaCreateFromCanonical,
     vcEddsaVerifyFromCanonical,
     vcCheckCredential,
     vcCheckCredentialSubject,
     vcCheckNoDataLoss,
     vcCheckRelatedResourceDigests,
+    cidValidate: cid.cidValidate,
+    cidRetrieveVerificationMethod: cid.cidRetrieveVerificationMethod,
     capabilities,
     openStore,
     queryStore,
@@ -2503,6 +2726,7 @@ function buildApi(driver) {
     _deltaLogCorruptLastForTest,
     queryRaw,
     isomorphic,
+    datasetMerge,
     fromQuads,
     literalValue,
     isValidLiteral,

package/lib/browser-engine.mjs

@@ -13,6 +13,18 @@
 //
 // No Node built-ins: the browser imports this file as it is.
 
+import { checkEngineStamp } from './engine-integrity.mjs';
+
+// version.json next to the engine, or null (absent, unreadable, not JSON).
+async function stampOf(url) {
+  try {
+    const r = await fetch(url);
+    return r.ok ? await r.json() : null;
+  } catch {
+    return null;
+  }
+}
+
 async function instantiate(url, imports) {
   try {
     return await WebAssembly.instantiateStreaming(fetch(url), imports);
@@ -59,7 +71,22 @@ export function browserEngine(name, defaultAssetsUrl) {
       // newer loader (the loader's own locateFile does the same).
       const version = loader.wasmVersion ? `?v=${loader.wasmVersion}` : '';
       const wasmUrl = new URL(`${name}.wasm`, assetsUrl).href + version;
-      return loader.loadL4({ instantiateWasm: (imports) => instantiate(wasmUrl, imports) });
+      // The release stamp check (engine-integrity.mjs, issue 1106): with a
+      // stamped version.json next to the full engine, its bytes are hashed
+      // before they are compiled (no streaming compile then). Without one,
+      // the streaming path as before.
+      const stamp = name === 'l4factoidal'
+        ? await stampOf(new URL('version.json', assetsUrl).href + version) : null;
+      if (!stamp || stamp.stamped !== true) {
+        return loader.loadL4({ instantiateWasm: (imports) => instantiate(wasmUrl, imports) });
+      }
+      const response = await fetch(wasmUrl);
+      if (!response.ok) {
+        throw new Error(`factoidal: fetching ${wasmUrl} failed: ${response.status} ${response.statusText}`);
+      }
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      await checkEngineStamp(bytes, stamp, { where: wasmUrl });
+      return loader.loadL4({ instantiateWasm: (imports) => WebAssembly.instantiate(bytes, imports) });
     })();
     enginePromise.catch(() => { enginePromise = null; });
     return enginePromise;

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 };
+}