provared 0.5.0 → 0.7.0

package/src/signatures.js

@@ -14,7 +14,7 @@
 // not built in, which is never a pass.
 
 import { Refusal } from './encoding.js';
-import { checkKey, importPublicKey, thumbprint, weakEd25519 } from './keys.js';
+import { badEd25519Signature, checkKey, importPublicKey, thumbprint } from './keys.js';
 
 const SLH = 'SLH-DSA-SHA2-256s';
 
@@ -99,10 +99,11 @@ export async function verifySignature(jwk, signature, data, without = []) {
   if (!Object.hasOwn(VERIFY_PARAMS, jwk.alg)) return 'invalid';
   const params = VERIFY_PARAMS[jwk.alg];
   if (without.includes(jwk.alg) || !(await methodAvailable(jwk.alg))) return 'unavailable';
-  // An Ed25519 signature whose first half is a point of small order is
-  // refused here, whatever the device's own library would say: libraries
-  // differ on it (format description, section 3.8).
-  if (jwk.alg === 'Ed25519' && (signature.length !== 64 || weakEd25519(signature.subarray(0, 32)))) return 'invalid';
+  // An Ed25519 signature whose first half is a point of small order, or
+  // whose second half, the number S, is not below the order L, is refused
+  // here, whatever the device's own library would say: libraries differ on
+  // both (format description, section 3.8).
+  if (jwk.alg === 'Ed25519' && badEd25519Signature(signature)) return 'invalid';
   try {
     const key = await importPublicKey(jwk);
     return (await globalThis.crypto.subtle.verify(params, key, signature, data)) ? 'valid' : 'invalid';
@@ -180,7 +181,12 @@ const signerShape = (alg) =>
 function writtenSlhKey(item, where) {
   let made;
   try {
-    made = nodeCrypto.createPrivateKey(item);
+    // A Web Crypto CryptoKey of another method is refused here, without
+    // handing it to Node.js: createPrivateKey would turn it into a KeyObject
+    // of that method, refused below all the same, but handing it a CryptoKey
+    // is deprecated (DEP0203) and prints a warning.
+    if (typeof globalThis.CryptoKey === 'function' && item instanceof globalThis.CryptoKey && item.algorithm.name !== SLH) made = null;
+    else made = nodeCrypto.createPrivateKey(item);
   } catch {
     made = null; // not a private key Node.js can read, or no Node.js here
   }

package/src/slip.js

@@ -22,21 +22,52 @@ const MAX_PERIOD_SECONDS = 366 * 86400;
 // begins or ends with a hyphen, and the last is not all digits. A browser
 // writes a page's address in exactly this form, with a name in another
 // script written in its "xn--" form, which the rule takes as it is.
+// eslint-disable-next-line security/detect-unsafe-regex -- each part has a bounded length, and a full stop or colon separates the parts.
 const ORIGIN = /^(https|http):\/\/([a-z0-9.-]{1,253})(?::([1-9][0-9]{0,4}))?$/;
+// eslint-disable-next-line security/detect-unsafe-regex -- a label has at most 63 characters.
 const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 
+// The scheme and the host of a text in the form above, or null where the
+// text is not in that form.
+function pageAddressParts(text) {
+  if (typeof text !== 'string') return null;
+  const m = ORIGIN.exec(text);
+  if (!m) return null;
+  const labels = m[2].split('.');
+  const port = m[3] !== undefined ? Number(m[3]) : null;
+  if (!labels.every((l) => LABEL.test(l)) || /^[0-9]+$/.test(labels[labels.length - 1]) || (port !== null && (port > 65535 || port === (m[1] === 'https' ? 443 : 80)))) {
+    return null;
+  }
+  return { scheme: m[1], host: m[2] };
+}
+
+/**
+ * Whether a text is the address of a page in the one form the format
+ * allows for a slip's "issuer.origin" (format description, section 4.1):
+ * "https://" (or "http://localhost"), a website name in lower case, a port
+ * only where it is needed, and nothing more. The addresses a reader names
+ * as the ones a permission must have been signed at (the option
+ * "issuerOrigins") must be in this form too, so that an address with a
+ * capital letter or a path is refused, and does not quietly match nothing.
+ * @param {unknown} text
+ * @returns {boolean}
+ */
+export function isPageAddress(text) {
+  const parts = pageAddressParts(text);
+  return parts !== null && (parts.scheme === 'https' || (parts.scheme === 'http' && parts.host === 'localhost'));
+}
+
 function checkOrigin(origin, rpId) {
   f.text(origin, 1, 300, 'issuer.origin');
+  // eslint-disable-next-line security/detect-unsafe-regex -- a name has at most 253 characters.
   if (typeof rpId !== 'string' || !/^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$/.test(rpId)) {
     throw f.fail('issuer.rpId', 'must be a website name in lower case, such as example.org.');
   }
-  const m = ORIGIN.exec(origin);
-  const labels = m ? m[2].split('.') : [];
-  const port = m && m[3] !== undefined ? Number(m[3]) : null;
-  if (!m || !labels.every((l) => LABEL.test(l)) || /^[0-9]+$/.test(labels[labels.length - 1]) || (port !== null && (port > 65535 || port === (m[1] === 'https' ? 443 : 80)))) {
+  const parts = pageAddressParts(origin);
+  if (parts === null) {
     throw f.fail('issuer.origin', 'must be the address of a page: https://, a website name in lower case, a port only if it is needed, and nothing more, such as https://sign.example.org.');
   }
-  const [, scheme, host] = m;
+  const { scheme, host } = parts;
   if (!(scheme === 'https' || (scheme === 'http' && host === 'localhost'))) {
     throw f.fail('issuer.origin', 'must begin https://, or http://localhost.');
   }
@@ -48,6 +79,29 @@ function checkOrigin(origin, rpId) {
 /** Not part of the public interface: for the shared test files. */
 export const checkOriginForTests = checkOrigin;
 
+/** The most addresses a reader may name as the ones a permission must have been signed at. */
+export const MAX_ISSUER_ORIGINS = 64;
+
+/**
+ * The addresses a reader names as the ones a permission must have been
+ * signed at (the option "issuerOrigins"; format description, section 4.4):
+ * a list of at most 64, each in the form isPageAddress accepts. Anything
+ * else is refused, never set aside: an address with a capital letter or a
+ * path would match nothing, and every permission would then read as signed
+ * elsewhere. Every place in the list is read by its number, a gap included.
+ * @param {object} options the checker's options
+ * @throws {Refusal} "bad-field"
+ */
+export function checkOriginsOption(options) {
+  const { issuerOrigins } = options;
+  if (issuerOrigins === undefined) return;
+  let sound = Array.isArray(issuerOrigins) && issuerOrigins.length <= MAX_ISSUER_ORIGINS;
+  for (let i = 0; sound && i < issuerOrigins.length; i++) sound = isPageAddress(issuerOrigins[i]);
+  if (!sound) {
+    throw f.fail('issuerOrigins', 'must be a list of at most 64 page addresses, each https://, a website name in lower case, a port only if it is needed, and nothing more, such as https://sign.example.org.');
+  }
+}
+
 /**
  * Confirm a list of limits against the actions it may name (format
  * description, section 4.1). A slip and a pass share it.
@@ -279,6 +333,7 @@ export async function preparePasskeyRecord(kind, content) {
  * @param {any} record the slip as a JavaScript object
  * @param {object} [options]
  * @param {string[]} [options.issuerKeys] thumbprints of the issuer keys the checker expects
+ * @param {string[]} [options.issuerOrigins] the addresses of the pages at which the checker expects the slip to have been signed, each in the form of section 4.1 (see isPageAddress)
  * @param {string[]} [options.withoutMethods] see verifySignature
  * @param {Record<string, string[]>} [options.disclosures] for covered fields: the disclosures handed over, by the fingerprint of the record they belong to
  * @param {string[]} [disclosures] the disclosures for this slip, where they come with it (a page of a Show)
@@ -349,6 +404,18 @@ export async function checkSlip(record, options = {}, disclosures) {
     } else {
       result.notes.push('The issuer\'s key was not compared with a key you already trust. The name on the slip is only a label.');
     }
+
+    // The address the slip was signed at, compared with the ones the reader
+    // named, where they named any (section 4.4). An approval and a
+    // cancellation are signed with the same passkey, and the passkey check
+    // holds each to the slip's address, so the slip's is the one compared.
+    if (options.issuerOrigins !== undefined) {
+      checkOriginsOption(options);
+      let named = false;
+      for (let i = 0; i < options.issuerOrigins.length; i++) if (options.issuerOrigins[i] === issuer.origin) named = true;
+      if (!named) throw new Refusal('issuer-origin-not-expected', 'The slip was signed at a page address other than the ones expected.');
+      result.notes.push(`This slip was signed at ${issuer.origin}, an address you named.`);
+    }
   } catch (e) {
     result.problems.push(problemFrom(e));
   }

package/src/timestamp.js

@@ -9,9 +9,9 @@
 // service's certificate. It follows no chain of certificates and asks no
 // outside party: the person checking decides whom to trust.
 
-import { TAG, badStamp, children, contentOf, ecdsaToRaw, expect, hexOf, readElement, timeOf, validateDer, wholeOf } from './der.js';
+import { TAG, badStamp, children, contentOf, ecdsaToRaw, expect, hexOf, readElement, setInOrder, timeOf, validateDer, wholeOf } from './der.js';
 import { Refusal, equalBytes, formatTime, sha256, toBase64url } from './encoding.js';
-import { weakEd25519 } from './keys.js';
+import { badEd25519Signature, weakEd25519 } from './keys.js';
 
 /** The largest time-stamp, in bytes. */
 export const MAX_STAMP_BYTES = 12288;
@@ -162,6 +162,8 @@ function checkKeyEncoding(bytes, certificate, method, size) {
 // force, and its public key.
 function readCertificate(bytes, element) {
   const whole = wholeOf(bytes, expect(element, TAG.SEQUENCE, 'a certificate'));
+  // A certificate is DER (RFC 5280 section 4.1), so the order of every set inside it is held here.
+  validateDer(bytes, element);
   const tbs = expect(children(bytes, element, 3)[0], TAG.SEQUENCE, 'the body of a certificate');
   const parts = children(bytes, tbs, 12);
   // The version, in [0], is absent only in the oldest kind of certificate.
@@ -204,14 +206,17 @@ function signingCertificateOf(bytes, value, v2) {
 }
 
 const KIND_NOT_ACCEPTED = 'A time-stamp was signed with a kind of key that is not accepted: RSA, ECDSA on the curves P-256 and P-384, and Ed25519 are.';
+const ED25519_DIGEST = 'A time-stamp signed with Ed25519 names a fingerprint method other than SHA-512, or gives the method parameters, which RFC 8419 does not allow.';
+const ED25519_PARAMETERS = 'A time-stamp signed with Ed25519 gives its signing method parameters, which RFC 8419 does not allow.';
 
 // Check the service's signature with the public key of its certificate.
 // Returns "valid", "invalid", or "unavailable" where this device has no
 // built-in support for the method. The fingerprint method is the one the
 // signer names (RFC 5652 section 5.4); a signing method that names another
 // is refused; a key of a kind that is not accepted is refused in words that
-// say so.
-async function verifyWith(certificate, bytes, signatureOid, digestName, signature, signed, without) {
+// say so. "parameters" holds the parameters, if any, of the signing method
+// and of the signer's fingerprint method.
+async function verifyWith(certificate, bytes, signatureOid, digestName, signature, signed, without, parameters) {
   const subtle = globalThis.crypto.subtle;
   let importParams;
   let verifyParams;
@@ -237,7 +242,11 @@ async function verifyWith(certificate, bytes, signatureOid, digestName, signatur
       return 'invalid';
     }
   } else if (certificate.keyOid === OID.ed25519) {
+    // With Ed25519 the signer's fingerprint method is SHA-512 with no
+    // parameters, and the signing method carries none (RFC 8419, section 3.1).
     if (signatureOid !== OID.ed25519) return 'invalid';
+    if (digestName !== 'SHA-512' || parameters.digest !== undefined) throw invalid(ED25519_DIGEST);
+    if (parameters.signature !== undefined) throw invalid(ED25519_PARAMETERS);
     checkKeyEncoding(bytes, certificate, 'Ed25519');
     method = 'Ed25519';
     importParams = { name: 'Ed25519' };
@@ -253,8 +262,8 @@ async function verifyWith(certificate, bytes, signatureOid, digestName, signatur
     // A device with no Ed25519 says so when the key is loaded.
     return method === 'Ed25519' && e && e.name === 'NotSupportedError' ? 'unavailable' : 'invalid';
   }
-  // An Ed25519 signature whose first half is a point of small order is refused, as everywhere (format description, section 3.8).
-  if (method === 'Ed25519' && (raw.length !== 64 || weakEd25519(raw.subarray(0, 32)))) return 'invalid';
+  // An Ed25519 signature whose first half is a point of small order, or whose number S is not below L, is refused, as everywhere (format description, section 3.8).
+  if (method === 'Ed25519' && badEd25519Signature(raw)) return 'invalid';
   try {
     return (await subtle.verify(verifyParams, key, raw, signed)) ? 'valid' : 'invalid';
   } catch {
@@ -275,7 +284,8 @@ async function verifyWith(certificate, bytes, signatureOid, digestName, signatur
  *   soundly, by a service the checker did not name. "unavailable": this
  *   device cannot check the service's signing method; no time is given.
  *   "authority" is the fingerprint of the certificate that signed. "when"
- *   is the stated time, to the second, rounded down.
+ *   is the stated time, to the second, rounded down; "time" is it in
+ *   milliseconds, a fraction of a second kept to the millisecond.
  * @throws {Refusal} "stamp-bad-data", "stamp-wrong-data" or "stamp-invalid"
  */
 export async function checkStamp(token, fingerprintBytes, options) {
@@ -287,10 +297,18 @@ export async function checkStamp(token, fingerprintBytes, options) {
   if (!(fingerprintBytes instanceof Uint8Array)) throw badStamp('there is no fingerprint to compare it with.');
 
   // The outer wrapper, and the signed data inside it (RFC 5652 sections 3
-  // and 5.1). Every part is read, and must be strict DER.
+  // and 5.1). Every part the reader can tell apart is read, and must be
+  // strict DER, except that the order of a set is held only where a standard
+  // requires DER: the signed attributes (RFC 5652 section 5.3), the statement
+  // (RFC 3161 section 2.4.2) and each certificate (RFC 5280 section 4.1),
+  // each walked again below with the order held. The signed data's own sets
+  // (the fingerprint methods, the certificates, the withdrawn certificates,
+  // the signers) and the rest of the signer may be in any order: CMS does not
+  // require DER of them, and real services list their certificates in chain
+  // order, the signing certificate before its issuer.
   const wrapper = expect(readElement(token, 0), TAG.SEQUENCE, 'the wrapper');
   if (wrapper.end !== token.length) throw badStamp('it has bytes left over.');
-  validateDer(token, wrapper);
+  validateDer(token, wrapper, false);
   const outer = children(token, wrapper, 2);
   if (outer.length !== 2 || hexOf(token, expect(outer[0], TAG.OID, 'the kind of content')) !== OID.signedData) throw badStamp('it is not signed data.');
   const inner = children(token, expect(outer[1], TAG.CONTEXT_0, 'the signed data'), 1);
@@ -309,7 +327,11 @@ export async function checkStamp(token, fingerprintBytes, options) {
   let next = 3;
   const certificates = [];
   if (parts[next] && parts[next].tag === TAG.CONTEXT_0) {
-    for (const c of children(token, parts[next], 8)) {
+    // A set of the signed data's own (RFC 5652 section 10.2.3), which CMS does
+    // not require to be in DER order; each certificate inside it is DER (RFC
+    // 5280 section 4.1), and is held to it when it is read.
+    const items = children(token, parts[next], 8);
+    for (const c of items) {
       // Other kinds of certificate may sit here; only the ordinary kind is read.
       if (c.tag === TAG.SEQUENCE) certificates.push(readCertificate(token, c));
     }
@@ -324,9 +346,16 @@ export async function checkStamp(token, fingerprintBytes, options) {
   if (!signer[1] || !((signerVersion === '01' && signer[1].tag === TAG.SEQUENCE) || (signerVersion === '03' && signer[1].tag === 0x80))) {
     throw badStamp('the signer is not named as its standard sets out.');
   }
-  const digestName = HASHES[algorithmOf(token, signer[2], 'the signer\'s fingerprint method').oid];
+  const digesting = algorithmOf(token, signer[2], 'the signer\'s fingerprint method');
+  const digestName = HASHES[digesting.oid];
   const attributes = expect(signer[3], TAG.CONTEXT_0, 'the signed attributes');
-  const signatureOid = algorithmOf(token, signer[4], 'the signing method').oid;
+  // A set under a tag of its own, in DER (RFC 5652 section 5.3), so its order,
+  // and the order of every set inside it, is held to DER here.
+  const attributeList = children(token, attributes, 16);
+  if (!setInOrder(token, attributeList)) throw badStamp('the signed attributes are not in the order DER requires.');
+  for (const a of attributeList) validateDer(token, a);
+  const signing = algorithmOf(token, signer[4], 'the signing method');
+  const signatureOid = signing.oid;
   const signature = contentOf(token, expect(signer[5], TAG.OCTET_STRING, 'the signature'));
   if (signer.length > 7 || (signer.length === 7 && signer[6].tag !== TAG.CONTEXT_1)) throw badStamp('the signer holds parts that are not in the order its standard sets out.');
 
@@ -344,7 +373,9 @@ export async function checkStamp(token, fingerprintBytes, options) {
   let kindNamed = false;
   let digestNamed = false;
   let named = null;
-  for (const attribute of children(token, attributes, 16)) {
+  let newerNamed = false;
+  let olderNamed = false;
+  for (const attribute of attributeList) {
     const pair = children(token, expect(attribute, TAG.SEQUENCE, 'an attribute'), 2);
     const name = hexOf(token, expect(pair[0], TAG.OID, 'the name of an attribute'));
     const values = children(token, expect(pair[1], TAG.SET, 'the value of an attribute'), 4);
@@ -360,8 +391,16 @@ export async function checkStamp(token, fingerprintBytes, options) {
       digestNamed = true;
     } else if (name === OID.signingCertificateV2 || name === OID.signingCertificate) {
       if (values.length !== 1) throw invalid('A time-stamp does not say, in one way, which certificate signed it.');
-      // Where both forms are present, the newer one is used.
-      if (named === null || name === OID.signingCertificateV2) named = signingCertificateOf(token, values[0], name === OID.signingCertificateV2);
+      // Each form at most once: RFC 5035 section 3 for the newer form, and
+      // for the older section 5.4.2 of RFC 2634 as RFC 5035 section 5 writes
+      // it. Where both forms are present, the newer one is used: this
+      // format's choice, where RFC 5035 section 7 lets a reader refuse a
+      // time-stamp whose two forms disagree.
+      const newer = name === OID.signingCertificateV2;
+      if (newer ? newerNamed : olderNamed) throw invalid('A time-stamp names the certificate that signed it more than once in the same form, which its standard does not allow.');
+      if (newer) newerNamed = true;
+      else olderNamed = true;
+      if (named === null || newer) named = signingCertificateOf(token, values[0], newer);
     }
   }
   if (!kindNamed || !digestNamed) throw invalid('A time-stamp\'s signature does not cover its statement.');
@@ -382,7 +421,7 @@ export async function checkStamp(token, fingerprintBytes, options) {
   // 5.4). The bytes are copied, so that the caller's time-stamp is not changed.
   const signed = new Uint8Array(wholeOf(token, attributes));
   signed[0] = TAG.SET;
-  const state = await verifyWith(certificate, token, signatureOid, digestName, signature, signed, without);
+  const state = await verifyWith(certificate, token, signatureOid, digestName, signature, signed, without, { signature: signing.parameters, digest: digesting.parameters });
   if (state === 'unavailable') return { state: 'unavailable', when: null, time: NaN, authority: null };
   if (state !== 'valid') throw invalid('A time-stamp\'s signature does not fit the certificate it names.');
   if (statement.time < certificate.notBefore || statement.time > certificate.notAfter) {

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