provared 0.5.0 → 0.7.0

package/README.md

@@ -1,5 +1,7 @@
 # <img src="https://prova.red/favicon.svg" alt="" width="36"> Provared
 
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/provared/provared/badge)](https://scorecard.dev/viewer/?uri=github.com/provared/provared)
+
 Proof of what an AI agent was allowed to do, and what it then did.
 
 A person signs the permission with a passkey. The agent signs a receipt
@@ -86,6 +88,11 @@ agent = create_agent(model, tools=[order_supplies, send_message],
                      })])   # last among the middleware that wrap tool calls
 ```
 
+The package is listed among the middleware in
+[LangChain's own documentation](https://docs.langchain.com/oss/python/integrations/middleware).
+For JavaScript agents, [examples/frameworks/](examples/frameworks/) shows the
+same with the Vercel AI SDK, through `recordTools`.
+
 ## The four parts
 
 | Part | What it is |
@@ -125,7 +132,7 @@ each part protects against, is in
 
 - **[The guide](docs/guide.md)**: the whole library, in one document.
   Installing and importing; the command-line checker; what a slip can
-  say; seals, time-stamps and the chain of block headers; cancelling;
+  say; seals, time-stamps, witnesses and the chain of block headers; cancelling;
   who stands behind a name; covered fields; passing a slip on; the check
   before acting; the stub writer beside an agent and the connector for
   its tools; what the checker returns; what it never does; what is not
@@ -136,6 +143,14 @@ each part protects against, is in
 - **[The Python version](python/README.md)**, which gives the same
   answers, with examples for three agent frameworks and packages for
   two of them.
+- **Two programs beside an agent, each on npm with its own README:**
+  [the recorder beside Claude Code](integrations/claude-code/README.md)
+  (`npm install -g provared-claude-code`, also installable as a Claude
+  Code plugin), which checks and receipts every tool call Claude Code
+  makes; and [the executor for MCP tool servers](mcp-executor/README.md)
+  (`npm install -g provared-mcp-executor`), which stands between an
+  agent and its tool servers, holds their credentials, and countersigns
+  each receipt with keys of its own.
 - **[The pages at prova.red](https://prova.red/)**: the checker's answer
   for the sample record, a worked example for developers, and the same
   in plain words for a reader who does not write code.
@@ -156,9 +171,9 @@ each part protects against, is in
 
 ## Status
 
-**Version 0.5.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, built with AI tools since 3 October 2026; fixes as time
-allows. The code has been through 50 rounds of review by AI reviewers,
+allows. The code has been through more than 80 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.

package/bin/provared-check.mjs

@@ -1,9 +1,9 @@
 #!/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>]...
-//                  [--root <top fingerprint>] [--size <entries>] [--json]
+//                  [--seal <file>]... [--witness <fingerprint>]... [--root <top fingerprint>] [--size <entries>] [--json]
 //
 // Exit codes:
 //   0  the record is intact (no problem found, every signature checked),
@@ -20,7 +20,7 @@
 
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { 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,8 +29,9 @@ 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>]...
+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]
 
@@ -38,6 +39,9 @@ const USAGE = `Usage: provared-check <file> [--issuer <thumbprint>]... [--sealer
   --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;
@@ -47,6 +51,12 @@ const USAGE = `Usage: provared-check <file> [--issuer <thumbprint>]... [--sealer
   --cancellation   a JSON file of the person's own copy of a cancellation, as the entry it would be in a book:
                    {"cancellation": {...}, "stamps": [...]}. It counts even where the book leaves it out; may be repeated.
                    It may hold "acknowledgements": what the agent's side signed when it was handed the cancellation
+  --seal           a JSON file of a seal held elsewhere (by you, an auditor, a copy kept apart), as the entry it is in the book:
+                   {"seal": {...}, "stamps": [...]}. The book must hold that seal at the place it states: one that ends
+                   before it was cut short. It counts only with --sealer naming its recorder; may be repeated.
+                   It may hold "witnesses": statements that witnesses signed for that seal, such as ones that came later
+  --witness        the fingerprint of the key set of a witness you trust: a seal counts as witnessed only by such a
+                   witness. Being witnessed excuses nothing; may be repeated
   --root           the top fingerprint you already trust
   --size           the number of entries you already trust; keep it with the top fingerprint
   --headers        a file of Bitcoin block headers, as provared-headers keeps it. It is checked here, from the chain's
@@ -61,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', '--cancellation': 'cancellations' };
+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: [], cancellations: [], 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 };
@@ -82,10 +92,13 @@ function parseArguments(argv) {
       if (i + 1 >= argv.length) return { error: `${a} needs a value.` };
       const value = argv[++i];
       if (Object.hasOwn(ONCE, a) && out[ONCE[a]] !== undefined) return { error: `${a} may be given once.` };
-      if (['--issuer', '--sealer', '--stamp-service', '--voucher', '--root'].includes(a) && !FINGERPRINT.test(value)) {
+      if (['--issuer', '--sealer', '--stamp-service', '--voucher', '--witness', '--root'].includes(a) && !FINGERPRINT.test(value)) {
         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;
@@ -94,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', 'cancellations']) {
+    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) {
@@ -282,10 +295,22 @@ function printSeal(e) {
     console.log(`  Recorder's key set fingerprint:      ${e.sealer}`);
     printStamps(e.stamps);
     if (e.stamps.length === 0) console.log('  No outside time-stamp: the time is only the recorder\'s own word.');
+    printWitnesses(e.witnesses);
   }
   if (e.signatures && e.signatures.length) console.log(`  Recorder's signatures: ${e.signatures.map((s) => `${s.method} ${s.state}`).join('; ')}`);
 }
 
+// The witness statements beside a seal. What a statement says is shown only where it passed its check.
+function printWitnesses(list) {
+  for (const w of list ?? []) {
+    if (w.state === 'invalid') console.log('  Witness statement, NOT USED: it did not pass its check (see the problems)');
+    else if (w.state === 'unavailable') console.log('  Witness statement, NOT CHECKED: this device cannot check both of its signatures');
+    else if (w.counted) console.log(`  WITNESSED by ${label(w.name)} (a label), a witness you named as trusted (key set ${w.witness}), at ${w.when} (the witness's own word)`);
+    else if (w.trusted) console.log(`  Witness statement, NOT COUNTED: from a witness you named as trusted (key set ${w.witness}), but it was not counted (see the notes beside the seal)`);
+    else console.log(`  Witness statement, NOT COUNTED: from a witness you did not name as trusted (key set ${w.witness})`);
+  }
+}
+
 function printCancellation(e) {
   console.log(`\nEntry ${e.index}: CANCELLATION ${e.fingerprint ?? ''}`);
   if (hidden(e)) console.log(hidden(e));
@@ -313,8 +338,53 @@ function printAcknowledgement(e) {
   if (e.signatures && e.signatures.length) console.log(`  Agent's signatures: ${e.signatures.map((s) => `${s.method} ${s.state}`).join('; ')}`);
 }
 
+// A denial: the agent's own side says it did not take an action, and why.
+function printDenial(e) {
+  console.log(`\nEntry ${e.index}: DENIAL ${e.fingerprint ?? ''}`);
+  if (hidden(e)) console.log(hidden(e));
+  else {
+    const c = e.content;
+    const amount = c.amount ? `, ${c.amount.value} ${safe(c.amount.unit)}` : '';
+    const service = c.with ? `, with [${safe(c.with)}]` : '';
+    console.log(`  ${c.pass ? `The helper agent of pass ${c.pass}` : 'The slip\'s own agent'} states that it did not take an action`);
+    console.log(`  Under slip ${c.slip}`);
+    console.log(`  ${c.when} (the agent's side's own word): not taken ${safe(c.action)}${amount}${service}`);
+    if (c.details) console.log(`  Documents named: ${c.details.length}, by their fingerprints only`);
+    console.log(`  Who said no: ${DENIAL_SOURCES[c.source]}`);
+    if (c.codes) console.log(`  Reasons given: ${c.codes.join(', ')}`);
+    console.log('  This shows what the agent\'s side said. It is not counted against the agent, and it does not show that the action was not taken in some other way.');
+  }
+  if (e.signatures && e.signatures.length) console.log(`  Agent's signatures: ${e.signatures.map((s) => `${s.method} ${s.state}`).join('; ')}`);
+}
+
+// A seal held elsewhere, handed over beside the book.
+function printHeldSeal(h, n) {
+  console.log(`\nHanded over beside the book, ${n}: SEAL HELD ELSEWHERE ${h.fingerprint ?? ''}`);
+  if (h.problems.length) {
+    console.log('  It did not pass its check, so it was not used. See the problems at the top.');
+    return;
+  }
+  // What a seal says is shown only where this device checked at least one of its signatures.
+  if (h.verified === 'none') {
+    console.log('  What this seal says is not shown, because this device could not check its signatures.');
+    for (const n of h.notes) console.log(`  Note: ${n}`);
+    return;
+  }
+  const c = h.content;
+  console.log(`  Covers the first ${c.size} entries, with the top fingerprint ${c.root}, and stands at entry ${h.place}`);
+  console.log(`  Sealed at (the recorder's own word): ${c.when}`);
+  console.log(`  Recorder:                            ${label(c.by.name)} (a label, not checked)`);
+  console.log(`  Recorder's key set fingerprint:      ${h.sealer}`);
+  printStamps(h.stamps);
+  printWitnesses(h.witnesses);
+  console.log(h.used ? (h.inBook === null ? '  In the book at that place: NO' : `  In the book at that place: yes, at entry ${h.inBook}`) : '  In the book at that place: not compared, because it was not used');
+  console.log(`  Recorder's signatures: ${h.signatures.map((s) => `${s.method} ${s.state}`).join('; ')}`);
+  for (const n of h.notes) console.log(`  Note: ${n}`);
+}
+
 // A cancellation the person kept, handed over beside the book.
 function printHeld(h, n) {
+  if (h.kind === 'seal') return printHeldSeal(h, n);
   console.log(`\nHanded over beside the book, ${n}: CANCELLATION ${h.fingerprint ?? ''}`);
   if (h.problems.length) {
     console.log('  It did not pass its check, so it was not used. See the problems at the top.');
@@ -403,6 +473,7 @@ function print(result, isShow) {
     else if (e.kind === 'seal') printSeal(e);
     else if (e.kind === 'cancellation') printCancellation(e);
     else if (e.kind === 'acknowledgement') printAcknowledgement(e);
+    else if (e.kind === 'denial') printDenial(e);
     else if (e.kind === 'pass') printPass(e);
     else if (e.kind === 'vouching') printVouching(e);
     else if (e.kind === 'withdrawal') printWithdrawal(e);
@@ -436,7 +507,13 @@ function print(result, isShow) {
   if (!s.problemFound) {
     const stamped = s.sealed ? `yes: the first ${s.sealed.entries} entries existed by ${s.sealed.when}` : 'no';
     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}` : ''}`);
   if (s.counts.cancellations || s.counts.acknowledgements || s.counts.vouchings || s.counts.passes) {
@@ -445,15 +522,39 @@ function print(result, isShow) {
   if (s.counts.approved || s.counts.refusals || s.counts.terms) {
     console.log(`  Approved by the person ${s.counts.approved}, refusals ${s.counts.refusals}, terms for agents ${s.counts.terms}`);
   }
+  if (s.counts.denials) console.log(`  Denials (the agent's side's own word, not counted against it) ${s.counts.denials}`);
   console.log('\nWhat this check does not show');
   for (const l of s.limits) console.log(`  - ${l}`);
 }
 
 // Whether the check rests on keys the person named: the passkey they trust
-// and, where the record has a seal, the recorder they expect. Without them a
-// record agrees only with the keys inside it, which anyone could have made.
+// and, where the record has a seal or seals held elsewhere were handed over,
+// the recorder they expect. Without them a record agrees only with the keys
+// inside it, which anyone could have made, and a seal handed over is not
+// compared with the book.
 function named(s) {
-  return args.issuerKeys.length > 0 && (s.counts.seals === 0 || args.sealKeys.length > 0);
+  return args.issuerKeys.length > 0 && ((s.counts.seals === 0 && args.seals.length === 0) || args.sealKeys.length > 0);
+}
+
+// How far a witness the person named reaches. It excuses nothing, and is not needed for exit code 0.
+function witnessedWords(s) {
+  if (!s.witnessed) return args.witnesses.length ? 'no' : 'no (you named no witness you trust, --witness)';
+  const w = s.witnessed;
+  return `yes: the seal at entry ${w.seal}, which covers the first ${w.entries} entries (${w.seals.length} of ${s.counts.seals} seals witnessed)`;
+}
+
+// Whether the seals held elsewhere that were handed over were compared with the book.
+function heldWords(result) {
+  if (args.sealKeys.length === 0) return 'NO: you named no recorder you expect (--sealer), so the seals handed over were not compared with the book. This is not a pass.';
+  const seals = (result.held ?? []).filter((h) => h.kind === 'seal');
+  const used = seals.filter((h) => h.used).length;
+  return used === seals.length ? 'yes' : `NO: ${seals.length - used} of ${seals.length} handed over were not compared with the book (see the note beside each one). This is not a pass.`;
+}
+
+// Whether every seal handed over beside the book was compared with it. One that was not (it gives another book
+// number, or could not be used) gives no pass, as one handed over with no recorder named does not.
+function heldAllCompared(result) {
+  return (result.held ?? []).filter((h) => h.kind === 'seal').every((h) => h.used);
 }
 
 function trustWords(s) {
@@ -461,6 +562,7 @@ function trustWords(s) {
   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.';
+  if (s.counts.seals === 0) return `NO: you named ${passkeys}, but no recorder you expect (--sealer) for the seals handed over beside the book. 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.';
 }
 
@@ -516,10 +618,12 @@ 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;
 if (args.vouchers.length) options.vouchers = args.vouchers;
+if (args.witnesses.length) options.witnesses = args.witnesses;
 if (args.disclosures !== undefined) {
   try {
     options.disclosures = JSON.parse(readFileSync(args.disclosures, 'utf8'));
@@ -539,6 +643,17 @@ if (args.cancellations.length) {
     }
   }
 }
+if (args.seals.length) {
+  options.seals = [];
+  for (const file of args.seals) {
+    try {
+      options.seals.push(JSON.parse(readFileSync(file, 'utf8')));
+    } catch {
+      console.error(`The file of a seal could not be read: ${file}`);
+      process.exit(2);
+    }
+  }
+}
 if (args.expectedRoot !== undefined) options.expectedRoot = args.expectedRoot;
 if (args.expectedSize !== undefined) options.expectedSize = args.expectedSize;
 
@@ -594,7 +709,7 @@ try {
     if (chain) printChain(chain, fromChain);
   }
   const s = result.summary;
-  code = s.problemFound ? 2 : s.intact && s.withinSlips && named(s) ? 0 : 1;
+  code = s.problemFound ? 2 : s.intact && s.withinSlips && named(s) && heldAllCompared(result) ? 0 : 1;
 } catch {
   // The checker is written never to throw. If it ever does, that is not a pass.
   console.error('The check could not be completed. This is not a pass.');