provared 0.5.0 → 0.6.0

package/docs/threat-model.md

@@ -91,6 +91,20 @@ follows the checking steps of the Web Authentication standard.
   section 6b. Slips should still be short-lived.
 - Who the issuer is. The slip proves which key signed, not whose key it
   is.
+- Against a page that has the passkey sign a record dressed as a sign-in.
+  A passkey signs only a challenge, and the challenge for a slip, an
+  approval or a cancellation is the fingerprint of the record, which the
+  person cannot read on the device's prompt. Any page at an origin under
+  the slip's `rpId` (the website's own operator, a script running on one
+  of its pages, or the operator of any subdomain) can hand the device the
+  fingerprint of a record it wrote as an ordinary sign-in challenge: the
+  client data of a sign-in and of a record have the same shape, and the
+  person sees a sign-in prompt. No device and no page need be broken into.
+  The checker compares the origin and the rpId only with what the slip
+  itself says. So a passkey that signs records should be registered to a
+  relying party (an `rpId`) used for nothing else, and the page that asks
+  for the signature should show the record first. The checker has no
+  option yet by which a reader names the origin they expect.
 
 ## 4. The Stub and the countersignature
 
@@ -479,7 +493,8 @@ unnoticed).
   what is left still checks. This can hide the very stub that shows the agent outside its
   slip. A seal closes this for everything before it (section 6a). After
   the last seal, only a copy of a top fingerprint, with its number of
-  entries, held by someone else would show it.
+  entries, or a copy of a later seal, held by someone else would show it
+  (section 6a, "Seals held elsewhere").
 - **Writing a different history with the agent's keys.** A1, A3 or A5
   can sign a second, different chain under the same slip. Countersigned
   stubs resist this, because the service's keys are needed. One-sided
@@ -549,8 +564,38 @@ person checking gives.
 - **The end of the book.** The last seal, with everything after it, can
   be removed, and what is left still checks. Only a copy of that seal, or
   of its top fingerprint and number of entries, held by someone else
-  shows it. A public place where seals are kept would close this; it is
-  not built.
+  shows it. A seal held elsewhere can be handed to the checker beside the
+  book (below), and a witness that signs for each seal (section 6f)
+  holds the latest one it signed for. A public place where seals are
+  kept, which gathers the seals of many books, is not built.
+- **Seals held elsewhere.** The person, an auditor, or any copy kept out
+  of the recorder's reach can hand the checker, beside the book, up to 64
+  seal entries it holds (option `seals`, `--seal` on the command line, files on
+  the checking page). A seal at entry n stands at entry n of the
+  book, so the checker reports a book that ends before that place
+  (`book-cut-short`) and a book that holds another line there
+  (`seal-not-in-book`). This closes the end of a book cut off after a seal
+  someone else holds, back to any place before that seal, and a second
+  history shown to someone who holds a seal of the first. What it does
+  not close: a book cut back after the latest seal anyone holds; a book,
+  or a part of one, never shown to anyone who keeps a seal; and a holder
+  who keeps no seal at all. A seal handed over counts only where the
+  person named its recorder (`sealKeys`), and only where the device checked
+  its Ed25519 and ML-DSA-87 signatures; 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 those two, and says so; on a device
+  without ML-DSA it is not used. It is compared with the book by its
+  content: the same content with other signatures is the same seal, and
+  is said, not reported against the book. It can only show a problem
+  with the book, never excuse one, so this widens nothing. Nothing in a
+  seal names its book, so a seal of another book by the same recorder
+  (one it kept before, when it started a new book) is reported against
+  the book being checked: hand over only that book's seals. A seal handed over that does not pass its own check is a
+  problem with the whole check, never set aside. Its time-stamps are
+  checked and shown, but are not used for the entries of the book: where
+  they differ from those beside the same seal in the book, the checker
+  says so. A Show does not use a seal held elsewhere, and says so: single
+  pages cannot show what the book holds at the place the seal states.
 - **Entries after the last time-stamp.** They are not time-stamped.
 - **A recorder who seals a false book.** A1 holding the agent's keys and
   the recorder's keys can write another history and seal it. A time-stamp
@@ -659,7 +704,17 @@ person checking gives.
   such a key, so the checker refuses the key itself. For the same reason
   it refuses an Ed25519 signature whose point R is of small order, under
   any key: the key's own holder could make one for any message, which one
-  library accepts and another refuses. The key in a
+  library accepts and another refuses. It also refuses, itself, an
+  Ed25519 signature whose number S is not below the order L, which RFC
+  8032 requires and some libraries do not check, and an ES256 passkey key
+  that is not a point on its curve (`bad-key`), which can check nothing
+  and which libraries report in different ways. A time-stamp signed with
+  Ed25519 must name SHA-512 as its fingerprint method, with no
+  parameters, as RFC 8419 requires, and may name the certificate that
+  signed it only once in each form (RFC 5035, sections 3 and 5): two
+  checkers could otherwise pick different certificates. A time-stamp is
+  read as strict DER throughout, every set it holds in the order DER
+  requires, so that two checkers cannot read one time-stamp in two ways. The key in a
   certificate must be written exactly as its standard sets out, so that
   two checkers cannot disagree about whether it can be read.
 
@@ -893,6 +948,174 @@ make a pass: it needs the keys of the agent that passes on.
   every stub under it, as outside the slip. The record is still sound.
   Only an eleventh pass in a row, which no slip can allow, is refused.
 
+## 6e. The denial
+
+A denial (format description, section 28) is the agent's side's signed
+statement that it did not take an action that was asked for, and who
+said no: the check before acting, the person, or a rule of the software
+around the agent.
+
+**Protects.** That a denial in the book was signed by the agent the slip
+names, or by the helper its pass names, under a slip that is earlier in
+the book (`slip-missing`, `pass-missing`, `pass-mismatch`,
+`signature-invalid`). A6 cannot make one. A7 cannot use one to change
+any other answer: a denial is in no chain, adds to no total, and is never
+counted against the agent, so a flood of denials, or a denial that names
+an action far outside the slip, makes no stub read as outside it. A
+denial changed after it was signed, or under another kind of record's
+labels, is refused like any record. In this library, `act` writes a
+denial only where it did not take the action, so one call through `act`,
+`recordTools` or `record_function` leaves a stub or a denial, never both
+(the connector for an agent's tools asks for no denial until it knows
+the person will not approve). `deny` is different: it records whatever
+its caller states, and a caller can write a denial for a request that
+also has a stub; the checker shows both. The writer keeps to a set
+number of denials an hour of its own clock (600 by default), counting
+each it writes at the clock's time, so that an agent that asks again and
+again cannot fill its book quickly: at 600 an hour a book's 100,000
+entries still fill in about a week. A stub is never kept out by that
+limit.
+
+**Does not protect.**
+
+- **It is the agent's side's own word.** A3 can write a denial for an
+  action it then took some other way, or a false reason. Only the other
+  side's records, or the service's own refusal, can show otherwise.
+- **An agent can simply not write one.** A book with no denial shows
+  nothing about how often the agent was stopped. A1 or A2 can also leave
+  denials out of a copy of the book after the last seal, as any entry.
+- **What was asked for is in clear.** A denial names the action, the
+  amount and the service. Its documents are fingerprints only, and the
+  library never writes arguments into it; but a fingerprint of a short
+  or guessable value can be guessed.
+- **The source is not checked.** Nothing shows that the person, or a
+  rule, said no: `person` and `rule` are the agent's side's statement.
+  A denial by the check before acting names the codes the check gave,
+  and nothing in the record shows that the check was made.
+- **Older checkers** refuse a book that holds a denial (`unknown-entry`).
+
+## 6f. Witnesses, and a book shown two ways
+
+A recorder that keeps a book (A1, A2) can show one history to one reader
+and another to another (a "split view"): each copy checks, and each is
+sealed, so a reader who holds one copy cannot see the other. A witness
+(format description, section 29) is a party with a key set of its own
+that keeps, for each recorder, person and agent, the latest seal it
+signed for, and signs a statement for a new seal only where the new seal
+extends that one: in the same book, by a consistency proof (RFC 9162,
+section 2.1.4), or as the first seal of the next book (section 21.6). The
+person and the agent are those the permission on a book's first line
+names: its passkey and the agent's key set. So every permission one
+person gives one agent under one recorder, renewals included, is one
+sequence: the independent review showed that a sequence known by the
+permission alone let a book that started with a renewal fork the
+history, and a witness now refuses it. The statement sits beside the seal on its line, or is
+handed to a checker later with a copy of the seal.
+
+**Protects.** That a statement a checker counts was signed by a witness
+the person named, by the fingerprint of its key set, and speaks of that
+very seal: its `seal`, `size` and `root` must be the seal's, both its
+signatures must check, and it may not be dated more than 300 seconds
+before the seal (`witness-invalid`). A6 and A7 cannot make one, and a
+statement from a witness nobody named is shown and not counted. A
+statement that does not pass is a problem; one handed over beside the
+book is a problem with the whole check, and the seal it came with is
+used all the same. Being witnessed excuses nothing: it changes no other
+answer, and a book with a problem is never said to be witnessed.
+
+A witness knows which books are one sequence only by the passkey and the
+agent of the permission on their first line and the keys of their
+recorder, and the recorder (A1, A2) chooses the first line and its keys: it can start a history with another first line, or
+seal it with new keys, and the same honest witness signs for it as
+another sequence. So a statement counts only where the person fixed
+both: the book's first line is a permission that passed its check,
+signed by a passkey the person named (`issuerKeys`), and the person
+named the recorders they expect (`sealKeys`). The independent review of
+this step showed a history that began with made-up terms, then the
+permission, signed by the same witness and read as witnessed; it now
+reads as not witnessed, and the witness itself no longer keeps a book
+whose first line is not a permission.
+
+And every permission among the entries a seal covers must name the same
+passkey and agent as the first line's. The third round of the review
+showed a fork through a second agent of the same person under the same
+recorder, the gateway's own set-up: a book that started with agent Y's
+permission, then held agent X's permission and X's stubs without the
+one over its limit, was signed by the witness as the first book of the
+person and agent Y, and read as witnessed. It now reads as not
+witnessed, with a note saying why; so does one that starts with a
+second passkey's permission for X. A witness cannot refuse such a book
+itself: it sees a book's first line, not its entries. A Show counts a
+statement only where its pages hold every entry the seal covers, so it
+never counts one that the whole book would not.
+
+What it narrows, where the witness keeps section 29.3 and the person
+fixed the start: a second history sealed by the same recorder and
+starting from any permission that passkey gave the same agent needs that
+witness to sign for it too, which it does not do. So two readers who name that witness, the
+same passkey and the same recorder cannot be shown two such histories
+that both carry its statements and that disagree before the earlier of
+the two seals it signed for. A new book cannot start from an earlier
+seal than the latest the witness holds, so the books of one permission
+cannot fork either. Two witnesses need two to fail. The latest seal a
+witness holds, handed over beside the book it is of as a seal held
+elsewhere (section 6a), shows that book cut back to before that seal
+(`book-cut-short`, `seal-not-in-book`). The witness program in the
+library (`openWitness`) checks a seal's three signatures, signs nothing
+on a device that cannot check SLH-DSA (so there is none in the Python
+version), ties the first line to the seal with an audit path at first
+contact and at each new book, keeps it tied with each consistency proof,
+never signs two different seals of one book at one size, never again
+signs for a book once it has signed for the next, and hands back what it
+holds with each statement, to be kept before the statement is given
+out.
+
+**Does not protect.**
+
+- **Other recorder keys, or another agent.** A history sealed with
+  another key set, even one the person also named, or that starts from a
+  permission for another agent, is another sequence to a witness, and a
+  fork made that way is not caught. A person who names two recorders
+  should know that a fork sealed with the second reads as witnessed. One
+  recorder key set keeps one sequence for each person and agent, so books
+  kept side by side for one agent need recorder keys of their own, and
+  are then other sequences.
+- **What a later book holds.** A later book can repeat, or leave out,
+  what an earlier book holds: each book is checked on its own.
+- **A book sealed again under another number.** A book cut short can be
+  sealed again with another book number. A seal held elsewhere is then of
+  another 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, and the checking page gives no green
+  answer. The reader learns that their seal was not compared, not where
+  the book was cut.
+- **What is never shown to a witness.** A recorder can keep a book, or
+  the end of one, from every witness. Nothing in a book obliges it to be
+  witnessed, and a checker that is not handed the witness's latest seal
+  does not know of later seals. Where that latest seal is of a later
+  book, a checker of an earlier book cannot use it to show that earlier
+  book cut short: it cannot tell whether a seal of the next book is that
+  book's first (section 21.6).
+- **A witness that fails.** A witness that signs for two histories, or
+  that loses what it holds or is put back to an older copy of it, can
+  sign a fork, and nothing in either history shows it. The library's
+  witness, opened again from what it kept, signs nothing until it is
+  brought up to date (`update`) and told so (`ready`); it cannot tell
+  whether what it was given is the latest it gave out. Whoever can change
+  what it keeps can make it forget a sequence, which it then signs for
+  again from any seal: its state must be kept as safely as its keys.
+- **The entries.** A witness sees a seal's size and top fingerprint,
+  not the entries: it shows that the entries existed in that form when
+  it saw the seal, not that they are true.
+- **Time.** A statement's `when` is the witness's own word, and is not
+  used as a time-stamp.
+- **Limits across books.** A checker counts a limit within the book it
+  checks, not across the books of a permission.
+- **A device that cannot check both of a statement's signatures**
+  counts nothing, and the record is not fully checked there.
+- **Older checkers** refuse a seal's line that holds `witnesses`
+  (`unknown-entry`), and a seal that gives `book` (`bad-field`).
+
 ## 7. The checker and the checking page
 
 **Protects.** A7 cannot crash the checker, make it run a script, or make
@@ -923,7 +1146,11 @@ it show a pass for a record that does not check.
   the checker itself put there.
 - "Within its slip" is said only if every stub and every pass was
   compared on this device.
-- Records over a fixed size, or nested too deeply, are refused.
+- Records over a fixed size, or nested too deeply, are refused. A book
+  may hold 100,000 lines of 131,072 bytes, about 13 gigabytes in all;
+  this library takes a book as one text, so it can check no book larger
+  than one text the device can hold, and a checker should bound the size
+  it accepts (format description, section 9).
 - The content of a record must be written in one canonical form (RFC
   8785). A record with a repeated field name, stray spaces or an unusual
   number form is refused, so two checkers cannot read the same record in
@@ -988,7 +1215,10 @@ it show a pass for a record that does not check.
 ## 8. What is refused, and the test that proves it
 
 Each row is one test in `test/refusals.test.mjs`, named by its code. A
-further test reads this table and fails if a code here has no test.
+further test reads this table and fails if a code here has no test. This
+table is also the format's own list of finding codes, from which a denial
+names its reasons (format description, section 28); `test/denial.test.mjs`
+fails if the two differ.
 
 | Code | What is refused or reported |
 |---|---|
@@ -1001,8 +1231,8 @@ further test reads this table and fails if a code here has no test.
 | `payload-not-canonical` | Content that is not in the canonical form, including a repeated field name |
 | `payload-type-mismatch` | Content of one kind under the label of another, for example a stub presented as a countersignature |
 | `bad-field` | A missing, extra or wrongly typed field |
-| `bad-key` | A public key that is not exactly of an accepted kind |
-| `signature-invalid` | A signature that does not fit the key |
+| `bad-key` | A public key that is not exactly of an accepted kind, an Ed25519 key of small order or written in more than one way, or an ES256 key that is not a point on its curve |
+| `signature-invalid` | A signature that does not fit the key, or an Ed25519 signature whose R is a point of small order or whose S is not below the order L |
 | `passkey-wrong-type` | A passkey answer that was made for creating a passkey, not for signing |
 | `passkey-challenge-mismatch` | A passkey signature made for other content |
 | `passkey-origin-mismatch` | A passkey used on a website other than the one the slip names |
@@ -1041,10 +1271,13 @@ further test reads this table and fails if a code here has no test.
 | `seal-mismatch` | A seal that does not fit the entries before it: an entry was changed, added or removed after the seal was made. In a Show: a seal for another book, or for another length of this one |
 | `seal-chain-broken` | A seal that does not name the seal before it: a seal is missing, moved or changed |
 | `sealer-not-expected` | A seal signed with keys other than the ones the checker was told to expect |
+| `book-cut-short` | A book that ends before the place of a seal held elsewhere and handed over beside it: its end was cut off after that seal was made |
+| `seal-not-in-book` | A book that holds another line at the place of a seal held elsewhere and handed over beside it: it was changed after that seal was made, or the seal is of another book |
+| `witness-invalid` | A witness statement, beside a seal in the book or handed over with a seal held elsewhere, whose signatures do not fit the keys it gives, that speaks of another seal, or that is dated more than 300 seconds before its seal |
 | `dated-after-stamp` | An entry dated later than the outside time-stamp that covers it, or a seal dated later than its own time-stamp |
 | `stamp-bad-data` | A time-stamp that is not laid out as its standard sets out |
 | `stamp-wrong-data` | A time-stamp made for something other than this seal |
-| `stamp-invalid` | A time-stamp whose signature does not check, or that is dated outside the time its service's certificate was in force |
+| `stamp-invalid` | A time-stamp whose signature does not check, that names the certificate that signed it twice in one form, that is signed with Ed25519 and names a fingerprint method other than SHA-512, or that is dated outside the time its service's certificate was in force |
 | `headers-invalid` | A chain of block headers in which a header breaks a rule that every Bitcoin node applies, that does not hold the known blocks at their places, or that ends before the last of them (tested in `test/headers.test.mjs`) |
 | `record-not-sound` | The check before acting: the record so far has a problem, or could not be checked on this device, so no action is allowed |
 | `proof-invalid` | A one-page proof that does not lead to the top fingerprint |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provared",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Proof of what an AI agent was allowed to do, and what it then did. A passkey-signed permission with limits a machine can check, a signed receipt for each action, and a free checker. Evidence, not a verdict.",
   "author": "Pavel Izmaylov",
   "license": "Apache-2.0 AND CC-BY-4.0",
@@ -71,7 +71,7 @@
     "node": ">=24.7"
   },
   "scripts": {
-    "test": "node --disable-warning=ExperimentalWarning --test",
+    "test": "node --disable-warning=ExperimentalWarning --test \"test/**/*.test.mjs\"",
     "check": "node --disable-warning=ExperimentalWarning bin/provared-check.mjs",
     "headers": "node bin/provared-headers.mjs",
     "demo": "node --disable-warning=ExperimentalWarning demo/server.mjs"

package/page/check-page.js

@@ -6,7 +6,7 @@
 // request at all.
 
 import { checkBook, checkShow } from '../src/check.js';
-import { readBlocks, readFingerprints, renderResult, shown } from './render.js';
+import { readBlocks, readFingerprints, readHanded, renderResult, shown } from './render.js';
 
 const status = document.getElementById('status');
 const result = document.getElementById('result');
@@ -14,9 +14,6 @@ const result = document.getElementById('result');
 // This page reads the whole file into memory. A larger book is checked
 // with the command-line checker.
 const MAX_FILE_BYTES = 200000000;
-// A copy of a cancellation, or a file of disclosures, is small.
-const MAX_HANDED_BYTES = 1000000;
-const MAX_COPIES = 16;
 
 // What the person already trusts: one fingerprint to a line. A line that
 // is not a fingerprint stops the check, and the person is told which box.
@@ -25,6 +22,7 @@ const BOXES = [
   ['trust-sealer', 'sealKeys', 'whoever keeps and seals the book'],
   ['trust-stamps', 'stampServices', 'time-stamp services'],
   ['trust-vouchers', 'vouchers', 'organisations whose vouching you trust'],
+  ['trust-witnesses', 'witnesses', 'witnesses you trust'],
 ];
 
 function trusted() {
@@ -42,34 +40,14 @@ function trusted() {
   return options;
 }
 
-async function jsonFrom(file, what) {
-  if (file.size > MAX_HANDED_BYTES) throw new Error(`The file of ${what}, ${shown(file.name)}, is too large. Nothing was checked.`);
-  try {
-    return JSON.parse(await file.text());
-  } catch {
-    throw new Error(`The file of ${what}, ${shown(file.name)}, is not JSON. Nothing was checked. Choose another file, or clear these files.`);
-  }
-}
-
-// What the person was handed with the record: their own copies of
-// cancellations, and disclosures for covered fields. A file that cannot be
-// read stops the check: it is never set aside silently.
-async function handedOver() {
-  const options = {};
-  const said = [];
-  const copies = [...document.getElementById('cancellations').files];
-  if (copies.length > MAX_COPIES) throw new Error('At most 16 copies of cancellations can be handed over at once. Nothing was checked.');
-  if (copies.length) {
-    options.cancellations = [];
-    for (const file of copies) options.cancellations.push(await jsonFrom(file, 'a cancellation'));
-    said.push(copies.length === 1 ? 'one copy of a cancellation' : `${copies.length} copies of cancellations`);
-  }
-  const [disclosures] = document.getElementById('disclosures').files;
-  if (disclosures) {
-    options.disclosures = await jsonFrom(disclosures, 'disclosures');
-    said.push('disclosures for covered fields');
-  }
-  return { options, said };
+// What the person was handed with the record: the files chosen in the
+// panel "What you were handed with the record" (render.js, readHanded).
+function handedOver() {
+  return readHanded({
+    cancellations: [...document.getElementById('cancellations').files],
+    seals: [...document.getElementById('seals').files],
+    disclosures: document.getElementById('disclosures').files[0] ?? null,
+  });
 }
 
 async function check(text, name, { beside = true, trust = null } = {}) {
@@ -131,6 +109,7 @@ if (chooser.files.length > 0) checkChosen(chooser);
 
 document.getElementById('clear-beside').addEventListener('click', () => {
   document.getElementById('cancellations').value = '';
+  document.getElementById('seals').value = '';
   document.getElementById('disclosures').value = '';
   status.textContent = 'The files you were handed with a record are cleared.';
 });

package/page/index.html

@@ -26,6 +26,8 @@
     <textarea id="trust-stamps" rows="2" spellcheck="false"></textarea>
     <label for="trust-vouchers">Organisations whose vouching for names you trust (the fingerprint of each one's key set)</label>
     <textarea id="trust-vouchers" rows="2" spellcheck="false"></textarea>
+    <label for="trust-witnesses">Witnesses you trust to have seen the seals (the fingerprint of each one's key set)</label>
+    <textarea id="trust-witnesses" rows="2" spellcheck="false"></textarea>
     <label for="trust-blocks">Blocks of a public blockchain that you trust to be part of the chain (the fingerprint of each block: 64 characters, the digits 0 to 9 and the letters a to f)</label>
     <textarea id="trust-blocks" rows="2" spellcheck="false"></textarea>
   </details>
@@ -34,6 +36,8 @@
     <p class="quiet">Choose these files first, then choose the record file. They stay chosen, and are used with every record you check, until you clear them. The sample record is checked without them.</p>
     <label for="cancellations">The person's own copies of cancellations: one file for each, up to 16. A copy counts even where the book leaves the cancellation out. A file may also hold what the agent's side signed when it was handed the cancellation.</label>
     <input type="file" id="cancellations" accept=".json,.txt" multiple>
+    <label for="seals">Seals of the book held elsewhere, by you, an auditor or a copy kept apart: one file for each, up to 64. The book must hold each at the place it states; one that ends before it was cut short. A seal counts only where you named its recorder above. A file may also hold statements that witnesses signed for the seal.</label>
+    <input type="file" id="seals" accept=".json,.txt" multiple>
     <label for="disclosures">Disclosures for covered fields of a slip: one file</label>
     <input type="file" id="disclosures" accept=".json,.txt">
     <p><button type="button" class="second" id="clear-beside">Clear these files</button></p>