@sanning/proof 0.11.1 → 0.12.0

package/src/handoff.ts

@@ -1,4 +1,4 @@
-// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.9).
+// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.17).
 //
 // Two agents exchange a message and each side records what it held. This module
 // is the TypeScript half of the reference reading of those two records: which
@@ -119,14 +119,23 @@
 // `not_a_handoff_record` are findings reported beside a verdict rather than
 // verdicts.
 //
-// THE COST OF GRADING EVERY CANDIDATE, stated rather than left to be found. A
-// reader whose pile holds two or more records of the complementary type signed
-// by the counterparty key can no longer reach `verified`: every one of them is
-// graded and the worst of them is the reading. Two agents that exchange more
-// than one message land there. That is the price of never letting a value the
-// audited party writes decide what reaches a check, and the belt is the pack
-// layer: the declaration (evidence-bundle.md 5.4) says which records a pack
-// claims are a pair.
+// THE COST OF GRADING EVERY CANDIDATE, AND THE ACCOUNTED-FOR RULE THAT PAYS
+// MOST OF IT (envelope-spec.md 4.1 v1.17, amendment A20). Grading every
+// candidate means the records of a party's OTHER exchanges are candidates too,
+// and they fail. Up to v1.16 that put `verified` out of reach for any two agents
+// that exchanged more than one message in one direction, and the declaration
+// named as the belt cannot be one: evidence-bundle.md 5.5 forbids the reading
+// to consult `handoffs[]` to pair anything. So a candidate that grades `failed`
+// is SET ASIDE from the subject's verdict, failed checks and ambiguity when,
+// and only when, the reader holds another record `o` that accounts for it
+// (`accountedFor` below): `o` is signed by the subject's own key and is the
+// subject's type; `o` names the candidate's signer and the candidate names the
+// subject's key back; `o`'s sequence differs from the subject's; and the
+// candidate grades `verified` against `o`. The candidate stays in `candidates`
+// and `candidateReadings`, with `accountedFor` set. Setting one aside needs a
+// verified pair with a record the OTHER side signed, so a tampered record
+// stays live. Fan-in, fan-out, and one pair in two cases at one sequence still
+// read `failed`: the Python half's module docstring says why.
 
 export const CANDIDATE_NAMESPACE = "handoff.";
 export const DEFINED_EVENT_TYPES = ["handoff.sent", "handoff.received"] as const;
@@ -315,6 +324,16 @@ export interface CandidateReading {
   ref: string;
   verdict: HandoffVerdict;
   failedChecks: string[];
+  /**
+   * The ref of the record that ACCOUNTS FOR this candidate, or `null` (4.1
+   * v1.17, A20). Set only on a candidate that graded `failed` and that the
+   * reader holds a verified pair for elsewhere; such a candidate is still
+   * reported here and takes no part in the subject's verdict, failed checks or
+   * ambiguity. Every reading this kernel returns carries it. It is optional in
+   * the type only so that code which builds a `CandidateReading` itself keeps
+   * compiling: the field is an addition.
+   */
+  accountedFor?: string | null;
 }
 
 export interface HandoffReading {
@@ -325,7 +344,12 @@ export interface HandoffReading {
   findings: string[];
   /** Ordered, never filtered. */
   candidates: string[];
-  /** One entry per candidate, in the same order, and nothing left out of it. */
+  /**
+   * One entry per candidate, in the same order, and nothing left out of it. A
+   * candidate another record accounts for is here with `accountedFor` set, and
+   * where every candidate is accounted for the reading is `counterpart_absent`
+   * with the candidates still listed.
+   */
   candidateReadings: CandidateReading[];
 }
 
@@ -620,23 +644,42 @@ export function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): H
   // and took none of them out of this list.
   const graded: CandidateReading[] = candidates.map((candidate) => {
     const { verdict, checks } = gradePair(subject, candidate);
-    return { ref: candidate.ref, verdict, failedChecks: checks };
+    const by = verdict === "failed" ? accountedFor(subject, candidate, held) : null;
+    return { ref: candidate.ref, verdict, failedChecks: checks, accountedFor: by };
   });
-  const worst = Math.max(...graded.map((g) => VERDICT_RANK[g.verdict]));
+
+  // The verdict, the failed checks and the ambiguity are taken over the
+  // candidates nothing accounts for. The others stay in the report.
+  const live = graded.filter((g) => g.accountedFor === null);
+  if (live.length === 0) {
+    // Every candidate is another exchange's record, each proven so by a
+    // verified pair with a record the subject's own key signed: an absence,
+    // reported with the candidates it looked at.
+    return {
+      ref: subject.ref,
+      verdict: null,
+      failedChecks: [],
+      findings: ["counterpart_absent"],
+      candidates: candidates.map((c) => c.ref),
+      candidateReadings: graded,
+    };
+  }
+  const worst = Math.max(...live.map((g) => VERDICT_RANK[g.verdict]));
   const verdict = (Object.keys(VERDICT_RANK).find(
     (name) => VERDICT_RANK[name] === worst,
   ) as HandoffVerdict)!;
 
-  // Over every candidate, not only the ones at the winning verdict: `malformed`
-  // outranks `failed`, so a single junk record would otherwise strip the named
-  // `message_hash` failure out of the report (proof#133 review, ruling 6).
+  // Over every live candidate, not only the ones at the winning verdict:
+  // `malformed` outranks `failed`, so a single junk record would otherwise
+  // strip the named `message_hash` failure out of the report (proof#133
+  // review, ruling 6).
   const failed = new Set<string>();
-  for (const g of graded) for (const check of g.failedChecks) failed.add(check);
+  for (const g of live) for (const check of g.failedChecks) failed.add(check);
 
   const findings: string[] = [];
   // Never a free choice: a reader permitted to take one match can be handed an
   // honest decoy beside a tampered record.
-  if (candidates.length > 1) findings.push("counterpart_ambiguous");
+  if (live.length > 1) findings.push("counterpart_ambiguous");
   if (verdict === "malformed") findings.push("malformed_record");
 
   return {
@@ -649,6 +692,54 @@ export function readHandoff(subject: HeldRecord, held: readonly HeldRecord[]): H
   };
 }
 
+/**
+ * The ref of the record that accounts for a FAILED candidate, or `null` (4.1
+ * v1.17, A20). The candidate is another exchange's record, and not a deviation
+ * on this one, only where the reader holds a record `o`, other than the
+ * subject, for which all four hold:
+ *
+ *   1. `o` is signed by the SUBJECT's own key, and is the subject's type;
+ *   2. `o` names the candidate's signer, and the candidate names the subject's
+ *      key back;
+ *   3. `o`'s `sequence` differs from the subject's;
+ *   4. the candidate grades `verified` against `o`.
+ *
+ * Condition 1 is what the audited party cannot supply: a verified pair needs
+ * the OTHER side's signature over the digest and the number. Condition 3 is
+ * the position guard (proof#129): a second record at the subject's own number
+ * is a second claim about the subject's message. The first `o` in the order
+ * the records are held is reported, so two kernels name one record. The
+ * Python half, `_accounted_for`, carries the full reasoning.
+ */
+function accountedFor(
+  subject: HeldRecord,
+  candidate: HeldRecord,
+  held: readonly HeldRecord[],
+): string | null {
+  const own = normalizedSigningKey(subject.publicKey);
+  const theirs = normalizedSigningKey(candidate.publicKey);
+  // Condition 2: the candidate names the subject's key back.
+  if (normalizedSigningKey(section(candidate.record, "event").counterparty_public_key) !== own) {
+    return null;
+  }
+  const subjectSequence = section(subject.record, "event").sequence;
+  for (const other of held) {
+    if (other === subject) continue;
+    // Condition 1: signed by the subject's own key, of the subject's own type.
+    if (normalizedSigningKey(other.publicKey) !== own) continue;
+    if (eventType(other) !== eventType(subject)) continue;
+    // Condition 2: o names the candidate's signer.
+    if (normalizedSigningKey(section(other.record, "event").counterparty_public_key) !== theirs) {
+      continue;
+    }
+    // Condition 3: another position than the subject's.
+    if (sameNumber(section(other.record, "event").sequence, subjectSequence)) continue;
+    // Condition 4: a verified pair.
+    if (gradePair(other, candidate).verdict === "verified") return other.ref;
+  }
+  return null;
+}
+
 /**
  * EVERY record the reader holds gets a reading, in the order given.
  *

package/src/index.ts

@@ -193,7 +193,8 @@ export type {
 // because the omission happens before any reader runs. Reading several parties'
 // packs at once is what closes it: a `handoff.sent` with no counterpart is
 // always named, and where a pack signed by the key it names is in the case, the
-// reading says that pack holds no counterpart. Whether a party that presented
+// reading says that pack holds no counterpart (unless every candidate was
+// accounted for under A20, which reads as no counterpart and names no pack). Whether a party that presented
 // no such pack recorded anything is not established (proof#143). `readCase`
 // verifies every pack itself, offline, so it is async. Matching is on keys and hashes alone and NEVER on tenancy, so a pair from two
 // organizations verifies (DL-60).

package/vectors/README.md

@@ -117,3 +117,38 @@ happened, and the reason this file moved here.
 Nothing in a case names a transport. A directory read and a browser drop produce
 the same account and must produce the same verdict; a table that encoded one
 surface's mechanism would let the other one drift while staying green.
+
+## `case-split.json`
+
+How `case` turns the folders it was handed into packs: the verify page's
+splitting rule (`sanning-io/verify-page` `src/lib/case.ts` `splitCase`,
+`src/lib/pack.ts` `assemble`) over a walk whose rules are the command's own,
+restated in [`../src/cli.ts`](../src/cli.ts) and `src/sanning_proof/cli.py`
+because the page's code lives in the page. Two tables and the limits:
+
+- `trees`: a directory tree to create (files, folders, symbolic links, a name
+  given as bytes, or a folder filled with N empty files), the arguments, and
+  the packs, the outside paths and the paths that are not regular files, or
+  the refusal. The rows include the decision file unpacked, a symbolic link
+  under `logs/`, each side of the depth and entry limits, and names that are
+  not UTF-8.
+- `parses`: how `bundle.json` bytes become JSON through the reader `verify`
+  and `case` share, including each side of the nesting limit.
+- `limits`: the walk depth (32), the entry count (50,000) and the JSON nesting
+  depth (512), which both kernels assert they state.
+
+Asserted by [`../test/case-cli.test.ts`](../test/case-cli.test.ts) **and by
+the Python kernel against the same trees**, in `tests/test_case_cli.py`, and
+run through both commands by `cross-kernel/run_case_cli.sh`.
+
+Every expectation is a literal written in
+`tools/gen-vectors/gen_case_split_vectors.py`, not the output of either
+kernel. The splitting rows were graded against the page's own code when the
+table was first written. The walk rows (links, depth, entry count, names, a
+`.zip` argument) and the reader rows are the command's own rules, and the page
+does not share them: it opens a dropped `.zip`, drops a leading byte-order
+mark, and reads whatever the browser hands it for a link, a bad name or a deep
+tree. One splitting row disagrees with the page on purpose: `record-file-names` keeps
+a record named `__proto__`, which the page's `assemble` loses because it keys
+disclosed content by a plain object. A page that vendors this table fails that
+row until it keys content by a `Map`.