provared 0.4.0 → 0.6.0

package/docs/guide.md

@@ -6,7 +6,7 @@ Everything about the format, the library, the checker, the stub writer beside an
 
 ## Status
 
-**Version 0.4.0, a draft.** Published as it is, by one author in their
+**Version 0.6.0, a draft.** Published as it is, by one author in their
 own time; fixes as time allows. The format may still change, so do not
 rely on a draft record staying checkable.
 
@@ -21,7 +21,7 @@ An Internet-Draft is a working document, not a standard.
 |---|---|---|
 | **Slip** | A short permission a person signs with a passkey: which agent, which actions, what limits and conditions, with whom, from when until when, and why | Built |
 | **Stub** | A signed receipt for each action, pointing back to its slip, countersigned by the other side where possible, and approved by the person where the slip asks for it | Built |
-| **Seal** | The stubs chained together and gathered under one top fingerprint, signed by whoever keeps the book and time-stamped by an outside service | Built. A public place where seals are kept is not |
+| **Seal** | The stubs chained together and gathered under one top fingerprint, signed by whoever keeps the book, time-stamped by an outside service, and signed for by witnesses | Built, with the part of a witness that decides and signs. A public place where seals are kept is not |
 | **Show** | One page shown to a checker with proof that it is in the book, and when the book was sealed, with the names it does not need kept covered | Built. Only a slip's names and purpose can be covered so far |
 
 ## What is here
@@ -151,9 +151,9 @@ be loaded from anywhere. The tool prints the file's SHA-256 fingerprint,
 so that a copy can be compared with it. (Tried on 8 October 2026 in the
 three browser builds this repository is tested with, and on 13 October
 2026 in Chrome 155, Edge 155 and Brave 155.) The file for
-version 0.4.0 is attached to the release on GitHub. Its SHA-256
+version 0.6.0 is attached to the release on GitHub. Its SHA-256
 fingerprint is
-`49da6617ff493ddda2b2b65bfb6bedebdf8cf07ea6faa32b039f065eda207307`.
+`ae48c425616d70849aa8d43b1d71ef7ee56736da3ba6a00eaa4375c428e60a25`.
 
 **Run the demonstration in a browser.**
 
@@ -168,8 +168,9 @@ is invented: nothing is bought, sent or deleted. The checking
 page on its own is at `http://localhost:8787/check`. It takes a record
 file, the fingerprints you already trust (keys, time-stamp services,
 blocks), and what you were handed with the record: the person's own
-copies of cancellations, and disclosures for covered fields. All of it is
-read in the browser and sent nowhere.
+copies of cancellations, seals of the book held elsewhere, and
+disclosures for covered fields. All of it is read in the browser and
+sent nowhere.
 
 ## What a slip can say
 
@@ -236,6 +237,214 @@ The fingerprints for the sample are in
 `samples/office-supplies.expected.json`. The sample's time-stamp service
 is made up, as its passkey is.
 
+### Seals held elsewhere
+
+Whoever keeps the book can cut off its end, with the last seal, and what
+is left still checks. Anyone who keeps a copy of a seal elsewhere (the
+person, an auditor, a second copy out of the recorder's reach) can hand
+it to the checker beside the book, as the entry it is in the book:
+
+```
+provared-check record.jsonl --seal seal.json --sealer <fingerprint> --issuer <thumbprint>
+```
+
+In the library: `seals`, up to 64. A seal at entry n covers the n
+entries before it, so the book must hold that very seal at entry n. A
+book that ends before it is reported as cut short (`book-cut-short`); a
+book that holds another line there, as changed (`seal-not-in-book`).
+Both are problems with the book. A seal handed over is checked as any
+seal is, and counts only where you named its recorder (`--sealer`, or
+`sealKeys`); one that does not pass its own check is a problem with the
+whole check. On a device without SLH-DSA (the Python version, and
+browsers that have ML-DSA, such as Edge and Brave 155 when tested) it
+counts on its Ed25519 and ML-DSA-87 signatures, and says so; on a device
+without ML-DSA it is not used. The seal is compared with the book by its
+content: the same content with other signatures is the same seal, and
+the answer says that the signatures differ. Nothing in a seal names its
+book, so hand over only seals of the book being checked: a seal of
+another book by the same recorder (for example the book it kept before
+it started a new one) is reported as `seal-not-in-book` or
+`book-cut-short`. Without `--sealer`, the seals handed over are not
+compared with the book, and the command-line checker says so on a line
+of its own and gives no pass.
+Its own time-stamps are shown but are not used for the entries of the
+book. The answer lists each one in `held`, after any cancellations. A
+Show does not use one. What it does not catch: a book cut back after the
+latest seal anyone holds, or a book never shown to anyone who holds one.
+
+### Witnesses
+
+A witness is a party, with a key set of its own, that keeps for each
+book the latest seal it has signed for, and signs a short statement for
+a new seal only where the new seal extends that one (format
+description, section 29). The recorder sends it the seal and a
+consistency proof (RFC 9162, section 2.1.4); the statement goes beside
+the seal on its line, in `witnesses`, up to four, or is handed to the
+checker later with a copy of the seal (`--seal` with a file of
+`{"seal": ..., "witnesses": [...]}`). Name the witnesses you trust by
+the fingerprints of their key sets:
+
+```
+provared-check record.jsonl --witness <fingerprint> --sealer <fingerprint> --issuer <thumbprint>
+```
+
+In the library: `witnesses`. The answer's `summary.witnessed` gives the
+latest seal for which a statement from a witness you trust counts, the
+entries it covers, those witnesses, and every seal witnessed; the
+command-line checker prints it as "Witnessed by a witness you trust?".
+A statement that does not check, or that speaks of another seal, is a
+problem (`witness-invalid`). A statement counts only where you also
+named the passkey you trust (`--issuer`) and the recorder you expect
+(`--sealer`), the book starts with a permission signed by that passkey,
+and every permission before the seal is from that passkey for the same
+agent (a Show must hold every page the seal covers): a witness knows a book only by the passkey and the agent of
+the permission it starts from and its recorder's keys, and the recorder
+chooses the first line and its keys. Being witnessed excuses nothing
+and is not needed for a pass. What it adds: a second history of the
+entries before a witnessed seal, sealed by the same recorder and
+starting from any permission that passkey gave that agent (a renewal
+included), shown to someone else, would need that witness to sign for it
+too. What it does not: a history sealed with other keys, even keys you
+also named, or one that starts from a permission for another agent;
+anything never shown to the witness; or the time. To see whether the end
+of the book is missing, ask the witness for the latest seal it holds for
+this recorder, passkey and agent, and hand that seal over beside the book
+it is of. One recorder key set keeps one sequence for each person and
+agent: books kept side by side for one agent need recorder keys of
+their own.
+
+A recorder may keep the record of one permission in several books: a
+seal says which in `book` (2, 3 and so on; the first book has no
+number), and the first seal of a later book names the last seal of the
+book before. `writeSeal` takes `book`. A witness treats every book of one
+recorder, person and agent as one sequence: it signs for a new book only
+where its first seal starts from the latest seal it holds, and never
+again for the book before. A checker of one book does not see the book
+before; handed that book's last seal, it says whether this book follows
+on from it (format description, section 21.6). A seal handed over that
+gives another book number than the book is not compared with it, and
+gives no pass: the command-line checker says "Seals held elsewhere
+compared? NO" and does not end with code 0, even for an honest book.
+To check book n − 1 against the seal book n starts from, check book
+n − 1 with that seal handed over beside it.
+
+The library holds a witness: `openWitness({ by, signers, state })`, with
+`witness(entry, proof, firstLine)`, which signs only for a seal whose
+three signatures it checked and that extends the seal it holds, and
+hands back its state with each statement, to be saved before the
+statement is given out; `update`, `ready`, `latest` and `state`.
+`witnessProof(book, size, from)` makes the proof to send it (`from`:
+the size of the seal the witness holds of the same book, or none for a
+first seal and for the first seal of the next book), and `bookIdentity`
+names a sequence as a witness knows it: by the recorder's keys with the
+passkey and the agent of the permission on the book's first line. Whoever can change a witness's
+state can make it forget a sequence: keep it as safely as its keys. A
+witness needs SLH-DSA, so it needs Node.js; the Python version has none.
+
+### A central sealer
+
+The recorder's three keys need not sit on the agent's computer. A
+central sealer, run by a team other than the one that runs the agent,
+holds them and seals books it never sees: the recorder sends it the
+leaf fingerprint of each new line (`leafFingerprint(line)`: the SHA-256
+of the byte 0x00 and the line), and asks for a seal; the sealer builds
+the same tree as the checker, signs a seal over its own number of
+entries and top fingerprint, and hands back the seal's entry, which the
+recorder adds to its book with the stub writer's `add` (format
+description, section 21.7). A sealer sent a wrong fingerprint signs a
+seal the book refuses (`seal-mismatch`).
+
+```js
+import { leafFingerprint, openSealer, toBase64url } from 'provared';
+
+const sealer = await openSealer({ by: { keys, name: 'Our central sealer' }, signers, state });
+const first = toBase64url(await leafFingerprint(lines[0]));       // a book is known by its first line
+await sealer.extend(first, 0, await Promise.all(lines.map(leafFingerprint)));
+const made = await sealer.seal(first, { previous: null });         // the seal the book's latest seal names, or null
+// save made.state first, then hand made.entry to the book
+```
+
+`extend(book, at, leaves)` takes lines only at the place it holds, so a
+line is never taken twice. `seal(book, { previous })` signs only where
+`previous` is the latest seal it holds of that book: a sealer whose
+state is behind the book signs nothing until it is brought up to date
+with `update(book, entry, leaves)` (the book's latest seal, and the leaf
+fingerprints since the latest seal it holds); a book that lost a seal
+the sealer gave takes it back with `latest(book)`. A later book is named
+`{ first, number }`, and its first `extend` names the book it follows
+(`{ follows }`); its first seal names the last seal of that book, which
+is then closed, and so is a book brought up to date from such a first
+seal (bring books up to date in their order: a later book's first seal
+is refused, `not-up-to-date`, while the sealer holds the book before at
+an earlier seal than the one it names). Every book with one first line
+is one chain: a book whose first line the sealer holds starts only as
+the next book after the latest with that first line (`not-next-book`). A sealer that serves several
+recorders gives each its own calls, `sealer.forRecorder(name)`: a book,
+and every book after it, belongs to the recorder that started it, and
+another recorder's calls about it are refused (`other-recorder`) or
+answered as if the sealer did not hold it. Recorders that do not trust
+each other are given rules, `sealer.forRecorder(name, { agents, books })`:
+the fingerprints of the key sets of the agents whose permissions each may
+start books with (an agent belongs to one recorder), and the most books
+each may hold. Then every book is started with its first line itself
+(`extend(book, 0, leaves, { line })`, or `update(book, entry, leaves, {
+line })` for a book brought in), which must be a permission for one of
+the recorder's own agents (`agent-not-allowed`, or `other-recorder` for
+another recorder's agent); so no recorder can start a book whose first
+line is a permission for another recorder's agent. `releaseUnsealed()` takes off the
+books that hold no seal, for which nothing was signed. Save the state
+handed back with a seal, with a book started (`extend`) and with
+`update` before the answer is given out, and the one `releaseUnsealed`
+hands back. Of a seal entry brought in with `update`, the sealer keeps
+the seal, whose three signatures it checks, and its time-stamps, read
+for their form only: it checks no time-stamp's signature, so one that
+`latest` gives back is not vouched for by the sealer. A book is
+kept in the state at its latest seal, or with none at its first line:
+started again, the sealer asks for the lines since. It keeps at most
+1,000 books, about 52 KB of state for each sealed book. It checks every
+seal it signs, so it needs Node.js; the Python version has
+`leaf_fingerprint` only.
+
+What a central sealer adds, and what still needs a witness. With its
+state kept, it never signs two different histories of one first line.
+With rules, it starts a recorder's books only from permissions for that
+recorder's own agents, and so learns each first line. It sees only
+fingerprints after the first line, so it cannot tell that a book which
+starts from another first line (another permission for the same agent,
+or, with no rules, any record the agent's side can sign) repeats lines
+of a book it has sealed. A sealer that loses its state, or is put back
+to an older copy, can be made to sign a second history, and two states
+kept with one key set are two sealers. A witness is the check for these
+(format description, sections 21.7 and 29).
+
+One case a witness does not settle. A recorder, through its own calls
+alone, can start a book from a permission for one of its own agents and
+copy into it the permissions and stubs of another recorder's agent,
+leaving out any it chooses (a stub over a limit, say); the sealer seals
+it. Where one person's passkey signed the permissions for both agents,
+a reader who names that passkey and the sealer's key set finds the book
+intact and within its slips. A witness statement on its seal is not
+counted (the seal covers a permission for an agent other than the first
+line's), so the seal reads as not witnessed, but nothing reports why.
+What shows it: a seal of the other recorder's own book, held elsewhere
+and handed to the checker with this book (`seals`, `--seal`), gives
+`book-cut-short` or `seal-not-in-book`; or, where the two books'
+numbers differ, it cannot be compared, and the checker says so and
+gives no pass. So readers of books from a
+sealer shared by recorders that do not trust each other should hold
+each recorder's own seals elsewhere, or the organisation should run a
+sealer, with its own key set, for each recorder (format description,
+section 21.7).
+
+The folder `sealer/` of the repository holds `provared-sealer`, a small
+program around it: it listens on 127.0.0.1, takes questions only from the
+recorders it was given (each proves that it holds its token, which never
+travels), names each recorder with its agents and its number of books,
+keeps one state for all of them, keeps its keys in a file for its owner
+alone or reaches them through signer modules named in its settings, and
+makes sure the state is on the disk before it answers a question that
+changed it. See its README.
+
 ### Knowing that a block is part of the chain
 
 **Experimental.** `provared-headers` is new in version 0.1.0 and may
@@ -533,7 +742,8 @@ A call that the slip does not allow throws `NotTaken`, with the answer
 of the check before acting, and the tool is not run. Where the slip asks
 for the person's own approval, a tool's `approve` function is asked for
 it once. By default the stub of a call names one document,
-`arguments`: the fingerprint of the call's arguments, written in one
+`provared.arguments` (the reserved name of section 27 of the format
+description): the fingerprint of the call's arguments, written in one
 form (RFC 8785). So the record fixes exactly what was asked for without
 holding it; `argumentsFingerprint` works the same fingerprint out again.
 The arguments must be JSON: a list with a gap in it, or with a named
@@ -551,6 +761,132 @@ not a promise. The numbers `0` and `-0` share a fingerprint, as RFC
 though the tool has run and its stub is in the book. `recordTools`
 names no agent software, and works with any function.
 
+### Denials: the calls the agent's side refused
+
+A book shows what the agent did, not how often it was stopped. Opened
+with `denials: true`, the stub writer also writes a **denial** whenever
+`act` does not take an action: the agent's side's own signed statement
+that it did not take it, and why (format description, section 28).
+
+```js
+const recorder = await openRecorder({ book, slip, privateKeys, issuerKeys, denials: true });
+
+const outcome = await recorder.act({ action: 'provared.data.delete' }, async () => removeTheFiles());
+outcome.done;              // false: the slip does not allow it
+outcome.denial.written;    // true: the book now holds a denial, by "check", with the reason "action-not-allowed"
+
+// A refusal that came from elsewhere: the person said no, or a rule of the software around the agent did.
+await recorder.deny({ action: 'provared.order.place', amount: { unit: 'GBP', value: 900 } }, { source: 'person' });
+```
+
+A denial names what was asked for (its action, amount and service) and
+who said no: `check` (the check before acting, with the codes it gave),
+`person` or `rule`. Its documents are fingerprints only; arguments are
+never written into it. `more.denial: false` asks `act` to write none
+for one call. A writer writes at most `denialsPerHour` (600 by default)
+in any hour by its clock. Each denial it writes, or is handed through
+`add`, counts at the clock's time when it joins the book, whatever date
+it states; those of its own chain that the book already held when it
+was opened count at the dates they state. Past that it writes none, and
+each answer's `notWritten` says how many it left out since it was
+opened. A writer opened again on a book counts the book's denials at
+their stated dates, so a caller who dates denials back and then opens
+the writer again can get a second burst (5 and then 5 more within 3,302
+seconds, at a limit of 5). At 600 an hour, an agent that is refused again and again still
+fills a book's 100,000 entries in about a week: the limit slows that,
+it does not stop it. A stub is never kept out by that limit, and
+nothing that goes wrong in writing a denial makes `act` or `deny` fail:
+the answer says what was done. `deny` does throw where the call itself
+is malformed: a request that is not an object, or that cannot be copied
+as plain data, a `when` that is neither
+a number nor a date, `codes` that cannot be copied, or a call from
+inside an action, which is refused as every call from there is. It
+writes nothing for a writer opened without `denials: true`, and takes a
+`when` within 300 seconds of the clock. It records what its caller
+states: it does not check that the action was not taken, so a caller
+can write a denial for a request that also has a stub.
+
+`recordTools` passes it on: with a writer that writes denials, a call
+that is not run leaves one, and `NotTaken` holds what was done
+(`denial`). Where a tool can ask the person for approval, no denial is
+written until it is known that the call will not run: so one call
+leaves a stub or a denial, never both. A checker shows each denial as
+the agent's side's own word, counts it (`summary.counts.denials`), and
+never counts it against the agent. An agent can simply not write one,
+so a book without denials shows nothing about refusals.
+
+### Binding a stub to the platform's own record
+
+Where the other side will not countersign, a stub can still be matched
+with the other system's own log of the call: name, among its documents,
+the fingerprint of an identifier that both records hold. Document names
+that begin `provared.` are reserved for this (format description,
+section 27); any other such name is refused.
+
+| Name | The fingerprint of | Made with |
+|---|---|---|
+| `provared.arguments` | The call's arguments, in the one form of RFC 8785 | `argumentsFingerprint` |
+| `provared.http-request` | The request: its method, its address exactly as sent, and its body where it has one; no header | `httpRequestFingerprint` |
+| `provared.http-response` | The answer: its status code, and its body where it has one; no header | `httpResponseFingerprint` |
+| `provared.trace-id` | The trace-id of the W3C Trace Context `traceparent` header the agent's side sent (its form is not checked) | `identifierFingerprint` |
+| `provared.request-id` | An identifier the agent's side chose and sent with the call | `identifierFingerprint` |
+| `provared.event-id` | An identifier the platform gave for the call | `identifierFingerprint` |
+| `provared.error` | The error text the agent's software was given | `identifierFingerprint` |
+
+`DOCUMENT_NAMES` lists them, each with the exact text it stands for. An
+HTTP request or answer is written as the signature base of RFC 9421
+(nothing is signed with it): the address is taken exactly as it was
+sent, never rewritten, so give it in the form that was sent. A body is
+the bytes RFC 9530 digests: after any content coding (such as gzip),
+before any transfer coding; a body of `null` is no body. The three
+identifiers may be named more than once in a stub; every other reserved
+name once at most. A trace-id is fingerprinted as given: its form (32
+lower-case hexadecimal characters in the W3C standard) is not checked.
+
+An identifier that the platform gives only in its answer cannot be in a
+stub signed before the action. `act` takes `detailsAfter` for it:
+
+```js
+import { identifierFingerprint } from 'provared';
+
+const outcome = await recorder.act(
+  { action: 'provared.data.change', with: 'tickets' },
+  async () => updateTheTicket(),               // gives the platform's answer
+  { detailsAfter: async (answer) => [{ name: 'provared.event-id', sha256: await identifierFingerprint(answer.requestId) }] },
+);
+outcome.detailsAfter;   // { added: 1, problem: null }
+```
+
+The stub is still written and checked with the whole book before the
+action, so it is known to fit. After the action it is signed again with
+up to four further documents, within the same call, so that no other
+call comes between; it keeps the time the action began. If
+`detailsAfter` fails, gives no answer in the time the other side is
+given to countersign (`countersignWithin`), gives more than four
+documents, or gives one that would be refused, the stub is written
+without them, and `outcome.detailsAfter.problem` says why: an action
+that was taken always gets its stub. The request may then name at most
+28 documents of its own, and no approval may be given, because an
+approval covers exactly the documents the person saw. `detailsAfter`
+must not call the writer.
+
+A matching identifier shows that the two records speak of one call, not
+that the call did what either says: the platform's identifier is the
+platform's word. It binds the two only where the platform writes the
+same identifier into its own log; which one a platform keeps is for you
+to find out, so record both one you sent and one you were given where
+you can. Only an identifier picks out one call: a fingerprint of a
+request, an answer, the arguments or an error shows only that the
+content matches, since identical requests, and identical answers (many a
+`200` with the body `{}`), share one fingerprint. A platform that logs
+the decoded body of a compressed message will not match the body's
+fingerprint. An identifier that is short or easy to guess can be guessed
+from its fingerprint.
+
+`recordTools` names the arguments `provared.arguments` by default (before
+version 0.6.0, `arguments`; every checker reads both); a tool can name
+them otherwise through its own `details` function.
+
 ## How signing works
 
 - **The person** signs a slip with a passkey. A passkey signs a short
@@ -575,6 +911,107 @@ names no agent software, and works with any function.
   signatures were not checked, and does not show a pass. Node.js checks
   all of them.
 
+### Keys held elsewhere: signers
+
+The keys of an agent, a service, an organisation or a recorder need not
+sit in the memory of the program that writes the records. Wherever a
+writer takes `privateKeys` (`openRecorder`, `writeStub`, `countersign`,
+`writeRefusal`, `writeTerms`, `writePass`, `writeAcknowledgement`,
+`writeVouching`, `writeWithdrawal` and `writeSeal`), each item may be a
+key, as before, or a **signer**: an object with two members.
+
+- `key`: the public key, as a JSON Web Key in one of the shapes the
+  format allows (format description, section 3.8).
+- `sign(data)`: a promise of the signature over exactly those bytes, as a
+  `Uint8Array` or an `ArrayBuffer`.
+
+A signer lets a key live in a key service or a hardware module. Keys and
+signers may be mixed: an agent may keep its ML-DSA-87 key in a key
+service and its Ed25519 key elsewhere. `signerFromKey(alg, privateKey,
+key)` wraps a key held in memory as a signer, so that both take one path.
+
+```js
+import { openRecorder, signerFromKey } from 'provared';
+
+// "keyService.sign" stands for the service's own call. It must sign the
+// bytes themselves, not a fingerprint of them.
+const held = {
+  key: agentKeys[1],                       // the agent's ML-DSA-87 public key, as the slip names it
+  sign: (data) => keyService.sign('agent-ml-dsa-87', data),
+};
+const recorder = await openRecorder({
+  book, slip, issuerKeys,
+  privateKeys: [signerFromKey('Ed25519', ed25519PrivateKey, agentKeys[0]), held],
+  signWithin: 10000,                       // milliseconds for each signature; 30,000 by default
+});
+```
+
+A record made through a signer is the same record as one made with the
+key itself: the same content, the same labels and the same Ed25519
+signature. ML-DSA-87 and SLH-DSA signatures are made afresh each time,
+with a key or through a signer, so those differ between any two
+signings, as they always did.
+
+A signer is not taken on trust:
+
+- Its two members are read once. Its key must be exactly a key of the
+  method of its place in the list, as plain data.
+- A signer for a method this device does not have built in is refused
+  before any signer is asked to sign, since its signatures could not be
+  checked here.
+- Where the writer knows the key the record must be signed with, the
+  signer's key must be that key: the agent's keys as the slip names them,
+  or a helper's as its pass names them, in the stub writer; the keys
+  `by` names in `writeSeal`, `writeRefusal`, `writeTerms` and
+  `writeVouching`. A signer for another key is refused (`bad-key`)
+  before any signer is asked to sign. This catches the most likely
+  fault of a key held elsewhere: a mistyped key name in its settings.
+  The stub writer compares when it is opened, with the slip, or the
+  pass it acts under, as its book holds it. Opened with a pass that its
+  book does not yet hold, it compares nothing then, and refuses each
+  action (`pass-missing`), as it always did.
+- `writeStub`, `countersign`, `writePass`, `writeAcknowledgement` and
+  `writeWithdrawal`, used by themselves, cannot know which key the
+  record must be signed with. There a signer for another key gives a
+  record that fails its own check, as a wrong key in memory always did.
+- Every signature it gives is checked against its key before it is
+  used. A signature of the wrong length, one that does not check
+  (another key used, or other bytes signed, such as a fingerprint of
+  them), something other than bytes, or a `sign` that throws: no record
+  is made (`signature-invalid`), nothing is written to a book, and the
+  error names the place in the list, the method and the key's
+  thumbprint.
+- In the stub writer, a signer is given `signWithin` milliseconds for
+  each signature (30,000 by default). After that the action is not
+  taken, nothing is written, the writer goes on to its next call, and a
+  late answer is not used. A signer that calls the writer is refused at
+  once, as an action that does so is. The other writers set no time of
+  their own: a signer that never answers leaves the call waiting, so give
+  the signer's own connection a time limit.
+
+Where no record is made, signers earlier in the list may already have
+signed, and a signer that ran out of time may still sign later. So a key
+service's own log may hold signatures that match no record.
+
+A key given as before is used exactly as before: a private Web Crypto
+`CryptoKey` of the method of its place and, in a seal's SLH-DSA place, a
+private 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). Anything
+else that is not a signer (a public key, a key of another method or
+kind, a value that only looks like a key) is refused (`bad-field`).
+
+What a signer does not change:
+
+- **The library cannot know how a key held elsewhere is kept**, who else
+  can ask for signatures with it, or whether the service keeps it safe.
+  It checks only that each signature fits the key the signer names.
+- **A record does not say where a key was kept.** A record signed
+  through a key service reads the same as one signed with a key in
+  memory, and a key set split between two places reads as one agent.
+- **Each signature costs one more check.** Measured on one computer on
+  15 October 2026: about 0.3 thousandths of a second for Ed25519, 0.6
+  for ML-DSA-87 and 2 for SLH-DSA-SHA2-256s.
+
 ## Using the library
 
 ```js
@@ -626,15 +1063,15 @@ answer with a named reason. It keeps two things apart:
 |---|---|
 | `size`, `root` | How many entries the book holds, and its top fingerprint |
 | `problems` | Problems with the book as a whole |
-| `entries` | One for each line: `index`, `kind` (`slip`, `stub`, `refusal`, `terms`, `seal`, `cancellation`, `acknowledgement`, `vouching`, `withdrawal`, `pass` or `unreadable`), `fingerprint`, `verified` (`all`, `some` or `none` of its signatures confirmed here), `problems`, `breaches`, `notes`, the signature states, and `content`. Where a time-stamp you trust on a later seal covers the entry: `existedBy`, the time by which it is shown to have existed. On a seal or a cancellation that passed its check: `stampedAt`, the time its own time-stamps give it |
-| `held` | One for each cancellation handed over beside the book: whether it passed its check and was used, whether the book holds it (`inBook`), the time its time-stamp gives, and the acknowledgements handed over with it (`acknowledgements`: who acknowledged, and when by their own word) |
+| `entries` | One for each line: `index`, `kind` (`slip`, `stub`, `refusal`, `terms`, `seal`, `cancellation`, `acknowledgement`, `vouching`, `withdrawal`, `pass`, `denial` or `unreadable`), `fingerprint`, `verified` (`all`, `some` or `none` of its signatures confirmed here), `problems`, `breaches`, `notes`, the signature states, and `content`. Where a time-stamp you trust on a later seal covers the entry: `existedBy`, the time by which it is shown to have existed. On a seal or a cancellation that passed its check: `stampedAt`, the time its own time-stamps give it |
+| `held` | One for each cancellation handed over beside the book (`kind` `cancellation`): whether it passed its check and was used, whether the book holds it (`inBook`), the time its time-stamp gives, and the acknowledgements handed over with it (`acknowledgements`: who acknowledged, and when by their own word). Then one for each seal held elsewhere (`kind` `seal`): whether it passed its check and was used, the entry it stands at (`place`), whether the book holds it there (`inBook`), its recorder's key set (`sealer`), its signatures and time-stamps |
 | `summary.problemFound` | A problem was found somewhere in the record |
 | `summary.fullyChecked` | Every signature was checked on this device |
 | `summary.intact` | No problem was found **and** every signature was checked. The only answer that is a pass |
 | `summary.methodsMissing` | The signing methods this device lacks, if any, for example `ML-DSA-87` |
 | `summary.withinSlips` | Every stub was compared with its slip, and none is outside it |
 | `summary.firstBreach` | The first entry that shows the agent outside its slip, if any |
-| `summary.counts` | Slips, stubs, countersigned stubs (the countersignature confirmed on this device), one-sided stubs (no countersignature; a stub that was not checked, because its slip failed, is neither), stubs the person approved, refusals, sets of terms, and the other kinds of entry |
+| `summary.counts` | Slips, stubs, countersigned stubs (the countersignature confirmed on this device), one-sided stubs (no countersignature; a stub that was not checked, because its slip failed, is neither), stubs the person approved, refusals, sets of terms, denials (the agent's side's own word, never counted against it), and the other kinds of entry |
 | `summary.sealed` | How far the last time-stamp you trust reaches: how many entries, the time they existed by, and whether a service or a block (`by`) gave it. Otherwise nothing |
 | `summary.limits` | What no check can show, in plain sentences |
 
@@ -654,9 +1091,11 @@ Options: `issuerKeys` (the thumbprints of issuer keys you trust),
 expect), `stampServices` (the fingerprints of the certificates of the
 time-stamp services you trust), `blocks` (the fingerprints of the
 blocks of a public blockchain you trust), `vouchers` (the fingerprints of the key
-sets of the organisations whose vouching you trust), `disclosures` (the
+sets of the organisations whose vouching you trust), `witnesses` (the
+fingerprints of the key sets of the witnesses you trust), `disclosures` (the
 disclosures of covered fields that you were handed), `cancellations`
-(the person's own copies of cancellations), `expectedRoot` and
+(the person's own copies of cancellations), `seals` (seals of the book
+held elsewhere), `expectedRoot` and
 `expectedSize` (a top fingerprint and a number of entries you already
 hold a copy of). Give
 them whenever you have them.
@@ -680,7 +1119,8 @@ Writing records: `prepareSlip` and `assembleSlip`, `prepareApproval` and
 `writeRefusal` and `writeTerms` (the service), `writeVouching` and
 `writeWithdrawal` (an organisation), `writePass` (an agent, to a helper
 agent), `writeSeal` (whoever keeps
-the book; it needs Node.js), `writeBook` and `makeShow`, all from
+the book; it needs Node.js), `writeWitness` and `openWitness` (a
+witness; `openWitness` needs Node.js), `consistencyProof`, `writeBook` and `makeShow`, all from
 `provared`. The library asks no time-stamp service itself: you send
 the seal's fingerprint to the service you choose and put its answer
 beside the seal. In a browser, `createPasskey`, `signSlipWithPasskey`,
@@ -706,6 +1146,10 @@ prepared, then `assembleSlip`; keep the disclosures it prepared.
 - A name in a record is a label. Only keys are checked. A vouching
   record shows which organisation stood behind a name, not how well it
   checked.
+- An identifier of another system's, named in a stub, shows that the
+  two records speak of one call, not that the call did what either
+  says. A fingerprint of a request, an answer, the arguments or an error
+  shows only that the content matches, not that it was the same call.
 
 And about time:
 
@@ -717,7 +1161,10 @@ And about time:
   the agent outside its slip;
 - the last seal, with everything after it, can itself be removed. Only a
   copy of it, or of its top fingerprint and number of entries, held by
-  someone else shows that;
+  someone else shows that: hand such a copy of a seal to the checker
+  (`--seal`, or `seals`), such as the latest seal a witness holds;
+- a witness statement is the witness's own word for when it saw the
+  seal, and is not used as a time-stamp;
 - time-stamp services sign with methods of today's kind, which are not
   quantum-safe.
 
@@ -730,7 +1177,9 @@ connects to anything: to the Bitcoin nodes you name, for block headers.
 
 ## Not built yet
 
-A public place where seals are kept; covering fields other than a slip's
+A public place where seals are kept, which gathers the seals of many
+books; a witness that runs as a service (the library holds the part that
+decides and signs); covering fields other than a slip's
 names and purpose; connectors for particular agent software (the
 general one, `recordTools`, is built); a compact binary form; the
 recorder service. The checking page cannot yet take a chain of block