@sanning/proof 0.19.1 → 0.20.0

package/src/json-schema.ts

@@ -0,0 +1,295 @@
+// A JSON Schema (draft 2020-12) validator for the keywords the pinned
+// sanning.agent schemas use, and no others. It reads schemas handed to it as
+// data, resolves `$ref` among them by `$id`, and never fetches anything. A
+// keyword outside the supported set throws rather than being skipped: a later
+// pin that adds one must fail loudly, never validate less than it says.
+//
+// Errors are collected in all-errors mode and returned as the reasons of
+// agent-events.md §10 step 4 and §10.1: `unknown_field` (additionalProperties), `missing_field`
+// (required) and `bad_value` (anything else), each at a JSON Pointer.
+
+export type JsonSchema = boolean | { readonly [keyword: string]: unknown };
+
+export type SchemaReason = "unknown_field" | "missing_field" | "bad_value";
+
+export interface SchemaError {
+  readonly reason: SchemaReason;
+  readonly at: string;
+}
+
+// Keywords that carry no assertion.
+const ANNOTATIONS = new Set(["$schema", "$id", "$defs", "title", "description"]);
+const ASSERTIONS = new Set([
+  "$ref",
+  "type",
+  "const",
+  "enum",
+  "not",
+  "anyOf",
+  "properties",
+  "additionalProperties",
+  "required",
+  "minProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "pattern",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+]);
+
+type SchemaObject = { readonly [keyword: string]: unknown };
+
+/** Validate against schemas that reference each other by `$id`. */
+export class SchemaSet {
+  private readonly documents = new Map<string, SchemaObject>();
+  private readonly patterns = new Map<string, RegExp>();
+
+  constructor(documents: readonly JsonSchema[]) {
+    for (const d of documents) {
+      if (typeof d !== "object" || typeof d.$id !== "string") {
+        throw new Error("json-schema: every document needs an $id");
+      }
+      supportedOnly(d);
+      this.documents.set(stripFragment(d.$id), d);
+    }
+  }
+
+  /** Every error `value` has against the document whose `$id` is `id`; empty when it validates. */
+  validate(id: string, value: unknown): SchemaError[] {
+    const doc = this.documents.get(id);
+    if (doc === undefined) throw new Error(`json-schema: no document ${id}`);
+    const errors: SchemaError[] = [];
+    this.check(doc, id, value, "", errors);
+    return errors;
+  }
+
+  private check(schema: JsonSchema, base: string, value: unknown, at: string, errors: SchemaError[]): void {
+    if (schema === true) return;
+    if (schema === false) {
+      errors.push({ reason: "bad_value", at });
+      return;
+    }
+    const s = schema;
+    const bad = (): void => {
+      errors.push({ reason: "bad_value", at });
+    };
+
+    if (s.$ref !== undefined) {
+      const [doc, target] = this.resolve(String(s.$ref), base);
+      this.check(target, doc, value, at, errors);
+    }
+    if (s.type !== undefined) {
+      const types = Array.isArray(s.type) ? (s.type as string[]) : [s.type as string];
+      if (!types.some((t) => hasType(value, t))) bad();
+    }
+    if (has(s, "const") && !deepEqual(value, s.const)) bad();
+    if (s.enum !== undefined && !(s.enum as unknown[]).some((e) => deepEqual(value, e))) bad();
+    if (s.not !== undefined && this.passes(s.not as JsonSchema, base, value)) bad();
+    if (s.anyOf !== undefined) {
+      const branchErrors: SchemaError[] = [];
+      let passed = false;
+      for (const branch of s.anyOf as JsonSchema[]) {
+        const e: SchemaError[] = [];
+        this.check(branch, base, value, at, e);
+        if (e.length === 0) {
+          passed = true;
+          break;
+        }
+        branchErrors.push(...e);
+      }
+      if (!passed) {
+        errors.push(...branchErrors);
+        bad();
+      }
+    }
+
+    if (typeof value === "string") {
+      if (s.pattern !== undefined && !this.pattern(String(s.pattern)).test(value)) bad();
+      if (s.minLength !== undefined && codePoints(value) < (s.minLength as number)) bad();
+      if (s.maxLength !== undefined && codePoints(value) > (s.maxLength as number)) bad();
+    }
+    if (typeof value === "number") {
+      if (s.minimum !== undefined && value < (s.minimum as number)) bad();
+      if (s.maximum !== undefined && value > (s.maximum as number)) bad();
+    }
+    if (Array.isArray(value)) {
+      if (s.minItems !== undefined && value.length < (s.minItems as number)) bad();
+      if (s.maxItems !== undefined && value.length > (s.maxItems as number)) bad();
+      if (s.uniqueItems === true && !allUnique(value)) bad();
+      if (s.items !== undefined) {
+        value.forEach((item, i) => this.check(s.items as JsonSchema, base, item, `${at}/${i}`, errors));
+      }
+    }
+    if (isObject(value)) {
+      const props = (s.properties ?? {}) as Record<string, JsonSchema>;
+      if (s.required !== undefined) {
+        for (const name of s.required as string[]) {
+          if (!has(value, name)) errors.push({ reason: "missing_field", at: `${at}/${escapeToken(name)}` });
+        }
+      }
+      if (s.minProperties !== undefined && Object.keys(value).length < (s.minProperties as number)) bad();
+      for (const key of Object.keys(value)) {
+        const child = `${at}/${escapeToken(key)}`;
+        if (has(props, key)) {
+          this.check(props[key]!, base, value[key], child, errors);
+        } else if (s.additionalProperties === false) {
+          errors.push({ reason: "unknown_field", at: child });
+        } else if (s.additionalProperties !== undefined) {
+          this.check(s.additionalProperties as JsonSchema, base, value[key], child, errors);
+        }
+      }
+    }
+  }
+
+  private passes(schema: JsonSchema, base: string, value: unknown): boolean {
+    const e: SchemaError[] = [];
+    this.check(schema, base, value, "", e);
+    return e.length === 0;
+  }
+
+  private resolve(ref: string, base: string): [string, JsonSchema] {
+    const url = new URL(ref, base);
+    const doc = stripFragment(url.href);
+    let target: unknown = this.documents.get(doc);
+    if (target === undefined) throw new Error(`json-schema: no document for $ref ${ref}`);
+    const fragment = decodeURIComponent(url.hash.slice(1));
+    if (fragment !== "") {
+      if (!fragment.startsWith("/")) throw new Error(`json-schema: unsupported $ref ${ref}`);
+      for (const token of fragment.slice(1).split("/")) {
+        const t = unescapeToken(token);
+        if (!isObject(target) || !has(target, t)) throw new Error(`json-schema: unresolved $ref ${ref}`);
+        target = target[t];
+      }
+    }
+    return [doc, target as JsonSchema];
+  }
+
+  private pattern(source: string): RegExp {
+    let re = this.patterns.get(source);
+    if (re === undefined) {
+      // ECMA-262 with the `u` flag, as JSON Schema reads `pattern`: `$` is the
+      // end of the string, with no exception for a final newline.
+      re = new RegExp(source, "u");
+      this.patterns.set(source, re);
+    }
+    return re;
+  }
+}
+
+/** Throw on a keyword this validator does not implement, anywhere in `schema`. */
+function supportedOnly(schema: JsonSchema): void {
+  const stack: unknown[] = [schema];
+  while (stack.length > 0) {
+    const s = stack.pop();
+    if (typeof s === "boolean") continue;
+    if (!isObject(s)) throw new Error("json-schema: a schema is an object or a boolean");
+    for (const [k, v] of Object.entries(s)) {
+      if (!ANNOTATIONS.has(k) && !ASSERTIONS.has(k)) throw new Error(`json-schema: unsupported keyword ${k}`);
+      if (k === "properties" || k === "$defs") stack.push(...Object.values(v as object));
+      else if (k === "anyOf") stack.push(...(v as unknown[]));
+      else if (k === "items" || k === "not" || k === "additionalProperties") stack.push(v);
+    }
+  }
+}
+
+function stripFragment(id: string): string {
+  const i = id.indexOf("#");
+  return i === -1 ? id : id.slice(0, i);
+}
+
+function hasType(value: unknown, type: string): boolean {
+  switch (type) {
+    case "null":
+      return value === null;
+    case "boolean":
+      return typeof value === "boolean";
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return Number.isInteger(value);
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return isObject(value);
+    default:
+      throw new Error(`json-schema: unsupported type ${type}`);
+  }
+}
+
+/** String length as JSON Schema counts it: in code points, not UTF-16 code units. */
+function codePoints(s: string): number {
+  let n = 0;
+  for (const _ of s) n++;
+  return n;
+}
+
+function allUnique(items: readonly unknown[]): boolean {
+  for (let i = 0; i < items.length; i++) {
+    for (let j = i + 1; j < items.length; j++) {
+      if (deepEqual(items[i], items[j])) return false;
+    }
+  }
+  return true;
+}
+
+/** JSON equality, without recursion so a deeply nested value cannot overflow the stack. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  const stack: [unknown, unknown][] = [[a, b]];
+  while (stack.length > 0) {
+    const [x, y] = stack.pop()!;
+    if (x === y) continue;
+    if (Array.isArray(x)) {
+      if (!Array.isArray(y) || x.length !== y.length) return false;
+      for (let i = 0; i < x.length; i++) stack.push([x[i], y[i]]);
+      continue;
+    }
+    if (isObject(x)) {
+      if (!isObject(y)) return false;
+      const kx = Object.keys(x);
+      if (kx.length !== Object.keys(y).length) return false;
+      for (const k of kx) {
+        if (!has(y, k)) return false;
+        stack.push([x[k], y[k]]);
+      }
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+export function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+export function has(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+/** One JSON Pointer reference token (RFC 6901). */
+export function escapeToken(t: string): string {
+  return t.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+export function unescapeToken(t: string): string {
+  return t.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+/** Freeze `value` and every object and array inside it. */
+export function deepFreeze<T>(value: T): T {
+  const stack: unknown[] = [value];
+  while (stack.length > 0) {
+    const v = stack.pop();
+    if (v !== null && typeof v === "object" && !Object.isFrozen(v)) {
+      Object.freeze(v);
+      stack.push(...Object.values(v));
+    }
+  }
+  return value;
+}

package/src/merkle.ts

@@ -1,16 +1,10 @@
-// RFC 9162 binary Merkle tree — build, audit paths, inclusion verification.
+// RFC 9162 binary Merkle tree: build, audit paths, inclusion verification.
 //
-// A faithful port of the Go reference (the agent producer's pkg/merkle), in lockstep
-// with the Python kernel's sanning_proof.merkle. All hashing is SHA-256 with
-// RFC 9162 §2.1 domain separation: leaves prefixed 0x00, interior nodes 0x01.
-// A tree of n leaves splits into a left subtree of k leaves (the largest
-// power of two < n) and a right subtree of n−k — NOT the Bitcoin
-// duplicate-last-leaf variant, which produces different roots for
-// non-power-of-two leaf counts.
-//
-// The empty tree (zero leaves) hashes to SHA-256("") — EMPTY_TREE_ROOT_HEX.
-// Conformance is byte-for-byte against the 7 merkle-tree-* vectors of
-// test-vectors-v1.0 (test/conformance.test.ts).
+// SHA-256 with RFC 9162 §2.1 domain separation: leaves prefixed 0x00, interior
+// nodes 0x01. A tree of n leaves splits into a left subtree of k leaves (the
+// largest power of two < n) and a right subtree of n-k, not the Bitcoin
+// duplicate-last-leaf variant. The empty tree hashes to SHA-256("")
+// (EMPTY_TREE_ROOT_HEX).
 
 import { sha256Bytes } from "./crypto.js";
 
@@ -31,9 +25,8 @@ export async function nodeHash(left: Uint8Array, right: Uint8Array): Promise<Uin
   return sha256Bytes(buf);
 }
 
-// The RFC 9162 Merkle Tree Hash of already-hashed leaves. Callers pass leaf
-// hashes — the output of leafHash on each leaf's canonical bytes. Zero leaves
-// yields SHA-256("").
+// The RFC 9162 Merkle Tree Hash of already-hashed leaves (the output of
+// `leafHash`). Zero leaves yields SHA-256("").
 export async function merkleRoot(leafHashes: Uint8Array[]): Promise<Uint8Array> {
   const n = leafHashes.length;
   if (n === 0) return sha256Bytes(new Uint8Array(0));
@@ -42,9 +35,8 @@ export async function merkleRoot(leafHashes: Uint8Array[]): Promise<Uint8Array>
   return nodeHash(await merkleRoot(leafHashes.slice(0, k)), await merkleRoot(leafHashes.slice(k)));
 }
 
-// The inclusion proof for the leaf at index m, per RFC 9162 §2.1.3: sibling
-// hashes bottom-up; empty for a single-leaf tree (the leaf hash itself is the
-// root). Throws RangeError when m is out of range.
+// The inclusion proof for the leaf at index m (RFC 9162 §2.1.3): sibling hashes
+// bottom-up, empty for a single-leaf tree. Throws RangeError when m is out of range.
 export async function auditPath(m: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]> {
   if (!Number.isInteger(m) || m < 0 || m >= leafHashes.length) {
     throw new RangeError("merkle: leaf index out of range");
@@ -62,10 +54,8 @@ async function path(m: number, leafHashes: Uint8Array[]): Promise<Uint8Array[]>
   return [...(await path(m - k, leafHashes.slice(k))), await merkleRoot(leafHashes.slice(0, k))];
 }
 
-// Verify an RFC 9162 §2.1.3 inclusion proof. `leaf` is the leaf hash
-// (leafHash of the canonical leaf bytes); `path` is the audit path bottom-up;
-// `expectedRoot` is the merkleRoot committed by the checkpoint envelope.
-// True iff the path reconstructs the expected root. Never throws.
+// Verify an RFC 9162 §2.1.3 inclusion proof. `leaf` is the leaf hash, `path` the
+// audit path bottom-up, `expectedRoot` the root the checkpoint commits to. Never throws.
 export async function verifyInclusion(
   leaf: Uint8Array,
   leafIndex: number,
@@ -78,18 +68,16 @@ export async function verifyInclusion(
   }
   if (totalLeaves === 1) return auditPath.length === 0 && bytesEqual(leaf, expectedRoot);
 
-  // Arithmetic, not bitwise: JavaScript's `&` and `>>=` truncate to 32 bits,
-  // so a tree past 2**31 leaves walked a different tree here than in the
-  // Python kernel, whose integers are unbounded. `% 2` and a halving floor
-  // are exact for every safe integer, and the stated index and count reach
-  // this walk as safe integers.
+  // Arithmetic, not bitwise: `&` and `>>=` truncate to 32 bits, so a tree past
+  // 2**31 leaves would walk a different tree. `% 2` and halving floor are exact
+  // for every safe integer.
   let fn = leafIndex;
   let sn = totalLeaves - 1;
   let r = leaf;
   const half = (v: number): number => Math.floor(v / 2);
 
   for (const p of auditPath) {
-    if (sn === 0) return false; // path longer than the tree depth — malformed
+    if (sn === 0) return false; // path longer than the tree depth
     if (fn % 2 === 1 || fn === sn) {
       r = await nodeHash(p, r);
       if (fn % 2 === 0) {