provared 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,8 +1,297 @@
 # Changelog
 
-## Unreleased
+## 0.3.0 (10 October 2026)
 
-Draft version 0 of the format. Nothing is published or frozen.
+- 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
+  time, the Python package `provared` on the Python Package Index. Both
+  give the same answers, as the shared test files in `test-vectors/`
+  show. The version rises from 0.1.0 because the format's rules changed:
+  the exact rule for a page address in a slip, weak Ed25519 keys and
+  signatures refused, and strict keys in a time-stamp service's
+  certificate. Version 0.1.0 accepts a forged time-stamp where the
+  person checking names as trusted a service whose certificate has an RSA
+  public number of 1; 0.2.0 refuses it. The entries below say what
+  changed.
+- 2026-10-08: fixes from an independent review of `record_function`, the
+  examples and the wording for a proposed action. None made a book read
+  as intact, or within its slip, when it was not.
+  - Python: a whole number in a tool's arguments that JavaScript cannot
+    hold exactly (beyond 2^53 - 1, unless a float holds it exactly) is
+    refused. Before, `2**60 + 1` and `2**60` left the same fingerprint in
+    their stubs, though the tool was handed the exact number. JSON is now
+    read as JavaScript reads it here too: a whole number beyond 2^53 - 1
+    is the nearest float.
+  - Python: a number of a class built on int or float (an Enum of whole
+    numbers, say) is written as its value, so its fingerprint is that of
+    the same arguments kept as JSON. Before, it was written as its name,
+    which is not JSON.
+  - A generator function is refused as a tool (`recordTools` and
+    `record_tools`) and by `record_function`: calling one does not run
+    its body, so its stub was written for an action not yet taken.
+  - Python: a dict in a tool's arguments whose names are not all text is
+    refused. Before, `{101: 2, "101": 5}` reached the tool as `{"101": 5}`.
+  - Python: `record_function` refuses, when it is handed the function, a
+    parameter whose type can never be plain data (a class of its own,
+    such as a model or a date, a tuple or a set), an object whose
+    `__call__` is defined with `async def`, and a function whose name is
+    not text, each in words of its own. A call whose arguments are not
+    plain data names the argument.
+  - Python: the README and the docstring say that the function is run
+    with a copy of its arguments, and what the record leaves out (an
+    argument bound into a `functools.partial` in place).
+  - The check before acting says "the action gives no amount", not "the
+    stub gives no amount". The shared file `check-before.json` now holds
+    a case for each of the words for a proposed action.
+  - Examples: `offline()` also refuses the other kinds of name look-up,
+    messages sent without a connection, starting another program, a
+    connection made by Python's event loop on Windows (which raises no
+    audit event), and a connection to a port on this computer that the
+    same program does not hold, such as a proxy's. The tests check that
+    nothing was refused while each example ran. Its README says exactly
+    what it refuses.
+- 2026-10-08: examples for three widely used Python agent frameworks, in
+  `python/examples/`, the one folder that names them. Each records an
+  agent's tools with `record_function`, runs the agent with the
+  framework's own stand-in model (no AI service is called; tracing is
+  switched off; any connection outside the program is refused while it
+  runs), and checks the book. Each is tested
+  (`python/examples/test_examples.py`). The library itself still names no
+  product.
+- 2026-10-08: the check before acting speaks of an action that is only
+  proposed: "With this action the total would be 280 GBP", not "With this
+  stub the total is", since no stub exists for an action that is not
+  taken. Likewise for a count and a period. The codes are unchanged; the
+  checker's words for a stub are unchanged.
+- 2026-10-08: the Python version gains `record_function`, which puts one
+  ordinary function behind the stub writer and keeps its name, its
+  parameters and its description, so that an agent framework describes
+  the recorded function to its model as it would the function. Python
+  only: a JavaScript tool takes its arguments as one object. Tested
+  (`python/tests/test_record_function.py`).
+- 2026-10-08: `test-vectors/README.md` says what each shared file holds
+  and what must match: Provared's own libraries give every answer
+  exactly, words included; another implementation needs to match the
+  codes and the shape of each answer. The Python package is made ready
+  for the Python Package Index (version 0.1.0, both licence files); it is
+  not yet published there.
+- 2026-10-08: faults found by a second independent review, of the
+  Python stub writer and of the changes above. In 1,183 random
+  scenarios (about 79,500 steps) played in both languages, and 140 runs
+  with several threads at once, no action was taken after the person's
+  cancellation was handed over, and the writer's view of its book always
+  equalled a whole check. Each fault is fixed and each is now a test
+  (`python/tests/test_review2.py`).
+  - **An Ed25519 signature whose first half (R) is a point of small
+    order is refused**, in both languages, whatever the key. The holder
+    of an honest key could make one for any message; Node.js refused it
+    and the OpenSSL beneath the Python version accepted it, so one
+    record had two answers (format description, section 3.8).
+  - A copy of what the stub writer is handed is refused if it nests more
+    than 64 levels deep, in both languages. Before, the JavaScript
+    library's limit depended on how much of the stack was in use. The
+    depth is measured on the copy, so the caller's value is still read
+    once.
+  - Python: a cancellation handed to `add` beside a member whose name is
+    a number, None or something stranger, or in a read-only mapping, is
+    read, and stops the writer, as in JavaScript. An error from the other
+    side that is not an `Exception` (such as `SystemExit`) leaves a
+    one-sided stub, as any other failure does. `snapshot()` hands back
+    the book and the cancellations the writer holds, read together, so
+    that another thread's call cannot fall between the two. A number too
+    large for a float is no time; options holding objects that cannot be
+    copied are kept as they are, as the JavaScript library keeps them;
+    the record writers take a datetime with a time zone, as the
+    JavaScript ones take a Date.
+- 2026-10-08: faults found by an independent review of the Python
+  version, which also changed the JavaScript library.
+  - **Weak Ed25519 keys are refused.** Under one of the eight Ed25519
+    keys of small order, anyone can make a signature that checks.
+    Node.js refused such signatures; the OpenSSL beneath the Python
+    version accepted them, so with such a key trusted, a slip made by
+    someone holding no private key read as sound there. RFC 8032 does
+    not say to refuse these keys and libraries differ, so now the
+    checker refuses them itself, with any key written in more than one
+    way (y not below p): `bad-key` for a key in a record,
+    `stamp-invalid` for a time-stamp service's key.
+  - **The page address in a slip follows an exact rule.** The checker
+    used the URL Standard's own reader of addresses, which for a name
+    beginning `xn--` rests on tables of Unicode that differ from one
+    version of Node.js to the next, so two checkers could disagree. Now
+    `issuer.origin` must be written as a browser writes it, by a rule
+    that needs no such tables: `https://` (or `http://localhost`), a
+    host of lower-case letters, digits and hyphens in labels, a port
+    only where it is not the scheme's own, and nothing more (format
+    description, section 4.1). Some addresses the URL Standard allows
+    are now refused: underscores and other signs in a host, port 0,
+    addresses of numbers.
+  - A time-stamp service's key of another kind, or on another curve, is
+    refused in words that say so, not as a signature that "does not
+    fit".
+  - A time is read only from a number of milliseconds or a Date. Text,
+    true or a list were read by rules that differ from one device to
+    another (text with no time zone was taken as local time).
+  - `withoutMethods` that is not a list is set aside when a slip is
+    checked, as everywhere else. Before, it made the slip's check fail.
+- 2026-10-08: the Python version gains the stub writer beside an agent
+  (`open_recorder`) and the connector for an agent's tools
+  (`record_tools`, `arguments_fingerprint`, `NotTaken`). So it now does
+  everything the JavaScript library does.
+  - They are ported one to one and give the same answers: two new
+    shared files, `test-vectors/recorder-scenarios.json` (32 scenarios,
+    about 1,000 steps) and `test-vectors/tool-scenarios.json` (8
+    scenarios), each a world of records made beforehand and a list of
+    steps (actions, records, cancellations in every form the writer
+    takes, time-stamps, acknowledgements, a clock that fails, writers
+    opened again, tools called), with the transcript of what happened.
+    The two libraries play each scenario (`test/helpers/scenarios.mjs`
+    and `python/tests/scenarios.py`) and must write the same transcript,
+    down to the words of every message and how many times the clock was
+    read.
+  - In Python every call is an ordinary function. The writer's calls
+    wait for one another across threads. A call to the writer from
+    inside an action it is taking, or from the other side while it
+    countersigns, is refused at once, as in Node.js. The other side is
+    asked in a thread of its own and given 30 seconds, as before. A
+    function handed over that gives a coroutine is refused.
+  - `key_set_from_seeds` and `key_set_seeds`: an agent's keys kept
+    between runs as their two 32-byte seeds.
+  - The Python reading of base64url and the copy of a check's options
+    are faster; they give the same answers (a value shared many times in
+    the options is now copied once, as the JavaScript library copies it).
+  - `test/helpers/world.mjs` can be given the agent's and the service's
+    key sets, so that a scenario can hand the same keys to Python.
+- 2026-10-08: two faults in the check of a time-stamp from a service,
+  found while writing the Python version.
+  - An RSA key with the public number 1 in a service's certificate was
+    accepted. Under it, anyone can make a signature that checks, so a
+    time-stamp could be made without the service's private key. It
+    counted only where the person checking had named that certificate as
+    trusted. An even public number was accepted too. Now the public
+    number must be odd, from 3 to 2^32 - 1 (`stamp-invalid`).
+  - The public key inside a certificate was read loosely: a compressed or
+    "hybrid" point, RSA numbers with needless or missing sign bytes,
+    bytes after the key, any parameters, and unused bits all loaded. Now
+    the key must be written exactly as its own standard sets out
+    (`stamp-bad-data`), as the rest of a time-stamp already must be, so
+    that two checkers cannot disagree about whether it can be read.
+  - Each is a shared test (`test-vectors/stamps-strict-keys.json`).
+- 2026-10-08: shared test files, and the start of a Python version.
+  - `test-vectors/` holds records and values, each with the answer this
+    library gives: the canonical form, base64url, times, keys, a
+    passkey's signature, the envelope of a record, the content of a stub
+    and of a countersignature, page addresses and 170 slips, sound and
+    faulty. `tools/make-vectors.mjs` writes them;
+    `test/vectors.test.mjs` checks that this library still gives every
+    answer. Any other implementation of the format can be tested against
+    them.
+  - `python/` holds a Python version, built in stages against the same
+    files. It is not yet published. It now checks everything the
+    JavaScript library checks: slips, stubs, countersignatures, limits,
+    approvals, refusals and terms, passes, cancellations and
+    acknowledgements, vouching records, seals and their time-stamps,
+    block time-stamps, the tree and its proofs, Shows, the chain of
+    block headers, and the check before acting. It gives the same answer
+    in every one of the 63 shared files, and in 6,091 random books
+    compared on this computer. One difference is stated: "cryptography",
+    the one package it needs, has no SLH-DSA yet, so a seal's third
+    signature is reported as not checked on this device and never as a
+    pass. The stub writer and the connector for an agent's tools are
+    still to come.
+  - A slip whose page address cannot be read, and one whose address is
+    not in its plain form, are now refused with the same words. The code
+    (`bad-field`) is unchanged.
+- 2026-10-07: the README links to the individual Internet-Draft
+  `draft-izmaylov-agent-permission-receipts`, which describes the core of
+  the format.
+
+## 0.1.0 (6 October 2026)
+
+Draft version 0 of the format, published and not frozen.
 
 - 2026-10-05: `provared-headers` is marked as experimental, in the
   README and in what the command prints.