provared 0.3.0 → 0.5.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.3.0, a draft.** Published as it is, by one author in their
+**Version 0.5.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.
 
@@ -149,11 +149,11 @@ in a browser straight from the disk; it needs no server. The file allows
 itself no request of any kind: its content security policy lets nothing
 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.) The file for
-version 0.3.0 is attached to the release on GitHub; it is the same
-file, byte for byte, as for version 0.2.0, because nothing the page
-holds changed. Its SHA-256 fingerprint is
-`7e142fa119458ce00c5fdd6e1cafc75cb3bb4672624157a0a0ef4624f92812ae`.
+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
+fingerprint is
+`cec1b8d5e6e7a11c00478c6e83d9f9b5963340ec656657ea0ac84f32e8e52bda`.
 
 **Run the demonstration in a browser.**
 
@@ -388,7 +388,8 @@ const answer = await checkBefore(
   { issuerKeys: ['the thumbprint of the passkey you trust'] },
 );
 
-answer.allowed;   // true only if the record so far is sound, fully checked, and the action is inside the slip
+answer.allowed;   // true only if the record so far is sound, fully checked (but for a seal's third signature, below), and the action is inside the slip
+answer.notChecked; // present only where the device went on without checking a seal's third signature (SLH-DSA)
 answer.breaches;  // why not, in the checker's own codes
 answer.problems;  // why the question could not be answered with a yes
 answer.needs;     // what the slip asks to go with it: 'approval', 'countersignature'
@@ -550,6 +551,77 @@ 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.
 
+### 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` still names the arguments `arguments` by default; a tool
+can name them `provared.arguments` through its own `details` function.
+
 ## How signing works
 
 - **The person** signs a slip with a passkey. A passkey signs a short
@@ -562,9 +634,118 @@ names no agent software, and works with any function.
   offers a quantum-safe passkey yet.
 - **Whoever keeps the book** signs each seal with three keys: the same
   two, and SLH-DSA-SHA2-256s, which rests only on fingerprint functions.
-- **Browsers are only now adding ML-DSA, and have no SLH-DSA.** Where a
-  browser lacks a method, the checking page says that those signatures
-  were not checked, and does not show a pass. Node.js checks all of them.
+- **The browsers tried have ML-DSA; none has SLH-DSA.** Tried on the
+  author's computer on 13 October 2026: Chrome 155, Edge 155 and
+  Brave 155 each offer Ed25519 and ML-DSA (all three strengths) to a
+  page, and check real signatures made with them. None of the three
+  offers SLH-DSA. So in these browsers the checking page checks every
+  signature of a slip, a stub, a countersignature and the other records,
+  but not a seal's third signature: a book with a seal reads "not
+  complete" there, and the time-stamp beside the seal is not counted.
+  Where a browser lacks a method, the checking page says that those
+  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
 
@@ -697,6 +878,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:
 

package/docs/threat-model.md

@@ -58,10 +58,10 @@ keys. People decide what it means.
   under a seal, whose three signatures include two quantum-safe ones.
   The outside time-stamps themselves are of today's kind.
 - **A signature that cannot be checked is not a pass.** Where a device
-  has no built-in ML-DSA, the checker says so, and never reports the
-  record as intact. An entry none of whose signatures the device could
-  check is not treated as evidence: what it says is not shown, and it is
-  not compared with its slip.
+  has no built-in ML-DSA, or no SLH-DSA for a seal, the checker says
+  so, and never reports the record as intact. An entry none of whose
+  signatures the device could check is not treated as evidence: what it
+  says is not shown, and it is not compared with its slip.
 - **A record does not show that an action was wise, lawful or wanted.**
 - **A badly written slip is faithfully recorded as a badly written slip.**
 
@@ -123,6 +123,60 @@ fingerprint.
 - The documents themselves. A stub holds fingerprints of documents, not
   the documents. Whoever keeps the documents must keep them.
 
+**A stub bound to the other system's own record of the call.** Where the
+other side will not countersign, a stub may name, under a reserved name
+(format description, section 27), the fingerprint of the identifier the
+platform gave the call (`provared.event-id`), of one the agent's side
+chose and sent (`provared.trace-id`, `provared.request-id`), of part
+of the request and the answer (`provared.http-request`: the method, the
+address and the body; `provared.http-response`: the status and the
+body; no header is covered), or of the error the agent was given
+(`provared.error`).
+
+- *What it shows.* Someone who holds the platform's own log can work the
+  fingerprint out again and match the two records, without either
+  side's help. For an identifier, the two speak of one call. An agent's
+  side that later claims another identifier for the call, or a platform
+  that later shows another, is caught by the mismatch.
+- *Only an identifier picks out one call.* A request, an answer, the
+  arguments or an error shows only that the content matches: identical
+  requests, and identical answers (many a `200` with the body `{}`),
+  share one fingerprint, so a match with one of them does not show that
+  it was the same call. Only `provared.trace-id`, `provared.request-id`
+  and `provared.event-id` are meant to pick out one call, and only they
+  may be named more than once in a stub.
+- *The body's bytes* are what RFC 9530 digests: the content after any
+  content coding (such as gzip) and before any transfer coding. A
+  platform that logs the decoded body of a message sent compressed will
+  not match.
+- *A trace-id's form is not checked.* The W3C standard writes it as 32
+  lower-case hexadecimal characters, but any text is fingerprinted as
+  given.
+- *What it does not show.* That the call did what either record says:
+  the platform's identifier is the platform's word, and the stub is
+  still the agent's side's word. That the platform keeps the identifier
+  at all: which one a platform writes into its log differs from one
+  platform to another, and is for whoever relies on it to find out. That
+  the fingerprint was made from the text the name says: a checker cannot
+  tell; only someone who holds that text can. An identifier that is
+  short or easy to guess gives no privacy through its fingerprint.
+- *Against A1 and A3* (the agent's own side). The binding is written by
+  the agent's side, so a dishonest one can leave it out, or name a
+  wrong identifier; only the match with the platform's log, made later,
+  catches the second. It adds nothing against an agent that writes no
+  stub.
+- *Two spellings of one address.* An HTTP address is taken exactly as it
+  was sent and never rewritten, so that two programs fingerprint the
+  same request the same way. A program that records a rewritten address
+  (`%2f` for `%2F`, a host in capitals) makes a fingerprint that will not
+  match: whoever writes the stub must give the address as sent.
+- *A reserved name not on the list* is refused (`bad-field`), so that a
+  name that may be given a meaning later cannot be used now with another;
+  so is one of the four once-only names named twice (two `provared.arguments`
+  fingerprints in one stub would leave unclear which was the call's). A
+  book written before this rule that holds such a name no longer passes
+  its check.
+
 ## 4a. Limits, conditions, approvals and the other side's records
 
 **Protects.** That what the person allowed is stated exactly, and that a
@@ -235,6 +289,25 @@ disagree about. Totals are added as whole numbers of any size.
   of the arguments fixes what was asked for without holding it; where
   the arguments are few and easy to guess, the fingerprint can be
   guessed.
+- **Documents named after the action** (`detailsAfter` in the stub
+  writer's `act`). The stub is first written and checked with the whole
+  book before the action, as always; after the action, it is signed
+  again with up to four further documents, still within the same call,
+  so that no other call comes between, and keeps the time the action
+  began. The room for them is kept beforehand: with today's limits the
+  largest stub, with 32 documents of the longest names, and a
+  countersignature still fits a line, and the writer checks this again
+  for each such call. If what `detailsAfter` gives cannot go in (it
+  fails, gives no answer within the time the other side is given to
+  countersign, gives more than four, or gives a document that would be
+  refused), the stub made before the action is written without them,
+  and the answer says why: an action that was taken always gets its
+  stub. What it gives is copied when it is read, so a later change to
+  it changes nothing. A call to the writer from inside it is refused at
+  once. It cannot be used with an approval, because an approval covers
+  exactly the documents the person saw. The stub is signed twice for
+  such an action, and only one of the two is written: a signer kept
+  elsewhere is asked once more.
 - **The check before acting refuses more in one case.** An action that
   would add to a period which a stub dated after it already overfills is
   refused, though a checker would report nothing new for it.
@@ -450,7 +523,12 @@ within 5 minutes for a time-stamp from a service, and to within 2 hours
 and 5 minutes for a block time-stamp). A6 cannot make a
 seal: it needs the recorder's three keys. A8 must break Ed25519, ML-DSA-87
 and SLH-DSA together to forge a seal; the third rests only on fingerprint
-functions. Nobody can move a time-stamp to another seal: it is made over
+functions. One exception, stated: the check before acting on a device
+without SLH-DSA (the Python version, every browser) goes on after a seal
+whose first two signatures check there, so on that device a seal rests on
+Ed25519 and ML-DSA-87 alone, and a third signature of the right length
+that would not check is not seen. A device with SLH-DSA, such as the
+command-line checker, sees it. Nobody can move a time-stamp to another seal: it is made over
 the seal's fingerprint.
 
 A block time-stamp is a second witness of the time, which rests on no
@@ -490,8 +568,12 @@ person checking gives.
   does not read what a certificate says its key is for. It checks that
   the stated time lies within the certificate's dates, and leaves the
   rest to the person who chose to trust it.
-- **A browser.** No browser offers SLH-DSA or ML-DSA to a page yet. A
-  checker there reports a seal as not fully checked, never as a pass.
+- **A browser.** Tried on the author's computer on 13 October 2026:
+  Chrome 155, Edge 155 and Brave 155 offer ML-DSA to a page; none of the
+  three offers SLH-DSA. So a checker in a browser
+  reports a seal as not fully checked, never as a pass, and counts no
+  time-stamp beside it. In a browser without ML-DSA, every record signed
+  with ML-DSA is reported as not fully checked too.
 - **A few bytes of a time-stamp's wrapper** are not covered by the
   service's signature (the list of fingerprint methods, and the lines
   that name the certificate by its issuer). Changing them changes nothing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provared",
-  "version": "0.3.0",
+  "version": "0.5.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",

package/page/index.html

@@ -8,7 +8,7 @@
 </head>
 <body>
 <main>
-  <h1>Check a record</h1>
+  <h1><svg class="mark" viewBox="0 0 64 64" width="32" height="32" aria-hidden="true"><circle cx="32" cy="32" r="32" fill="#8f000f"/><path d="M20 15 H37 L45 23 V49 H20 Z" fill="#ffffff"/><path d="M37 15 V23 H45" fill="none" stroke="#8f000f" stroke-width="2.5" stroke-linejoin="round"/><path d="M25 29 H40 M25 35 H36" stroke="#8f000f" stroke-width="2.5" stroke-linecap="round"/><path d="M24.5 43 C27 39, 29 46, 31.5 42.5 C34 39, 36 46, 40.5 41.5" fill="none" stroke="#8f000f" stroke-width="3" stroke-linecap="round"/></svg>Check a record</h1>
   <p class="motto">Provared, draft version 0. Evidence, not a verdict.</p>
   <p>Choose a record file. It is checked here, in this browser. Nothing is sent anywhere.</p>
   <p>

package/page/style.css

@@ -148,3 +148,6 @@ details.more summary { cursor: pointer; font-weight: 600; }
 details.more label { display: block; margin-top: 0.7rem; }
 details.more input[type="file"] { display: block; max-width: 100%; margin-top: 0.3rem; color: var(--text); }
 details.more textarea { width: 100%; box-sizing: border-box; font-family: ui-monospace, monospace; font-size: 0.85rem; color: var(--text); background: var(--page); border: 1px solid var(--line); border-radius: 0.3rem; }
+
+/* The mark: a permission slip with a signature, beside a heading or the site's name. */
+.mark { vertical-align: -0.2em; margin-right: 0.4em; }

package/spec/provared-format.md

@@ -226,10 +226,22 @@ Because the slip names both keys, taking the quantum-safe signature off a
 stub does not leave a valid stub.
 
 A checker on a device with no built-in ML-DSA MUST report that the
-quantum-safe signature could not be checked, and MUST NOT report the
-record as intact. An entry none of whose signatures the device could
-check MUST NOT be treated as evidence: what it says is not shown as fact,
-and it is not compared with its slip.
+quantum-safe signature could not be checked (unless it is of the wrong
+length, below), and MUST NOT report the record as intact. An entry none
+of whose signatures the device could check MUST NOT be treated as
+evidence: what it says is not shown as fact, and it is not compared with
+its slip.
+
+**A signature of the wrong length.** A signature whose length is not its
+method's (64 bytes for Ed25519, 4,627 for ML-DSA-87, 29,792 for
+SLH-DSA-SHA2-256s) can never check. A checker MUST report it as invalid,
+whether or not the device has the method: it is a problem with the
+record, not a signature left unchecked. This holds for every signature of
+a record, the passkey's Ed25519 signature on a slip among them, and so
+for the check of a whole book or of a Show as for the check before acting
+(section 20). It does not reach the signature inside a time-stamp from a
+service (section 21.2): a device without that time-stamp's method does
+not check it, whatever its length, and does not count it.
 
 A recorder is known by a key set of exactly three keys: Ed25519,
 ML-DSA-87, then SLH-DSA-SHA2-256s (FIPS 205, the plain method with an
@@ -238,8 +250,8 @@ order, and counts as signed only if all three check. The third rests only
 on fingerprint functions, so it would stand even if the mathematics
 behind ML-DSA were broken. When this draft was written, no browser
 offered it to a page, and Node.js offered it outside the standard
-interface: a checker in a browser reports it as not checked, which is
-never a pass.
+interface: a checker in a browser reports it as not checked (or, if it is
+of the wrong length, as invalid), which is never a pass.
 
 The issuer's passkey signature on a slip is of today's kind only. No
 device offers a quantum-safe passkey.
@@ -428,7 +440,10 @@ checker keeps no state.
 | `pass` | For a helper agent: the pass it acts under. Optional | The fingerprint of the pass (section 25) |
 | `when` | When it was done | A time |
 
-A stub holds fingerprints of documents, never the documents.
+A stub holds fingerprints of documents, never the documents. A document
+`name` is a label chosen by whoever wrote the stub, except that names
+that begin `provared.` are reserved (section 27). The same label MAY
+appear more than once; section 27 says which reserved names may.
 
 ### 5.2 Signing and checking
 
@@ -646,6 +661,11 @@ the seal's own date (section 21.1, rule 4).
   that the organisation checked well.
 - The fingerprints of an agent's software in a slip are a statement of
   what the person approved, not proof of what ran.
+- A reserved identifier that binds a stub to another system's own
+  record of the call (section 27) shows that the two records speak of
+  one call, not that the call did what either says. A matching
+  fingerprint of a request, an answer, arguments or an error shows only
+  that the content matches, not that it was the same call.
 
 ## 14. Standards used
 
@@ -667,6 +687,8 @@ the seal's own date (section 21.1, rule 4).
 | RFC 3161; RFC 5652; RFC 5280; ITU-T X.690 | Time-stamps: the statement, its signed wrapper, the certificate, and the byte layout (DER) |
 | The OpenTimestamps proof file, version 1 (an open format; not the work of a standards body) | Block time-stamps: the steps from a fingerprint to the Merkle root of a block |
 | RFC 9901 (Selective Disclosure for JSON Web Tokens) | Covered fields |
+| RFC 9421 (HTTP Message Signatures), section 2.5, only its way of writing a message as text; RFC 9530 (Digest Fields); RFC 9110, section 5.6.2 | The texts that the reserved document names `provared.http-request` and `provared.http-response` stand for (section 27). Nothing is signed with RFC 9421 |
+| W3C Trace Context (a W3C Recommendation) | The trace-id that `provared.trace-id` stands for (section 27) |
 
 ## 15. Choices that go beyond the standards
 
@@ -723,6 +745,12 @@ is frozen.
     pass.
 18. The acknowledgement of section 26 and its label
     `vnd.provared.acknowledgement.v0+json`.
+19. The reserved document names of section 27, and the exact texts their
+    fingerprints are made from: an HTTP address taken exactly as it was
+    sent, never rewritten; a body that is present but empty given a
+    Content-Digest, and an absent body none; no header covered; SHA-256
+    only; only the three identifiers may be named more than once; the
+    form of a trace-id not checked.
 
 ## 16. The shared list: actions, kinds of action, rules of conduct
 
@@ -918,7 +946,18 @@ holds too much. A checker reports nothing new for it, because the
 finding stands with the later stub. The answer MUST be that nothing is allowed
 (`record-not-sound`) if the book so far has a problem, if any signature
 in it could not be checked on that device, or if the check was not told
-which issuer keys it trusts. An action dated before the last stub of
+which issuer keys it trusts. One exception is allowed: where every
+signature that could not be checked is the third signature of a seal
+(section 21.1) whose first two signatures were checked on that device,
+and nothing else was left unchecked, the check MAY go on, and its answer
+MUST then name the method it did not check. A seal widens no permission;
+a device without that method would otherwise be refused everything once
+the book holds a seal. On such a device a seal rests on its first two
+signatures only: a third signature of the right length that would not
+check is not seen there. A third signature of the wrong length is not
+left unchecked: as section 3.9 sets out, it is invalid on every device,
+so the seal is a problem there and nothing is allowed. An action dated
+before the last stub of
 its own chain (the agent's, or the helper's under its pass; section 7)
 is refused (`time-went-backwards`).
 
@@ -1695,6 +1734,112 @@ section 22. Nothing obliges an agent's side to acknowledge: a
 cancellation with no acknowledgement shows nothing about whether the
 agent's side was told.
 
+## 27. Reserved document names
+
+Where the other side of an action will not countersign, the next best
+binding is the other system's own identifier for the call, named in the
+stub by its fingerprint. An investigator who holds that system's own log
+can then work out the fingerprint again and match the two records,
+without either side's help. Only an identifier is meant to pick out one
+call. A stub may also name fingerprints of some of what was sent and
+received (the arguments; an HTTP request's method, address and body; an
+answer's status and body); those show that the content matches, not
+that it was the same call.
+
+So document names (section 5.1) that begin `provared.` are reserved. A
+document name that begins `provared.` and is not in this list MUST be
+refused (`bad-field`), in a stub, an approval (section 17) and the
+check before acting (section 20). The comparison is exact: a name in
+other letters, such as `Provared.invoice`, is a label like any other.
+`provared.trace-id`, `provared.request-id` and `provared.event-id` MAY
+each appear more than once in one stub (identifiers from two systems,
+say); every other name in the list MUST appear at most once, and a
+record that names one of them twice MUST be refused (`bad-field`), in
+the same places. The `sha256` of each is the SHA-256, in base64url, of
+exactly this text, in UTF-8:
+
+| Name | The text whose SHA-256 is given |
+|---|---|
+| `provared.arguments` | The call's arguments, written in the one form of RFC 8785 |
+| `provared.http-request` | The request, written as below, over `"@method"`, `"@target-uri"` and, where there is a body, `"content-digest"` |
+| `provared.http-response` | The answer, written as below, over `"@status"` and, where there is a body, `"content-digest"` |
+| `provared.trace-id` | The trace-id of the W3C Trace Context `traceparent` header that the agent's side sent, exactly as sent. That standard writes it as 32 lower-case hexadecimal characters; this format does not check the form, and a checker cannot |
+| `provared.request-id` | An identifier that the agent's side chose and sent with the call, exactly as sent |
+| `provared.event-id` | An identifier that the platform gave for the call, exactly as it gave it |
+| `provared.error` | The error text that the agent's software was given, exactly as given |
+
+An identifier or an error text MUST be one character or more, and
+well-formed Unicode.
+
+**How a request or an answer is written.** As the signature base of RFC
+9421 (HTTP Message Signatures), section 2.5, with no signature
+parameters. RFC 9421 is used only for this exact way of writing a
+message as text; nothing is signed with it. For each component, in the
+order given: a line `"<component>": <value>` and a line feed (0x0A);
+then the line `"@signature-params": (` with the components, each in
+double quotation marks and separated by one space, and `)`, with no line
+feed after it. The values:
+
+- `"@method"`: the method exactly as sent, a token of RFC 9110, section
+  5.6.2. Its letters are not changed, as RFC 9421, section 2.2.1, sets
+  out.
+- `"@target-uri"`: the absolute address exactly as sent. It MUST begin
+  `http://` or `https://`, hold only the visible characters of ASCII
+  (0x21 to 0x7E), and hold no fragment (`#`). It is never rewritten:
+  two spellings of one address (`%2F` and `%2f`, a host in capitals, a
+  port written or left out) give two fingerprints. Whoever writes the
+  stub MUST give the address in the form that was sent.
+- `"@status"`: the status code of the answer, a whole number from 100 to
+  599, written in digits.
+- `"content-digest"`: present only where the message has a body; a body
+  that is present and empty has one. The value is the field value of RFC
+  9530 with SHA-256 only: `sha-256=:`, the SHA-256 of the body's bytes,
+  in base64 with padding (RFC 4648, section 4), and `:`. The body's
+  bytes are what RFC 9530 digests: the content after any content coding
+  (such as gzip) and before any transfer coding. A system that keeps
+  the decoded body, where the body was sent compressed, will not match.
+
+No header is covered, and nothing else of the message: two messages
+that differ only in their headers give one fingerprint.
+
+For example, the request `POST https://example.com/foo?param=Value&Pet=dog`
+with the body `{"hello": "world"}` is written as these four lines:
+
+```
+"@method": POST
+"@target-uri": https://example.com/foo?param=Value&Pet=dog
+"content-digest": sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
+"@signature-params": ("@method" "@target-uri" "content-digest")
+```
+
+**What a binding shows, and what it does not.**
+
+- An identifier binds the two records only where the other system writes
+  the same identifier into its own log. Which one a system keeps differs
+  from one system to another, and is for whoever relies on it to find
+  out. Recording both kinds, one the agent's side chose and sent
+  (`provared.trace-id`, `provared.request-id`) and one the platform gave
+  back (`provared.event-id`), gives the better chance of a match.
+- The platform's identifier is the platform's word. A matching
+  identifier shows that the two records speak of one call, not that the
+  call did what either says.
+- Only `provared.trace-id`, `provared.request-id` and `provared.event-id`
+  are meant to pick out one call. `provared.arguments`,
+  `provared.http-request`, `provared.http-response` and `provared.error`
+  show only that the content matches: identical requests, and identical
+  answers (many a `200` with the body `{}`), share one fingerprint, so a
+  match with one of them does not show that it was the same call.
+- A fingerprint of an identifier, or of arguments, that is short or easy
+  to guess can be guessed: it hides nothing from someone who can try
+  the likely values.
+- A checker cannot see whether a fingerprint was made from the text this
+  section names: only someone who holds that text can work it out again.
+- Records written before this section was added may use names that
+  begin `provared.` that are not in the list, or name one of the four
+  once-only names twice; such records are refused, so a book that holds
+  one no longer passes its check. A checker that does not know this
+  section reads a reserved name as a label.
+
 ---
 
 Copyright 2026 Pavel Izmaylov. This document is licensed under the

package/src/dev.d.ts

@@ -50,5 +50,5 @@ export function developmentSlip(fields: DevelopmentSlipFields): Promise<Developm
 /** The stub writer opened under a development slip, in one call. */
 export function developmentRecorder(
   fields: DevelopmentSlipFields,
-  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number },
+  more?: { options?: CheckOptions; now?: () => number; countersignWithin?: number; signWithin?: number },
 ): Promise<Omit<DevelopmentSlip, 'book'> & { recorder: Recorder }>;

package/src/dev.js

@@ -110,7 +110,7 @@ export async function developmentSlip(fields = {}) {
  * The stub writer, opened under a development slip, in one call: the
  * shortest way to a first record. The same as developmentSlip followed by
  * openRecorder; "more" is passed to openRecorder (options, now,
- * countersignWithin).
+ * countersignWithin, signWithin).
  *
  * @param {object} fields the members of the slip; "actions" is required
  * @param {object} [more]