@sanning/proof 0.15.0 → 0.16.0

package/dist/declaration.d.ts

@@ -60,7 +60,7 @@ export interface DeclarationContentFinding {
     eventId?: string;
 }
 /** Everything this check reports that is NOT a deviation, as a closed set. */
-export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld"];
+export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld", "other_declaration_held", "other_declaration_withheld"];
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 /**
  * One named non-deviation finding, as data.

package/dist/declaration.js

@@ -130,10 +130,10 @@
 // The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
 // byte-order mark, no non-finite literal. `jcs_loads` in
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
-import { hexToBytes } from "./crypto.js";
-import { jcsParse } from "./verifier.js";
+import { hexToBytes, utf8 } from "./crypto.js";
+import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
-import { hasSideContent, inBodyContentOffered } from "./side-content.js";
+import { hasSideContent, inBodyContentOffered, sideContentEntry, } from "./side-content.js";
 /** The first declaration schema, which every earlier reader knows. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
 /**
@@ -255,6 +255,23 @@ export const DECLARATION_NOTE_KINDS = [
      * because its payload binding is undetermined.
      */
     "role_step_withheld",
+    /**
+     * Rule 10 (v1.29, A36). A record whose signed `event_type` is `declaration`
+     * and whose content HANDED IN to this reader is exactly `JCS(object)` of a
+     * declaration object of a version this reader knows, carrying exactly that
+     * version's keys, and not this pack's own. The note names the content handed
+     * in, never the record: whether those bytes bind to the record's
+     * `content_hash` is the bundle verifier's check, and an accuser can hand in
+     * declaration-shaped bytes for an honest record. What the pack holds is what
+     * the declaration in its body says, so this moves no verdict.
+     */
+    "other_declaration_held",
+    /**
+     * Rule 10. A record whose signed `event_type` is `declaration` and whose
+     * content did not reach this reader from either channel, so whether it is a
+     * declaration other than this pack's own is UNKNOWN.
+     */
+    "other_declaration_withheld",
 ];
 /**
  * The record committed inside one `events[]` entry, or `null`.
@@ -500,6 +517,155 @@ function roleReading(p, role, claimed) {
     }
     return null;
 }
+/**
+ * The `event_type` a declaration record is signed under: a reserved
+ * single-segment name, and the one `@sanning/anchor`'s `bundle` anchors a
+ * declaration as.
+ */
+const DECLARATION_EVENT_TYPE = "declaration";
+/**
+ * The keys a declaration object carries, under every version this reader
+ * knows: exactly these, no more and no fewer (5.4.1).
+ */
+const DECLARATION_KEYS = ["declaration_version", "case_id", "agents", "period", "records", "handoffs"];
+function hasExactKeys(value, keys) {
+    if (!isObject(value))
+        return false;
+    const have = Object.keys(value);
+    return have.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+/**
+ * Whether `obj` is shaped like a declaration this reader knows: one of
+ * `DECLARATION_VERSIONS` compared exactly, exactly the keys that version
+ * defines, and the value types this module reads.
+ *
+ * It is the shape test `@sanning/anchor`'s `isDeclarationShape` makes, and it
+ * checks shape only, not the 5.4.1 rules `readDeclaration` grades: a stale
+ * declaration is somebody else's claim, and this reader does not grade it, it
+ * names it.
+ */
+function isDeclarationShape(obj) {
+    if (!isObject(obj))
+        return false;
+    const version = obj["declaration_version"];
+    if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2)
+        return false;
+    if (!hasExactKeys(obj, DECLARATION_KEYS))
+        return false;
+    if (!isId(obj["case_id"]))
+        return false;
+    const agents = obj["agents"];
+    if (!Array.isArray(agents) || !agents.every((a) => typeof a === "string"))
+        return false;
+    const period = obj["period"];
+    if (!hasExactKeys(period, ["start", "end"]))
+        return false;
+    if (typeof period["start"] !== "string" || typeof period["end"] !== "string")
+        return false;
+    const recordKeys = version === DECLARATION_VERSION_V2 ? ["event_id", "disclosure", "role"] : ["event_id", "disclosure"];
+    const records = obj["records"];
+    if (!Array.isArray(records))
+        return false;
+    for (const r of records) {
+        if (!hasExactKeys(r, recordKeys) || typeof r["event_id"] !== "string")
+            return false;
+    }
+    const handoffs = obj["handoffs"];
+    if (!Array.isArray(handoffs))
+        return false;
+    return handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]));
+}
+/**
+ * The content bytes disclosed for one record, or `null` where none are usable:
+ * `events[].content` first, then the side-content map, chosen the way the
+ * bundle verifier chooses the bytes it binds.
+ */
+function disclosedBytes(ev, p, content) {
+    const inBody = isObject(ev) ? ev["content"] : undefined;
+    if (typeof inBody === "string") {
+        try {
+            return hexToBytes(inBody);
+        }
+        catch {
+            // falls through to the side channel, as the bundle verifier does
+        }
+    }
+    if (!p.nameable)
+        return null;
+    const side = sideContentEntry(content, p.eventId).value;
+    if (side instanceof Uint8Array)
+        return side;
+    if (typeof side === "string") {
+        try {
+            return hexToBytes(side);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Whether `raw` is exactly `JCS(object)` of a declaration-shaped object.
+ * Canonical bytes, not merely parseable ones: a declaration is anchored as
+ * `JCS(declaration)`, and nothing an agent writes by accident.
+ */
+function isDeclarationBytes(raw) {
+    try {
+        const obj = jcsParse(raw);
+        return isDeclarationShape(obj) && sameBytes(utf8(jcs(obj)), raw);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Rule 10: every record that is a declaration other than the pack's own, in
+ * bundle order.
+ *
+ * The record's `event_type` is read from its signed `event_bytes`, so a record
+ * whose bytes the pack withholds is not named: the reader cannot see what it
+ * was signed as. Its content is read from either channel; a record whose
+ * content is byte for byte `JCS` of the pack's own declaration is the pack's
+ * own and is never named.
+ */
+function otherDeclarationNotes(bundle, pack, declaration, content) {
+    const events = pack.length > 0 ? (bodyOf(bundle)?.events ?? []) : [];
+    let own = null;
+    try {
+        own = utf8(jcs(declaration));
+    }
+    catch {
+        own = null;
+    }
+    const notes = [];
+    pack.forEach((p, i) => {
+        if (p.record === null || p.record.event_type !== DECLARATION_EVENT_TYPE)
+            return;
+        const raw = disclosedBytes(events[i], p, content);
+        if (raw === null) {
+            // Offered and unusable is not withheld: something arrived, it is not a
+            // declaration, and the bundle verifier names what is wrong with it.
+            // Nothing arrived is the reading the reader cannot settle.
+            if (!p.disclosed)
+                notes.push({ kind: "other_declaration_withheld", eventId: p.eventId });
+            return;
+        }
+        if (own !== null && sameBytes(raw, own))
+            return;
+        if (isDeclarationBytes(raw))
+            notes.push({ kind: "other_declaration_held", eventId: p.eventId });
+    });
+    return notes;
+}
 /**
  * Check a pack against the declaration inside its body.
  *
@@ -719,6 +885,11 @@ export function checkDeclaration(bundle, content) {
                 deviations.push({ kind, eventId });
         }
     }
+    // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
+    // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
+    // never a deviation: the pack holds what its own declaration says whatever
+    // one of its records says.
+    notes.push(...otherDeclarationNotes(bundle, pack, declaration, content));
     // A proven deviation wins: it is a mismatch between what the pack claimed
     // and what its own signed body carries, and a failing check always wins.
     // With no deviation and a content-dependent finding, the pack lines up with
@@ -838,6 +1009,14 @@ export function renderNote(note) {
         case "role_step_withheld":
             return (`${note.eventId} is signed as a step and this pack withholds its ` +
                 "record bytes, so whether it is one is UNKNOWN");
+        case "other_declaration_held":
+            return (`the content handed in for ${note.eventId} is a declaration that is ` +
+                "not this pack's own: it says what some pack holds, and what this " +
+                "pack holds is what the declaration in its body says");
+        case "other_declaration_withheld":
+            return (`${note.eventId} is signed as a declaration and no content for it ` +
+                "reached this verifier, so whether it is a declaration other than " +
+                "this pack's own is UNKNOWN");
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1 and sanning.events/v2. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
   "devDependencies": {
     "@types/node": "^20.19.41",
     "typescript": "^5.4.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"

package/src/declaration.ts

@@ -131,10 +131,15 @@
 // The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
 // byte-order mark, no non-finite literal. `jcs_loads` in
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
-import { hexToBytes } from "./crypto.js";
-import { jcsParse } from "./verifier.js";
+import { hexToBytes, utf8 } from "./crypto.js";
+import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace, type HandoffRecord } from "./handoff.js";
-import { hasSideContent, inBodyContentOffered, type SideContentMap } from "./side-content.js";
+import {
+  hasSideContent,
+  inBodyContentOffered,
+  sideContentEntry,
+  type SideContentMap,
+} from "./side-content.js";
 
 /** The first declaration schema, which every earlier reader knows. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
@@ -278,6 +283,23 @@ export const DECLARATION_NOTE_KINDS = [
    * because its payload binding is undetermined.
    */
   "role_step_withheld",
+  /**
+   * Rule 10 (v1.29, A36). A record whose signed `event_type` is `declaration`
+   * and whose content HANDED IN to this reader is exactly `JCS(object)` of a
+   * declaration object of a version this reader knows, carrying exactly that
+   * version's keys, and not this pack's own. The note names the content handed
+   * in, never the record: whether those bytes bind to the record's
+   * `content_hash` is the bundle verifier's check, and an accuser can hand in
+   * declaration-shaped bytes for an honest record. What the pack holds is what
+   * the declaration in its body says, so this moves no verdict.
+   */
+  "other_declaration_held",
+  /**
+   * Rule 10. A record whose signed `event_type` is `declaration` and whose
+   * content did not reach this reader from either channel, so whether it is a
+   * declaration other than this pack's own is UNKNOWN.
+   */
+  "other_declaration_withheld",
 ] as const;
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 
@@ -698,6 +720,149 @@ function roleReading(
   return null;
 }
 
+/**
+ * The `event_type` a declaration record is signed under: a reserved
+ * single-segment name, and the one `@sanning/anchor`'s `bundle` anchors a
+ * declaration as.
+ */
+const DECLARATION_EVENT_TYPE = "declaration";
+
+/**
+ * The keys a declaration object carries, under every version this reader
+ * knows: exactly these, no more and no fewer (5.4.1).
+ */
+const DECLARATION_KEYS = ["declaration_version", "case_id", "agents", "period", "records", "handoffs"];
+
+function hasExactKeys(value: unknown, keys: string[]): value is Record<string, unknown> {
+  if (!isObject(value)) return false;
+  const have = Object.keys(value);
+  return have.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+
+/**
+ * Whether `obj` is shaped like a declaration this reader knows: one of
+ * `DECLARATION_VERSIONS` compared exactly, exactly the keys that version
+ * defines, and the value types this module reads.
+ *
+ * It is the shape test `@sanning/anchor`'s `isDeclarationShape` makes, and it
+ * checks shape only, not the 5.4.1 rules `readDeclaration` grades: a stale
+ * declaration is somebody else's claim, and this reader does not grade it, it
+ * names it.
+ */
+function isDeclarationShape(obj: unknown): boolean {
+  if (!isObject(obj)) return false;
+  const version = obj["declaration_version"];
+  if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2) return false;
+  if (!hasExactKeys(obj, DECLARATION_KEYS)) return false;
+  if (!isId(obj["case_id"])) return false;
+  const agents = obj["agents"];
+  if (!Array.isArray(agents) || !agents.every((a) => typeof a === "string")) return false;
+  const period = obj["period"];
+  if (!hasExactKeys(period, ["start", "end"])) return false;
+  if (typeof period["start"] !== "string" || typeof period["end"] !== "string") return false;
+  const recordKeys =
+    version === DECLARATION_VERSION_V2 ? ["event_id", "disclosure", "role"] : ["event_id", "disclosure"];
+  const records = obj["records"];
+  if (!Array.isArray(records)) return false;
+  for (const r of records) {
+    if (!hasExactKeys(r, recordKeys) || typeof r["event_id"] !== "string") return false;
+  }
+  const handoffs = obj["handoffs"];
+  if (!Array.isArray(handoffs)) return false;
+  return handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]));
+}
+
+/**
+ * The content bytes disclosed for one record, or `null` where none are usable:
+ * `events[].content` first, then the side-content map, chosen the way the
+ * bundle verifier chooses the bytes it binds.
+ */
+function disclosedBytes(
+  ev: unknown,
+  p: PackRecord,
+  content: SideContentMap | null | undefined,
+): Uint8Array | null {
+  const inBody = isObject(ev) ? ev["content"] : undefined;
+  if (typeof inBody === "string") {
+    try {
+      return hexToBytes(inBody);
+    } catch {
+      // falls through to the side channel, as the bundle verifier does
+    }
+  }
+  if (!p.nameable) return null;
+  const side = sideContentEntry(content, p.eventId).value;
+  if (side instanceof Uint8Array) return side;
+  if (typeof side === "string") {
+    try {
+      return hexToBytes(side);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * Whether `raw` is exactly `JCS(object)` of a declaration-shaped object.
+ * Canonical bytes, not merely parseable ones: a declaration is anchored as
+ * `JCS(declaration)`, and nothing an agent writes by accident.
+ */
+function isDeclarationBytes(raw: Uint8Array): boolean {
+  try {
+    const obj = jcsParse(raw);
+    return isDeclarationShape(obj) && sameBytes(utf8(jcs(obj)), raw);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rule 10: every record that is a declaration other than the pack's own, in
+ * bundle order.
+ *
+ * The record's `event_type` is read from its signed `event_bytes`, so a record
+ * whose bytes the pack withholds is not named: the reader cannot see what it
+ * was signed as. Its content is read from either channel; a record whose
+ * content is byte for byte `JCS` of the pack's own declaration is the pack's
+ * own and is never named.
+ */
+function otherDeclarationNotes(
+  bundle: unknown,
+  pack: PackRecord[],
+  declaration: unknown,
+  content: SideContentMap | null | undefined,
+): DeclarationNote[] {
+  const events = pack.length > 0 ? (bodyOf(bundle)?.events ?? []) : [];
+  let own: Uint8Array | null = null;
+  try {
+    own = utf8(jcs(declaration));
+  } catch {
+    own = null;
+  }
+  const notes: DeclarationNote[] = [];
+  pack.forEach((p, i) => {
+    if (p.record === null || p.record.event_type !== DECLARATION_EVENT_TYPE) return;
+    const raw = disclosedBytes(events[i], p, content);
+    if (raw === null) {
+      // Offered and unusable is not withheld: something arrived, it is not a
+      // declaration, and the bundle verifier names what is wrong with it.
+      // Nothing arrived is the reading the reader cannot settle.
+      if (!p.disclosed) notes.push({ kind: "other_declaration_withheld", eventId: p.eventId });
+      return;
+    }
+    if (own !== null && sameBytes(raw, own)) return;
+    if (isDeclarationBytes(raw)) notes.push({ kind: "other_declaration_held", eventId: p.eventId });
+  });
+  return notes;
+}
+
 /**
  * Check a pack against the declaration inside its body.
  *
@@ -915,6 +1080,12 @@ export function checkDeclaration(
     }
   }
 
+  // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
+  // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
+  // never a deviation: the pack holds what its own declaration says whatever
+  // one of its records says.
+  notes.push(...otherDeclarationNotes(bundle, pack, declaration, content));
+
   // A proven deviation wins: it is a mismatch between what the pack claimed
   // and what its own signed body carries, and a failing check always wins.
   // With no deviation and a content-dependent finding, the pack lines up with
@@ -1120,6 +1291,18 @@ export function renderNote(note: DeclarationNote): string {
         `${note.eventId} is signed as a step and this pack withholds its ` +
         "record bytes, so whether it is one is UNKNOWN"
       );
+    case "other_declaration_held":
+      return (
+        `the content handed in for ${note.eventId} is a declaration that is ` +
+        "not this pack's own: it says what some pack holds, and what this " +
+        "pack holds is what the declaration in its body says"
+      );
+    case "other_declaration_withheld":
+      return (
+        `${note.eventId} is signed as a declaration and no content for it ` +
+        "reached this verifier, so whether it is a declaration other than " +
+        "this pack's own is UNKNOWN"
+      );
   }
 }