provared 0.5.0 → 0.7.0

package/src/types.d.ts

@@ -155,9 +155,10 @@ export type BookEntry =
   | { stub: SignedRecord; countersignature?: SignedRecord; approval?: SignedRecord }
   | { refusal: SignedRecord }
   | { terms: SignedRecord }
-  | { seal: SignedRecord; stamps?: StampItem[] }
+  | { seal: SignedRecord; stamps?: StampItem[]; witnesses?: SignedRecord[] }
   | { cancellation: SignedRecord; stamps?: StampItem[] }
   | { acknowledgement: SignedRecord }
+  | { denial: SignedRecord }
   | { vouching: SignedRecord }
   | { withdrawal: SignedRecord }
   | { pass: SignedRecord };
@@ -168,7 +169,7 @@ export interface Show {
   root: Fingerprint;
   /** "disclosures" reveal covered fields of the record on that page. */
   pages: { index: number; entry: string; path: Fingerprint[]; disclosures?: string[] }[];
-  seal?: { seal: SignedRecord; stamps?: StampItem[] };
+  seal?: { seal: SignedRecord; stamps?: StampItem[]; witnesses?: SignedRecord[] };
 }
 
 // --- what the checker answers ---
@@ -199,6 +200,28 @@ export interface Stamp {
   /** For a block: its number, as the proof states it. Nothing checks it. */
   height?: number;
 }
+/** A witness statement beside a seal, as the checker found it (format description, section 29). */
+export interface WitnessCheck {
+  /** The statement's own fingerprint. */
+  fingerprint: Fingerprint | null;
+  /** The fingerprint of the witness's key set: how the person names a witness they trust. */
+  witness: Fingerprint | null;
+  /** The witness's name, a label. */
+  name: string | null;
+  /** When the witness says it signed: its own word. */
+  when: Time | null;
+  /** "valid": it passed its check and both its signatures were checked here. "unavailable": this device could not check them both. */
+  state: 'valid' | 'unavailable' | 'invalid';
+  /** Whether its witness is one the person named. */
+  trusted: boolean;
+  /**
+   * Whether it counts: valid, trusted, its seal passed its own check with its first two signatures checked here, the book
+   * starts with a permission signed by a passkey you named, you named the recorders you expect, and every permission the
+   * seal covers names the first line's passkey and agent (a Show must hold every page the seal covers). Section 29.2.
+   */
+  counted: boolean;
+  signatures: KeySignature[];
+}
 /** A time-stamp beside a seal or a cancellation: a service's answer, or a proof with the header of its block. */
 export type StampItem = Base64url | { block: Base64url; proof: Base64url };
 /** Who vouches for a name, if anyone does. */
@@ -206,7 +229,7 @@ export type Vouched = { counted: boolean; by: string; keys: Fingerprint } | null
 
 export interface CheckedEntry {
   index: number;
-  kind: 'slip' | 'stub' | 'refusal' | 'terms' | 'seal' | 'cancellation' | 'acknowledgement' | 'vouching' | 'withdrawal' | 'pass' | 'unreadable';
+  kind: 'slip' | 'stub' | 'refusal' | 'terms' | 'seal' | 'cancellation' | 'acknowledgement' | 'vouching' | 'withdrawal' | 'pass' | 'denial' | 'unreadable';
   fingerprint: Fingerprint | null;
   /** How much of the entry's own signing this device confirmed. */
   verified: 'all' | 'some' | 'none';
@@ -257,6 +280,8 @@ export interface CheckedEntry {
   service?: string | null;
   sealer?: Fingerprint;
   stamps?: Stamp[];
+  /** A seal: the witness statements on its line. */
+  witnesses?: WitnessCheck[];
   counted?: boolean;
 }
 
@@ -281,11 +306,18 @@ export interface Summary {
     seals: number;
     cancellations: number;
     acknowledgements: number;
+    denials: number;
     vouchings: number;
     passes: number;
   };
   /** How far the last time-stamp from a trusted service reaches. */
   sealed: { entries: number; when: Time; seal: number; by: 'service' | 'block' } | null;
+  /**
+   * How far a witness the person named reaches: the latest seal for which a statement counts, the entries it covers,
+   * the witnesses whose statements count for it, and every seal for which one counts. Null where none does, or where a
+   * problem was found. It excuses nothing.
+   */
+  witnessed: { seal: number; entries: number; by: Fingerprint[]; seals: number[] } | null;
   /** What no check can show, in plain sentences. */
   limits: string[];
 }
@@ -333,6 +365,46 @@ export interface HeldAcknowledgement {
   inBook: number | null;
 }
 
+/** A seal held elsewhere, as it is handed over: the entry it is in the book. */
+export interface HandedSeal {
+  seal: SignedRecord;
+  stamps?: StampItem[];
+  /** Witness statements for the seal, 1 to 4, none from one witness twice: those beside it in the book, or that came later. */
+  witnesses?: SignedRecord[];
+}
+
+/**
+ * A seal held elsewhere (by the person, an auditor, a copy kept apart), handed over beside the book. The book
+ * must hold the same seal at the place it states: a book that ends before that place was cut short
+ * ("book-cut-short"), and one that holds another line there was changed ("seal-not-in-book").
+ */
+export interface HeldSeal {
+  kind: 'seal';
+  fingerprint: Fingerprint | null;
+  /** The fingerprint of the key set that signed it. */
+  sealer: Fingerprint | null;
+  /** The entry of the book at which it stands: the number of entries it covers. Null where it could not be read. */
+  place: number | null;
+  /** That entry, where the book holds the same seal there; null otherwise, or where it was not used. */
+  inBook: number | null;
+  /**
+   * Whether it was compared with the book: it passed its check, its recorder is one you named, this device checked its
+   * first two signatures, and it gives the book's own number (section 21.6). One that was not compared gives no pass.
+   */
+  used: boolean;
+  verified: 'all' | 'some' | 'none';
+  problems: Finding[];
+  notes: string[];
+  signatures: KeySignature[];
+  /** Its own time-stamps: checked and shown, not used for the entries of the book. */
+  stamps: Stamp[];
+  /** The witness statements handed over with it. One that counts, for a seal the book holds at its place, counts for that seal. */
+  witnesses: WitnessCheck[];
+  content?: any;
+  /** The earliest time a time-stamp from a trusted service gives it, where all three of its signatures were checked. */
+  stampedAt?: Time;
+}
+
 export interface CheckResult {
   format: string;
   size: number;
@@ -340,14 +412,21 @@ export interface CheckResult {
   problems: Finding[];
   notes: string[];
   entries: CheckedEntry[];
-  /** What was handed over beside the book, and what came of it. */
-  held: HeldCancellation[];
+  /** What was handed over beside the book, and what came of it: the cancellations first, then the seals. */
+  held: (HeldCancellation | HeldSeal)[];
   summary: Summary;
 }
 
 export interface CheckOptions {
   /** The thumbprints of the issuer keys the checker expects. */
   issuerKeys?: string[];
+  /**
+   * The addresses of the pages at which the checker expects every slip to
+   * have been signed, each in the form of the format description's section
+   * 4.1 (https://, a website name in lower case, a port only if needed). At
+   * most 64. A slip signed at any other address is refused.
+   */
+  issuerOrigins?: string[];
   /** The key set fingerprints of the recorders the checker expects. */
   sealKeys?: Fingerprint[];
   /** The certificate fingerprints of the time-stamp services the checker trusts. */
@@ -356,6 +435,8 @@ export interface CheckOptions {
   blocks?: string[];
   /** The key set fingerprints of the organisations whose vouching the checker trusts. */
   vouchers?: Fingerprint[];
+  /** The key set fingerprints of the witnesses the checker trusts (format description, section 29). */
+  witnesses?: Fingerprint[];
   /** For covered fields: the disclosures handed over, by the fingerprint of the slip they belong to. */
   disclosures?: Record<Fingerprint, string[]>;
   /**
@@ -364,6 +445,11 @@ export interface CheckOptions {
    * out, or holds them with a later time-stamp.
    */
   cancellations?: HandedCancellation[];
+  /**
+   * Seals held elsewhere, each as the entry it is in the book. At most 64. The book must hold each at the
+   * place it states. Each counts only where its recorder is one named in "sealKeys".
+   */
+  seals?: HandedSeal[];
   expectedRoot?: Fingerprint;
   expectedSize?: number;
   /** Signing methods to treat as not built into this device. It can only withhold a pass. */
@@ -402,10 +488,24 @@ export interface Checker {
 /** The options are fixed when the checker is opened. The book so far may be empty. */
 export function openChecker(text?: string, options?: CheckOptions): Promise<Checker>;
 export function checkShow(show: Show | string, options?: CheckOptions): Promise<CheckResult>;
-export function checkSlip(record: SignedRecord, options?: Pick<CheckOptions, 'issuerKeys' | 'withoutMethods' | 'disclosures'>, disclosures?: string[]): Promise<SlipCheck>;
+export function checkSlip(record: SignedRecord, options?: Pick<CheckOptions, 'issuerKeys' | 'issuerOrigins' | 'withoutMethods' | 'disclosures'>, disclosures?: string[]): Promise<SlipCheck>;
+/**
+ * Whether a text is the address of a page in the one form the format allows for a slip's "issuer.origin" (format
+ * description, section 4.1), which is also the form each address in "issuerOrigins" must have: https:// (or
+ * http://localhost), a website name in lower case, a port only where it is needed, and nothing more.
+ */
+export function isPageAddress(text: unknown): boolean;
 export function methodAvailable(alg: string): Promise<boolean>;
 export function thumbprint(key: PublicKey): Promise<string>;
 export function keySetFingerprint(keys: KeySet | SealKeySet): Promise<Fingerprint>;
+/**
+ * Check a consistency proof (RFC 9162, section 2.1.4.2): that the tree of m leaves whose root is rootM is the first
+ * part of the tree of n leaves whose root is rootN. For m equal to n the proof is empty and the roots the same; for
+ * m of 0 the proof is empty and rootM the root of the empty tree. Never throws for a bad proof.
+ */
+export function verifyConsistency(m: number, n: number, rootM: Uint8Array, rootN: Uint8Array, proof: Uint8Array[]): Promise<boolean>;
+/** Check an audit path (RFC 9162, section 2.1.3.2). */
+export function verifyInclusion(index: number, size: number, leaf: Uint8Array, path: Uint8Array[], root: Uint8Array): Promise<boolean>;
 /** The fingerprint of a block, as it is written everywhere: 64 hex characters. */
 export function blockFingerprint(header: Uint8Array): Promise<string>;
 /** A chain of Bitcoin block headers, checked on this device from the chain's first block. */
@@ -433,6 +533,8 @@ export function conditionWords(condition: Condition): string;
 export function neverWords(name: string): string;
 export const LIMITS: string[];
 export const REFUSAL_REASONS: Record<string, string>;
+/** Who said no, in a denial: "check", "person" or "rule", each with its meaning. */
+export const DENIAL_SOURCES: Record<'check' | 'person' | 'rule', string>;
 
 export interface Proposal extends Request {
   slip: Fingerprint;
@@ -478,8 +580,18 @@ export interface Recorder {
        * answer says why.
        */
       detailsAfter?: (result: T) => DocumentRef[] | null | undefined | Promise<DocumentRef[] | null | undefined>;
+      /** False writes no denial for this call, where the writer was opened with "denials: true". */
+      denial?: boolean;
     },
-  ): Promise<{ done: boolean; answer: BeforeAnswer; result?: T; stub?: WrittenStub; detailsAfter?: { added: number; problem: Finding | null } }>;
+  ): Promise<{ done: boolean; answer: BeforeAnswer; result?: T; stub?: WrittenStub; detailsAfter?: { added: number; problem: Finding | null }; denial?: DenialAnswer }>;
+  /**
+   * Writes a denial for an action that was not taken where "act" wrote none: the person said no, a rule of the
+   * software around the agent said no, or ("check", with the codes of that answer) the check before acting said no
+   * on a call for which "act" was asked to write none. A writer opened without "denials: true" writes none.
+   */
+  deny(request: Request, more: { source: 'check' | 'person' | 'rule'; codes?: string[]; when?: number | Date }): Promise<DenialAnswer>;
+  /** Whether this writer writes denials, as it was opened. */
+  readonly denials: boolean;
   book(): string;
   /**
    * What the record shows as it stands: the answer a whole check of the book gives, with the cancellations
@@ -503,6 +615,11 @@ export interface Recorder {
    */
   add(entry: BookEntry): Promise<{ acknowledgement?: SignedRecord }>;
 }
+/**
+ * What the stub writer did about a denial. "notWritten" counts the denials not written because of the hourly
+ * limit since the writer was opened.
+ */
+export type DenialAnswer = { written: true; fingerprint: Fingerprint; line: string; notWritten: number } | { written: false; problem: Finding; notWritten: number };
 /** A stub the stub writer wrote. A countersignature that did not check is left out, and "problem" says why. */
 export type WrittenStub = Written & { seq: number; line: string; countersignature: { accepted: boolean; problem: Finding | null } };
 export function openRecorder(o: {
@@ -519,6 +636,10 @@ export function openRecorder(o: {
   countersignWithin?: number;
   /** How long a signer is given for each signature, in milliseconds. Defaults to 30,000. After that nothing is written. */
   signWithin?: number;
+  /** True to write a denial whenever "act" does not take an action, and to let "deny" write one. Defaults to false. */
+  denials?: boolean;
+  /** The most denials written in any hour, by the clock: 1 to 100,000. Defaults to 600. */
+  denialsPerHour?: number;
 }): Promise<Recorder>;
 
 /** One of an agent's tools, as it is described to recordTools. */
@@ -530,7 +651,7 @@ export interface RecordedTool<A = any, R = any> {
   /** The id of the service the tool deals with, as the slip names it. */
   with?: string | ((args: A) => string | undefined);
   amount?: Amount | ((args: A) => Amount | undefined);
-  /** The documents to name in the stub, or false for none. By default: "arguments", the fingerprint of the arguments. */
+  /** The documents to name in the stub, or false for none. By default: "provared.arguments", the fingerprint of the arguments. */
   details?: false | ((args: A) => DocumentRef[] | Promise<DocumentRef[]>);
   /** Asks the other side to countersign the stub. */
   countersign?: (stub: SignedRecord, args: A) => Promise<SignedRecord | null>;
@@ -539,9 +660,11 @@ export interface RecordedTool<A = any, R = any> {
 }
 /** A call through a recorded tool that was not run. "answer" is what the check before acting said. */
 export class NotTaken extends Error {
-  constructor(tool: string, answer: BeforeAnswer);
+  constructor(tool: string, answer: BeforeAnswer, denial?: DenialAnswer);
   tool: string;
   answer: BeforeAnswer;
+  /** Where the stub writer writes denials: what it did about the denial for this call. */
+  denial?: DenialAnswer;
 }
 /**
  * Puts an agent's tools behind the stub writer: each call asks first, runs the tool only if the slip allows
@@ -624,6 +747,15 @@ export function writeAcknowledgement(
   fields: { slip: Fingerprint; cancellation: Fingerprint; pass?: Fingerprint; when?: number | Date; id?: Base64url },
   privateKeys: SigningKey[],
 ): Promise<Written>;
+/** The format's own list of finding codes, from which a denial by the check before acting names its reasons. */
+export const FINDING_CODES: readonly string[];
+/** The reasons of a refusal by the check before acting, as a denial names them: 1 to 16 codes, each once. */
+export function denialCodes(answer: Pick<BeforeAnswer, 'problems' | 'breaches'>): string[];
+/** The agent's side states that it did not take an action that was asked for, and why. */
+export function writeDenial(
+  fields: Request & { slip: Fingerprint; pass?: Fingerprint; source: 'check' | 'person' | 'rule'; codes?: string[]; when?: number | Date; id?: Base64url },
+  privateKeys: SigningKey[],
+): Promise<Written>;
 /**
  * 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
@@ -631,10 +763,139 @@ export function writeAcknowledgement(
  */
 export function writeSeal(
   book: string,
-  fields: { by: { keys: SealKeySet; name: string }; previous?: Fingerprint; when?: number | Date; id?: Base64url },
+  /** "book": the book's number among the books of one permission, 2 or more; 1 or none for the first (section 21.6). */
+  fields: { by: { keys: SealKeySet; name: string }; previous?: Fingerprint; book?: number; when?: number | Date; id?: Base64url },
   privateKeys: unknown[],
 ): Promise<Written & { fingerprintBytes: Uint8Array }>;
 
+/** The most witness statements beside one seal, or handed over with one seal held elsewhere. */
+export const MAX_WITNESSES: 4;
+/** A witness signs for a seal. This only writes the statement; it does not check the seal (see openWitness). */
+export function writeWitness(
+  fields: { seal: Fingerprint; size: number; root: Fingerprint; by: { keys: KeySet; name: string }; when?: number | Date; id?: Base64url },
+  privateKeys: SigningKey[],
+): Promise<Written>;
+/** The consistency proof from the tree of the first m leaves to the tree of all of them (RFC 9162, section 2.1.4.1). Empty for m of 0 or m equal to the number of leaves. */
+export function consistencyProof(leaves: Uint8Array[], m: number): Promise<Uint8Array[]>;
+/** The audit path of one leaf (RFC 9162, section 2.1.3). */
+export function inclusionPath(leaves: Uint8Array[], index: number): Promise<Uint8Array[]>;
+/** How a witness keeps sequences of books apart: the recorder's key set, with the passkey and the agent's key set that the permission on the book's first line names. */
+export function bookIdentity(keys: SealKeySet, firstLine: Uint8Array): Promise<Fingerprint>;
+/**
+ * What a witness is sent with a seal: the consistency proof from the seal it holds for the book ("from", its number
+ * of entries), or, where it holds none or the seal is the first of the next book, the audit path of the book's first line in
+ * the new seal's tree.
+ */
+export function witnessProof(book: string, size: number, from?: number | null): Promise<Uint8Array[]>;
+/** A witness's state, as it hands it back: to be saved before a statement is given out. */
+export interface WitnessState {
+  type: 'provared.witness-state.v0';
+  /** The fingerprint of the witness's key set. */
+  by: Fingerprint;
+  /** For each recorder, passkey (its thumbprint) and agent (the fingerprint of its key set): the latest seal this witness signed for, and its statement. */
+  books: { passkey: Fingerprint; agent: Fingerprint; seal: SignedRecord; statement: SignedRecord }[];
+}
+export type WitnessAnswer<T> = T | { refused: Finding };
+export interface Witness {
+  /** Sign for a seal if it extends the latest seal of its book this witness holds. The state handed back holds the new seal: save it first. */
+  witness(entry: { seal: SignedRecord; stamps?: StampItem[]; witnesses?: SignedRecord[] }, proof: Uint8Array[], firstLine: Uint8Array): Promise<WitnessAnswer<{ statement: SignedRecord; state: WitnessState }>>;
+  /** Take as the latest seal of its book a seal this witness signed for before, from a copy of what it gave out. It signs nothing. */
+  update(entry: { seal: SignedRecord; witnesses: SignedRecord[]; stamps?: StampItem[] }, proof: Uint8Array[], firstLine: Uint8Array): Promise<WitnessAnswer<{ state: WitnessState }>>;
+  /** Opened from a saved state, the witness signs nothing until it is told it has been brought up to date. */
+  ready(): void;
+  latest(book: Fingerprint): { seal: SignedRecord; statement: SignedRecord } | null;
+  state(): WitnessState;
+}
+/** A witness needs SLH-DSA, so it needs Node.js. */
+export function openWitness(o: {
+  by: { keys: KeySet; name: string };
+  signers: SigningKey[];
+  state?: WitnessState;
+  clock?: () => number;
+  withoutMethods?: string[];
+}): Promise<Witness>;
+
+/** The leaf fingerprint of one line of a book, without its line feed: SHA-256 of 0x00 and the line (RFC 6962, section 2.1). What a recorder sends a central sealer. */
+export function leafFingerprint(line: string): Promise<Uint8Array>;
+/** Which book a sealer call is about: the leaf fingerprint of its first line (a first book), or that with the book's number (section 21.6). */
+export type SealerBook = Fingerprint | { first: Fingerprint; number?: number };
+/** A central sealer's state, as it hands it back: to be saved before the answer is given out. At most 1,000 books. */
+export interface SealerState {
+  type: 'provared.sealer-state.v0';
+  /** The fingerprint of the sealer's key set. */
+  by: Fingerprint;
+  /**
+   * For each book: its first line's leaf fingerprint and number, the recorder it belongs to (absent for the sealer's own calls),
+   * the book it follows, whether a later book follows it, and its latest seal with the tree's parts at that seal. A book is kept at
+   * its latest seal, or with none at its first line: lines that no seal covers are asked for again after a start.
+   */
+  books: {
+    first: Fingerprint;
+    number: number;
+    recorder?: string;
+    follows?: Fingerprint;
+    closed: boolean;
+    /** The latest seal and its time-stamps (at most four); witness statements are never kept. */
+    latest?: { entry: { seal: SignedRecord; stamps?: StampItem[] }; parts: Base64url[] };
+  }[];
+}
+export type SealerAnswer<T> = T | { refused: Finding; size?: number };
+/** The calls of a central sealer, made as one recorder (forRecorder) or as none (the sealer's own). */
+export interface SealerCalls {
+  /**
+   * Take in the leaf fingerprints of new lines of one book, in order, from place "at" (the number of lines it holds). A later book
+   * names the book it follows; a book whose first line the sealer holds starts only as the next book after the latest with that
+   * first line. "line" is the book's first line itself: where any recorder has a list of agents, a book is started only with it,
+   * and it must be a permission for an agent of the caller's own. Where the call started a book, the answer holds the state: save it first.
+   */
+  extend(book: SealerBook, at: number, leaves: Uint8Array[], more?: { follows?: Fingerprint; line?: string }): Promise<SealerAnswer<{ size: number; state?: SealerState }>>;
+  /** Sign a seal over the tree this sealer holds; "previous" is the seal the new seal must name, as the book shows it. The state handed back holds the new seal: save it first. */
+  seal(
+    book: SealerBook,
+    more: { previous: Fingerprint | null; when?: number | Date; id?: Base64url },
+  ): Promise<SealerAnswer<{ entry: { seal: SignedRecord; stamps?: StampItem[] }; line: string; fingerprint: Fingerprint; fingerprintBytes: Uint8Array; state: SealerState; stampProblem?: Finding }>>;
+  /**
+   * Bring the sealer up to date for a book from a later seal it signed, with the leaf fingerprints from its own latest seal to that one.
+   * Where it is the first seal of a later book, the book before is closed; where the sealer holds that book at an earlier seal than the
+   * one named, it is refused until that book is brought up to date. A book it does not hold is started here under the same rules
+   * as with extend, "line" included. It signs nothing. It keeps the seal, whose three signatures it checks, and its time-stamps
+   * (at most four), read for their form only: no time-stamp's signature is checked. It keeps no witness statements; an entry longer
+   * than a line of a book may be is refused (too-large). The entry is read once, and only that copy is used.
+   */
+  update(
+    book: SealerBook,
+    entry: { seal: SignedRecord; stamps?: StampItem[]; witnesses?: SignedRecord[] },
+    leaves: Uint8Array[],
+    more?: { line?: string },
+  ): Promise<SealerAnswer<{ size: number; state: SealerState }>>;
+  latest(book: SealerBook): { entry: { seal: SignedRecord; stamps?: StampItem[] }; line: string; fingerprint: Fingerprint } | null;
+  held(book: SealerBook): { first: Fingerprint; number: number; follows: Fingerprint | null; size: number; closed: boolean; latest: Fingerprint | null; sealed: number } | null;
+}
+export interface Sealer extends SealerCalls {
+  state(): SealerState;
+  /**
+   * The same calls for one named recorder (a label): its books, and every book after them, are its own. "rules": the fingerprints
+   * of the key sets of the agents whose permissions it may start books with (1 to 64; an agent belongs to one recorder), and the
+   * most books it may hold (1 to 1,000). A recorder's rules are fixed by the first call that gives them.
+   */
+  forRecorder(recorder: string, rules?: { agents?: Fingerprint[]; books?: number }): SealerCalls;
+  /**
+   * Take off the books that hold no seal (nothing was signed for them): every recorder's, or one recorder's (null for the sealer's
+   * own calls). The state handed back is to be saved.
+   */
+  releaseUnsealed(o?: { recorder?: string | null }): Promise<{ released: { first: Fingerprint; number: number; recorder: string | null }[]; state: SealerState }>;
+}
+/** A central sealer: it seals books it is sent only the leaf fingerprints of. It checks every seal it signs, so it needs Node.js. */
+export function openSealer(o: {
+  by: { keys: SealKeySet; name: string };
+  signers: unknown[];
+  /** Ask a time-stamp service for a stamp over a seal's fingerprint: an item of "stamps", or null. */
+  stamp?: (fingerprintBytes: Uint8Array) => Promise<StampItem | null> | StampItem | null;
+  state?: SealerState;
+  clock?: () => number;
+  signWithin?: number;
+}): Promise<Sealer>;
+
 /** A proof from a public blockchain and the 80-byte header of its block, in the form they have in "stamps". */
 export function blockStampItem(proof: Uint8Array, header: Uint8Array): { block: Base64url; proof: Base64url };
 
@@ -667,7 +928,7 @@ export const DOCUMENT_NAMES: Readonly<Record<string, string>>;
 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. */
+/** For "provared.trace-id", "provared.request-id", "provared.event-id", "provared.error", "provared.tool-name" and "provared.tool-call-id": SHA-256 of the text's UTF-8 bytes, exactly as given. A tool's result ("provared.tool-result") is fingerprinted with argumentsFingerprint. */
 export function identifierFingerprint(id: string): Promise<Fingerprint>;
 export const ACTION_KINDS: Record<string, string>;
 export const SHARED_ACTIONS: Record<string, [kind: string, meaning: string]>;

package/src/witness.js

@@ -0,0 +1,63 @@
+// The witness statement: a party with a key set of its own (a witness)
+// states that it saw a seal, that the seal extends every earlier seal of
+// the same book it signed for, and that it will sign for no seal of that
+// book that does not extend this one. It is signed with the witness's two
+// keys. A statement sits beside its seal in the seal's book entry, as
+// time-stamps do, or is handed to a checker beside a seal held elsewhere.
+// Format description, section 29.
+
+import { formatTime, randomId } from './encoding.js';
+import * as f from './fields.js';
+import { KINDS } from './jws.js';
+import { checkKeySet } from './keys.js';
+import { signWithKeySet } from './stub.js';
+
+/** The most witness statements one seal entry may hold, or that may be handed over with one seal. */
+export const MAX_WITNESSES = 4;
+
+/**
+ * Confirm every member of a witness statement's content.
+ * @param {any} c
+ */
+export function validateWitnessContent(c) {
+  f.members(c, ['by', 'id', 'root', 'seal', 'size', 'type', 'when'], [], 'witness');
+  f.id(c.id, 'id');
+  f.fingerprintText(c.seal, 'seal');
+  f.wholeNumber(c.size, 'size');
+  if (c.size < 1) throw f.fail('size', 'must be 1 or more.');
+  f.fingerprintText(c.root, 'root');
+  f.members(c.by, ['keys', 'name'], [], 'by');
+  f.label(c.by.name, 'by.name');
+  checkKeySet(c.by.keys, 'by.keys');
+  f.time(c.when, 'when');
+}
+
+/**
+ * Write and sign a witness statement for a seal. This function only writes
+ * the statement: it does not check the seal. A witness should sign only as
+ * the format description, section 29.3, sets out; openWitness
+ * (witnessing.js) does.
+ *
+ * @param {object} fields
+ * @param {string} fields.seal the seal's fingerprint
+ * @param {number} fields.size the seal's "size", repeated
+ * @param {string} fields.root the seal's "root", repeated
+ * @param {{keys: object[], name: string}} fields.by the witness's public key set and its name (a label)
+ * @param {number|Date} [fields.when] defaults to now
+ * @param {any[]} privateKeys the witness's private keys, or signers (signatures.js): Ed25519, then ML-DSA-87. A
+ *   signer must hold the key "by" names in its place
+ * @returns {Promise<{record: object, fingerprint: string}>}
+ */
+export async function writeWitness(fields, privateKeys) {
+  const content = {
+    type: KINDS.witness.type,
+    id: fields.id ?? randomId(),
+    seal: fields.seal,
+    size: fields.size,
+    root: fields.root,
+    by: fields.by,
+    when: formatTime(fields.when ?? Date.now()),
+  };
+  validateWitnessContent(content);
+  return signWithKeySet('witness', content, privateKeys, content.by.keys);
+}