@sanning/proof 0.11.1 → 0.13.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

@@ -12,7 +12,7 @@
 // gateway/transport concerns are consumer-layer logic composed above it.
 
 // ACCEPTED_SPEC_MAJORS is exported for parity with the sibling kernels'
-// registries (Python ACCEPTED_SPEC_VERSIONS, Go SupportedSpecMajor): a consumer
+// registries (Python ACCEPTED_SPEC_MAJORS, Go SupportedSpecMajor): a consumer
 // can see which profiles this build admits without inferring it from probe
 // calls. It is frozen at its definition (`Object.freeze`, typed
 // `readonly string[]`) because the verifier reads that same array — an exported
@@ -60,6 +60,7 @@ export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions
 // bytes, and only for events whose verification bound them to the committed
 // content_hash. Additive; verifyEvidenceBundle's behavior is unchanged.
 export {
+  ACCEPTED_EVIDENCE_MAJORS,
   ANCHOR_TRACE_BODY_TYPE,
   EXPORT_BODY_TYPE,
   STAMP_BODY_VERSION,
@@ -128,6 +129,8 @@ export type {
 // derivation to it, and diff its copy against ours. Additive — no existing
 // export changes.
 export {
+  PACK_GRADE_CAUSE_KINDS,
+  PACK_VERDICTS,
   accountDisclosure,
   completenessNotes,
   gradeCauses,
@@ -162,7 +165,14 @@ export type {
 // optional fourth argument, so a surface gets one verdict; omitting it is the
 // pre-§5.4 behavior, unchanged. Additive: no existing export changes.
 export {
+  DECLARATION_CONTENT_KINDS,
+  DECLARATION_DEVIATION_KINDS,
+  DECLARATION_NOTE_KINDS,
+  DECLARATION_ROLES,
+  DECLARATION_VERDICTS,
   DECLARATION_VERSION,
+  DECLARATION_VERSION_V2,
+  DECLARATION_VERSIONS,
   checkDeclaration,
   declarationClaims,
   packRecords,
@@ -180,6 +190,7 @@ export type {
   DeclarationDeviationKind,
   DeclarationNote,
   DeclarationNoteKind,
+  DeclarationRole,
   DeclarationVerdict,
   PackRecord,
 } from "./declaration.js";
@@ -193,7 +204,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).
@@ -205,20 +217,53 @@ export {
   CASE_EXCEPTION_KINDS,
   CASE_QUARANTINED_PROFILES,
   CASE_RECORD_PROFILES,
+  CASE_NOTE_KINDS,
+  CASE_RELIANCE,
   CASE_VERDICTS,
+  CONTENT_WITHHELD_BY_DECLARATION,
+  VERDICT_DISPLAY_TITLES,
+  WITNESS_NOT_LOOKED_UP,
+  WITNESS_STATES,
   readCase,
+  renderCaseNote,
   renderCaseSummary,
   renderException,
+  renderWitnessLine,
 } from "./case.js";
 export type {
   CaseException,
   CaseExceptionKind,
+  CaseNote,
+  CaseNoteKind,
   CasePack,
+  CasePackReading,
   CaseReading,
   CaseRecordReading,
   CaseVerdict,
+  WitnessLine,
+  WitnessState,
 } from "./case.js";
 
+// The case file's index (src/case-file.ts, evidence-bundle.md §5.6, A25):
+// compared with the drop it describes, with NO verdict contribution. The index
+// is never an input to `readCase`. Pure: bytes and a file list in.
+export {
+  CASE_FILE_FINDING_KINDS,
+  CASE_FILE_INDEX_NAME,
+  CASE_FILE_VERSION,
+  HOW_TO_VERIFY_NAME,
+  REPORT_README_FIRST_LINE,
+  howToVerifyText,
+  isPackRef,
+  readCaseFileIndex,
+  renderCaseFileFinding,
+} from "./case-file.js";
+export type {
+  CaseFileFinding,
+  CaseFileFindingKind,
+  CaseFileIndexReading,
+} from "./case-file.js";
+
 // Chain reading (src/chain.ts): following the pointer every sanning.events/v2
 // record carries to the record before it, over the records ONE bundle presents.
 //
@@ -257,13 +302,25 @@ export type {
 // signed, offline-verifiable sanning.evidence.export/v2 artifact from a source
 // anchor-trace bundle + operator attestations + an exporter Ed25519 key. The
 // inverse of verifyEvidenceBundle's verifyExportBody dispatch.
+// One exit-code table for every verb (0.13.0): the verdict word to the exit
+// code, and the help text every verb prints. Additive.
+export {
+  EXIT_CODES,
+  EXIT_CODES_HELP,
+  EXIT_FAILED,
+  EXIT_MALFORMED,
+  EXIT_MIXED,
+  EXIT_UNDETERMINED,
+  EXIT_VERIFIED,
+  exitCodeFor,
+} from "./exit-codes.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 
 // Agent inclusion-proof bundle verification: the
 // sanning.agent.proof/v1 bundle. The CLI sniffs spec_version and routes here so
 // one verifier covers both agent and anchor bundles.
-export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+export { AGENT_PROOF_SPEC_VERSION, isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 export type {
   AgentProofBundle,
   AgentProofResult,

package/src/message-parts.ts

@@ -278,17 +278,19 @@ const HELD_UNCHECKED_RESULTS: readonly string[] = [
 
 /**
  * The keys that make a part carry its content INLINE, in the order they are
- * read. Named rather than inferred: `bytes` is A2A's spelling of an inline file
- * part, and `data` and `content` are the two other spellings in the wild. The
- * FIRST of them present with a value that is not `null` is the inline content,
- * so a part spelling it twice reads one way in both kernels.
+ * read. Named rather than inferred: `bytes`, `data` and `content` are the
+ * spellings in the wild. None is A2A 1.0.0's: its `Part` has no `kind` and
+ * carries a file as `raw` or `url`, so a literal A2A part reads
+ * `part_not_a_file` (envelope-spec §4.1, A19). The FIRST of them present with
+ * a value that is not `null` is the inline content, so a part spelling it
+ * twice reads one way in both kernels.
  *
  * A key present with `null` is an ABSENT inline value, on A14's ruling that an
- * absent value and one written as `null` name one thing. That matters: an A2A
- * `FilePart` with `uri` set carries `"bytes": null`, and so does proto3 JSON,
- * and reading those as inline made a conformant DESCRIPTOR part uncheckable
- * (proof#156 gate). They fall through to the descriptor rule, which is what
- * they are.
+ * absent value and one written as `null` name one thing. That matters: a
+ * proto3 JSON encoder can write an unset field as `"bytes": null`, and reading
+ * that as inline made a conformant DESCRIPTOR part uncheckable
+ * (proof#156 gate). Such a part falls through to the descriptor rule, which is
+ * what it is.
  */
 // A conformant DESCRIPTOR part that also carries a `content` or `data` key
 // meaning something else (a filename, a metadata blob) is reclassified by this

package/src/types.ts

@@ -48,6 +48,11 @@ export interface VerifyOptions {
   // Content bind: the caller's own hash of an artifact (e.g. the in-browser
   // hash of a user's file) to match against the hashes the envelope commits to.
   expectedContentHash?: string;
+  // NARROWS the accept-set for this call and never widens it: the set used is
+  // `ACCEPTED_SPEC_MAJORS` intersected with this list, so a caller cannot
+  // admit a profile this kernel does not. The Python twin is
+  // `accepted_spec_majors` (P-10, 0.13.0).
+  acceptedSpecMajors?: readonly string[];
 }
 
 export interface VerificationResult {

package/src/verifier.ts

@@ -23,7 +23,7 @@ import type { ContentRole, Envelope, VerificationResult, VerifyOptions } from ".
 // profile-specific dialect (no underscore strip, that is mlflow-only).
 //
 // Exported for parity with the sibling kernels' registries — Python
-// `ACCEPTED_SPEC_VERSIONS`, Go `SupportedSpecMajor` — so the accept-set is
+// `ACCEPTED_SPEC_MAJORS`, Go `SupportedSpecMajor` — so the accept-set is
 // assertable rather than inferable: test/accept-set.test.ts holds it to the
 // ratified §4/§5 set transcribed in cross-kernel/accept-set.json, and the
 // cross-kernel gate probes one signed envelope per identifier. This entry list
@@ -231,6 +231,16 @@ const JCS_BOM = "";
  * Throws for anything that is not conformant; every call site treats a throw as
  * "this reader cannot read these bytes" and names the check that failed.
  */
+/**
+ * Bytes as strict UTF-8, a leading byte-order mark KEPT as a character.
+ * `utf8_strict` in the Python twin's `canonicalize.py` is the same rule, and
+ * `jcsParse` below performs the identical decode. Throws on bytes that are not
+ * UTF-8.
+ */
+export function utf8Strict(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+
 export function jcsParse(bytes: Uint8Array): unknown {
   const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
   if (text.startsWith(JCS_BOM)) throw new Error("jcsParse: leading byte-order mark");
@@ -311,9 +321,17 @@ function hasLoneSurrogate(s: string): boolean {
 // `<major>.<minor>` where minor is `[0-9]+`. A non-numeric minor suffix is
 // malformed, not a tolerated future version — matching the Python kernel's
 // 0.1.1 semantics (the TS/Go fail-open lenience was closed deliberately).
-export function specVersionSupported(specVersion: string): boolean {
+//
+// `accepted` NARROWS the registry and never widens it, as the Python twin's
+// `spec_version_supported(spec_version, accepted)` does (P-10, 0.13.0).
+export function specVersionSupported(
+  specVersion: string,
+  accepted?: readonly string[],
+): boolean {
   if (typeof specVersion !== "string" || specVersion === "") return false;
-  return ACCEPTED_SPEC_MAJORS.some((m) => {
+  const registry =
+    accepted === undefined ? ACCEPTED_SPEC_MAJORS : ACCEPTED_SPEC_MAJORS.filter((m) => accepted.includes(m));
+  return registry.some((m) => {
     if (specVersion === m) return true;
     if (!specVersion.startsWith(`${m}.`)) return false;
     const minor = specVersion.slice(m.length + 1);
@@ -456,22 +474,26 @@ export function contentHashes(env: Envelope): { role: ContentRole; hash: string
 // signature, so stripping it to fake "external" — or injecting one to fake
 // "inline" — breaks the signature).
 //
-// The second argument accepts the legacy `expectedContentHash` string form
-// or a VerifyOptions object ({ payloadBytes, expectedContentHash }).
+// The second argument is a VerifyOptions object ({ payloadBytes,
+// expectedContentHash, acceptedSpecMajors }). Until 0.13.0 it could also be a
+// bare `expectedContentHash` string; that overload is gone (P-10), so the two
+// kernels take one options shape: write `{ expectedContentHash: hash }`.
 export async function verifyEnvelope(
   env: Envelope,
-  optionsOrContentHash?: string | VerifyOptions,
+  options?: VerifyOptions,
 ): Promise<VerificationResult> {
-  const opts: VerifyOptions =
-    typeof optionsOrContentHash === "string"
-      ? { expectedContentHash: optionsOrContentHash }
-      : (optionsOrContentHash ?? {});
+  if (typeof options === "string") {
+    throw new TypeError(
+      "verifyEnvelope: pass { expectedContentHash } rather than a bare string (0.13.0)",
+    );
+  }
+  const opts: VerifyOptions = options ?? {};
   // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
   // — the Python kernel's spelling — previously fell through as `undefined`, so
   // the content bind silently never ran and the caller got a clean pass with no
   // errors at all. A check that quietly does not happen is worse than one that
   // fails: the caller believes they verified an artifact they never checked.
-  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash"]);
+  const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash", "acceptedSpecMajors"]);
   const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
   if (unknownOptions.length > 0) {
     throw new TypeError(
@@ -551,7 +573,7 @@ async function verifyEnvelopeChecked(
     };
   }
 
-  const specVersionOk = specVersionSupported(env.spec_version);
+  const specVersionOk = specVersionSupported(env.spec_version, opts.acceptedSpecMajors);
   if (!specVersionOk) errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
 
   // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
@@ -625,7 +647,7 @@ async function verifyEnvelopeChecked(
   let signatureOk = false;
   try {
     const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
-    signatureOk = await ed25519Verify(env.signature, utf8(jcs(envelopeForSig)), env.public_key);
+    signatureOk = await ed25519Verify(utf8(jcs(envelopeForSig)), env.signature, env.public_key);
     if (!signatureOk) errors.push("Ed25519 signature verification failed");
   } catch (e) {
     errors.push(`signature verification error: ${stringifyErr(e)}`);