provared 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,345 @@
 # Changelog
 
+## 0.5.0 (17 October 2026)
+
+- **The README's count of review rounds: 50.** The 40 recorded by
+  version 0.4.0, and 10 since: five of the Agno package, three of the
+  signer interface and two of the stub bound to the platform's own
+  record, each listed below.
+- **`provared-agno` 0.1.0, an Agno tool hook**
+  (`python/integrations/provared-agno/`): every tool call of an Agno
+  agent is checked against the slip before it runs, and a stub is
+  written once it has run. A call the slip does not allow is not run, and
+  the model is told why. Agno's own steering tools cannot carry an action
+  past the record: a hand-over, or a task in a team's task mode, goes
+  only to a member with the same writer's hooks, read from Agno's own
+  list of tasks, not from the session's copy that the model can rewrite.
+  A stub is written only once its tool has completed, even where a
+  helper agent runs inside the tool, on the same event loop or on one of
+  its own; a tool that never completes leaves none, and a cancelled tool
+  that completes all the same is recorded. Checked by an independent reviewer
+  over five rounds (faults found in the first four, the fifth clean);
+  each fault is a test, 68 in all. Not on the Python Package Index yet:
+  the README gives the command to install it from this repository.
+- **Signers: keys held elsewhere, in both languages.** Wherever a writer
+  takes `privateKeys` (`private_keys` in Python), each item may be a key,
+  as before, or a signer: an object with `key`, the public key, and
+  `sign(data)`, which gives the signature bytes. So a key may live in a
+  key service or a hardware module. `signerFromKey` (`signer_from_key`)
+  wraps a key held in memory as a signer. A record made through a signer
+  is the same record: the same content, labels and Ed25519 signature. A
+  signer is not taken on trust: before any signer is asked to sign, its
+  key must be plain data, of the method of its place, of a method the
+  device can check, and, where the writer knows it, the key the record
+  must be signed with (`bad-key`); every signature it gives is checked
+  against its key before it is used, and one of the wrong length, one
+  that does not check, something other than bytes or an error leaves no
+  record (`signature-invalid`), with the method and the key named. The
+  stub writer gives a signer 30 seconds for each signature (`signWithin`,
+  `sign_within`); after that nothing is written and the writer goes on.
+  In Python no seal is written, with keys or signers, as before. Every
+  private key that made a correct record before still does, in the same
+  way: in JavaScript a private Web Crypto key of the place's method for
+  Ed25519 and ML-DSA-87, and for a seal's SLH-DSA-SHA2-256s a Node.js
+  KeyObject or what Node.js's own signing call read before (PEM text,
+  DER bytes with their format, a JSON Web Key with its format); in Python
+  a private key of `cryptography` of the place's method. Refused now
+  (`bad-field`), though accepted before: in JavaScript, a private key of
+  another kind in a seal's SLH-DSA place, and in Python a private key of
+  another method or kind (such as Ed448 in the Ed25519 place); each made
+  a record that failed its own check. In Python, an object with only
+  `sign` now needs `key` as well: it is a signer. Anything else that is
+  neither a key nor a signer (a public key, a key of another method in
+  JavaScript's first two places, a value that only looks like a key) is
+  refused with `bad-field`, where before it failed with the platform's
+  own error. No record and no rule of the format changes. `signWithin`
+  must be 1 to 2,147,483,647 milliseconds (`bad-field`). Checked by an
+  independent reviewer over three rounds, the third clean; each fault is
+  fixed and is now a test.
+  Tests: `test/signers.test.mjs`, `test/signers-unavailable.test.mjs` and
+  `python/tests/test_signers.py`.
+- **A stub bound to the platform's own record of the call, in both
+  languages** (format description, section 27). Document names that
+  begin `provared.` are now reserved: seven are listed
+  (`provared.arguments`, `provared.http-request`,
+  `provared.http-response`, `provared.trace-id`, `provared.request-id`,
+  `provared.event-id`, `provared.error`), each with the exact text its
+  fingerprint is made from, so that someone who holds another system's
+  own log can match a stub to it. Only the three identifiers
+  (`trace-id`, `request-id`, `event-id`) pick out one call; the others
+  show only that the content matches, and the request and answer
+  fingerprints cover no header. Any other name that begins `provared.`
+  is refused (`bad-field`) in a stub, an approval and the check before
+  acting; before, it was a label. So is any of the seven but the three
+  identifiers named twice in one record. **A book written before this
+  change that holds a stub, or an approval, with such a name now fails
+  its check, and the check before acting then refuses every action
+  under it** (and a stub writer will not open on it). A checker of
+  version 0.4.0 or earlier reads the reserved names as labels.
+  `DOCUMENT_NAMES`,
+  `httpRequestFingerprint`, `httpResponseFingerprint` and
+  `identifierFingerprint` (`http_request_fingerprint` and so on in
+  Python) make the fingerprints; an HTTP request or answer is written as
+  the signature base of RFC 9421, with the Content-Digest of RFC 9530
+  over the body after any content coding, and its address is taken
+  exactly as sent; a body of null (None) is no body. The stub writer's `act`
+  takes `detailsAfter` (`details_after` in Python): up to four further
+  documents, from what the action gave back, such as the identifier a
+  platform gave the call. The stub is still checked with the whole book
+  before the action; after it, the stub is signed again with them in the
+  same call, and keeps the time the action began. If they cannot go in,
+  the stub is written without them and `detailsAfter` in the answer says
+  why: an action that was taken always gets its stub (where the second
+  signing fails, it says so: `details-not-added`). It cannot be used
+  with an approval. With it, the request may name at most 28 documents
+  (`bad-field`), and an action whose stub would leave no room for four
+  more is not taken (`too-large`); `detailsAfter` is given as long as the
+  other side is given to countersign. `recordTools` and `record_function` still name the
+  arguments `arguments` by default. Shared test files: `stub-contents.json`
+  gains cases (made again; its earlier cases are unchanged), and
+  `http-fingerprints.json` and `recorder-details-after.json` are new.
+  Checked by an independent reviewer in two rounds, the second clean.
+  Tests: `test/documents.test.mjs` and `python/tests/test_documents.py`.
+
+## 0.4.0 (14 October 2026)
+
+- **The command-line checker counts the keys it was given.** With two
+  passkeys named, its summary said "yes: the passkey you trust"; it now
+  says "the passkeys you trust", and "the recorders you expect" where
+  more than one recorder is named; the same key named twice counts once.
+  Only the words change; tests hold them. The guide gives the fingerprint
+  of the checking page built as one file for this version, which changed
+  because the checker it holds, and the page itself, changed.
+- **The README's count of review rounds is brought up to date: 40.** The
+  25 recorded by version 0.3.0, and 15 since: three of the library's
+  changes of 11 to 13 October (the seal rule, then a narrow review of four
+  commits and a check of its fixes), three of the signing page, six of the
+  recorder beside Claude Code, two of the record page's book in a release,
+  and one of the asynchronous reads below. Each reviewer is a fresh
+  session given the code, the documents and a brief of what to look at;
+  the README now says so, and that a fault may be stated as a limit rather
+  than fixed.
+- **The two framework packages require version 0.4.0**, so that an
+  agent behind either goes on after its book is sealed (below).
+  `provared-langchain` becomes 0.1.1, which also carries the keywords,
+  the homepage and the mark added on 10 and 11 October.
+  `pydantic-ai-provared` 0.1.0 is its first version; its README already
+  gave the command to install it. Both are published separately, on the
+  Python Package Index.
+- **The LangChain and Pydantic AI packages read the stub writer safely
+  from asynchronous code**: `await middleware.snapshot()` and
+  `await capability.snapshot()` give the book and the cancellations the
+  writer holds, waiting in a thread of their own. The READMEs said to
+  read it with `asyncio.to_thread(writer.snapshot)`; but in the event
+  loop's shared threads such a read waits for the action in progress,
+  and enough of them at once leave no shared thread for a tool that
+  needs one, so the tool and the reads wait for ever. Found while
+  building a package for another framework; checked by an independent
+  reviewer, and a test in each package fails without it.
+- **A proposed action dated by text gets a plain refusal.** The check
+  before acting took a time given as text, or a number or a Date that
+  gives no time, to the catch-all "the checker met something it did not
+  expect" (`check-failed`). It now answers `bad-field`: "when: must be a
+  number of milliseconds, or a Date" (the stub writer's own words), or
+  "when: does not give a time" (new words, for a number such as Infinity,
+  a Date that is not a time, or a Date wrapped in a Proxy). In Python a
+  datetime counts as dated only where its time zone gives an offset, as
+  Python's own rule for an "aware" time says. Nothing that was allowed is
+  refused, and nothing that was refused is allowed. The stub writer
+  answers in the same words: its "before" and "act" took a Date wrapped
+  in a Proxy to a plain TypeError, and now answer "when: does not give a
+  time", as the check before acting does; its "record", which does not
+  ask first, took any time that gives none to a plain "Invalid time
+  value" error, and now refuses it with `bad-field` in those words. In
+  both languages; the shared test file for the check before acting gains
+  two cases, and in the stub writer's scenarios the one step that hands in
+  a time of Infinity changes its words, and the one step that records an
+  action at a time outside the range of times changes its answer. Tests
+  in both languages hold a Date in a Proxy and, in Python, a time zone
+  that gives no offset.
+- **A record's signature of the wrong length is invalid on every
+  device.** An Ed25519 signature is 64 bytes, an ML-DSA-87 signature 4,627
+  and an SLH-DSA-SHA2-256s signature 29,792 (RFC 8032, FIPS 204, FIPS 205).
+  One of another length can never check, and a device that has the method
+  already said "invalid"; a device without it said "not checked on this
+  device". Now every device says "invalid", for every signature of a
+  record, the passkey's Ed25519 signature on a slip among them. So, on a
+  device without SLH-DSA, a seal whose third signature is cut short or
+  empty is a problem, not something the check before acting goes on
+  without. The signature inside a time-stamp from a service is not
+  covered: on a device without its method a time-stamp is not checked,
+  whatever its length, and is not counted. A third signature of the right
+  length that would not check is still not seen on a device without
+  SLH-DSA. The format description states the rule in section 3.9 and
+  what it means for a seal in section 20; the list of threats says that a
+  third signature of the right length is not seen there. In both
+  languages; the shared test files for a whole book and for the check
+  before acting gain a case each, and tests in both languages hold each
+  method's length, shorter and longer, with the method and without it.
+- **The check before acting goes on without a seal's third signature, and
+  says so** (decision F-106; this changes choice 66 of the draft). Found on
+  11 October 2026: a device that cannot check SLH-DSA-SHA2-256s, which is
+  every Python stub writer (and so the LangChain and Pydantic AI packages)
+  and every browser, was refused every action as soon as its book held a
+  seal, because the check allowed nothing unless every signature in the
+  record so far had been checked on that device. Now, where the only
+  signatures not checked are the third ones of seals whose first two were
+  checked there, and nothing else was left unchecked, the check goes on and
+  its answer carries `notChecked: ['SLH-DSA-SHA2-256s']`. Any other
+  signature left unchecked still refuses everything, and the full checker's
+  answers are unchanged. In both languages: the shared test file for the
+  check before acting gains seven cases with a seal, besides the one with
+  a third signature cut short counted above (found missing by two
+  independent reviews, which showed that weaker rules passed every test:
+  the last case, a permission and a seal alone on a device without
+  ML-DSA-87, holds the rule that the seal's ML-DSA-87 signature must have
+  been checked), and the shared test file for the stub writer's scenarios
+  is remade. Tests in both languages hold the same rule.
+- **The signing page names the agent's keys by the fingerprint of their
+  key set** before the passkey is asked, worked out by the library's own
+  `keySetFingerprint` (as a recorder's key set is named), and asks the
+  person to compare it with the one the agent's software printed when it
+  made its keys: a link, or a permission pasted from elsewhere, could
+  carry someone else's keys under a familiar name. Keys that are not a
+  key set are refused there, in the library's own words. A test holds the
+  page's words against the library's fingerprint.
+- **The signing page fills itself from a link, and shows everything a
+  link could slip in before the passkey is asked.** A link to
+  prova.red/sign/ may hold a starting permission after "#"; that part
+  stays in the browser and is never sent to a server. A link that cannot
+  be read leaves the page's own starting point and says why; a second
+  link opened in the same tab fills the page again. Because a link can
+  name anything, the page now shows, besides the agent's key-set
+  fingerprint (above): each service's keys by the fingerprint of their key
+  set, as a checker names them (keys that are not a key set are refused,
+  in the library's own words); and the agent's software statement, marked
+  as the person's statement and not proof of what runs. Shown inside
+  another page, it offers nothing to sign or cancel, since another site
+  could frame it filled from a link of its choosing. It now has a content
+  security policy that lets it load only its own scripts and style sheet
+  and send nothing anywhere; the message of the commit that added the
+  link said its policy was unchanged, but the page had none. Tests hold
+  each point. Checked by an independent reviewer over three rounds.
+- **The recorder beside Claude Code is a package of its own,
+  `provared-claude-code` 0.1.0** (published separately, on npm), in
+  `integrations/claude-code/`, in place of the recorder of 10 October.
+  `init` makes the keys, writes the hooks and prints a link to the signing
+  page filled in with a starting permission; `use` puts the signed
+  permission in place; `renew` takes a new permission while the recorder
+  runs, with no moment in which a call finds it gone. A permission from a
+  passkey the recorder has not trusted before is taken only with
+  `--new-passkey`, and the passkeys it trusts are kept in
+  `trusted-passkeys.json`. The hooks `init` writes match every tool,
+  record calls that failed, and refuse a call where the hook itself fails
+  (`"onFailure": "block"`). A command is named by reading its line three
+  ways (as a shell splits it, from every known program's name, and with
+  the first version's patterns), and the strictest name counts; a line
+  handed to a shell, to `eval`, `iex` or `Invoke-Expression`, and the
+  command `find -exec` runs are read the same way. A call allowed under
+  one permission and taken while a renewal switched to the next is
+  recorded under the one it was allowed under, and the stub of a call that
+  was taken is always written. `keys` and `init` print the fingerprint of
+  the agent's key set, which the signing page asks the person to compare;
+  `seal` shows the recorder's error. Checked by an independent reviewer in
+  six rounds; each fault found is a test (57 in all).
+- **The record page's book and the checker's answer are kept in a release
+  of the repository, not in the repository itself**: they grow by
+  megabytes a day, and GitHub refuses a file over 100 MB.
+  `tools/make-record-page.mjs` writes their SHA-256 fingerprints beside
+  the page (`site/records/files.sha256`); the site's publishing run
+  fetches both from the release "record" and publishes nothing unless each
+  matches, and every file the page links is there. Readers see no change.
+  The tool now reads the growing book once, into the page's own folder,
+  leaving out a last line still being written, so that the page, the
+  checker's answer and the fingerprints describe one book (the page of
+  14 October said 3,771 receipts above a summary of 3,770 stubs). It
+  counts the passkeys that signed the book's permissions from the book,
+  and refuses a passkey named to it that signed none. Checked by an
+  independent reviewer in two rounds.
+- **What browsers check, tried again 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
+  them offers SLH-DSA. The README, the guide, the list of threats, the
+  home page, the worked example and the tool that writes the record page
+  now say so; they said, from a try on 12 October, that Chrome 154 did
+  not check ML-DSA. No code changes.
+- **The recorder beside Claude Code appends to the book, and no longer
+  loses a receipt while another program reads the file.** It wrote the
+  whole book to a temporary file and renamed it over the old one; on
+  Windows that is refused while anyone holds the file open (an uploader,
+  a virus scanner), and the hook then reported "the action was taken and
+  is not in the record". Found on 11 October 2026, when a program that
+  uploads the book was reading it every two seconds: 7 of one helper's 23
+  tool calls were taken and not recorded. A book only grows, so the
+  recorder now appends the new lines; where the file does not match the
+  book it is replaced, with retries for up to two seconds. A test holds
+  the file open while the recorder saves.
+
+- 2026-10-11: **one mark everywhere**: a permission slip with a
+  signature, white on red (#8f000f), as `site/favicon.svg`, in the
+  social preview `site/preview.png` beside the word, as inline SVG in the
+  header of every page at prova.red, of the checking page and of the
+  signing page (no page makes a request for it), and at the top of the
+  README and of the three Python packages' READMEs, which the registries
+  show with the next published version. The four colours of the parts stay as they are inside the
+  pages. The style sheet gains one rule for the mark and a new version
+  number. No code changes.
+- 2026-10-10: **a real record on prova.red**, `tools/make-record-page.mjs`:
+  writes `site/records/` from the book that the recorder beside Claude
+  Code keeps. It copies the book and its slip beside the page, runs the
+  command-line checker with the passkey and the recorder the reader is
+  told to trust, keeps the whole answer as a text file, and writes the
+  page from what the checker answered: the slip in the checker's own
+  words, the counts by day, by kind of action and by tool, the seals,
+  any entry outside the permission, the summary exactly as printed, and
+  what the check does not show. The page says that a refused call
+  leaves no entry and that every receipt is one-sided. It is run again
+  each day while the permission lasts; the home page links to it. A
+  test runs the tool on the sample record into a folder of its own.
+- 2026-10-10: **the pages at prova.red, the README and the framework
+  packages, after the adoption review**: the line under each page's
+  title names its reader and then the slogan; "How it is built" on the
+  home page is two sentences; the developer page says "the person"
+  throughout, names the nearest other projects beside what the
+  author found nowhere else, and gives the author's own reason for
+  building it; the plain-words page names Article 12 and
+  Article 26 of the AI Act, no longer repeats its opening, and asks a
+  reader who breaks it to open an issue; every page ends with two
+  lines about the author; the README shows the LangChain example; the
+  two framework packages gain keywords and a homepage. No code changes.
+- 2026-10-10: **a signing page**, `page/sign.html`, served at
+  prova.red/sign/: a person writes a permission as JSON (the agent's
+  name and two public keys, the actions, limits, conditions, stated
+  rules, with whom, from when until when, and why), sees it in words,
+  signs it with a passkey made for the website, and saves the signed
+  file; the page shows the passkey's thumbprint and the permission's
+  fingerprint. It can also sign a cancellation of a permission signed
+  with the same passkey. It uses the library's browser part and
+  `render.js`, loads nothing from anywhere else and sends nothing. The
+  workflow serves it beside the checking page.
+- 2026-10-10: **the recorder beside Claude Code**, `integrations/claude-code/`:
+  a hook that Claude Code runs before and after each tool call, and a
+  small service on 127.0.0.1 that holds the stub writer open on one book
+  under a slip the person signed. Before a call, the check before acting
+  refuses a call outside the slip and Claude Code is told why; after it,
+  a stub is written naming the tool and the SHA-256 fingerprint of its
+  arguments; the service seals the book on request with the recorder's
+  three keys. Tool calls are named from the shared list by the hook,
+  not by the agent (a command that removes something is
+  `provared.data.delete`; one that publishes is `provared.code.release`);
+  tools that only talk to the person are not recorded. The agent's two
+  keys and the recorder's three are kept as JSON Web Keys in files the
+  person keeps. If the service is not running, a call is refused: no
+  record, no action. The folder names a product, as the framework
+  packages do; the library names none, and the npm package does not
+  hold it. Five tests run the hook as Claude Code runs it.
+- **The tests clean up after themselves.** Nine test files made a
+  temporary folder for each run and left it behind; on 13 October 2026
+  the computer's temporary folder held about 2,800 of them. A small
+  helper, `test/helpers/temp.mjs`, now makes each folder and removes it
+  when that test file's tests end. Run with an empty temporary folder,
+  the library's tests leave nothing in it.
+
 ## 0.3.0 (10 October 2026)
 
 - 2026-10-10: **a development stand-in for a passkey**, `provared/dev`

package/README.md

@@ -1,4 +1,4 @@
-# Provared
+# <img src="https://prova.red/favicon.svg" alt="" width="36"> Provared
 
 Proof of what an AI agent was allowed to do, and what it then did.
 
@@ -72,7 +72,19 @@ The same in Python is
 `from provared.dev import development_recorder`. For a LangChain agent,
 `pip install provared-langchain` puts every tool call behind the same
 check with no change to the tools
-([python/integrations/provared-langchain](python/integrations/provared-langchain)).
+([python/integrations/provared-langchain](python/integrations/provared-langchain)):
+
+```py
+from langchain.agents import create_agent
+from provared_langchain import ProvaredMiddleware
+
+agent = create_agent(model, tools=[order_supplies, send_message],
+                     middleware=[..., ProvaredMiddleware(writer, {
+                         'order_supplies': {'action': 'supplies.order', 'with': 'supplier',
+                                            'amount': lambda a: {'unit': 'GBP', 'value': a['total_gbp']}},
+                         'send_message': 'provared.message.send',
+                     })])   # last among the middleware that wrap tool calls
+```
 
 ## The four parts
 
@@ -129,7 +141,12 @@ each part protects against, is in
   in plain words for a reader who does not write code.
 - **[The checking page](https://prova.red/check/)**, which checks a
   record in a browser and loads nothing from anywhere; also built as
-  one file, attached to each release.
+  one file, attached to each release. It uses only the signing methods
+  the browser has built in. Tried on the author's computer on
+  13 October 2026: Chrome 155, Edge 155 and Brave 155 each check the
+  quantum-safe signatures on receipts (ML-DSA). None of the three has the
+  third method a seal is signed with (SLH-DSA), so in a browser a book
+  with a seal is never a pass. The command-line checker checks all three.
 - **The core of the format as an individual Internet-Draft** at the
   IETF:
   [draft-izmaylov-agent-permission-receipts](https://datatracker.ietf.org/doc/draft-izmaylov-agent-permission-receipts/).
@@ -139,12 +156,13 @@ each part protects against, is in
 
 ## 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, built with AI tools since 3 October 2026; fixes as time
-allows. The code has been through 25 rounds of review by AI reviewers,
-each a fresh session given only the code and the documents; every fault
-was fixed and kept as a test. No person other than the author has
-reviewed it yet. That is an invitation. The format may still change.
+allows. The code has been through 50 rounds of review by AI reviewers,
+each reviewer a fresh session given the code, the documents and a brief
+of what to look at; every fault was fixed, or stated as a limit, and
+kept as a test. No person other than the author has reviewed it yet.
+That is an invitation. The format may still change.
 Every published version stays on npm and the Python Package Index, so a
 record made with one version can always be checked by that version.
 

package/bin/provared-check.mjs

@@ -457,7 +457,9 @@ function named(s) {
 }
 
 function trustWords(s) {
-  if (named(s)) return s.counts.seals ? 'yes: the passkey you trust, and the recorder you expect' : 'yes: the passkey you trust';
+  const passkeys = new Set(args.issuerKeys).size === 1 ? 'the passkey you trust' : 'the passkeys you trust';
+  const recorders = new Set(args.sealKeys).size === 1 ? 'the recorder you expect' : 'the recorders you expect';
+  if (named(s)) return s.counts.seals ? `yes: ${passkeys}, and ${recorders}` : `yes: ${passkeys}`;
   if (args.issuerKeys.length === 0) return 'NO: you named no passkey you trust (--issuer), so anyone could have made this record. This is not a pass.';
   return 'NO: the record has a seal, and you named no recorder you expect (--sealer), so anyone could have sealed it. This is not a pass.';
 }