provared 0.4.0 → 0.6.0

package/src/recorder.js

@@ -32,16 +32,36 @@
 // objects changes nothing.
 
 import { MAX_LINE_BYTES, answerOf, carryOn, checkCountersignature, entryLine, fixedOptions, forkCarried, latestWhen, promoteCarried, startCarried } from './book.js';
-import { Refusal, canonicalJson, fingerprint, fromBase64url, parseTime, problemFrom, utf8 } from './encoding.js';
-import { checkBeforeRead } from './guard.js';
+import { Refusal, canonicalJson, fingerprint, formatTime, fromBase64url, parseTime, problemFrom, utf8 } from './encoding.js';
+import { checkBeforeRead, lineBound } from './guard.js';
+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 { writeStub } from './stub.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
+// request may name beside them, so that a stub never names more than 32.
+const MAX_DETAILS_AFTER = 4;
+const MAX_DETAILS_BEFORE = 32 - MAX_DETAILS_AFTER;
+// The room kept for them: the largest documents a stub may name, a name of
+// 200 characters that are each written as six (a control character, which
+// the one form of RFC 8785 writes as "\u00XX"), with a fingerprint.
+const ROOM_DOCUMENT = Object.freeze({ name: '\u0001'.repeat(200), sha256: 'A'.repeat(43) });
+// The stub with the further documents could not be made or signed.
+class NotAdded extends Error {}
 // The most cancellations a check may be handed beside a book (book.js).
 const MAX_HANDED = 16;
 
@@ -204,17 +224,38 @@ function plainHeld(copy) {
  * @param {object} o
  * @param {string} o.book the book so far: at least the slip
  * @param {string} o.slip the fingerprint of the slip
- * @param {CryptoKey[]} o.privateKeys the agent's private keys: Ed25519, then ML-DSA-87
+ * @param {any[]} o.privateKeys the agent's private keys, or signers (signatures.js): Ed25519, then ML-DSA-87
  * @param {string[]} o.issuerKeys the thumbprints of the passkeys this agent's software trusts; a slip from any other key allows nothing
  * @param {string} [o.pass] for a helper agent: the fingerprint of the pass it acts under
  * @param {object} [o.options] further options for the checker (sealKeys, stampServices, blocks, vouchers, cancellations).
  *   They are read once, as a whole check reads them, and fixed
  * @param {() => number} [o.now] the clock, in milliseconds; defaults to the device's. "act" takes an action at the clock's time, and nothing is written that is dated more than 300 seconds ahead of it
  * @param {number} [o.countersignWithin] how long the other side is given to countersign, in milliseconds; defaults to 30,000
- * @returns {Promise<object>} the writer: before, record, act, book, check, cancellations, add
- * @throws {Refusal} "record-not-sound" if the book so far has a problem
+ * @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
+ * @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 }) {
+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;
@@ -226,6 +267,13 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
   if (!(Number.isFinite(countersignWithin) && countersignWithin >= 1 && countersignWithin <= MAX_WAIT_MS)) {
     throw new Refusal('bad-field', 'countersignWithin: must be a number of milliseconds from 1 to 2,147,483,647.');
   }
+  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
@@ -340,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) => {
@@ -370,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);
@@ -403,6 +462,17 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
     }
   };
 
+  // The agent's keys, or signers (signatures.js). A signer is read once,
+  // here, and must hold the keys that the slip, or the pass this writer
+  // acts under, names for its agent. Each of its signatures is waited for
+  // "signWithin" at most, under the same mark as an action, so that a
+  // signer that calls the writer is refused at once; after that nothing is
+  // written, and a late answer is not used. Keys of the platform are used
+  // as they always were.
+  const passEntry = pass ? result.entries.find((e) => e.kind === 'pass' && e.fingerprint === pass) : undefined;
+  const ownKeys = pass ? passEntry?.content?.to?.keys : slipEntry?.content?.agent?.keys;
+  const signing = await holdSigningKeys(privateKeys, KEY_SET_METHODS, ownKeys, signWithin, runInside);
+
   // What a call hands in, copied at the moment of the call.
   const asked = (request, more) => {
     if (request === null || typeof request !== 'object') throw new Refusal('bad-field', 'The request must be an object.');
@@ -412,8 +482,13 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
       when: more.when === undefined || more.when === null ? undefined : timeOf(more.when),
       terms: more.terms,
       countersign: more.countersign,
+      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 {
@@ -448,6 +523,20 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
     if (call.hasApproval) proposal.approval = call.approval;
     return proposal;
   };
+  // Whether the stub for this request, with the countersignature the check
+  // before acting keeps room for, would still fit a line with the largest
+  // further documents that "detailsAfter" may add: the same bound as the
+  // check before acting uses, over the request with those documents.
+  const roomForMore = (request, when) => {
+    try {
+      const c = { action: request.action, when: formatTime(when) };
+      for (const name of ['amount', 'with']) if (request[name] !== undefined) c[name] = request[name];
+      c.details = [...(Array.isArray(request.details) ? request.details : []), ...Array(MAX_DETAILS_AFTER).fill(ROOM_DOCUMENT)];
+      return lineBound(c, undefined) <= MAX_LINE_BYTES;
+    } catch {
+      return false;
+    }
+  };
   const aheadOfClock = (when) => when > now() + CLOCK_ALLOWANCE_MS;
   const behindClock = (when) => when < now() - CLOCK_ALLOWANCE_MS;
 
@@ -491,7 +580,7 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
         pass,
         when,
       },
-      privateKeys,
+      signing,
     );
     const entry = { stub: stub.record };
     if (call.hasApproval) entry.approval = call.approval;
@@ -569,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
@@ -644,7 +781,7 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
       }
       let made;
       try {
-        made = (await writeAcknowledgement({ slip, cancellation, pass, when }, privateKeys)).record;
+        made = (await writeAcknowledgement({ slip, cancellation, pass, when }, signing)).record;
       } catch {
         return undefined;
       }
@@ -808,10 +945,28 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
      * If taking the action never ends, the writer waits: it cannot know
      * what happened.
      *
+     * Where an identifier or a document comes only with what the action
+     * gives back (the identifier a platform gave the call, say), "detailsAfter"
+     * names it: a function of what the action gave, that gives up to four
+     * further documents ({name, sha256} each). The stub is then signed again
+     * after the action, with them, still in this call's turn, so that no
+     * other call comes between; it keeps the time the action began. The
+     * request may then name at most 28 documents, and no approval may be
+     * given (an approval covers exactly the documents the person saw).
+     * "detailsAfter" is given as long as the other side is given to
+     * countersign. If it fails, gives no answer in time, gives something
+     * that is not a list of at most four documents, or gives documents with
+     * which the stub would not pass the check of the book, the stub made
+     * before the action is written, without them: an action that was taken
+     * always gets its stub. "detailsAfter" in the answer says what was added
+     * and, where nothing was, why.
+     *
      * @param {{action: string, amount?: object, with?: string, details?: object[]}} request
      * @param {() => Promise<any>} perform takes the action; it must not call this writer
      * @param {object} [more] as for "record"; "when" defaults to the clock and must be within 300 seconds of it
-     * @returns {Promise<{done: boolean, answer: object, result?: any, stub?: object}>}
+     * @param {(result: any) => object[]|Promise<object[]>} [more.detailsAfter] further documents, from what the action gave; it must not call this writer
+     * @returns {Promise<{done: boolean, answer: object, result?: any, stub?: object, detailsAfter?: {added: number, problem: object|null}}>}
+     *   "detailsAfter" is there only where it was given and the action was taken
      */
     act(request, perform, more = {}) {
       return calling(request, more, async (call) => {
@@ -837,6 +992,19 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
             message: 'The slip asks for the other side to countersign this action, and the stub writer was given no way to ask for a countersignature.',
           });
         }
+        const later = call.detailsAfter;
+        const hasLater = later !== undefined && later !== null;
+        if (hasLater) {
+          const named = Array.isArray(call.request.details) ? call.request.details.length : 0;
+          if (typeof later !== 'function') stop({ code: 'bad-field', message: 'detailsAfter: must be a function of what the action gives.' });
+          else if (call.hasApproval) {
+            stop({ code: 'bad-field', message: 'detailsAfter: cannot be used with an approval. An approval covers exactly the documents the person saw, so no document may be added to the stub after the action.' });
+          } else if (named > MAX_DETAILS_BEFORE) {
+            stop({ code: 'bad-field', message: `detailsAfter: the request may then name at most ${MAX_DETAILS_BEFORE} documents, so that there is room for ${MAX_DETAILS_AFTER} more.` });
+          } else if (answer.allowed && !roomForMore(call.request, when)) {
+            stop({ code: 'too-large', message: 'With room for the documents that "detailsAfter" may add, the record of this action would be longer than a line of a book may be.' });
+          }
+        }
         let made;
         let tried;
         if (answer.allowed) {
@@ -847,10 +1015,91 @@ 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);
-        const stub = await commit(await countersigned(made, call), made, tried);
-        return { done: true, answer, result: outcome, stub };
+        if (!hasLater) {
+          const stub = await commit(await countersigned(made, call), made, tried);
+          return { done: true, answer, result: outcome, stub };
+        }
+        // The further documents, from what the action gave back. The stub
+        // with them is signed now, still in this turn, and keeps the time
+        // the action began. If anything about them fails, the stub made
+        // before the action, which is known to fit, is the one written: an
+        // action that was taken always gets its stub.
+        const further = { added: 0, problem: null };
+        let chosen = made;
+        let chosenTried = tried;
+        try {
+          const given = await runInside(() => within(Promise.resolve(later(outcome)), countersignWithin));
+          let documents;
+          try {
+            documents = given === undefined || given === null ? [] : clone(given);
+          } catch {
+            throw new Refusal('bad-field', 'detailsAfter: must give a list of documents, as plain data.');
+          }
+          if (!Array.isArray(documents)) throw new Refusal('bad-field', 'detailsAfter: must give a list of documents.');
+          if (documents.length > MAX_DETAILS_AFTER) throw new Refusal('bad-field', `detailsAfter: gave ${documents.length} documents; it may give ${MAX_DETAILS_AFTER} at most.`);
+          if (documents.length > 0) {
+            const base = Array.isArray(call.request.details) ? call.request.details : [];
+            const all = [...base, ...documents];
+            // The documents are checked first, so that a refusal of them says why in its own words.
+            validateRequest({ action: call.request.action, details: all });
+            const withThem = { ...call, request: { ...call.request, details: all } };
+            let next;
+            try {
+              next = await composeStub(withThem, when);
+            } catch {
+              // The stub made before the action is the one written: say so, whatever failed.
+              throw new NotAdded('The stub with the further documents could not be made or signed, so the stub made before the action was written, without them.');
+            }
+            chosenTried = await fitsBook(next, 'With the documents that "detailsAfter" gave, the stub would not pass the check of the book.');
+            chosen = next;
+            further.added = documents.length;
+          }
+        } catch (e) {
+          chosen = made;
+          chosenTried = tried;
+          further.problem =
+            e instanceof NotAdded
+              ? { code: 'details-not-added', message: e.message }
+              : e instanceof Refusal
+                ? problemFrom(e)
+                : { code: 'details-not-added', message: 'detailsAfter failed, or gave no answer in time, so the stub was written without further documents.' };
+        }
+        const stub = await commit(await countersigned(chosen, call), chosen, chosenTried);
+        return { done: true, answer, result: outcome, stub, detailsAfter: further };
+      });
+    },
+
+    /**
+     * 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);
       });
     },
 
@@ -1094,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) };
@@ -1149,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;
 }

package/src/seal.js

@@ -6,7 +6,7 @@ import { Refusal, fingerprint, formatTime, fromBase64url, randomId, toBase64url,
 import * as f from './fields.js';
 import { KINDS, encodeContent, protectedHeaders, signingInput, withinSize } from './jws.js';
 import { SEAL_METHODS, checkSealKeySet } from './keys.js';
-import { sign } from './signatures.js';
+import { signingKeys } from './signatures.js';
 import { MAX_STAMP_BYTES } from './timestamp.js';
 import { treeRoot } from './tree.js';
 
@@ -25,7 +25,7 @@ export const CLOCK_ALLOWANCE_MS = 300 * 1000;
  * @param {any} c
  */
 export function validateSealContent(c) {
-  f.members(c, ['by', 'id', 'root', 'size', 'type', 'when'], ['previous'], 'seal');
+  f.members(c, ['by', 'id', 'root', 'size', 'type', 'when'], ['book', 'previous'], 'seal');
   f.id(c.id, 'id');
   f.members(c.by, ['keys', 'name'], [], 'by');
   f.label(c.by.name, 'by.name');
@@ -34,6 +34,13 @@ export function validateSealContent(c) {
   if (c.size < 1) throw f.fail('size', 'must be 1 or more.');
   f.fingerprintText(c.root, 'root');
   if (Object.hasOwn(c, 'previous')) f.fingerprintText(c.previous, 'previous');
+  // The number of the book among the books a recorder keeps under one permission (section 21.6). Absent for the
+  // first book, so that every seal written before numbers existed reads as it did; written only from 2.
+  if (Object.hasOwn(c, 'book')) {
+    f.wholeNumber(c.book, 'book');
+    if (c.book < 2) throw f.fail('book', 'must be 2 or more: the first book has no number.');
+    if (!Object.hasOwn(c, 'previous')) throw f.fail('previous', 'is missing: every seal of a book after the first names the seal before it, and the first names the last seal of the book before.');
+  }
   f.time(c.when, 'when');
 }
 
@@ -102,30 +109,52 @@ export async function keySetFingerprint(keys) {
  * @param {string} book the book so far
  * @param {object} fields
  * @param {{keys: object[], name: string}} fields.by the recorder's public key set and its name (a label)
- * @param {string} [fields.previous] the fingerprint of the seal before this one in the book, if there is one
+ * @param {string} [fields.previous] the fingerprint of the seal before this one in the book, if there is one; for
+ *   the first seal of a book after the first, the fingerprint of the last seal of the book before
+ * @param {number} [fields.book] the book's number among the books the recorder keeps under one permission (section
+ *   21.6): 2 or more for a book after the first; 1 or none for the first, which carries no number
  * @param {number|Date} [fields.when] defaults to now
- * @param {any[]} privateKeys the recorder's private keys, in the order of the key set
+ * @param {any[]} privateKeys the recorder's private keys, or signers (signatures.js), in the order of the key set. A signer must hold the key "by" names in its place
  * @returns {Promise<{record: object, fingerprint: string, fingerprintBytes: Uint8Array}>}
  *   "fingerprintBytes" is what a time-stamp service is asked to stamp
  */
 export async function writeSeal(book, fields, privateKeys) {
   const lines = book.split('\n');
   if (lines[lines.length - 1] === '') lines.pop();
+  return sealOver(lines.length, await treeRoot(lines.map(utf8)), fields, privateKeys);
+}
+
+/**
+ * Sign a seal over a number of entries and their top fingerprint, worked out
+ * by the caller: writeSeal from the book, and the central sealer (sealer.js)
+ * from the tree it built from the leaf fingerprints it was sent. One path, so
+ * that the two give the same seal for the same book. Not part of the public
+ * interface: a size and a top fingerprint handed in from outside are never
+ * signed (choice 388).
+ * @param {number} size
+ * @param {Uint8Array} root
+ * @param {object} fields as writeSeal takes them
+ * @param {any[]} privateKeys
+ */
+export async function sealOver(size, root, fields, privateKeys) {
   const content = {
     type: KINDS.seal.type,
     id: fields.id ?? randomId(),
     by: fields.by,
-    size: lines.length,
-    root: toBase64url(await treeRoot(lines.map(utf8))),
+    size,
+    root: toBase64url(root),
     when: formatTime(fields.when ?? Date.now()),
   };
   if (fields.previous) content.previous = fields.previous;
+  // The book's number: 1, or none, for the first book, which then carries no number.
+  if (fields.book !== undefined && fields.book !== null && fields.book !== 1) content.book = fields.book;
   validateSealContent(content);
   const { contentBytes, payloadB64 } = encodeContent(content);
   const headers = protectedHeaders('seal');
+  const signers = await signingKeys(privateKeys, SEAL_METHODS, content.by.keys);
   const signatures = [];
   for (let i = 0; i < SEAL_METHODS.length; i++) {
-    const signature = await sign(SEAL_METHODS[i], privateKeys[i], signingInput(headers[i], payloadB64));
+    const signature = await signers[i](signingInput(headers[i], payloadB64));
     signatures.push({ protected: headers[i], signature: toBase64url(signature) });
   }
   const name = await fingerprint(contentBytes);