provared 0.3.0 → 0.5.0

package/src/documents.js

@@ -0,0 +1,149 @@
+// The reserved names of the documents a stub names (format description,
+// section 27), and the fingerprints they stand for.
+//
+// A stub's "details" names documents by their fingerprints. Most names are
+// labels that whoever wrote the stub chose. Names that begin "provared."
+// are reserved: each one on the list below says exactly which text its
+// fingerprint is made from, so that an investigator who holds that text
+// (the call's arguments, the HTTP request, the identifier a platform's own
+// log shows for the call) can work the fingerprint out again and match
+// the stub to it, without either side's help.
+
+import { Refusal, fingerprint, sha256, toBase64url, utf8 } from './encoding.js';
+
+/** Every document name that begins with this is reserved for the list below. */
+export const RESERVED_DOCUMENT_PREFIX = 'provared.';
+
+/** The reserved document names, and the exact text whose SHA-256 each one gives. */
+export const DOCUMENT_NAMES = Object.freeze({
+  'provared.arguments': "The call's arguments, written in the one form of RFC 8785.",
+  'provared.http-request': 'The request, written as the signature base of RFC 9421, section 2.5, over "@method", "@target-uri" and, where there is a body, "content-digest" (RFC 9530, with SHA-256). No header is covered.',
+  'provared.http-response': 'The answer, written as the signature base of RFC 9421, section 2.5, over "@status" and, where there is a body, "content-digest" (RFC 9530, with SHA-256). No header is covered.',
+  'provared.trace-id': 'The trace-id of the W3C Trace Context "traceparent" header that the agent\'s side sent, which that standard writes as 32 lower-case hexadecimal characters. Its form is not checked.',
+  'provared.request-id': "An identifier that the agent's side chose and sent with the call, exactly as sent.",
+  'provared.event-id': 'An identifier that the platform gave for the call, exactly as it gave it.',
+  'provared.error': "The error text that the agent's software was given, exactly as given.",
+});
+
+/**
+ * The reserved names that may appear more than once in one record: an
+ * identifier from each of several systems. Every other reserved name may
+ * appear once at most.
+ */
+export const REPEATABLE_DOCUMENT_NAMES = Object.freeze(['provared.trace-id', 'provared.request-id', 'provared.event-id']);
+
+/**
+ * Whether a document name is reserved and not on the list: such a name is refused.
+ * @param {string} name
+ */
+export function isUnknownReservedDocument(name) {
+  return typeof name === 'string' && name.startsWith(RESERVED_DOCUMENT_PREFIX) && !Object.hasOwn(DOCUMENT_NAMES, name);
+}
+
+// A method is a token of RFC 9110, section 5.6.2: one or more of these.
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// An address is taken exactly as it was sent, never rewritten: so it must
+// already be in the form a request carries, an absolute http or https
+// address of visible ASCII characters, with no fragment (which is never
+// sent).
+const ADDRESS = /^https?:\/\/[\x21-\x22\x24-\x7e]+$/;
+
+function body(value, path) {
+  // Nothing given, or null: the message has no body.
+  if (value === undefined || value === null) return undefined;
+  if (!(value instanceof Uint8Array)) throw new Refusal('bad-field', `${path}: must be the bytes of the body, as sent.`);
+  return value;
+}
+
+// Base64 with padding (RFC 4648, section 4), as a byte sequence of RFC 8941 is written.
+function base64(bytes) {
+  const text = toBase64url(bytes).replace(/-/g, '+').replace(/_/g, '/');
+  return text + '='.repeat((4 - (text.length % 4)) % 4);
+}
+
+// The Content-Digest field value of RFC 9530, with SHA-256 only.
+async function contentDigest(bytes) {
+  return `sha-256=:${base64(await sha256(bytes))}:`;
+}
+
+// The signature base of RFC 9421, section 2.5: a line for each component,
+// "<identifier>: <value>" and a line feed, then the line
+// "@signature-params" with the list of the components and no parameters,
+// and no line feed after it. Nothing is signed with it: it is only an exact
+// way to write a request or an answer as text.
+function signatureBase(components) {
+  const lines = components.map(([id, value]) => `"${id}": ${value}\n`);
+  return lines.join('') + `"@signature-params": (${components.map(([id]) => `"${id}"`).join(' ')})`;
+}
+
+/**
+ * The text that the reserved name "provared.http-request" is made from.
+ * @param {{method: string, url: string, body?: Uint8Array}} r
+ * @returns {Promise<string>}
+ */
+export async function httpRequestBase(r) {
+  if (r === null || typeof r !== 'object') throw new Refusal('bad-field', 'The request must be an object.');
+  const { method, url } = r;
+  const given = body(r.body, 'body');
+  if (typeof method !== 'string' || !TOKEN.test(method)) throw new Refusal('bad-field', 'method: must be the method of the request as sent, a token such as GET or POST.');
+  if (typeof url !== 'string' || !ADDRESS.test(url)) {
+    throw new Refusal('bad-field', 'url: must be the address of the request as sent: an absolute http or https address of visible ASCII characters, with no fragment.');
+  }
+  const components = [
+    ['@method', method],
+    ['@target-uri', url],
+  ];
+  if (given !== undefined) components.push(['content-digest', await contentDigest(given)]);
+  return signatureBase(components);
+}
+
+/**
+ * The text that the reserved name "provared.http-response" is made from.
+ * @param {{status: number, body?: Uint8Array}} r
+ * @returns {Promise<string>}
+ */
+export async function httpResponseBase(r) {
+  if (r === null || typeof r !== 'object') throw new Refusal('bad-field', 'The answer must be an object.');
+  const { status } = r;
+  const given = body(r.body, 'body');
+  if (!Number.isInteger(status) || status < 100 || status > 599) throw new Refusal('bad-field', 'status: must be the status code of the answer, a whole number from 100 to 599.');
+  const components = [['@status', String(status)]];
+  if (given !== undefined) components.push(['content-digest', await contentDigest(given)]);
+  return signatureBase(components);
+}
+
+/**
+ * The fingerprint of an HTTP request, for the document "provared.http-request".
+ * @param {{method: string, url: string, body?: Uint8Array}} r the method and the address exactly as sent, and the body's bytes where there is a body
+ * @returns {Promise<string>}
+ * @throws {Refusal} "bad-field" if the request is not as set out
+ */
+export async function httpRequestFingerprint(r) {
+  return fingerprint(utf8(await httpRequestBase(r)));
+}
+
+/**
+ * The fingerprint of an HTTP answer, for the document "provared.http-response".
+ * @param {{status: number, body?: Uint8Array}} r the status code, and the body's bytes where there is a body
+ * @returns {Promise<string>}
+ * @throws {Refusal} "bad-field" if the answer is not as set out
+ */
+export async function httpResponseFingerprint(r) {
+  return fingerprint(utf8(await httpResponseBase(r)));
+}
+
+/**
+ * The fingerprint of an identifier or of an error text, exactly as given:
+ * SHA-256 of its UTF-8 bytes. For "provared.trace-id", "provared.request-id",
+ * "provared.event-id" and "provared.error".
+ * @param {string} id
+ * @returns {Promise<string>}
+ * @throws {Refusal} "bad-field" if it is not text, is empty, or is not well-formed Unicode
+ */
+export async function identifierFingerprint(id) {
+  if (typeof id !== 'string' || id.length === 0) throw new Refusal('bad-field', 'The identifier must be text of one character or more.');
+  if (typeof id.isWellFormed === 'function' ? !id.isWellFormed() : /[\ud800-\udfff]/.test(id.replace(/[\ud800-\udbff][\udc00-\udfff]/g, ''))) {
+    throw new Refusal('bad-field', 'The identifier holds text that is not well-formed Unicode.');
+  }
+  return fingerprint(utf8(id));
+}

package/src/guard.js

@@ -21,7 +21,7 @@ const notSound = (why) => new Refusal('record-not-sound', why);
 // 131,072 bytes, and an action whose record would not fit is not allowed.
 const STUB_BOUND = 6700 + 600;
 const COUNTERSIGNATURE_BOUND = 6900;
-function lineBound(c, approval) {
+export function lineBound(c, approval) {
   let approvalBytes = 0;
   if (approval !== undefined) {
     try {
@@ -50,9 +50,11 @@ function lineBound(c, approval) {
  * @param {object} options the same options as checkBook
  * @param {string[]} options.issuerKeys the thumbprints of the passkeys this check trusts. It must be given:
  *   a slip signed by any other key allows nothing
- * @returns {Promise<{allowed: boolean, problems: {code: string, message: string}[], breaches: {code: string, message: string}[], needs: string[]}>}
+ * @returns {Promise<{allowed: boolean, problems: {code: string, message: string}[], breaches: {code: string, message: string}[], needs: string[], notChecked?: string[]}>}
  *   "allowed" is true only if the record so far is sound, this device
- *   checked every signature in it, and the action would be inside the slip.
+ *   checked every signature in it (or every one but the third signature of
+ *   a seal whose first two it checked, which "notChecked" then names), and
+ *   the action would be inside the slip.
  *   "needs" lists what the slip asks to go with the action. A needed
  *   approval must be handed over, or the action is not allowed. A needed
  *   countersignature cannot be known beforehand: the action is allowed, and
@@ -76,6 +78,54 @@ export function checkBeforeRead(read, proposal, options = {}) {
   return decide(read, proposal, options);
 }
 
+// The methods not checked on this device, if the only thing not checked is
+// the third signature of one or more seals whose Ed25519 and ML-DSA-87
+// signatures were checked here; otherwise null. It counts as the checker
+// counts for "fully checked" (book.js): a signature whose method is not
+// built in, or an entry with nothing to check, is not checked; a time-stamp
+// from a service the reader did not name is not "unchecked", it is uncounted.
+function onlySealThirdUnchecked(result) {
+  if (result.summary.fullyChecked) return null;
+  let skipped = false;
+  let excused = 0;
+  const missing = new Set();
+  const note = (list) => { if (list.length === 0) skipped = true; for (const x of list) if (x.state === 'unavailable') missing.add(x.method); };
+  const stamps = (list) => { for (const x of list) if (x.state === 'unavailable') missing.add('stamp'); };
+  for (const e of result.entries) {
+    if (e.kind === 'seal') {
+      const sigs = e.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 note(sigs);
+      stamps(e.stamps ?? []);
+    } 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;
+    } else if (e.kind === 'stub') {
+      note(e.signatures ?? []);
+      const counter = e.countersignature ?? { state: 'absent', signatures: [] };
+      if (counter.state !== 'absent') note(counter.signatures ?? []);
+      const approval = e.approval ?? { state: 'absent' };
+      if (approval.state === 'unavailable') missing.add(approval.alg);
+    } else if (e.kind === 'cancellation') {
+      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)) {
+      note(e.signatures ?? []);
+    } else {
+      skipped = true;
+    }
+  }
+  for (const h of result.held ?? []) {
+    stamps(h.stamps ?? []);
+    for (const a of h.acknowledgements ?? []) note(a.signatures ?? []);
+  }
+  return !skipped && missing.size === 0 && excused > 0 ? [SEAL_THIRD] : null;
+}
+
+const SEAL_THIRD = 'SLH-DSA-SHA2-256s';
+
 async function decide(read, proposal, options) {
   const answer = { allowed: false, problems: [], breaches: [], needs: [] };
   try {
@@ -85,15 +135,33 @@ async function decide(read, proposal, options) {
     }
     const { result, state, beside } = await read();
     if (result.summary.problemFound) throw notSound('A problem was found in the record so far. It must be looked at before the agent acts again.');
-    // A record this device could only partly check is not a pass, here either.
-    if (!result.summary.fullyChecked) throw notSound('This device could not check every signature in the record so far.');
+    // A record this device could only partly check is not a pass, here
+    // either, with one stated exception: a seal's third signature
+    // (SLH-DSA), where its first two were checked here. A seal widens no
+    // permission, and a device without that method (the Python version,
+    // every browser) would otherwise be refused everything once the book
+    // holds a seal. The answer names what was not checked.
+    const notChecked = onlySealThirdUnchecked(result);
+    if (!result.summary.fullyChecked && !notChecked) throw notSound('This device could not check every signature in the record so far.');
+    if (notChecked) answer.notChecked = notChecked;
     if (!result.entries.every((e) => (e.kind === 'stub' || e.kind === 'pass' ? e.compared === true : true))) {
       throw notSound('This device could not compare every stub and every pass in the record so far with its slip.');
     }
     if (result.size >= MAX_ENTRIES) throw new Refusal('too-large', 'The book is full: it holds 100,000 entries.');
 
     f.members(proposal, ['action', 'slip'], ['amount', 'approval', 'details', 'pass', 'terms', 'when', 'with'], 'proposal');
-    const c = { action: proposal.action, when: formatTime(proposal.when ?? Date.now()) };
+    // The time, as the stub writer takes it: a number of milliseconds or a
+    // Date. Text is read by rules that differ between devices.
+    const given = proposal.when ?? Date.now();
+    if (typeof given !== 'number' && !(given instanceof Date)) throw new Refusal('bad-field', 'when: must be a number of milliseconds, or a Date.');
+    let ms;
+    try {
+      ms = new Date(given).getTime();
+    } catch {
+      ms = NaN; // a Date wrapped in a Proxy, which Date cannot read
+    }
+    if (!Number.isFinite(ms)) throw new Refusal('bad-field', 'when: does not give a time.');
+    const c = { action: proposal.action, when: formatTime(ms) };
     for (const name of ['amount', 'details', 'with']) if (proposal[name] !== undefined) c[name] = proposal[name];
     validateRequest(c);
     const when = f.time(c.when, 'when');

package/src/index.js

@@ -16,8 +16,12 @@
 //            writeVouching, writeWithdrawal (an organisation vouches for a name),
 //            writePass (an agent hands part of its permission to a helper agent),
 //            writeBook, makeShow
-// Keys:      generateKeySet, generateSealKeySet, thumbprint, keySetFingerprint
-// Names:     the shared list of actions, the kinds of action, the rules of conduct
+// Keys:      generateKeySet, generateSealKeySet, thumbprint, keySetFingerprint,
+//            signerFromKey (a key in memory as a signer: wherever "privateKeys"
+//            is taken, each item may be a key or a signer, an object with
+//            "key" and "sign", for a key held elsewhere)
+// Names:     the shared list of actions, the kinds of action, the rules of conduct;
+//            the reserved document names, and the fingerprints they stand for
 
 export * from './check.js';
 export { checkBefore } from './guard.js';
@@ -32,6 +36,7 @@ export { writeSeal } from './seal.js';
 export { blockStampItem } from './blockstamp.js';
 export { prepareCancellation, assembleCancellation, writeAcknowledgement, writeVouching, writeWithdrawal, VOUCHED_KINDS } from './standing.js';
 export { entryLine, writeBook, makeShow } from './book.js';
-export { generateKeySet, generateSealKeySet } from './signatures.js';
+export { generateKeySet, generateSealKeySet, signerFromKey } from './signatures.js';
 export { ACTION_KINDS, SHARED_ACTIONS, CONDUCT_RULES, RESERVED_PREFIX, actionKind } from './actions.js';
+export { DOCUMENT_NAMES, RESERVED_DOCUMENT_PREFIX, httpRequestFingerprint, httpResponseFingerprint, identifierFingerprint } from './documents.js';
 export { fingerprint, formatTime, randomId, toBase64url, fromBase64url, utf8, sha256 } from './encoding.js';

package/src/pass.js

@@ -46,7 +46,7 @@ export function validatePassContent(c) {
  * @param {string} fields.validFrom
  * @param {string} fields.validUntil
  * @param {number|Date} [fields.when] defaults to now
- * @param {CryptoKey[]} privateKeys the private keys of the agent that passes on: Ed25519, then ML-DSA-87
+ * @param {any[]} privateKeys the private keys of the agent that passes on, or signers: Ed25519, then ML-DSA-87
  * @returns {Promise<{record: object, fingerprint: string}>}
  */
 export async function writePass(fields, privateKeys) {

package/src/recorder.js

@@ -32,16 +32,30 @@
 // 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 { 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 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;
 
@@ -70,10 +84,18 @@ const notWritten = (why) => new Refusal('record-not-sound', why);
 
 // A time handed in: a number of milliseconds, or a Date. Text, true or a
 // list would be read by rules that differ from one device to another (text
-// with no time zone is taken as local time), so they are refused.
+// with no time zone is taken as local time), so they are refused. A Date
+// that cannot be read (one wrapped in a Proxy) gives no time, as a Date
+// that is not a time gives none, and the check before acting refuses it.
 function timeOf(when) {
   if (typeof when === 'number') return new Date(when).getTime();
-  if (when instanceof Date) return when.getTime();
+  if (when instanceof Date) {
+    try {
+      return when.getTime();
+    } catch {
+      return NaN;
+    }
+  }
   throw new Refusal('bad-field', 'when: must be a number of milliseconds, or a Date.');
 }
 
@@ -196,17 +218,20 @@ 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
+ * @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
- * @throws {Refusal} "record-not-sound" if the book so far has a problem
+ * @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 }) {
   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;
@@ -218,6 +243,9 @@ 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.');
+  }
   // 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
@@ -395,6 +423,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.');
@@ -404,6 +443,7 @@ 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,
     };
@@ -440,6 +480,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;
 
@@ -483,7 +537,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;
@@ -636,7 +690,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;
       }
@@ -775,6 +829,8 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
       return calling(request, more, async (call) => {
         await writeWaiting(now());
         const when = call.when ?? now();
+        // In the words of the check before acting, which "act" and "before" give.
+        if (!Number.isFinite(when)) throw new Refusal('bad-field', 'when: does not give a time.');
         if (aheadOfClock(when)) throw notWritten('The stub was not written: it is dated ahead of the clock.');
         const made = await composeStub(call, when);
         const tried = await fitsBook(made, 'The stub was not written: with it, the book would not pass its check.');
@@ -798,10 +854,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) => {
@@ -827,6 +901,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) {
@@ -839,8 +926,57 @@ export async function openRecorder({ book, slip, privateKeys, issuerKeys, pass,
         }
         if (!answer.allowed) return { done: false, answer };
         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 };
       });
     },
 

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';
 
@@ -104,7 +104,7 @@ export async function keySetFingerprint(keys) {
  * @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 {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
  */
@@ -123,9 +123,10 @@ export async function writeSeal(book, fields, privateKeys) {
   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);

package/src/service.js

@@ -79,7 +79,7 @@ export function validateTermsContent(c) {
  * @param {{unit: string, value: number}} [fields.amount]
  * @param {string} fields.reason one of REFUSAL_REASONS
  * @param {number|Date} [fields.when] defaults to now
- * @param {CryptoKey[]} privateKeys the service's private keys: Ed25519, then ML-DSA-87
+ * @param {any[]} privateKeys the service's private keys, or signers: Ed25519, then ML-DSA-87. A signer must hold the keys "by" names
  * @returns {Promise<{record: object, fingerprint: string}>}
  */
 export async function writeRefusal(fields, privateKeys) {
@@ -94,7 +94,7 @@ export async function writeRefusal(fields, privateKeys) {
   };
   if (fields.amount) content.amount = fields.amount;
   validateRefusalContent(content);
-  return signWithKeySet('refusal', content, privateKeys);
+  return signWithKeySet('refusal', content, privateKeys, content.by.keys);
 }
 
 /**
@@ -106,7 +106,7 @@ export async function writeRefusal(fields, privateKeys) {
  * @param {string[]} [fields.never] kinds of action and rules of conduct the service asks agents to keep
  * @param {string} fields.validFrom
  * @param {string} fields.validUntil
- * @param {CryptoKey[]} privateKeys the service's private keys: Ed25519, then ML-DSA-87
+ * @param {any[]} privateKeys the service's private keys, or signers: Ed25519, then ML-DSA-87. A signer must hold the keys "by" names
  * @returns {Promise<{record: object, fingerprint: string}>}
  */
 export async function writeTerms(fields, privateKeys) {
@@ -120,5 +120,5 @@ export async function writeTerms(fields, privateKeys) {
     validUntil: fields.validUntil,
   };
   validateTermsContent(content);
-  return signWithKeySet('terms', content, privateKeys);
+  return signWithKeySet('terms', content, privateKeys, content.by.keys);
 }