provared 0.5.0 → 0.6.0

package/src/check.d.ts

@@ -8,6 +8,8 @@ export {
   methodAvailable,
   thumbprint,
   keySetFingerprint,
+  verifyConsistency,
+  verifyInclusion,
   blockFingerprint,
   checkHeaderChain,
   blocksInChain,
@@ -17,5 +19,6 @@ export {
   neverWords,
   LIMITS,
   REFUSAL_REASONS,
+  DENIAL_SOURCES,
 } from './types.js';
 export type * from './types.js';

package/src/check.js

@@ -7,9 +7,11 @@
 export { checkBook, checkShow, openChecker, LIMITS } from './book.js';
 export { limitWords, conditionWords, neverWords } from './compare.js';
 export { REFUSAL_REASONS } from './service.js';
+export { DENIAL_SOURCES } from './denial.js';
 export { checkSlip } from './slip.js';
 export { keySetFingerprint } from './seal.js';
 export { blockFingerprint } from './blockstamp.js';
 export { checkHeaderChain, blocksInChain, MIN_BLOCKS_AFTER } from './headers.js';
 export { thumbprint } from './keys.js';
 export { methodAvailable } from './signatures.js';
+export { verifyConsistency, verifyInclusion } from './tree.js';

package/src/denial.js

@@ -0,0 +1,123 @@
+// The denial: the agent's own side states that it did not take an action
+// that was asked for, and why. It is signed with the agent's two keys, or
+// with the helper agent's under its pass. It is the agent's side's own
+// word, and an agent can simply not write one.
+// Format description, section 28.
+
+import { formatTime, randomId } from './encoding.js';
+import * as f from './fields.js';
+import { KINDS } from './jws.js';
+import { signWithKeySet, validateRequest } from './stub.js';
+
+/** Who said no. */
+export const DENIAL_SOURCES = {
+  check: 'The check before acting (section 20) did not allow the action.',
+  person: 'The person refused, or gave no approval when asked.',
+  rule: 'A rule of the software around the agent, outside the slip.',
+};
+
+/**
+ * The format's own list of finding codes: every code a checker or the check
+ * before acting gives (format description, section 28; the same list is in
+ * the list of threats, section 8). A denial whose source is "check" names
+ * its reasons from this list.
+ */
+export const FINDING_CODES = Object.freeze([
+  'not-json', 'bad-envelope', 'bad-base64url', 'too-large', 'unknown-type', 'bad-signatures-layout', 'payload-not-canonical',
+  'payload-type-mismatch', 'bad-field', 'bad-key', 'signature-invalid', 'passkey-wrong-type', 'passkey-challenge-mismatch',
+  'passkey-origin-mismatch', 'passkey-rpid-mismatch', 'passkey-user-not-present', 'passkey-user-not-verified', 'passkey-bad-data',
+  'issuer-not-expected', 'slip-missing', 'slip-unusable', 'chain-broken', 'time-went-backwards', 'duplicate-id', 'duplicate-slip',
+  'countersignature-invalid', 'countersignature-wrong-stub', 'countersignature-not-possible', 'line-not-canonical', 'unknown-entry',
+  'approval-mismatch', 'approval-reused', 'approval-invalid', 'approval-not-found', 'approval-dated-after-stub', 'terms-not-found',
+  'terms-unusable', 'terms-mismatch', 'pass-missing', 'pass-mismatch', 'pass-too-deep', 'cover-invalid', 'cancellation-invalid',
+  'cancellation-not-found', 'acknowledgement-mismatch', 'vouching-missing', 'seal-mismatch', 'seal-chain-broken', 'sealer-not-expected', 'book-cut-short', 'seal-not-in-book', 'witness-invalid',
+  'dated-after-stamp', 'stamp-bad-data', 'stamp-wrong-data', 'stamp-invalid', 'headers-invalid', 'record-not-sound', 'proof-invalid',
+  'root-mismatch', 'check-failed', 'action-not-allowed', 'party-not-allowed', 'outside-valid-time', 'amount-missing', 'over-limit',
+  'over-each-limit', 'over-count-limit', 'over-period-limit', 'countersignature-missing', 'approval-missing', 'prohibited',
+  'pass-not-allowed', 'pass-wider', 'after-cancellation', 'outside-terms',
+]);
+
+/** The most finding codes one denial may name. */
+export const MAX_DENIAL_CODES = 16;
+
+/**
+ * The reasons of a refusal by the check before acting, as a denial names
+ * them: the codes of its problems, then of its findings, each once, in that
+ * order, from the format's own list, at most 16. Where none is on the list,
+ * "check-failed".
+ * @param {{problems: {code: string}[], breaches: {code: string}[]}} answer the answer of the check before acting
+ * @returns {string[]}
+ */
+export function denialCodes(answer) {
+  const codes = [];
+  for (const p of [...answer.problems, ...answer.breaches]) {
+    if (p && typeof p.code === 'string' && FINDING_CODES.includes(p.code) && !codes.includes(p.code)) codes.push(p.code);
+  }
+  return codes.length ? codes.slice(0, MAX_DENIAL_CODES) : ['check-failed'];
+}
+
+/**
+ * Confirm every member of a denial's content.
+ * @param {any} c
+ */
+export function validateDenialContent(c) {
+  f.members(c, ['action', 'id', 'slip', 'source', 'type', 'when'], ['amount', 'codes', 'details', 'pass', 'with'], 'denial');
+  f.id(c.id, 'id');
+  f.fingerprintText(c.slip, 'slip');
+  if (Object.hasOwn(c, 'pass')) f.fingerprintText(c.pass, 'pass');
+  // What was asked for is written down as it was asked, as in a refusal: a
+  // reserved name that is not on the shared list may be why it was refused.
+  f.shortName(c.action, 'action');
+  // The amount, the service and the documents as in a stub; the service
+  // need not be one the slip names.
+  validateRequest({ ...c, action: 'x' });
+  if (typeof c.source !== 'string' || !Object.hasOwn(DENIAL_SOURCES, c.source)) throw f.fail('source', 'must be "check", "person" or "rule".');
+  if (c.source === 'check') {
+    if (!Object.hasOwn(c, 'codes')) throw f.fail('codes', 'is missing: a denial by the check before acting names its reasons.');
+    f.list(c.codes, 1, MAX_DENIAL_CODES, 'codes');
+    c.codes.forEach((code, i) => {
+      if (typeof code !== 'string' || !FINDING_CODES.includes(code)) throw f.fail(`codes[${i}]`, 'must be a code from the format\'s own list of finding codes.');
+    });
+    if (new Set(c.codes).size !== c.codes.length) throw f.fail('codes', 'a code is repeated.');
+  } else if (Object.hasOwn(c, 'codes')) {
+    throw f.fail('codes', 'only a denial by the check before acting names codes.');
+  }
+  f.time(c.when, 'when');
+}
+
+/**
+ * Write and sign a denial: the agent's side states that it did not take an
+ * action that was asked for, and why. It is signed with the keys of the
+ * agent the slip names or, where the signer is a helper agent, with the
+ * keys the pass names.
+ *
+ * @param {object} fields
+ * @param {string} fields.slip the fingerprint of the slip the agent acts under
+ * @param {string} [fields.pass] for a helper agent: the fingerprint of the pass it acts under
+ * @param {string} fields.action what was asked for
+ * @param {{unit: string, value: number}} [fields.amount]
+ * @param {string} [fields.with] the service asked for, as asked; it need not be one the slip names
+ * @param {{name: string, sha256: string}[]} [fields.details] fingerprints of documents, never the documents
+ * @param {'check'|'person'|'rule'} fields.source who said no
+ * @param {string[]} [fields.codes] where the source is "check": 1 to 16 finding codes, from FINDING_CODES
+ * @param {number|Date} [fields.when] defaults to now
+ * @param {any[]} privateKeys the agent's private keys, or signers: Ed25519, then ML-DSA-87
+ * @returns {Promise<{record: object, fingerprint: string}>}
+ */
+export async function writeDenial(fields, privateKeys) {
+  const content = {
+    type: KINDS.denial.type,
+    id: fields.id ?? randomId(),
+    slip: fields.slip,
+    action: fields.action,
+    source: fields.source,
+    when: formatTime(fields.when ?? Date.now()),
+  };
+  if (fields.pass) content.pass = fields.pass;
+  if (fields.amount) content.amount = fields.amount;
+  if (fields.with) content.with = fields.with;
+  if (fields.details && fields.details.length) content.details = fields.details;
+  if (fields.codes !== undefined && fields.codes !== null) content.codes = fields.codes;
+  validateDenialContent(content);
+  return signWithKeySet('denial', content, privateKeys);
+}

package/src/der.js

@@ -81,6 +81,30 @@ export function contentOf(bytes, element) {
   return bytes.subarray(element.start, element.end);
 }
 
+/**
+ * Whether the items of a set are in the order DER requires (X.690, section
+ * 11.6): their encodings compared as strings of bytes, the shorter padded
+ * at its end with zero bytes. Two equal encodings may stand side by side.
+ * @param {Uint8Array} bytes
+ * @param {{from: number, end: number}[]} items the elements of the set, in the order they appear
+ */
+export function setInOrder(bytes, items) {
+  for (let i = 1; i < items.length; i++) {
+    const a = items[i - 1];
+    const b = items[i];
+    const longest = Math.max(a.end - a.from, b.end - b.from);
+    for (let k = 0; k < longest; k++) {
+      const x = a.from + k < a.end ? bytes[a.from + k] : 0;
+      const y = b.from + k < b.end ? bytes[b.from + k] : 0;
+      if (x !== y) {
+        if (x > y) return false;
+        break;
+      }
+    }
+  }
+  return true;
+}
+
 /** The whole element, tag and length included. */
 export function wholeOf(bytes, element) {
   return bytes.subarray(element.from, element.end);
@@ -147,25 +171,45 @@ export function ecdsaToRaw(der, size) {
 /**
  * Walk a whole element and everything inside it, and refuse anything that
  * is not strict DER: a constructed part whose items do not fill it exactly,
- * a whole number or an object identifier that is not in its shortest form,
- * a truth value that is not written in the one way DER allows. Parts this
- * checker does not otherwise read are still read here, so that two checkers
- * cannot disagree about whether a time-stamp is well formed.
+ * a string (of bits, bytes or characters) or a time written in parts
+ * (X.690, section 10.2), a set whose items are not in order (section 11.6;
+ * only where "holdSetOrder" is true), a whole number or an object identifier
+ * that is not in its shortest form, a truth value that is not written in the
+ * one way DER allows, a string of bits whose unused bits are not zero. Parts
+ * this checker does not otherwise read are still read here, so that two
+ * checkers cannot disagree about whether a time-stamp is well formed. What a
+ * part holds as bytes (the value of an octet string) is read as bytes only.
+ * A part under a tag that hides its kind (a context tag): written in parts,
+ * the parts inside it are read like any other, but the tagged part itself is
+ * neither refused as a string written in parts nor held to the order of a
+ * set, since its tag does not say which it is; written in one piece, its
+ * value is read as bytes only. The order of a set is held only where a
+ * standard requires DER; checkStamp says where, and passes false for the
+ * rest of a time-stamp.
  * @param {Uint8Array} bytes
  * @param {{tag: number, start: number, end: number}} element
+ * @param {boolean} [holdSetOrder=true] whether the items of a set must be in DER order
  */
-export function validateDer(bytes, element) {
+export function validateDer(bytes, element, holdSetOrder = true) {
   let budget = 4000;
   const walk = (e, depth) => {
     if (--budget < 0 || depth > 24) throw badStamp('it holds too many parts, or parts nested too deeply.');
     const length = e.end - e.start;
     if (e.tag & 0x20) {
+      // Of the universal kinds, only a sequence and a set are written in
+      // parts; a string or a time is written in one piece (X.690, section 10.2).
+      if ((e.tag & 0xc0) === 0 && e.tag !== TAG.SEQUENCE && e.tag !== TAG.SET) {
+        throw badStamp('a string of bits, bytes or characters, or a time, is written in parts, which DER does not allow.');
+      }
+      const items = [];
       let at = e.start;
       while (at < e.end) {
         const child = readElement(bytes, at, e.end);
         walk(child, depth + 1);
+        items.push(child);
         at = child.end;
       }
+      if (holdSetOrder && e.tag === TAG.SET && !setInOrder(bytes, items)) throw badStamp('the items of a set are not in the order DER requires.');
       return;
     }
     const first = bytes[e.start];
@@ -185,7 +229,12 @@ export function validateDer(bytes, element) {
     } else if (e.tag === TAG.NULL) {
       if (length !== 0) throw badStamp('an empty value is not empty.');
     } else if (e.tag === TAG.BIT_STRING) {
-      if (length === 0 || first > 7) throw badStamp('a string of bits is not written as DER allows.');
+      // The first byte counts the unused bits of the last byte, 0 to 7; a
+      // string of no bits has none; and the unused bits are zero (X.690,
+      // sections 8.6.2 and 11.2.1).
+      if (length === 0 || first > 7 || (length === 1 && first !== 0) || (length > 1 && (bytes[e.end - 1] & ((1 << first) - 1)) !== 0)) {
+        throw badStamp('a string of bits is not written as DER allows.');
+      }
     }
   };
   walk(element, 0);

package/src/dev.d.ts

@@ -50,5 +50,5 @@ export function developmentSlip(fields: DevelopmentSlipFields): Promise<Developm
 /** The stub writer opened under a development slip, in one call. */
 export function developmentRecorder(
   fields: DevelopmentSlipFields,
-  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number; signWithin?: number },
+  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number; signWithin?: number; denials?: boolean; denialsPerHour?: number },
 ): Promise<Omit<DevelopmentSlip, 'book'> & { recorder: Recorder }>;

package/src/dev.js

@@ -110,7 +110,7 @@ export async function developmentSlip(fields = {}) {
  * The stub writer, opened under a development slip, in one call: the
  * shortest way to a first record. The same as developmentSlip followed by
  * openRecorder; "more" is passed to openRecorder (options, now,
- * countersignWithin, signWithin).
+ * countersignWithin, signWithin, denials, denialsPerHour).
  *
  * @param {object} fields the members of the slip; "actions" is required
  * @param {object} [more]

package/src/guard.js

@@ -98,6 +98,8 @@ function onlySealThirdUnchecked(result) {
       const third = sigs.length === 3 && by('Ed25519')?.state === 'valid' && by('ML-DSA-87')?.state === 'valid' && by(SEAL_THIRD)?.state === 'unavailable';
       if (third) excused++; else note(sigs);
       stamps(e.stamps ?? []);
+      // The witness statements beside it: each of their signatures counts, as for any record.
+      for (const w of e.witnesses ?? []) note(w.signatures ?? []);
     } else if (e.kind === 'slip') {
       if (!e.signature || e.signature.state === 'unavailable') missing.add(e.signature ? e.signature.alg : 'passkey');
       else if (e.signature.state === 'unchecked') skipped = true;
@@ -111,7 +113,7 @@ function onlySealThirdUnchecked(result) {
       if (!e.signature) skipped = true;
       else if (e.signature.state === 'unavailable') missing.add(e.signature.alg);
       stamps(e.stamps ?? []);
-    } else if (['refusal', 'terms', 'vouching', 'withdrawal', 'pass', 'acknowledgement'].includes(e.kind)) {
+    } else if (['refusal', 'terms', 'vouching', 'withdrawal', 'pass', 'acknowledgement', 'denial'].includes(e.kind)) {
       note(e.signatures ?? []);
     } else {
       skipped = true;
@@ -120,6 +122,15 @@ function onlySealThirdUnchecked(result) {
   for (const h of result.held ?? []) {
     stamps(h.stamps ?? []);
     for (const a of h.acknowledgements ?? []) note(a.signatures ?? []);
+    // A seal held elsewhere, handed over beside the book: excused as a seal in the book is.
+    if (h.kind === 'seal') {
+      const sigs = h.signatures ?? [];
+      const by = (method) => sigs.find((x) => x.method === method);
+      const third = sigs.length === 3 && by('Ed25519')?.state === 'valid' && by('ML-DSA-87')?.state === 'valid' && by(SEAL_THIRD)?.state === 'unavailable';
+      if (third) excused++;
+      else for (const x of sigs) if (x.state === 'unavailable') missing.add(x.method);
+      for (const w of h.witnesses ?? []) note(w.signatures ?? []);
+    }
   }
   return !skipped && missing.size === 0 && excused > 0 ? [SEAL_THIRD] : null;
 }

package/src/index.js

@@ -11,8 +11,13 @@
 //            writeStub (the agent), countersign, writeRefusal, writeTerms
 //            (the service), writeSeal (whoever keeps the book), blockStampItem
 //            (a proof from a public blockchain, to put beside a seal),
+//            writeWitness (a witness signs for a seal), openWitness (a witness
+//            that signs only for a seal that extends the last one it holds),
+//            openSealer (a central sealer, which seals books it is sent only
+//            the leaf fingerprints of: leafFingerprint),
 //            prepareCancellation + assembleCancellation (the person ends a slip),
 //            writeAcknowledgement (the agent's side says it was handed a cancellation),
+//            writeDenial (the agent's side says it did not take an action, and why),
 //            writeVouching, writeWithdrawal (an organisation vouches for a name),
 //            writePass (an agent hands part of its permission to a helper agent),
 //            writeBook, makeShow
@@ -33,8 +38,13 @@ export { writeStub, countersign } from './stub.js';
 export { writeRefusal, writeTerms } from './service.js';
 export { writePass } from './pass.js';
 export { writeSeal } from './seal.js';
+export { writeWitness, MAX_WITNESSES } from './witness.js';
+export { openWitness, bookIdentity, witnessProof } from './witnessing.js';
+export { openSealer, leafFingerprint } from './sealer.js';
+export { consistencyProof, inclusionPath } from './tree.js';
 export { blockStampItem } from './blockstamp.js';
 export { prepareCancellation, assembleCancellation, writeAcknowledgement, writeVouching, writeWithdrawal, VOUCHED_KINDS } from './standing.js';
+export { writeDenial, denialCodes, FINDING_CODES } from './denial.js';
 export { entryLine, writeBook, makeShow } from './book.js';
 export { generateKeySet, generateSealKeySet, signerFromKey } from './signatures.js';
 export { ACTION_KINDS, SHARED_ACTIONS, CONDUCT_RULES, RESERVED_PREFIX, actionKind } from './actions.js';

package/src/jws.js

@@ -66,6 +66,14 @@ export const KINDS = {
     type: 'provared.pass.v0',
     protected: ['{"typ":"vnd.provared.pass.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.pass.v0+json","alg":"ML-DSA-87"}'],
   },
+  denial: {
+    type: 'provared.denial.v0',
+    protected: ['{"typ":"vnd.provared.denial.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.denial.v0+json","alg":"ML-DSA-87"}'],
+  },
+  witness: {
+    type: 'provared.witness.v0',
+    protected: ['{"typ":"vnd.provared.witness.v0+json","alg":"Ed25519"}', '{"typ":"vnd.provared.witness.v0+json","alg":"ML-DSA-87"}'],
+  },
   seal: {
     type: 'provared.seal.v0',
     protected: [

package/src/keys.js

@@ -46,6 +46,50 @@ export function weakEd25519(bytes) {
   return y >= P || SMALL_ORDER_Y.has(y);
 }
 
+// The order L of the Ed25519 base point (RFC 8032, section 5.1). The number
+// S of a signature must be below it (RFC 8032, section 5.1.7); libraries
+// differ in whether they check, so a checker checks itself.
+const L = 2n ** 252n + 27742317777372353535851937790883648493n;
+
+/**
+ * Whether bytes are an Ed25519 signature that can never be valid, whatever
+ * the key: not 64 bytes; or its first half (the point R) is one under which
+ * anyone can sign or is written in more than one way; or its second half
+ * (the number S, little-endian) is not below L.
+ * @param {Uint8Array} signature
+ * @returns {boolean}
+ */
+export function badEd25519Signature(signature) {
+  if (signature.length !== 64) return true;
+  if (weakEd25519(signature.subarray(0, 32))) return true;
+  let s = 0n;
+  for (let i = 63; i >= 32; i--) s = (s << 8n) | BigInt(signature[i]);
+  return s >= L;
+}
+
+// The curve P-256 (FIPS 186-5, section D.1.2.3): y^2 = x^3 - 3x + b over
+// the whole numbers modulo p. A key whose two halves are not a point on it
+// can check no signature, and libraries report it in different ways, so a
+// checker refuses it itself.
+const P256_P = 2n ** 256n - 2n ** 224n + 2n ** 192n + 2n ** 96n - 1n;
+const P256_B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn;
+
+/**
+ * Whether two halves of 32 bytes each (x and y, big-endian) are a point on
+ * the curve P-256, each below p.
+ * @param {Uint8Array} x
+ * @param {Uint8Array} y
+ * @returns {boolean}
+ */
+export function onP256(x, y) {
+  let X = 0n;
+  let Y = 0n;
+  for (const b of x) X = (X << 8n) | BigInt(b);
+  for (const b of y) Y = (Y << 8n) | BigInt(b);
+  if (X >= P256_P || Y >= P256_P) return false;
+  return (Y * Y) % P256_P === (((X * X * X - 3n * X + P256_B) % P256_P) + P256_P) % P256_P;
+}
+
 function bad(where, why) {
   return new Refusal('bad-key', `${where}: ${why}`);
 }
@@ -94,9 +138,12 @@ export function checkKey(jwk, allowed, where) {
     if (bytesOf(jwk, 'pub', where).length !== 64) throw bad(where, 'an SLH-DSA-SHA2-256s public key is 64 bytes.');
   } else if (alg === 'ES256') {
     if (jwk.kty !== 'EC' || jwk.crv !== 'P-256') throw bad(where, 'an ES256 key has kty EC and crv P-256.');
-    if (bytesOf(jwk, 'x', where).length !== 32 || bytesOf(jwk, 'y', where).length !== 32) {
+    const x = bytesOf(jwk, 'x', where);
+    const y = bytesOf(jwk, 'y', where);
+    if (x.length !== 32 || y.length !== 32) {
       throw bad(where, 'the two halves of a P-256 public key are 32 bytes each.');
     }
+    if (!onP256(x, y)) throw bad(where, 'a P-256 public key must be a point on the curve, each half below the prime of the curve.');
   } else {
     if (jwk.kty !== 'RSA' || jwk.e !== 'AQAB') throw bad(where, 'an RS256 key has kty RSA and e AQAB.');
     const n = bytesOf(jwk, 'n', where);

package/src/recorder.js

@@ -38,12 +38,18 @@ import { KEY_SET_METHODS } from './keys.js';
 import { CLOCK_ALLOWANCE_MS, MAX_STAMPS } from './seal.js';
 import { holdSigningKeys } from './signatures.js';
 import { writeAcknowledgement } from './standing.js';
+import { denialCodes, writeDenial } from './denial.js';
 import { validateRequest, writeStub } from './stub.js';
 
 /** How long the other side is given to hand back its countersignature, unless the caller says otherwise: 30 seconds. */
 export const COUNTERSIGN_WITHIN_MS = 30000;
 /** How long a signer is given for each signature, unless the caller says otherwise: 30 seconds. */
 export const SIGN_WITHIN_MS = 30000;
+/** The most denials a writer writes in any hour, unless the caller says otherwise: 600. */
+export const DENIALS_PER_HOUR = 600;
+// The most a caller may set it to: as many as a book may hold entries.
+const MAX_DENIALS_PER_HOUR = 100000;
+const HOUR_MS = 3600000;
 // The longest wait a timer can hold.
 const MAX_WAIT_MS = 2 ** 31 - 1;
 // "detailsAfter" in "act": the most documents it may add, and the most the
@@ -227,11 +233,29 @@ function plainHeld(copy) {
  * @param {number} [o.countersignWithin] how long the other side is given to countersign, in milliseconds; defaults to 30,000
  * @param {number} [o.signWithin] how long a signer is given for each signature, in milliseconds; defaults to 30,000.
  *   After that the action is not taken and nothing is written; a late answer is not used
- * @returns {Promise<object>} the writer: before, record, act, book, check, cancellations, add
+ * @param {boolean} [o.denials] true to write a denial (format description, section 28) whenever "act" does not take an
+ *   action, and to let "deny" write one; defaults to false, and then no denial is written
+ * @param {number} [o.denialsPerHour] the most denials written in any hour, by the clock; defaults to 600. Each
+ *   denial this writer writes, or is handed through "add", counts at the clock's time when it joins the book, whatever
+ *   date it states; those the book held when the writer was opened count at the dates they state. Past the limit, a
+ *   denial is not written, and the answers count those not written
+ * @returns {Promise<object>} the writer: before, record, act, deny, book, check, cancellations, add
  * @throws {Refusal} "record-not-sound" if the book so far has a problem; "bad-field" or "bad-key" if an item of
  *   privateKeys is neither a key nor a signer, or is a signer that holds another key than the slip, or the pass, names
  */
-export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass, options = {}, now = Date.now, countersignWithin = COUNTERSIGN_WITHIN_MS, signWithin = SIGN_WITHIN_MS }) {
+export async function openRecorder({
+  book,
+  slip,
+  privateKeys,
+  issuerKeys,
+  pass,
+  options = {},
+  now = Date.now,
+  countersignWithin = COUNTERSIGN_WITHIN_MS,
+  signWithin = SIGN_WITHIN_MS,
+  denials = false,
+  denialsPerHour = DENIALS_PER_HOUR,
+}) {
   if (typeof now !== 'function') throw new Refusal('bad-field', 'now: must be a function that gives the time in milliseconds.');
   // A clock that gives anything but a time is a clock that failed: no comparison with it would hold.
   const device = now;
@@ -246,6 +270,10 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
   if (!(Number.isFinite(signWithin) && signWithin >= 1 && signWithin <= MAX_WAIT_MS)) {
     throw new Refusal('bad-field', 'signWithin: must be a number of milliseconds from 1 to 2,147,483,647.');
   }
+  if (typeof denials !== 'boolean') throw new Refusal('bad-field', 'denials: must be true or false.');
+  if (!(Number.isInteger(denialsPerHour) && denialsPerHour >= 1 && denialsPerHour <= MAX_DENIALS_PER_HOUR)) {
+    throw new Refusal('bad-field', 'denialsPerHour: must be a whole number from 1 to 100,000.');
+  }
   // Whom the writer trusts is fixed when it is opened: read once, as a whole
   // check reads it, and copied. The passkeys it trusts are its own
   // "issuerKeys", whatever the options say, read through the same fixed
@@ -360,12 +388,23 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
   const { result } = await standing();
   if (result.summary.problemFound) throw notWritten('A problem was found in the record so far. It must be looked at before the agent acts again.');
   let after = lastStub(result.entries);
+  // The times of the denials of this writer's own chain, which the hourly
+  // limit counts: those the book held when the writer was opened, at the
+  // dates they state; and each one that joins the book since, at the
+  // clock's time when it joined, whatever date it states (a denial may be
+  // dated up to 300 seconds back, and counting it there would let more
+  // than the limit be written in an hour of the clock).
+  const ownDenial = (e) => e.kind === 'denial' && e.problems.length === 0 && e.slip === slip && (e.pass ?? null) === (pass ?? null);
+  const denialTimes = result.entries.filter(ownDenial).map((e) => parseTime(e.content.when));
+  // How many denials were not written because of the hourly limit, since the writer was opened.
+  let notWrittenDenials = 0;
   // What was given at opening: the first sound acknowledgement of this
   // writer's own agent that came with a cancellation is the one it goes on
   // handing back; a cancellation that the book does not hold waits to be
   // written.
+  // (Seals held elsewhere, handed over with the options, come after the cancellations, and are not these.)
   result.held.forEach((h, i) => {
-    if (!h.used) return;
+    if (h.kind !== 'cancellation' || !h.used) return;
     // The person's cancellation of this writer's own slip, given when it was opened, stops it from the start.
     if (h.slip === slip) stopped = true;
     h.acknowledgements.forEach((a, j) => {
@@ -390,7 +429,7 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
   // holds without it, follows the cancellation into the book: it was still
   // waiting when the writer that signed it handed it back.
   result.held.forEach((h, i) => {
-    if (h.used && h.slip === slip && h.inBook !== null && acknowledged.has(h.fingerprint) && !written.has(h.fingerprint)) waiting.set(h.fingerprint, given[i].cancellation);
+    if (h.kind === 'cancellation' && h.used && h.slip === slip && h.inBook !== null && acknowledged.has(h.fingerprint) && !written.has(h.fingerprint)) waiting.set(h.fingerprint, given[i].cancellation);
   });
   // The services the slip names, to check a countersignature before it goes into the book.
   const slipEntry = result.entries.find((e) => e.kind === 'slip' && e.fingerprint === slip);
@@ -446,6 +485,10 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
       detailsAfter: more.detailsAfter,
       hasApproval: more.approval !== undefined && more.approval !== null,
       approval: undefined,
+      // For "act": false writes no denial for this call. For "deny": who said no, and why.
+      denial: more.denial,
+      source: more.source,
+      codes: more.codes === undefined ? undefined : plain(more.codes, 'codes'),
     };
     if (call.hasApproval) {
       try {
@@ -615,6 +658,54 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
     return { fits: true, checked };
   };
 
+  // A denial: the agent's side states that it did not take an action, and
+  // why. It is written into the book only if the book still passes its check
+  // with it and it is not dated ahead of the clock; it is tried on a reader
+  // split off the book's own, as a stub is, because a denial changes nothing
+  // read before it. At most "denialsPerHour" are written in any hour, by
+  // the clock: past it, none is written and the writer counts it. Whatever
+  // happens, the answer says what was done; nothing is thrown, so a denial
+  // never stands in the way of what the writer does next. The request is the
+  // copy made when the call was made, and only its action, amount, service
+  // and documents are written: the documents are fingerprints, never the
+  // documents themselves.
+  const denialAnswer = (problem) => ({ written: false, problem, notWritten: notWrittenDenials });
+  const writeDenialLine = async (request, source, codes, when) => {
+    try {
+      const at = now();
+      const t = when ?? at;
+      if (!Number.isFinite(t)) return denialAnswer({ code: 'bad-field', message: 'when: does not give a time.' });
+      if (aheadOfClock(t) || behindClock(t)) {
+        return denialAnswer({ code: 'record-not-sound', message: 'The denial was not written: a denial is written when the action is refused, so its date must be within 300 seconds of the stub writer\'s clock.' });
+      }
+      const inHour = denialTimes.filter((d) => d > at - HOUR_MS).length;
+      if (inHour >= denialsPerHour) {
+        notWrittenDenials++;
+        return denialAnswer({
+          code: 'denials-over-limit',
+          message: `The denial was not written: this stub writer has written ${denialsPerHour} denials in the last hour, the most it may. Since it was opened, ${notWrittenDenials} were not written for that reason.`,
+        });
+      }
+      const fields = { slip, action: request.action, source, when: t };
+      for (const name of ['amount', 'with', 'details']) if (request[name] !== undefined) fields[name] = request[name];
+      if (pass) fields.pass = pass;
+      if (codes) fields.codes = codes;
+      const made = await writeDenial(fields, signing);
+      const line = entryLine({ denial: made.record });
+      if (utf8(line).length > MAX_LINE_BYTES) return denialAnswer({ code: 'too-large', message: 'The denial is longer than a line of a book may be.' });
+      const tried = forkCarried(carried);
+      await carryOn(tried, line + '\n');
+      const checked = (await standing(tried)).result;
+      if (checked.summary.problemFound) return denialAnswer({ code: 'record-not-sound', message: 'The denial was not written: with it, the book would not pass its check.' });
+      carried = promoteCarried(tried);
+      text += line + '\n';
+      denialTimes.push(at);
+      return { written: true, fingerprint: made.fingerprint, line, notWritten: notWrittenDenials };
+    } catch (e) {
+      return denialAnswer(problemFrom(e));
+    }
+  };
+
   // A cancellation held beside the book is written into the book as soon as
   // it can be: once the date it gives is no longer ahead of the clock. It
   // goes in as the entry it is, without the acknowledgements that came with
@@ -924,7 +1015,10 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
             stop(problemFrom(e));
           }
         }
-        if (!answer.allowed) return { done: false, answer };
+        if (!answer.allowed) {
+          if (!denials || call.denial === false) return { done: false, answer };
+          return { done: false, answer, denial: await writeDenialLine(call.request, 'check', denialCodes(answer), undefined) };
+        }
         const outcome = await runInside(perform);
         if (!hasLater) {
           const stub = await commit(await countersigned(made, call), made, tried);
@@ -980,6 +1074,35 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
       });
     },
 
+    /**
+     * Write a denial for an action that was not taken, where "act" did not
+     * write one: the person refused, or gave no approval when asked
+     * ("person"); a rule of the software around the agent, outside the slip,
+     * said no ("rule"); or the check before acting said no, and the caller
+     * asked "act" to write no denial for that call ("check", with the codes
+     * of that answer: denialCodes gives them). Nothing is taken and no stub
+     * is written. A writer opened without "denials: true" writes none.
+     * @param {{action: string, amount?: object, with?: string, details?: object[]}} request what was asked for
+     * @param {{source: 'check'|'person'|'rule', codes?: string[], when?: number|Date}} more "codes" only for "check";
+     *   "when" defaults to the clock, and must be within 300 seconds of it
+     * @returns {Promise<{written: boolean, fingerprint?: string, line?: string, problem?: object, notWritten: number}>}
+     *   "notWritten": how many denials were not written because of the hourly limit since the writer was opened
+     */
+    deny(request, more = {}) {
+      return calling(request, more, async (call) => {
+        if (!denials) return denialAnswer({ code: 'bad-field', message: 'This stub writer was opened without "denials: true", so it writes no denial.' });
+        if (call.source !== 'check' && call.source !== 'person' && call.source !== 'rule') return denialAnswer({ code: 'bad-field', message: 'source: must be "check", "person" or "rule".' });
+        let at;
+        try {
+          at = now();
+        } catch (e) {
+          return denialAnswer(problemFrom(e));
+        }
+        await writeWaiting(at);
+        return writeDenialLine(call.request, call.source, call.codes, call.when);
+      });
+    },
+
     /** The book as it now stands. */
     book() {
       return text;
@@ -1220,6 +1343,7 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
             // An added stub of this writer's own chain moves its place in the chain on.
             after = lastStub(whole.checked.entries);
             const last = whole.checked.entries.at(-1);
+            if (ownDenial(last)) denialTimes.push(at);
             if (last.kind === 'cancellation' && last.slip === slip && last.verified === 'all') {
               stopped = true;
               return { acknowledgement: await acknowledge(last.fingerprint, JSON.parse(line).cancellation, true, at) };
@@ -1275,5 +1399,7 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
       });
     },
   };
+  // Whether this writer writes denials, as it was opened. It cannot be changed.
+  Object.defineProperty(writer, 'denials', { value: denials, enumerable: true });
   return writer;
 }