provared 0.6.0 → 0.7.0

package/bin/provared-check.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // provared-check: check a book or a Show from the command line.
 //
-//   provared-check <file> [--issuer <thumbprint>]... [--sealer <fingerprint>]... [--stamp-service <fingerprint>]...
+//   provared-check <file> [--issuer <thumbprint>]... [--origin <address>]... [--sealer <fingerprint>]... [--stamp-service <fingerprint>]...
 //                  [--block <fingerprint>]... [--voucher <fingerprint>]... [--disclosures <file>] [--cancellation <file>]...
 //                  [--seal <file>]... [--witness <fingerprint>]... [--root <top fingerprint>] [--size <entries>] [--json]
 //
@@ -20,7 +20,7 @@
 
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { DENIAL_SOURCES, MIN_BLOCKS_AFTER, REFUSAL_REASONS, blocksInChain, checkBook, checkHeaderChain, checkShow, conditionWords, limitWords, neverWords } from '../src/check.js';
+import { DENIAL_SOURCES, MIN_BLOCKS_AFTER, REFUSAL_REASONS, blocksInChain, checkBook, checkHeaderChain, checkShow, conditionWords, isPageAddress, limitWords, neverWords } from '../src/check.js';
 
 // Node.js marks its ML-DSA and SLH-DSA as experimental and says so on every
 // run. The checker does not repeat that warning; any other warning is shown.
@@ -29,16 +29,19 @@ process.on('warning', (w) => {
   if (w.name !== 'ExperimentalWarning') console.error(`${w.name}: ${w.message}`);
 });
 
-const USAGE = `Usage: provared-check <file> [--issuer <thumbprint>]... [--sealer <fingerprint>]... [--stamp-service <fingerprint>]...
-                      [--block <fingerprint>]... [--voucher <fingerprint>]... [--disclosures <file>] [--cancellation <file>]...
-                      [--seal <file>]... [--witness <fingerprint>]... [--root <top fingerprint>] [--size <entries>]
-                      [--headers <file>] [--json]
+const USAGE = `Usage: provared-check <file> [--issuer <thumbprint>]... [--origin <address>]... [--sealer <fingerprint>]...
+                      [--stamp-service <fingerprint>]... [--block <fingerprint>]... [--voucher <fingerprint>]...
+                      [--disclosures <file>] [--cancellation <file>]... [--seal <file>]... [--witness <fingerprint>]...
+                      [--root <top fingerprint>] [--size <entries>] [--headers <file>] [--json]
        provared-check --sample [--json]
 
   <file>           a book (one entry to a line) or a Show (one JSON object)
   --sample         check the sample record that comes with the library, naming the passkey, the recorder and the
                    time-stamp service it was made with as trusted (they are stand-ins, and the people are invented)
   --issuer         the thumbprint of an issuer key you already trust; may be repeated
+  --origin         the address of the page at which the person signs permissions, such as https://sign.example.org
+                   (https://, a website name in lower case, a port only if it is needed, and nothing more); a
+                   permission signed at any other address is refused; may be repeated
   --sealer         the fingerprint of the key set of a recorder you expect to have sealed the book; may be repeated
   --stamp-service  the fingerprint of the certificate of a time-stamp service you trust; may be repeated
   --block          the fingerprint (64 hex characters) of a block of a public blockchain that you trust to be part of the chain;
@@ -68,14 +71,14 @@ const FINGERPRINT = /^[A-Za-z0-9_-]{43}$/;
 const BLOCK = /^[0-9a-f]{64}$/;
 
 // Options that may be repeated, and those that may be given once.
-const LISTS = { '--issuer': 'issuerKeys', '--sealer': 'sealKeys', '--stamp-service': 'stampServices', '--block': 'blocks', '--voucher': 'vouchers', '--witness': 'witnesses', '--cancellation': 'cancellations', '--seal': 'seals' };
+const LISTS = { '--issuer': 'issuerKeys', '--origin': 'issuerOrigins', '--sealer': 'sealKeys', '--stamp-service': 'stampServices', '--block': 'blocks', '--voucher': 'vouchers', '--witness': 'witnesses', '--cancellation': 'cancellations', '--seal': 'seals' };
 const ONCE = { '--disclosures': 'disclosures', '--root': 'expectedRoot', '--size': 'expectedSize', '--headers': 'headers' };
 
 // The arguments, or the reason they cannot be used. A value that is not a
 // fingerprint is refused, never set aside: a typing error must not quietly
 // leave a time-stamp or a name uncounted.
 function parseArguments(argv) {
-  const out = { file: null, sample: false, issuerKeys: [], sealKeys: [], stampServices: [], blocks: [], vouchers: [], witnesses: [], cancellations: [], seals: [], disclosures: undefined, expectedRoot: undefined, expectedSize: undefined, json: false };
+  const out = { file: null, sample: false, issuerKeys: [], issuerOrigins: [], sealKeys: [], stampServices: [], blocks: [], vouchers: [], witnesses: [], cancellations: [], seals: [], disclosures: undefined, expectedRoot: undefined, expectedSize: undefined, json: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--help' || a === '-h') return { help: true };
@@ -93,6 +96,9 @@ function parseArguments(argv) {
         return { error: `The value of ${a} is not a fingerprint. A fingerprint is 43 letters, digits, hyphens or underscores, with no spaces.` };
       }
       if (a === '--block' && !BLOCK.test(value)) return { error: 'The value of --block is not the fingerprint of a block: 64 characters, the digits 0 to 9 and the letters a to f.' };
+      if (a === '--origin' && !isPageAddress(value)) {
+        return { error: 'The value of --origin is not a page address in its plain form: https://, a website name in lower case, a port only if it is needed, and nothing more, such as https://sign.example.org.' };
+      }
       if (a === '--size' && !/^\d{1,6}$/.test(value)) return { error: 'The value of --size is not a number of entries.' };
       if (Object.hasOwn(LISTS, a)) out[LISTS[a]].push(value);
       else out[ONCE[a]] = a === '--size' ? Number(value) : value;
@@ -101,7 +107,7 @@ function parseArguments(argv) {
   }
   if (out.sample) {
     if (out.file !== null) return { error: '--sample names the sample record itself: give no file with it.' };
-    for (const name of ['issuerKeys', 'sealKeys', 'stampServices', 'blocks', 'vouchers', 'witnesses', 'cancellations', 'seals']) {
+    for (const name of ['issuerKeys', 'issuerOrigins', 'sealKeys', 'stampServices', 'blocks', 'vouchers', 'witnesses', 'cancellations', 'seals']) {
       if (out[name].length) return { error: '--sample names what to trust itself: give no other option with it but --json.' };
     }
     if (out.disclosures !== undefined || out.expectedRoot !== undefined || out.expectedSize !== undefined || out.headers !== undefined) {
@@ -503,6 +509,10 @@ function print(result, isShow) {
     console.log(`  Time-stamped in a way you trust?      ${stamped}`);
     if (s.counts.seals || args.witnesses.length) console.log(`  Witnessed by a witness you trust?     ${witnessedWords(s)}${isShow && s.witnessed ? ' (single pages: this says nothing about totals over the whole book)' : ''}`);
     console.log(`  Checked against keys you named?       ${trustWords(s)}`);
+    // Shown only where the person named an address: a permission signed
+    // elsewhere is a problem, reported above, so here every one was signed
+    // at an address they named.
+    if (args.issuerOrigins.length) console.log(`  Signed at an address you named?       yes: every permission was signed at ${[...new Set(args.issuerOrigins)].join(' or ')}`);
     if (args.seals.length) console.log(`  Seals held elsewhere compared?        ${heldWords(result)}`);
   }
   console.log(`  Slips ${s.counts.slips}, stubs ${s.counts.stubs} (countersigned ${s.counts.countersigned}, one-sided ${s.counts.oneSided})${s.counts.seals ? `, seals ${s.counts.seals}` : ''}`);
@@ -608,6 +618,7 @@ try {
 
 const options = {};
 if (args.issuerKeys.length) options.issuerKeys = args.issuerKeys;
+if (args.issuerOrigins.length) options.issuerOrigins = args.issuerOrigins;
 if (args.sealKeys.length) options.sealKeys = args.sealKeys;
 if (args.stampServices.length) options.stampServices = args.stampServices;
 if (args.blocks.length) options.blocks = args.blocks;

package/docs/guide.md

@@ -6,7 +6,7 @@ Everything about the format, the library, the checker, the stub writer beside an
 
 ## Status
 
-**Version 0.6.0, a draft.** Published as it is, by one author in their
+**Version 0.7.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.
 
@@ -33,14 +33,16 @@ An Internet-Draft is a working document, not a standard.
 | `src/` | The library: the checker, the writers for every kind of record, the stub writer beside an agent and the connector for an agent's tools. No outside code |
 | `bin/provared-check.mjs` | The checker for the command line |
 | `bin/provared-headers.mjs`, `net/` | A command that fetches the chain of Bitcoin block headers from nodes you name, so that a block time-stamp can be checked with no node of your own. The only code here that makes a network request. Experimental |
-| `page/` | The checking page and the demonstration page |
+| `page/` | The checking page, the signing page and the demonstration page |
 | `demo/` | The demonstration: an invented office agent works under a permission and goes outside it four times |
 | `samples/` | A sample record, written once, that the tests keep checking |
-| `tools/` | Three small tools: one wrote the sample record, one writes the checking page as a single file, one writes the shared test files |
+| `tools/` | Small tools: one wrote the sample record, one writes the checking page as a single file, one writes the shared test files, one writes the record page at prova.red/records/, and one writes the files of the signing page's own site, sign.prova.red |
 | `test/` | The tests |
 | `test-vectors/` | Shared test files: records and values, each with the answer this library gives. Another implementation of the format can be tested against them |
-| `python/` | The Python version, `pip install provared`, which gives the same answers. See its own [README](../python/README.md), and its examples with three agent frameworks in `python/examples/`, and small packages for two of them in `python/integrations/` |
-| `site/` | The pages at [prova.red](https://prova.red/): what a record proves, with the checker's answer for the sample record, and a worked example. Published with GitHub Pages by `.github/workflows/pages.yml`, which also serves the checking page at `prova.red/check/` and as one file. The pages load nothing from anywhere and keep nothing about a reader |
+| `integrations/claude-code/` | The recorder beside Claude Code, `npm install -g provared-claude-code`, also a Claude Code plugin. See its own [README](https://github.com/provared/provared/blob/main/integrations/claude-code/README.md) |
+| `mcp-executor/` | An executor for MCP tool servers, `npm install -g provared-mcp-executor`: it holds the tool servers' credentials, checks each tool call against the permission, and countersigns each receipt with keys of its own. See its own [README](https://github.com/provared/provared/blob/main/mcp-executor/README.md) |
+| `python/` | The Python version, `pip install provared`, which gives the same answers. See its own [README](https://github.com/provared/provared/blob/main/python/README.md), and its examples with three agent frameworks in `python/examples/`, and small packages for two of them in `python/integrations/` |
+| `site/` | The pages at [prova.red](https://prova.red/): what a record proves, with the checker's answer for the sample record, and a worked example. Published with GitHub Pages by `.github/workflows/pages.yml`, which also serves the checking page at `prova.red/check/` and as one file. The signing page is served from a repository of its own at `sign.prova.red`, so that the passkeys made there belong to a name that serves nothing else. The pages load nothing from anywhere and keep nothing about a reader |
 
 The npm package holds `src/`, `bin/`, `net/`, `spec/`, `docs/`,
 `samples/` and the checking page. The tests, the shared test files, the
@@ -105,7 +107,7 @@ const passkey = await developmentPasskey();
 fills in the issuer (its key, page address and marked name) and the
 agent's keys; by default the slip runs from a minute ago for one day,
 holds no limits and names no other party, and its purpose says that it
-is for development. [examples/first-record.mjs](../examples/first-record.mjs)
+is for development. [examples/first-record.mjs](https://github.com/provared/provared/blob/main/examples/first-record.mjs)
 is a whole first record in one file. In Python the same is
 `provared.dev` (`development_passkey`, `development_slip`,
 `development_recorder`), with the writer as `.writer`.
@@ -151,9 +153,9 @@ 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, and on 13 October
 2026 in Chrome 155, Edge 155 and Brave 155.) The file for
-version 0.6.0 is attached to the release on GitHub. Its SHA-256
+version 0.7.0 is attached to the release on GitHub. Its SHA-256
 fingerprint is
-`ae48c425616d70849aa8d43b1d71ef7ee56736da3ba6a00eaa4375c428e60a25`.
+`c7b3d5fe1b9168628fc91308c7f952b970c05b3abeb908a132b8b2b78aaab1b5`.
 
 **Run the demonstration in a browser.**
 
@@ -761,6 +763,16 @@ 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.
 
+[examples/frameworks/](https://github.com/provared/provared/tree/main/examples/frameworks) in the repository shows
+`recordTools` beside a JavaScript agent framework, the Vercel AI SDK
+(`ai`, version 7). The SDK's own tool calls the recorded tool from its
+`execute` function, and the SDK hands the words of `NotTaken` back to the
+model as a failed tool call, so the agent is told why a call was not run.
+It runs with a scripted stand-in model and sends nothing anywhere; it has
+its own `package.json`, with exact versions, and is not part of the npm
+package. The Python examples are in
+[python/examples/](https://github.com/provared/provared/tree/main/python/examples) in the repository.
+
 ### Denials: the calls the agent's side refused
 
 A book shows what the agent did, not how often it was stopped. Opened
@@ -832,6 +844,9 @@ section 27); any other such name is refused.
 | `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` |
+| `provared.tool-name` | The name of the tool, exactly as the agent's software called it (not the slip's action name) | `identifierFingerprint` |
+| `provared.tool-call-id` | The identifier the model gave the tool call, exactly as received | `identifierFingerprint` |
+| `provared.tool-result` | The tool's result, in the one form of RFC 8785; never the result itself | `argumentsFingerprint` (the same one form) |
 
 `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
@@ -885,13 +900,42 @@ from its fingerprint.
 
 `recordTools` names the arguments `provared.arguments` by default (before
 version 0.6.0, `arguments`; every checker reads both); a tool can name
-them otherwise through its own `details` function.
+them otherwise through its own `details` function. It does not name the
+tool's name or its result: a tool's `details` function can add
+`provared.tool-name`, and `provared.tool-result` is added after the
+action, through `detailsAfter` of `act`. The MCP executor
+(`mcp-executor/`) names all three where it has them. Each of the three
+may be named once in a stub; a checker of version 0.5.0 or 0.6.0 refuses
+a stub that names any of them, and one of 0.4.0 or earlier reads them as
+labels.
+
+To show each receipt on the trace span of its call in an observability
+tool, use the OpenTelemetry bridge in `integrations/opentelemetry/` (not
+yet published); a span is a pointer to the receipt, not evidence. It puts
+`provared.trace-id` into a receipt only for a tool that you say sends the
+trace out with its call, in a `traceparent` header, as this section
+defines the name; it cannot see whether the tool really does. Where a
+tool gives the model's identifier for the call (`callId`), the receipt
+names it as `provared.tool-call-id`.
 
 ## How signing works
 
 - **The person** signs a slip with a passkey. A passkey signs a short
   value handed to it; that value is the SHA-256 fingerprint of the slip's
   exact signed bytes, so the signature covers the whole slip.
+- **The signing page is served at an address of its own**,
+  [sign.prova.red](https://sign.prova.red/), which serves nothing else
+  (its files are copied from `page/` by `tools/make-sign-site.mjs` into
+  the public repository `provared/sign`). A passkey can be asked to sign
+  by any page under the website name it was made for, and what it signs
+  is a fingerprint the person cannot read on the device's prompt, so a
+  passkey made for a name that serves other pages could be made to sign
+  a permission by one of them. A passkey made at sign.prova.red can be
+  asked only there. Whoever checks a record can name the address the
+  person signs at (`issuerOrigins`, or `--origin`, or the box on the
+  checking page): a permission signed under the same passkey anywhere
+  else is then refused (`issuer-origin-not-expected`). The list of
+  threats, section 3, says what this closes and what it does not.
 - **The agent and the service** each sign with two keys at once: Ed25519,
   which is today's kind, and ML-DSA-87, which is quantum-safe. A record
   counts only if both signatures check. A forger must break both.
@@ -1087,6 +1131,10 @@ wrong. Never show it as fact: the checking page and the command-line
 checker do not.
 
 Options: `issuerKeys` (the thumbprints of issuer keys you trust),
+`issuerOrigins` (the addresses of the pages at which the person signs
+permissions, such as `https://sign.example.org`, each in the one form
+the format allows; a permission signed anywhere else is refused with
+`issuer-origin-not-expected`; see "How signing works"),
 `sealKeys` (the fingerprints of the key sets of the recorders you
 expect), `stampServices` (the fingerprints of the certificates of the
 time-stamp services you trust), `blocks` (the fingerprints of the
@@ -1110,8 +1158,9 @@ where the record has a seal, the recorder you expect), 1 (no problem
 found, but the agent is outside its slip, not every signature could be
 checked, or you did not name whom you trust) or 2 (a problem was found,
 or what you gave on the command line could not be used). A value that
-is not a fingerprint is refused, never set aside. The checking page
-gives its green answer on the same terms.
+is not a fingerprint, or an address given with `--origin` that is not a
+page address in its plain form, is refused, never set aside. The
+checking page gives its green answer on the same terms.
 
 Writing records: `prepareSlip` and `assembleSlip`, `prepareApproval` and
 `assembleApproval` (the person), `writeStub` (the agent), `countersign`,

package/docs/threat-model.md

@@ -91,20 +91,47 @@ follows the checking steps of the Web Authentication standard.
   section 6b. Slips should still be short-lived.
 - Who the issuer is. The slip proves which key signed, not whose key it
   is.
-- Against a page that has the passkey sign a record dressed as a sign-in.
-  A passkey signs only a challenge, and the challenge for a slip, an
-  approval or a cancellation is the fingerprint of the record, which the
-  person cannot read on the device's prompt. Any page at an origin under
-  the slip's `rpId` (the website's own operator, a script running on one
-  of its pages, or the operator of any subdomain) can hand the device the
-  fingerprint of a record it wrote as an ordinary sign-in challenge: the
-  client data of a sign-in and of a record have the same shape, and the
-  person sees a sign-in prompt. No device and no page need be broken into.
-  The checker compares the origin and the rpId only with what the slip
-  itself says. So a passkey that signs records should be registered to a
-  relying party (an `rpId`) used for nothing else, and the page that asks
-  for the signature should show the record first. The checker has no
-  option yet by which a reader names the origin they expect.
+- Against a page that has the passkey sign a record dressed as a sign-in,
+  where the passkey's website name (its `rpId`) serves anything but the
+  signing page. A passkey signs only a challenge, and the challenge for a
+  slip, an approval or a cancellation is the fingerprint of the record,
+  which the person cannot read on the device's prompt. Any page at an
+  origin under the slip's `rpId` (the website's own operator, a script
+  running on one of its pages, or the operator of any subdomain) can hand
+  the device the fingerprint of a record it wrote as an ordinary sign-in
+  challenge: the client data of a sign-in and of a record have the same
+  shape, and the person sees a sign-in prompt. No device and no page need
+  be broken into. The checker compares the origin and the rpId with what
+  the slip itself says; and, where the reader names the address they
+  expect the person to sign at (`issuerOrigins`, `--origin`, or the box
+  on the checking page; format description, section 4.4), with that
+  address too, refusing a slip signed anywhere else
+  (`issuer-origin-not-expected`). What each measure does:
+  - A passkey made for a name that serves only the signing page closes
+    this for that passkey: the device lets it sign only for pages under
+    that name, so no other page can have it sign anything. Provared's own
+    signing page is served at sign.prova.red, a name that serves nothing
+    else.
+  - A reader who names the address is protected by naming alone against
+    every other address under the `rpId`, whatever name the passkey was
+    made for: the client data the passkey signs must say that address, so
+    a record signed at any other address under the `rpId` is refused. It
+    does not protect against another page served at the named address
+    itself.
+  - A page that shows the record before it asks for the signature helps
+    only against a page that asks openly for a record to be signed. It
+    does nothing against a prompt dressed as a sign-in, which shows no
+    record.
+  - Naming an address protects only the reader who names it. It does not
+    stop the passkey signing records at other pages, which readers who
+    name no address, or name another one, accept.
+
+  What stays open: a reader who names no address is protected only by
+  which passkey they trust; whoever serves the named address (the host of
+  the site, or whoever holds its domain name) can serve another page
+  there, and a reader's naming does not tell that page from the real one;
+  and a passkey made for a name that serves other pages stays exposed to
+  every reader who does not name the address.
 
 ## 4. The Stub and the countersignature
 
@@ -144,8 +171,11 @@ 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`).
+body; no header is covered), of the error the agent was given
+(`provared.error`), of the name of the tool that was called
+(`provared.tool-name`), of the identifier the model gave the tool call
+(`provared.tool-call-id`) or of the tool's result (`provared.tool-result`,
+in the one form of RFC 8785, as the arguments are).
 
 - *What it shows.* Someone who holds the platform's own log can work the
   fingerprint out again and match the two records, without either
@@ -158,7 +188,11 @@ body; no header is covered), or of the error the agent was given
   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.
+  may be named more than once in a stub. `provared.tool-call-id` picks
+  out the model's request for the call, which the agent's software may
+  carry out more than once (a retry): two stubs then name one identifier.
+  A tool's name and a tool's result are content: every call of one tool
+  shares its name's fingerprint, and identical results share one.
 - *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
@@ -172,8 +206,13 @@ body; no header is covered), or of the error the agent was given
   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.
+  tell; only someone who holds that text can. An identifier, a tool's
+  name or a result that is short or easy to guess gives no privacy
+  through its fingerprint: a tool's name is found by trying the
+  framework's or the server's tool names, and a short result (`"ok"`,
+  `{}`) by trying the likely values. The record holds fingerprints and
+  not the result itself so that the record stays small and fixed, not to
+  hide the result.
 - *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,
@@ -186,10 +225,14 @@ body; no header is covered), or of the error the agent was given
   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`
+  so is one of the seven 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.
+  its check. The three names added after version 0.6.0 (`provared.tool-name`,
+  `provared.tool-call-id`, `provared.tool-result`) are refused by a
+  checker of version 0.5.0 or 0.6.0, which knows the first seven only,
+  and read as labels by one of 0.4.0 or earlier: a book that names them
+  checks in full only with a later checker.
 
 ## 4a. Limits, conditions, approvals and the other side's records
 
@@ -1161,11 +1204,12 @@ it show a pass for a record that does not check.
   It asks for every header from the first block onwards, so a node does
   not learn which blocks matter to the person.
 - What the person hands the checking page beside a record (their own
-  copies of cancellations, disclosures for covered fields, the blocks
-  and fingerprints they trust) is read in the browser and sent nowhere.
-  A file that is not JSON, or a line that is not a fingerprint, stops
-  the check and says so: it is never set aside silently. The sample
-  record is checked without the files handed over.
+  copies of cancellations, disclosures for covered fields, the blocks,
+  the fingerprints and the signing page's address they trust) is read in
+  the browser and sent nowhere. A file that is not JSON, or a line that
+  is not a fingerprint or a page address in its plain form, stops the
+  check and says so: it is never set aside silently. The sample record
+  is checked without the files handed over.
 - The checker depends on no outside code. It uses only the cryptography
   built into the browser or Node.js.
 - **The checking page as one file** (`tools/make-single-page.mjs`) holds
@@ -1241,6 +1285,7 @@ fails if the two differ.
 | `passkey-user-not-verified` | A passkey signature where the device did not confirm the person |
 | `passkey-bad-data` | Passkey values that are cut short or malformed |
 | `issuer-not-expected` | A slip signed by a key other than the ones the checker was told to expect |
+| `issuer-origin-not-expected` | A slip signed at a page address other than the ones the checker was told to expect (section 3) |
 | `slip-missing` | A stub whose slip is not earlier in the book |
 | `slip-unusable` | A stub whose slip failed its own check |
 | `chain-broken` | A stub that is missing, moved, repeated or changed |

package/net/headers.js

@@ -232,6 +232,7 @@ export function apart(a, b) {
  */
 export function nodeAddress(text) {
   const line = String(text).split('#')[0].trim();
+  // eslint-disable-next-line security/detect-unsafe-regex -- no repetition inside repetition can match the same text two ways (labels split by a full stop the labels cannot match), so matching takes time in proportion to the input.
   const m = line.match(/^\[([0-9a-fA-F:.]+)\](?::(\d{1,5}))?$/) ?? line.match(/^([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*)\.?(?::(\d{1,5}))?$/);
   if (!m) return null;
   const host = m[1].toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "provared",
-  "version": "0.6.0",
+  "version": "0.7.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/check-page.js

@@ -6,7 +6,7 @@
 // request at all.
 
 import { checkBook, checkShow } from '../src/check.js';
-import { readBlocks, readFingerprints, readHanded, renderResult, shown } from './render.js';
+import { readBlocks, readFingerprints, readHanded, readOrigins, renderResult, shown } from './render.js';
 
 const status = document.getElementById('status');
 const result = document.getElementById('result');
@@ -37,6 +37,13 @@ function trusted() {
     throw new Error('A line in the box for blocks is not the fingerprint of a block. It is 64 characters: the digits 0 to 9 and the letters a to f. Correct it, or empty the box.');
   }
   if (blocks.values.length) options.blocks = blocks.values;
+  // The addresses at which the person expects the permissions to have been
+  // signed: each in the one form the format allows, or the check stops.
+  const origins = readOrigins(document.getElementById('trust-origins').value);
+  if (origins.bad.length) {
+    throw new Error('A line in the box for the address of the signing page is not a page address in its plain form: https://, a website name in lower case, a port only if it is needed, and nothing more, such as https://sign.example.org. Correct it, or empty the box.');
+  }
+  if (origins.values.length) options.issuerOrigins = origins.values;
   return options;
 }
 

package/page/index.html

@@ -20,6 +20,8 @@
     <p class="quiet">A check says more when you tell it which keys and services you expect. Put one fingerprint on each line. Use fingerprints you obtained yourself, from the people concerned.</p>
     <label for="trust-issuer">The person's passkey (its thumbprint)</label>
     <textarea id="trust-issuer" rows="2" spellcheck="false"></textarea>
+    <label for="trust-origins">The address of the page at which the person signs permissions (such as https://sign.example.org; a permission signed at any other address is refused)</label>
+    <textarea id="trust-origins" rows="2" spellcheck="false"></textarea>
     <label for="trust-sealer">Whoever keeps and seals the book (the fingerprint of its key set)</label>
     <textarea id="trust-sealer" rows="2" spellcheck="false"></textarea>
     <label for="trust-stamps">Time-stamp services (the fingerprint of each service's certificate)</label>

package/page/render.js

@@ -7,7 +7,7 @@
 // is kept inside its own box, so that a record cannot hide, reorder or
 // draw over the words around it.
 
-import { DENIAL_SOURCES, REFUSAL_REASONS, conditionWords, limitWords, neverWords } from '../src/check.js';
+import { DENIAL_SOURCES, REFUSAL_REASONS, conditionWords, isPageAddress, limitWords, neverWords } from '../src/check.js';
 
 // The same holds for characters that cannot be seen (zero-width characters,
 // soft hyphens, line separators, fillers), with which two different labels
@@ -54,6 +54,20 @@ export function readBlocks(text) {
   return { values: lines.filter((line) => /^[0-9a-fA-F]{64}$/.test(line)), bad: lines.filter((line) => !/^[0-9a-fA-F]{64}$/.test(line)) };
 }
 
+/**
+ * Read the box of page addresses, one to a line: the addresses at which the
+ * person expects the permissions to have been signed, each in the one form
+ * the format allows (https://, a website name in lower case, a port only if
+ * it is needed, and nothing more). As with the other boxes, a line that is
+ * not one is never dropped silently.
+ * @param {string} text
+ * @returns {{values: string[], bad: string[]}}
+ */
+export function readOrigins(text) {
+  const lines = String(text).split(/\s+/).filter((line) => line !== '');
+  return { values: lines.filter((line) => isPageAddress(line)), bad: lines.filter((line) => !isPageAddress(line)) };
+}
+
 /**
  * @param {unknown} text
  * @returns {string} the text, safe to place among other words
@@ -82,6 +96,17 @@ export function el(tag, className, text) {
 
 const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
 
+/**
+ * The heading of the card of the top fingerprint. It names the Seal only
+ * where the record holds one: a book, or the pages of a Show, with no seal
+ * has a top fingerprint and no seal.
+ * @param {{summary?: {counts?: {seals?: number}}}} result the checker's answer
+ * @returns {string}
+ */
+export function topFingerprintHeading(result) {
+  return (result?.summary?.counts?.seals ?? 0) > 0 ? 'The top fingerprint (the Seal)' : 'The top fingerprint';
+}
+
 /**
  * A time from a record, in words. The checker has already confirmed its
  * form; anything else is shown as it is.
@@ -625,7 +650,7 @@ export function renderResult(target, result, { isShow = false, checkedBy = 'Chec
 
   if (result.root) {
     const seal = el('div', 'card seal');
-    seal.append(el('h3', 'kind', 'The top fingerprint (the Seal)'));
+    seal.append(el('h3', 'kind', topFingerprintHeading(result)));
     const list = el('dl');
     row(list, 'Top fingerprint', result.root, true);
     row(list, 'Entries in the book', String(result.size));