provared 0.5.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.5.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.5.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
-`cec1b8d5e6e7a11c00478c6e83d9f9b5963340ec656657ea0ac84f32e8e52bda`.
+`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,60 @@ 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
@@ -619,8 +883,9 @@ 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` still names the arguments `arguments` by default; a tool
-can name them `provared.arguments` through its own `details` function.
+`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
 
@@ -798,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 |
 
@@ -826,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.
@@ -852,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`,
@@ -893,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.
 
@@ -906,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