provared 0.4.0 → 0.6.0

package/README.md

@@ -86,6 +86,9 @@ 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).
+
 ## The four parts
 
 | Part | What it is |
@@ -125,7 +128,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
@@ -156,9 +159,9 @@ each part protects against, is in
 
 ## Status
 
-**Version 0.4.0, a draft.** Published as it is, by one author in their
+**Version 0.6.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 40 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

@@ -3,7 +3,7 @@
 //
 //   provared-check <file> [--issuer <thumbprint>]... [--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, 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.
@@ -31,7 +31,8 @@ process.on('warning', (w) => {
 
 const USAGE = `Usage: provared-check <file> [--issuer <thumbprint>]... [--sealer <fingerprint>]... [--stamp-service <fingerprint>]...
                       [--block <fingerprint>]... [--voucher <fingerprint>]... [--disclosures <file>] [--cancellation <file>]...
-                      [--root <top fingerprint>] [--size <entries>] [--headers <file>] [--json]
+                      [--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)
@@ -47,6 +48,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 +68,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', '--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: [], 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,7 +89,7 @@ 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.' };
@@ -94,7 +101,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', '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 +289,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 +332,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 +467,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 +501,9 @@ 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)}`);
+    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 +512,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 +552,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.';
 }
 
@@ -520,6 +612,7 @@ 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 +632,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 +698,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.');