provared 0.4.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 {

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;
 
@@ -204,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;
@@ -226,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
@@ -403,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.');
@@ -412,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,
     };
@@ -448,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;
 
@@ -491,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;
@@ -644,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;
       }
@@ -808,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) => {
@@ -837,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) {
@@ -849,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);
 }