provared 0.4.0 → 0.6.0

package/src/tools.js

@@ -5,13 +5,16 @@
 // every call asks first, is run only if the slip allows it, and leaves a
 // stub. The agent's software then calls the tools as before.
 //
-// By default the stub of a call names one document, "arguments": the
-// fingerprint of the call's arguments. So the record fixes exactly what was
-// asked for, without holding it: whoever kept the arguments can show them
-// later, and anyone can work out the fingerprint again.
+// By default the stub of a call names one document, "provared.arguments"
+// (a reserved name, format description section 27): the fingerprint of the
+// call's arguments. So the record fixes exactly what was asked for, without
+// holding it: whoever kept the arguments can show them later, and anyone
+// can work out the fingerprint again. Before version 0.6.0 the document was
+// named "arguments"; a checker reads both.
 //
 // It names no agent software and depends on none: a tool is any function.
 
+import { denialCodes } from './denial.js';
 import { Refusal, fingerprint, utf8 } from './encoding.js';
 import * as f from './fields.js';
 
@@ -27,18 +30,22 @@ const NOT_A_GENERATOR = 'must not be a generator function: calling one does not
  * A call through a recorded tool that was not run: the check before acting
  * did not allow it, or the record so far has a problem. "answer" is what
  * the check before acting said (allowed, problems, breaches, needs).
+ * "denial", where the stub writer was opened with "denials: true", is what
+ * it said of the denial it wrote, or did not write, for the call.
  */
 export class NotTaken extends Error {
   /**
    * @param {string} tool the name of the tool
    * @param {{allowed: boolean, problems: object[], breaches: object[], needs: string[]}} answer
+   * @param {object} [denial]
    */
-  constructor(tool, answer) {
+  constructor(tool, answer, denial) {
     const first = [...answer.problems, ...answer.breaches][0];
     super(`The tool "${tool}" was not run. ${first ? first.message : 'The check before acting did not allow it.'}`);
     this.name = 'NotTaken';
     this.tool = tool;
     this.answer = answer;
+    if (denial !== undefined) this.denial = denial;
   }
 }
 
@@ -74,7 +81,7 @@ function oneForm(value, depth = 0) {
 /**
  * The fingerprint of the arguments of a call: SHA-256, in base64url, of the
  * arguments written in the one form of RFC 8785. It is what a recorded
- * tool puts into its stub, as the document "arguments".
+ * tool puts into its stub, as the document "provared.arguments".
  * @param {unknown} args JSON: objects, lists, text, numbers, true, false and null
  * @returns {Promise<string>}
  * @throws {Refusal} "bad-field" if the arguments are not JSON
@@ -118,8 +125,8 @@ const needsOnlyApproval = (answer) => answer.problems.length === 0 && answer.bre
  *   - "with" (optional): the id of the service the tool deals with, as the slip names it, or a function of the arguments that gives it;
  *   - "amount" (optional): {unit, value}, or a function of the arguments that gives it;
  *   - "details" (optional): a function of the arguments that gives the documents to name in the stub
- *     ({name, sha256} each), or false for none. By default: one document, "arguments", the fingerprint
- *     of the arguments (argumentsFingerprint);
+ *     ({name, sha256} each), or false for none. By default: one document, "provared.arguments", the
+ *     fingerprint of the arguments (argumentsFingerprint);
  *   - "countersign" (optional): asks the other side to countersign the stub; a function of the stub and the arguments;
  *   - "approve" (optional): asks the person for their approval where the slip asks for one; a function of the
  *     request ({action, amount?, with?, details?}) and the arguments, that gives {record} or nothing.
@@ -139,6 +146,8 @@ export function recordTools(recorder, tools, options = {}) {
   if (options === null || typeof options !== 'object') options = {};
   // What the tools are put behind is fixed here too.
   const act = recorder.act.bind(recorder);
+  // Whether the writer writes denials, read once: only then are denials asked for.
+  const deny = recorder.denials === true && typeof recorder.deny === 'function' ? recorder.deny.bind(recorder) : null;
   const onStub = typeof options.onStub === 'function' ? options.onStub : null;
   const recorded = {};
   for (const name of Object.keys(tools)) {
@@ -157,12 +166,12 @@ export function recordTools(recorder, tools, options = {}) {
     for (const member of ['amount', 'with']) if (typeof fixed[member] !== 'function') fixed[member] = copied(fixed[member], `tools.${name}.${member}`);
     for (const member of ['amount', 'with']) if (fixed[member] !== null && typeof fixed[member] === 'object') Object.freeze(fixed[member]);
     Object.freeze(fixed);
-    Object.defineProperty(recorded, name, { enumerable: true, value: (args) => call(act, onStub, name, fixed, args) });
+    Object.defineProperty(recorded, name, { enumerable: true, value: (args) => call(act, deny, onStub, name, fixed, args) });
   }
   return recorded;
 }
 
-async function call(act, onStub, name, spec, args) {
+async function call(act, deny, onStub, name, spec, args) {
   // The arguments are copied when the call is made. The fingerprint is made
   // from that copy, and the tool is run with a copy of it. Each of the
   // tool's other functions is handed a copy of its own.
@@ -177,7 +186,7 @@ async function call(act, onStub, name, spec, args) {
   let details;
   if (spec.details === false) details = [];
   else if (typeof spec.details === 'function') details = (await (0, spec.details)(structuredClone(given))) ?? [];
-  else details = given === undefined ? [] : [{ name: 'arguments', sha256: await argumentsFingerprint(given) }];
+  else details = given === undefined ? [] : [{ name: 'provared.arguments', sha256: await argumentsFingerprint(given) }];
   if (!Array.isArray(details)) throw f.fail(`tools.${name}.details`, 'must give a list of documents.');
   details = copied(details, `tools.${name}.details`);
   if (details.length > 0) request.details = details;
@@ -185,14 +194,22 @@ async function call(act, onStub, name, spec, args) {
   const more = {};
   if (typeof spec.countersign === 'function') more.countersign = (stub) => (0, spec.countersign)(stub, structuredClone(given));
   const perform = () => (0, spec.run)(structuredClone(given));
-  let outcome = await act(request, perform, more);
+  // Where the person may be asked for their approval, the first call
+  // writes no denial: the action may yet be taken. A denial is written once
+  // it is known that it will not be, so that one call never leaves both a
+  // stub and a denial.
+  const asking = typeof spec.approve === 'function' && deny !== null;
+  let outcome = await act(request, perform, asking ? { ...more, denial: false } : more);
   // Where the slip asks for the person's own approval of this action, and
   // that is the one thing missing, the person is asked, once.
   if (!outcome.done && typeof spec.approve === 'function' && needsOnlyApproval(outcome.answer)) {
     const approval = await (0, spec.approve)(structuredClone(request), structuredClone(given));
     if (approval) outcome = await act(request, perform, { ...more, approval });
+    else if (asking) outcome = { ...outcome, denial: await deny(request, { source: 'person' }) };
+  } else if (!outcome.done && asking) {
+    outcome = { ...outcome, denial: await deny(request, { source: 'check', codes: denialCodes(outcome.answer) }) };
   }
-  if (!outcome.done) throw new NotTaken(name, outcome.answer);
+  if (!outcome.done) throw new NotTaken(name, outcome.answer, outcome.denial);
   if (onStub) await onStub(outcome.stub, name);
   return outcome.result;
 }

package/src/tree.js

@@ -7,8 +7,13 @@
 //
 // The proof that one leaf is in the tree is the audit path of section
 // 2.1.1. It is checked with the steps of RFC 9162, section 2.1.3.2.
+//
+// The proof that a tree of m leaves is the first part of a tree of n leaves
+// (a consistency proof) is made as RFC 9162, section 2.1.4.1, sets out, and
+// checked with the steps of section 2.1.4.2. RFC 9162 builds the same tree
+// as RFC 6962.
 
-import { concatBytes, equalBytes, sha256 } from './encoding.js';
+import { Refusal, concatBytes, equalBytes, sha256 } from './encoding.js';
 
 const LEAF = new Uint8Array([0x00]);
 const NODE = new Uint8Array([0x01]);
@@ -61,6 +66,15 @@ export async function treeRoot(leaves) {
 export function treeBuilder(from = []) {
   /** @type {{hash: Uint8Array, size: number}[]} */
   const parts = from.slice();
+  const addLeafHash = async (hash) => {
+    if (!(hash instanceof Uint8Array) || hash.length !== 32) throw new Refusal('bad-field', 'leaf: must be a leaf fingerprint: 32 bytes.');
+    let node = { hash: hash.slice(), size: 1 };
+    while (parts.length && parts[parts.length - 1].size === node.size) {
+      const left = parts.pop();
+      node = { hash: await nodeHash(left.hash, node.hash), size: left.size * 2 };
+    }
+    parts.push(node);
+  };
   return {
     /** A builder that carries on from here by itself: what is added to one is not added to the other. */
     fork() {
@@ -68,12 +82,17 @@ export function treeBuilder(from = []) {
     },
     /** @param {Uint8Array} leaf the data of the next leaf */
     async add(leaf) {
-      let node = { hash: await leafHash(leaf), size: 1 };
-      while (parts.length && parts[parts.length - 1].size === node.size) {
-        const left = parts.pop();
-        node = { hash: await nodeHash(left.hash, node.hash), size: left.size * 2 };
-      }
-      parts.push(node);
+      await addLeafHash(await leafHash(leaf));
+    },
+    /**
+     * Add the next leaf by its fingerprint alone (leafHash of its data), as a
+     * sealer that never sees the lines does.
+     * @param {Uint8Array} hash 32 bytes
+     */
+    addLeafHash,
+    /** One fingerprint for each complete part of the tree, the largest first: what a sealer saves. */
+    parts() {
+      return parts.map((p) => ({ hash: p.hash.slice(), size: p.size }));
     },
     /** @returns {Promise<Uint8Array>} the root of the leaves added so far */
     async root() {
@@ -141,3 +160,116 @@ export async function verifyInclusion(index, size, leaf, path, root) {
   }
   return sn === 0 && equalBytes(r, root);
 }
+
+// The largest power of two smaller than n, for n of 2 or more (RFC 9162,
+// section 2.1.1: "k be the largest power of two smaller than n").
+function splitAt(n) {
+  let k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+// The root of the tree over the leaves whose hashes are hashes[lo] to
+// hashes[hi - 1], for hi > lo: MTH of RFC 9162, section 2.1.1.
+async function rangeRoot(hashes, lo, hi) {
+  if (hi - lo === 1) return hashes[lo];
+  const k = splitAt(hi - lo);
+  return nodeHash(await rangeRoot(hashes, lo, lo + k), await rangeRoot(hashes, lo + k, hi));
+}
+
+// SUBPROOF(m, D[lo:hi], b) of RFC 9162, section 2.1.4.1, for 0 < m <= hi - lo.
+async function subproof(hashes, m, lo, hi, b) {
+  const n = hi - lo;
+  if (m === n) return b ? [] : [await rangeRoot(hashes, lo, hi)];
+  const k = splitAt(n);
+  if (m <= k) return [...(await subproof(hashes, m, lo, lo + k, b)), await rangeRoot(hashes, lo + k, hi)];
+  return [...(await subproof(hashes, m - k, lo + k, hi, false)), await rangeRoot(hashes, lo, lo + k)];
+}
+
+/**
+ * The proof that the first m leaves form a tree that the whole tree extends:
+ * the consistency proof of RFC 9162, section 2.1.4.1, from the tree of the
+ * first m leaves to the tree of all of them. For m equal to the number of
+ * leaves, and for m of 0, the proof is empty (RFC 9162 defines a proof only
+ * for 0 < m; every tree extends the empty one).
+ * @param {Uint8Array[]} leaves the data of each leaf
+ * @param {number} m how many leaves the earlier tree has, from 0 to the number of leaves
+ * @returns {Promise<Uint8Array[]>}
+ */
+export async function consistencyProof(leaves, m) {
+  if (!Array.isArray(leaves)) throw new TypeError('the leaves must be a list');
+  if (!Number.isSafeInteger(m) || m < 0 || m > leaves.length) throw new RangeError('no such earlier tree');
+  if (m === 0 || m === leaves.length) return [];
+  const hashes = [];
+  for (const leaf of leaves) hashes.push(await leafHash(leaf));
+  return subproof(hashes, m, 0, hashes.length, true);
+}
+
+const isHash = (value) => value instanceof Uint8Array && value.length === 32;
+
+/**
+ * Check a consistency proof (RFC 9162, section 2.1.4.2): that the tree of m
+ * leaves whose root is rootM is the first part of the tree of n leaves whose
+ * root is rootN. Where m equals n the proof must be empty and the two roots
+ * the same; where m is 0 the proof must be empty and rootM the root of the
+ * empty tree (the SHA-256 hash of nothing). Anything that is not a proof of
+ * these sizes gives false: the function never throws for a bad proof.
+ * @param {number} m
+ * @param {number} n
+ * @param {Uint8Array} rootM 32 bytes
+ * @param {Uint8Array} rootN 32 bytes
+ * @param {Uint8Array[]} proof each 32 bytes
+ * @returns {Promise<boolean>}
+ */
+export async function verifyConsistency(m, n, rootM, rootN, proof) {
+  if (!Number.isSafeInteger(m) || !Number.isSafeInteger(n) || m < 0 || m > n) return false;
+  if (!isHash(rootM) || !isHash(rootN) || !Array.isArray(proof)) return false;
+  // Read place by place, a gap included: a gap is not a fingerprint.
+  const path = [];
+  for (let i = 0; i < proof.length; i++) {
+    if (!isHash(proof[i])) return false;
+    path.push(proof[i]);
+  }
+  if (m === n) return path.length === 0 && equalBytes(rootM, rootN);
+  if (m === 0) return path.length === 0 && equalBytes(rootM, await sha256(new Uint8Array(0)));
+  // The steps of RFC 9162, section 2.1.4.2, in their order.
+  // 1. An empty proof fails.
+  if (path.length === 0) return false;
+  // 2. Where m is an exact power of two, the root of the earlier tree is the first value.
+  // (Worked out by doubling, not with the bit operators, which hold only 32 bits.)
+  let power = 1;
+  while (power < m) power *= 2;
+  if (power === m) path.unshift(rootM);
+  // 3.
+  let fn = m - 1;
+  let sn = n - 1;
+  // 4. Sizes are below 2 to the power 53, so halving with Math.floor is exact.
+  while (fn % 2 === 1) {
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+  // 5.
+  let fr = path[0];
+  let sr = path[0];
+  // 6.
+  for (let i = 1; i < path.length; i++) {
+    const c = path[i];
+    if (sn === 0) return false;
+    if (fn % 2 === 1 || fn === sn) {
+      fr = await nodeHash(c, fr);
+      sr = await nodeHash(c, sr);
+      if (fn % 2 === 0) {
+        while (fn % 2 === 0 && fn !== 0) {
+          fn = Math.floor(fn / 2);
+          sn = Math.floor(sn / 2);
+        }
+      }
+    } else {
+      sr = await nodeHash(sr, c);
+    }
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+  // 7.
+  return equalBytes(fr, rootM) && equalBytes(sr, rootN) && sn === 0;
+}