provared 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,329 @@
 # Changelog
 
+## 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`
+  in JavaScript and `provared.dev` in Python, so that a first record can
+  be made without a browser: `developmentPasskey` (an ES256 key made in
+  memory that returns the three values a passkey returns, for the page
+  address `http://localhost`), `developmentSlip` (a slip it signed, with
+  new keys for the agent, a book holding the slip, and the stand-in's
+  thumbprint for a checker) and `developmentRecorder` (the stub writer
+  opened under such a slip, in one call). It is not a passkey and no
+  person confirms anything through it, so the issuer's name in every
+  slip it signs is made to end with " (development)", whatever name is
+  given, and the checker prints that name. The library itself (`provared`)
+  does not export it, and the checker does not use it. A first record in
+  one file: `examples/first-record.mjs` and
+  `python/examples/first_record.py`, each run by a test.
+- 2026-10-10: `provared-check --sample` checks the sample record that
+  comes with the library, naming the stand-in passkey, the recorder and
+  the time-stamp service it was made with as trusted, and prints their
+  fingerprints; with `--json` the result alone. A file or another option
+  given with it is refused.
+- 2026-10-10: the README is now a short landing page (install, a first
+  record, the four parts, what is only here, what a record does not
+  prove, where everything else is), and its former body is
+  `docs/guide.md`, unchanged but for the additions above. New:
+  `SECURITY.md` (how to report a fault in the security of a record) and
+  `CONTRIBUTING.md` (fault reports and other implementations welcome;
+  code only under a contributor agreement, whose text is not ready yet).
+  `package.json` and `python/pyproject.toml` gain a homepage, keywords
+  and a longer description. Version 0.3.0 in both, not yet published.
+- 2026-10-10: the pages at prova.red: the home page's first screen now
+  shows the checker's summary and the install lines before the four
+  parts, with the plain word first and the short name after ("the
+  permission (a Slip)"); a first record of your own, in three commands,
+  with the file above and the LangChain package; "what the author found
+  nowhere else (October 2026)"; the status promises that every published
+  version stays on npm and the Python Package Index. The plain-words page
+  says that the 25 rounds of review were by AI reviewers and that no
+  person other than the author has reviewed the code yet, gives the date
+  from which the EU AI Act's logging duty applies (2 December 2027),
+  marks its charity example as invented, and uses "flight recorder" only
+  as a description. The developer page shows the code that made the
+  sample record and says the same about the reviews. All three pages
+  gain preview tags, an icon (`favicon.svg`, four coloured squares) and
+  a preview image (`preview.png`, drawn from a small page in a headless
+  browser), with the content security policy widened by `img-src 'self'`
+  only; `robots.txt` and `sitemap.xml` are added, and the workflow copies
+  everything in `site/`. Nothing in the library changes for this.
+- 2026-10-10: the pages for prova.red, in `site/`: what a record
+  proves, the command-line checker's own answer for the sample record
+  (run on Node.js 24.19), how to try it, what is only here, how it is
+  built, where it is, a worked example for developers ("An agent goes
+  over its limit, and the record shows where") and "Provared in plain
+  words", three minutes for a reader who does not write code, with two
+  drawings that follow the sample record. No script, no font, no image,
+  no form: each page loads nothing from anywhere and keeps nothing about
+  a reader, and says so. The drawings carry their colours as plain SVG
+  attributes as well as through the style sheet, and the pages load the
+  style sheet under a versioned address, so a browser that kept an
+  earlier copy still draws them right. A workflow, `.github/workflows/pages.yml`,
+  publishes them with GitHub Pages from the main branch, with the
+  checking page at `/check/` (with the library and the sample it loads,
+  copied as they are) and built as one file at `/provared-check.html`.
+  The four actions it uses are GitHub's own, each pinned to the commit
+  of a released version. The site is not published until the domain
+  points at it. Nothing in the library, the checker or the package
+  changes.
+- 2026-10-08: two small Python packages for agent frameworks, in
+  `python/integrations/`, each in a folder of its own, which names its
+  framework. Each puts every tool call of an agent behind the stub
+  writer with no change to the tools: the check before acting is asked,
+  the tool runs only if the slip allows it, and a stub is written; a call
+  that is not allowed is not run, and the model is told why. Each checks
+  the call as the tool receives it: one must come last among the parts
+  that wrap tool calls, and refuses to run otherwise; the other wraps
+  each of the agent's own sets of tools, wherever it stands. Each works with ordinary
+  and asynchronous agents: the stub writer runs in a thread of its own
+  for each call, and cancelling a run cancels a tool that is waiting.
+  Each is tested with its framework's own stand-in model, inside the
+  examples' guard. An independent review found eight faults in the first
+  draft, among them a reviewer's change that got past the slip and
+  asynchronous agents that could hang; each is fixed and tested. They use
+  only the public interface of the `provared` package, which itself still
+  names no product. Not yet published.
+
 ## 0.2.0 (8 October 2026)
 
 - 2026-10-08: version 0.2.0, for the npm package and, for the first