provared 0.4.0 → 0.5.0

package/src/signatures.js

@@ -13,7 +13,8 @@
 // this file still loads in a browser. In a browser the method is reported as
 // not built in, which is never a pass.
 
-import { importPublicKey, weakEd25519 } from './keys.js';
+import { Refusal } from './encoding.js';
+import { checkKey, importPublicKey, thumbprint, weakEd25519 } from './keys.js';
 
 const SLH = 'SLH-DSA-SHA2-256s';
 
@@ -122,6 +123,280 @@ export async function sign(alg, privateKey, data) {
   return new Uint8Array(await globalThis.crypto.subtle.sign({ name: alg }, privateKey, data));
 }
 
+// --- signers ---
+//
+// Wherever a writer takes "privateKeys", each item may be a private key of
+// the platform (a Web Crypto CryptoKey, or a Node.js KeyObject), used as it
+// always was, or a signer: an object with "key", the public key as a JSON
+// Web Key in one of the shapes of the format description, section 3.8, and
+// "sign(data)", which gives the signature over exactly those bytes. A
+// signer lets a key live elsewhere: in a key service, or a hardware module.
+// It changes where a signature is made, not how: the record is the same.
+//
+// A signer is not taken on trust. Its two members are read once. Its key
+// must be of the method of its place in the list, a method this device can
+// check, and, where the writer knows the key the record must be signed
+// with, that key. All of this is settled before any signer is asked to
+// sign. Every signature it gives is checked against its key before it is
+// used. A signer that fails in any way leaves no record, and the error
+// names the method and the key. Signers earlier in the list may have
+// signed by then: a key service's own log may hold signatures that match
+// no record.
+
+/**
+ * Whether an item of "privateKeys" is a private key of the platform for the
+ * method of its place: a private Web Crypto CryptoKey of that method that
+ * may sign, or for SLH-DSA a private Node.js KeyObject of that kind. What
+ * only looks like one (an object made from CryptoKey's own prototype, a
+ * public key, a key of another method) is not one.
+ * @param {any} item
+ * @param {string} alg
+ * @returns {boolean}
+ */
+function platformKey(item, alg) {
+  try {
+    if (alg === SLH) return Boolean(nodeCrypto) && item instanceof nodeCrypto.KeyObject && item.type === 'private' && item.asymmetricKeyType === 'slh-dsa-sha2-256s';
+    return typeof globalThis.CryptoKey === 'function' && item instanceof globalThis.CryptoKey && item.type === 'private' && item.algorithm.name === alg && item.usages.includes('sign');
+  } catch {
+    return false; // a value that cannot even be looked into (a revoked Proxy), or one that only looks like a key
+  }
+}
+
+// What a place in "privateKeys" must hold.
+const signerShape = (alg) =>
+  `must be a private key for ${alg} (${alg === SLH ? 'a Node.js KeyObject, or what Node.js reads as one: PEM text, DER bytes with their format, or a JSON Web Key with its format' : 'a Web Crypto CryptoKey'}), or a signer: an object with "key", the public key, and "sign", a function that gives the signature bytes.`;
+
+/**
+ * In the SLH-DSA place, the seal writer has always handed the key to
+ * Node.js's own signing call, which also reads a key written out: PEM text,
+ * DER bytes with their format, or a JSON Web Key with its format. Such a
+ * key is still taken: it is read exactly as that call read it (with
+ * crypto.createPrivateKey, which the call itself uses), and then it must be
+ * a private SLH-DSA-SHA2-256s key, as a KeyObject must.
+ * @param {any} item
+ * @param {string} where
+ * @returns {any} the key, as a KeyObject
+ */
+function writtenSlhKey(item, where) {
+  let made;
+  try {
+    made = nodeCrypto.createPrivateKey(item);
+  } catch {
+    made = null; // not a private key Node.js can read, or no Node.js here
+  }
+  if (!platformKey(made, SLH)) throw new Refusal('bad-field', `${where}: ${signerShape(SLH)}`);
+  return made;
+}
+
+// A signer that gave no answer in the time the stub writer gives it.
+class NoAnswer extends Error {
+  constructor(ms) {
+    super(`no answer within ${ms} milliseconds`);
+    this.ms = ms;
+  }
+}
+
+// Two public keys that have passed checkKey: the same key, member for member.
+function sameKey(a, b) {
+  const names = Object.keys(b);
+  return Object.keys(a).length === names.length && names.every((n) => a[n] === b[n]);
+}
+
+// The signature bytes a signer gave, copied, or null where it gave anything
+// else. Bytes are a Uint8Array (a Node.js Buffer is one) or an ArrayBuffer,
+// which is what Web Crypto's own "sign" gives.
+function bytesOf(given) {
+  try {
+    if (given instanceof Uint8Array) return new Uint8Array(given);
+    if (given instanceof ArrayBuffer) return new Uint8Array(given.slice(0));
+  } catch {
+    // fall through: not bytes that can be read
+  }
+  return null;
+}
+
+/**
+ * Read one item of "privateKeys" for the method of its place.
+ * @param {any} item
+ * @param {string} alg
+ * @param {string} where its place, for messages
+ * @param {object} [expected] the public key the record must be signed with, where the writer knows it
+ * @returns {Promise<{platform: boolean, item: any, key?: object, call?: (data: Uint8Array) => any, sign: (data: Uint8Array) => Promise<Uint8Array>}>}
+ */
+async function takeItem(item, alg, where, expected) {
+  const platform = (privateKey) => ({ platform: true, item: privateKey, sign: (data) => sign(alg, privateKey, data) });
+  if (platformKey(item, alg)) return platform(item);
+  let key;
+  let fn;
+  if (item !== null && (typeof item === 'object' || typeof item === 'function')) {
+    try {
+      key = item.key;
+      fn = item.sign;
+    } catch {
+      throw new Refusal('bad-field', `${where}: could not be read.`);
+    }
+  }
+  if (typeof fn !== 'function') {
+    // Not a signer: in the SLH-DSA place, perhaps a key written out.
+    if (alg === SLH && item !== null && item !== undefined) return platform(writtenSlhKey(item, where));
+    throw new Refusal('bad-field', `${where}: ${signerShape(alg)}`);
+  }
+  if (key === undefined || key === null) throw new Refusal('bad-field', `${where}: ${signerShape(alg)}`);
+  let copy;
+  try {
+    copy = structuredClone(key);
+  } catch {
+    throw new Refusal('bad-key', `${where}.key: must be a public key, as plain data.`);
+  }
+  checkKey(copy, [alg], `${where}.key`);
+  Object.freeze(copy);
+  const label = `the ${alg} key ${await thumbprint(copy)}`;
+  if (expected && !sameKey(copy, expected)) {
+    throw new Refusal('bad-key', `${where}: the signer holds ${label}, which is not the key this record must be signed with (${await thumbprint(expected)}).`);
+  }
+  // Nothing is signed that this device cannot check: so a signer for a
+  // method it does not have built in is refused before any signer is asked.
+  if (!(await methodAvailable(alg))) {
+    throw new Refusal('bad-key', `${where}: this device does not have ${alg} built in, so it cannot check a signature from the signer for ${label}. No record was made.`);
+  }
+  const call = (data) => fn.call(item, data);
+  return { platform: false, item, key: copy, call, sign: (data) => signerSignature(call, copy, alg, label, where, data) };
+}
+
+// One signature from a signer, checked before it is used.
+async function signerSignature(call, key, alg, label, where, data) {
+  const failed = (why, cause) => {
+    const e = new Refusal('signature-invalid', `${where}: the signer for ${label} ${why} No record was made.`);
+    if (cause !== undefined) e.cause = cause;
+    return e;
+  };
+  let given;
+  try {
+    // The signer is handed a copy: nothing it does to it changes what is checked.
+    given = await call(data.slice());
+  } catch (e) {
+    if (e instanceof NoAnswer) throw failed(`gave no answer within ${e.ms} milliseconds.`);
+    throw failed('failed with an error.', e);
+  }
+  const signature = bytesOf(given);
+  if (signature === null) throw failed('gave something other than bytes.');
+  if (Object.hasOwn(SIGNATURE_BYTES, alg) && signature.length !== SIGNATURE_BYTES[alg]) {
+    throw failed(`gave a signature of ${signature.length} bytes, where an ${alg} signature is ${SIGNATURE_BYTES[alg]}.`);
+  }
+  // Whether the method is built in was settled before any signer was asked;
+  // a signature that cannot be checked even so is not used.
+  const state = await verifySignature(key, signature, data);
+  if (state !== 'valid') throw failed('gave a signature that does not check against its key: it holds another key, or signed other bytes.');
+  return signature;
+}
+
+/**
+ * Read every item of "privateKeys", one for each method, before anything is
+ * signed.
+ * @param {any} privateKeys
+ * @param {string[]} methods
+ * @param {object[]} [expected] the public keys the record must be signed with, where the writer knows them
+ * @returns {Promise<Awaited<ReturnType<typeof takeItem>>[]>}
+ */
+async function takeItems(privateKeys, methods, expected) {
+  let list;
+  try {
+    list = Array.isArray(privateKeys);
+  } catch {
+    list = false; // a revoked Proxy
+  }
+  if (!list) throw new Refusal('bad-field', `privateKeys: must be a list, one private key or signer for each of ${methods.join(', ')}.`);
+  const taken = [];
+  for (let i = 0; i < methods.length; i++) {
+    let item;
+    try {
+      item = privateKeys[i];
+    } catch {
+      throw new Refusal('bad-field', `privateKeys[${i}]: could not be read.`);
+    }
+    taken.push(await takeItem(item, methods[i], `privateKeys[${i}]`, expected ? expected[i] : undefined));
+  }
+  return taken;
+}
+
+/**
+ * The functions that sign, one for each method, for a writer that signs
+ * now. Keys of the platform sign as they always did; each signer is read
+ * and checked as set out above.
+ * @param {any} privateKeys
+ * @param {string[]} methods
+ * @param {object[]} [expected]
+ * @returns {Promise<((data: Uint8Array) => Promise<Uint8Array>)[]>}
+ */
+export async function signingKeys(privateKeys, methods, expected) {
+  return (await takeItems(privateKeys, methods, expected)).map((t) => t.sign);
+}
+
+/**
+ * For a writer that holds its keys, such as the stub writer: the list to
+ * use in place of "privateKeys". Keys of the platform are kept as they
+ * are. Each signer is read once, here, and checked against the key the
+ * records must be signed with where that is known; in its place stands a
+ * signer that waits "ms" milliseconds at most for each signature, through
+ * "run". A late answer is not used.
+ * @param {any} privateKeys
+ * @param {string[]} methods
+ * @param {object[]|undefined} expected
+ * @param {number} ms
+ * @param {(work: () => Promise<any>) => Promise<any>} [run]
+ * @returns {Promise<any[]>}
+ */
+export async function holdSigningKeys(privateKeys, methods, expected, ms, run = (work) => work()) {
+  return (await takeItems(privateKeys, methods, expected)).map((t) => {
+    if (t.platform) return t.item;
+    const waited = (data) =>
+      new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new NoAnswer(ms)), ms);
+        let answer;
+        try {
+          answer = Promise.resolve(t.call(data));
+        } catch (e) {
+          clearTimeout(timer);
+          reject(e);
+          return;
+        }
+        answer.then(
+          (value) => {
+            clearTimeout(timer);
+            resolve(value);
+          },
+          (e) => {
+            clearTimeout(timer);
+            reject(e);
+          },
+        );
+      });
+    return Object.freeze({ key: t.key, sign: (data) => run(() => waited(data)) });
+  });
+}
+
+/**
+ * Wrap a private key held in memory as a signer, so that a key in memory
+ * and a key held elsewhere take one path.
+ * @param {string} alg 'Ed25519', 'ML-DSA-87' or 'SLH-DSA-SHA2-256s'
+ * @param {any} privateKey a Web Crypto CryptoKey, or for SLH-DSA a Node.js KeyObject
+ * @param {object} publicJwk its public key, in one of the shapes of the format description, section 3.8
+ * @returns {{key: object, sign: (data: Uint8Array) => Promise<Uint8Array>}}
+ */
+export function signerFromKey(alg, privateKey, publicJwk) {
+  if (alg !== 'Ed25519' && alg !== 'ML-DSA-87' && alg !== SLH) throw new Refusal('bad-field', `alg: must be Ed25519, ML-DSA-87 or ${SLH}.`);
+  // Web Crypto holds the first two methods; Node.js's own module the third.
+  if (!platformKey(privateKey, alg)) throw new Refusal('bad-field', `privateKey: must be a private key for ${alg}: ${alg === SLH ? 'a Node.js KeyObject' : 'a Web Crypto CryptoKey'}.`);
+  let key;
+  try {
+    key = structuredClone(publicJwk);
+  } catch {
+    throw new Refusal('bad-key', 'key: must be a public key, as plain data.');
+  }
+  checkKey(key, [alg], 'key');
+  return Object.freeze({ key: Object.freeze(key), sign: (data) => sign(alg, privateKey, data) });
+}
+
 /**
  * Make a new key set for a recorder, which signs seals: an Ed25519 key, an
  * ML-DSA-87 key and an SLH-DSA-SHA2-256s key. It needs Node.js: no browser

package/src/standing.js

@@ -122,7 +122,7 @@ export function assembleCancellation(prepared, assertion) {
  * @param {string} fields.cancellation the fingerprint of the cancellation
  * @param {string} [fields.pass] for a helper agent: the fingerprint of the pass it acts under
  * @param {number|Date} [fields.when] when the cancellation was handed over; defaults to now
- * @param {CryptoKey[]} privateKeys the agent's private keys: Ed25519, then ML-DSA-87
+ * @param {any[]} privateKeys the agent's private keys, or signers: Ed25519, then ML-DSA-87
  * @returns {Promise<{record: object, fingerprint: string}>}
  */
 export async function writeAcknowledgement(fields, privateKeys) {
@@ -148,7 +148,7 @@ export async function writeAcknowledgement(fields, privateKeys) {
  * @param {string} fields.validFrom
  * @param {string} fields.validUntil
  * @param {number|Date} [fields.when] defaults to now
- * @param {CryptoKey[]} privateKeys the organisation's private keys: Ed25519, then ML-DSA-87
+ * @param {any[]} privateKeys the organisation'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 writeVouching(fields, privateKeys) {
@@ -162,7 +162,7 @@ export async function writeVouching(fields, privateKeys) {
     when: formatTime(fields.when ?? Date.now()),
   };
   validateVouchingContent(content);
-  return signWithKeySet('vouching', content, privateKeys);
+  return signWithKeySet('vouching', content, privateKeys, content.by.keys);
 }
 
 /**
@@ -171,7 +171,7 @@ export async function writeVouching(fields, privateKeys) {
  * @param {object} fields
  * @param {string} fields.vouching the fingerprint of the vouching record
  * @param {number|Date} [fields.when] defaults to now
- * @param {CryptoKey[]} privateKeys the private keys of the organisation that made the vouching record
+ * @param {any[]} privateKeys the private keys of the organisation that made the vouching record, or signers
  * @returns {Promise<{record: object, fingerprint: string}>}
  */
 export async function writeWithdrawal(fields, privateKeys) {

package/src/stub.js

@@ -1,11 +1,12 @@
 // The Stub (the receipt for one action) and the countersignature.
 // Format description, sections 5 and 6.
 
+import { DOCUMENT_NAMES, REPEATABLE_DOCUMENT_NAMES, isUnknownReservedDocument } from './documents.js';
 import { fingerprint, formatTime, randomId, toBase64url } from './encoding.js';
 import * as f from './fields.js';
 import { encodeContent, parseRecord, protectedHeaders, signingInput, withinSize, KINDS } from './jws.js';
 import { KEY_SET_METHODS } from './keys.js';
-import { sign } from './signatures.js';
+import { signingKeys } from './signatures.js';
 
 /**
  * Confirm every member of a stub's content (format description, section 5.1).
@@ -48,9 +49,17 @@ export function validateRequest(c) {
   if (Object.hasOwn(c, 'with')) f.shortName(c.with, 'with');
   if (Object.hasOwn(c, 'details')) {
     f.list(c.details, 1, 32, 'details');
+    const once = new Set();
     c.details.forEach((d, i) => {
       f.members(d, ['name', 'sha256'], [], `details[${i}]`);
       f.label(d.name, `details[${i}].name`);
+      if (isUnknownReservedDocument(d.name)) throw f.fail(`details[${i}].name`, 'names that begin "provared." are reserved, and this one is not on the list of document names.');
+      if (Object.hasOwn(DOCUMENT_NAMES, d.name) && !REPEATABLE_DOCUMENT_NAMES.includes(d.name)) {
+        if (once.has(d.name)) {
+          throw f.fail(`details[${i}].name`, 'this reserved name is named twice. Only provared.trace-id, provared.request-id and provared.event-id may be named more than once.');
+        }
+        once.add(d.name);
+      }
       f.fingerprintText(d.sha256, `details[${i}].sha256`);
     });
   }
@@ -71,12 +80,16 @@ export function validateCountersignatureContent(c) {
 
 // Sign content with a key set: two signatures side by side, Ed25519 then
 // ML-DSA-87, each over its own signing input (format description, 3.9).
-export async function signWithKeySet(kind, content, privateKeys) {
+// Each item of "privateKeys" is a key or a signer (signatures.js);
+// "expected" is the key set the record must be signed with, where the
+// writer knows it, and a signer that holds another key is refused.
+export async function signWithKeySet(kind, content, privateKeys, expected) {
   const { contentBytes, payloadB64 } = encodeContent(content);
   const headers = protectedHeaders(kind);
+  const signers = await signingKeys(privateKeys, KEY_SET_METHODS, expected);
   const signatures = [];
   for (let i = 0; i < KEY_SET_METHODS.length; i++) {
-    const signature = await sign(KEY_SET_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) });
   }
   return { record: withinSize({ payload: payloadB64, signatures }), fingerprint: await fingerprint(contentBytes) };
@@ -96,7 +109,7 @@ export async function signWithKeySet(kind, content, privateKeys) {
  * @param {string} [fields.terms] the fingerprint of the service's terms for agents that the agent relied on
  * @param {string} [fields.pass] for a helper agent: the fingerprint of the pass it acts under; "after" is then the stub before it under that pass
  * @param {number|Date} [fields.when] defaults to now
- * @param {CryptoKey[]} privateKeys the agent's private keys: Ed25519, then ML-DSA-87
+ * @param {any[]} privateKeys the agent's private keys, or signers (signatures.js): Ed25519, then ML-DSA-87
  * @returns {Promise<{record: object, fingerprint: string, seq: number}>}
  */
 export async function writeStub(fields, privateKeys) {
@@ -128,7 +141,7 @@ export async function writeStub(fields, privateKeys) {
  * reads the stub's fingerprint; it does not judge the stub.
  *
  * @param {object} stubRecord the stub as the agent sent it
- * @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
  * @param {number|Date} [when] defaults to now
  * @returns {Promise<object>} the countersignature record
  */

package/src/types.d.ts

@@ -50,6 +50,21 @@ export type KeySet = [Ed25519Key, MlDsaKey];
 export type SealKeySet = [Ed25519Key, MlDsaKey, SlhDsaKey];
 export type PublicKey = PasskeyKey | MlDsaKey | SlhDsaKey;
 
+/**
+ * A signer: a key held elsewhere (a key service, a hardware module) that signs on request. Wherever
+ * "privateKeys" is taken, each item may be a key or a signer. A signer's key must be of the method of
+ * its place, and, where the writer knows the key the record must be signed with, that key. Every
+ * signature it gives is checked against its key before it is used.
+ */
+export interface Signer {
+  /** The public key, in one of the shapes of the format description, section 3.8. */
+  key: Ed25519Key | MlDsaKey | SlhDsaKey;
+  /** The signature over exactly these bytes: 64 bytes for Ed25519, 4,627 for ML-DSA-87, 29,792 for SLH-DSA-SHA2-256s. */
+  sign(data: Uint8Array): Promise<Uint8Array | ArrayBuffer>;
+}
+/** A private key of the platform (a Web Crypto CryptoKey), or a signer. */
+export type SigningKey = CryptoKey | Signer;
+
 // --- what records hold ---
 
 export interface Amount {
@@ -451,8 +466,20 @@ export interface Recorder {
   act<T>(
     request: Request,
     perform: () => Promise<T>,
-    more?: { when?: number | Date; terms?: Fingerprint; approval?: { record: SignedRecord }; countersign?: (stub: SignedRecord) => Promise<SignedRecord | null> },
-  ): Promise<{ done: boolean; answer: BeforeAnswer; result?: T; stub?: WrittenStub }>;
+    more?: {
+      when?: number | Date;
+      terms?: Fingerprint;
+      approval?: { record: SignedRecord };
+      countersign?: (stub: SignedRecord) => Promise<SignedRecord | null>;
+      /**
+       * Up to four further documents, from what the action gave back. The stub is then signed after the action,
+       * in the same turn, and keeps the time the action began. The request may then name at most 28 documents,
+       * and no approval may be given. If it fails, the stub is written without them, and "detailsAfter" in the
+       * answer says why.
+       */
+      detailsAfter?: (result: T) => DocumentRef[] | null | undefined | Promise<DocumentRef[] | null | undefined>;
+    },
+  ): Promise<{ done: boolean; answer: BeforeAnswer; result?: T; stub?: WrittenStub; detailsAfter?: { added: number; problem: Finding | null } }>;
   book(): string;
   /**
    * What the record shows as it stands: the answer a whole check of the book gives, with the cancellations
@@ -481,7 +508,8 @@ export type WrittenStub = Written & { seq: number; line: string; countersignatur
 export function openRecorder(o: {
   book: string;
   slip: Fingerprint;
-  privateKeys: CryptoKey[];
+  /** The agent's private keys, or signers: Ed25519, then ML-DSA-87. A signer must hold the keys the slip, or the pass, names. */
+  privateKeys: SigningKey[];
   issuerKeys: string[];
   pass?: Fingerprint;
   options?: CheckOptions;
@@ -489,6 +517,8 @@ export function openRecorder(o: {
   now?: () => number;
   /** How long the other side is given to countersign, in milliseconds. Defaults to 30,000. */
   countersignWithin?: number;
+  /** How long a signer is given for each signature, in milliseconds. Defaults to 30,000. After that nothing is written. */
+  signWithin?: number;
 }): Promise<Recorder>;
 
 /** One of an agent's tools, as it is described to recordTools. */
@@ -564,21 +594,21 @@ export function writeStub(
     when?: number | Date;
     id?: Base64url;
   },
-  privateKeys: CryptoKey[],
+  privateKeys: SigningKey[],
 ): Promise<Written & { seq: number }>;
 /** An agent hands part of its permission to a helper agent. */
 export function writePass(
   fields: { slip: Fingerprint; from?: Fingerprint; to: Party; actions: string[]; limits?: Limit[]; validFrom: Time; validUntil: Time; when?: number | Date; id?: Base64url },
-  privateKeys: CryptoKey[],
+  privateKeys: SigningKey[],
 ): Promise<Written>;
-export function countersign(stub: SignedRecord, privateKeys: CryptoKey[], when?: number | Date): Promise<SignedRecord>;
+export function countersign(stub: SignedRecord, privateKeys: SigningKey[], when?: number | Date): Promise<SignedRecord>;
 export function writeRefusal(
   fields: { slip: Fingerprint; by: Party; action: string; amount?: Amount; reason: string; when?: number | Date; id?: Base64url },
-  privateKeys: CryptoKey[],
+  privateKeys: SigningKey[],
 ): Promise<Written>;
 export function writeTerms(
   fields: { by: Party; accepts: string[]; never?: string[]; validFrom: Time; validUntil: Time; id?: Base64url },
-  privateKeys: CryptoKey[],
+  privateKeys: SigningKey[],
 ): Promise<Written>;
 export type VouchedFor =
   | { kind: 'person'; key: PasskeyKey; name: string }
@@ -586,15 +616,19 @@ export type VouchedFor =
   | { kind: 'recorder'; keys: SealKeySet; name: string };
 export function writeVouching(
   fields: { by: Party; for: VouchedFor; validFrom: Time; validUntil: Time; when?: number | Date; id?: Base64url },
-  privateKeys: CryptoKey[],
+  privateKeys: SigningKey[],
 ): Promise<Written>;
-export function writeWithdrawal(fields: { vouching: Fingerprint; when?: number | Date; id?: Base64url }, privateKeys: CryptoKey[]): Promise<Written>;
+export function writeWithdrawal(fields: { vouching: Fingerprint; when?: number | Date; id?: Base64url }, privateKeys: SigningKey[]): Promise<Written>;
 /** The agent's side states that it was handed the person's cancellation of a slip, and when. */
 export function writeAcknowledgement(
   fields: { slip: Fingerprint; cancellation: Fingerprint; pass?: Fingerprint; when?: number | Date; id?: Base64url },
-  privateKeys: CryptoKey[],
+  privateKeys: SigningKey[],
 ): Promise<Written>;
-/** It needs Node.js: no browser has the seal's third signing method. */
+/**
+ * It needs Node.js: no browser has the seal's third signing method. "privateKeys": the recorder's three keys (two
+ * Web Crypto keys, and a Node.js KeyObject or what Node.js reads as one: PEM text, DER bytes with their format, or a
+ * JSON Web Key with its format), or signers, each holding the key "by" names in its place.
+ */
 export function writeSeal(
   book: string,
   fields: { by: { keys: SealKeySet; name: string }; previous?: Fingerprint; when?: number | Date; id?: Base64url },
@@ -612,6 +646,8 @@ export function makeShow(text: string, indexes: number[], options?: { seal?: num
 
 export function generateKeySet(): Promise<{ keys: KeySet; privateKeys: CryptoKey[] }>;
 export function generateSealKeySet(): Promise<{ keys: SealKeySet; privateKeys: unknown[] }>;
+/** A private key held in memory, wrapped as a signer: a CryptoKey, or for SLH-DSA-SHA2-256s a Node.js KeyObject. */
+export function signerFromKey(alg: 'Ed25519' | 'ML-DSA-87' | 'SLH-DSA-SHA2-256s', privateKey: unknown, key: Ed25519Key | MlDsaKey | SlhDsaKey): Signer;
 export function fingerprint(contentBytes: Uint8Array): Promise<Fingerprint>;
 export function sha256(bytes: Uint8Array): Promise<Uint8Array>;
 export function formatTime(when: number | Date): Time;
@@ -623,6 +659,16 @@ export function utf8(text: string): Uint8Array;
 // --- the shared list ---
 
 export const RESERVED_PREFIX: 'provared.';
+/** Document names that begin with this are reserved: only those in DOCUMENT_NAMES may be used. */
+export const RESERVED_DOCUMENT_PREFIX: 'provared.';
+/** The reserved document names, and the exact text whose SHA-256 each one gives (format description, section 27). */
+export const DOCUMENT_NAMES: Readonly<Record<string, string>>;
+/** For "provared.http-request": the method and the address exactly as sent, and the body's bytes where there is a body. */
+export function httpRequestFingerprint(r: { method: string; url: string; body?: Uint8Array }): Promise<Fingerprint>;
+/** For "provared.http-response": the status code, and the body's bytes where there is a body. */
+export function httpResponseFingerprint(r: { status: number; body?: Uint8Array }): Promise<Fingerprint>;
+/** For "provared.trace-id", "provared.request-id", "provared.event-id" and "provared.error": SHA-256 of the text's UTF-8 bytes, exactly as given. */
+export function identifierFingerprint(id: string): Promise<Fingerprint>;
 export const ACTION_KINDS: Record<string, string>;
 export const SHARED_ACTIONS: Record<string, [kind: string, meaning: string]>;
 export const CONDUCT_RULES: Record<string, string>;