@zanii/core 0.1.0

package/src/merkle.ts

@@ -0,0 +1,154 @@
+/**
+ * RFC 6962 / RFC 9162 Merkle tree: root, inclusion proofs, consistency proofs.
+ * All functions operate on arrays of *leaf hashes* (already 0x00-prefixed-hashed).
+ */
+import { sha256 } from '@noble/hashes/sha256';
+
+const LEAF_PREFIX = 0x00;
+const NODE_PREFIX = 0x01;
+
+/** SHA-256(0x00 || data) */
+export function leafHash(data: Uint8Array): Uint8Array {
+  const buf = new Uint8Array(1 + data.length);
+  buf[0] = LEAF_PREFIX;
+  buf.set(data, 1);
+  return sha256(buf);
+}
+
+function nodeHash(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const buf = new Uint8Array(1 + 64);
+  buf[0] = NODE_PREFIX;
+  buf.set(left, 1);
+  buf.set(right, 33);
+  return sha256(buf);
+}
+
+/** Largest power of two strictly less than n (n >= 2). */
+function split(n: number): number {
+  let k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+// ponytail: recursive slices, O(n log n) per call — swap for an incremental level-cached tree past ~100k leaves
+
+export function merkleRoot(leafHashes: Uint8Array[]): Uint8Array {
+  const n = leafHashes.length;
+  if (n === 0) return sha256(new Uint8Array(0));
+  if (n === 1) return leafHashes[0]!;
+  const k = split(n);
+  return nodeHash(merkleRoot(leafHashes.slice(0, k)), merkleRoot(leafHashes.slice(k)));
+}
+
+/** Audit path for leaf `index` in a tree of the given leaf hashes (RFC 6962 §2.1.1). */
+export function inclusionProof(index: number, leafHashes: Uint8Array[]): Uint8Array[] {
+  const n = leafHashes.length;
+  if (!Number.isInteger(index) || index < 0 || index >= n) {
+    throw new Error(`leaf index ${index} out of range for tree size ${n}`);
+  }
+  if (n === 1) return [];
+  const k = split(n);
+  return index < k
+    ? [...inclusionProof(index, leafHashes.slice(0, k)), merkleRoot(leafHashes.slice(k))]
+    : [...inclusionProof(index - k, leafHashes.slice(k)), merkleRoot(leafHashes.slice(0, k))];
+}
+
+const eq = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((x, i) => x === b[i]);
+
+/** RFC 9162 §2.1.3.2. Pure; returns false on any malformed input. */
+export function verifyInclusion(
+  leaf: Uint8Array,
+  index: number,
+  size: number,
+  proof: Uint8Array[],
+  root: Uint8Array,
+): boolean {
+  if (!Number.isInteger(index) || !Number.isInteger(size) || index < 0 || index >= size) return false;
+  let fn = index;
+  let sn = size - 1;
+  let r = leaf;
+  for (const p of proof) {
+    if (p.length !== 32) return false;
+    if (sn === 0) return false;
+    if (fn % 2 === 1 || fn === sn) {
+      r = nodeHash(p, r);
+      if (fn % 2 === 0) {
+        while (fn % 2 === 0 && fn !== 0) {
+          fn = Math.floor(fn / 2);
+          sn = Math.floor(sn / 2);
+        }
+      }
+    } else {
+      r = nodeHash(r, p);
+    }
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+  return sn === 0 && eq(r, root);
+}
+
+/** Consistency proof from tree size m to the current tree (RFC 6962 §2.1.2). */
+export function consistencyProof(m: number, leafHashes: Uint8Array[]): Uint8Array[] {
+  const n = leafHashes.length;
+  if (!Number.isInteger(m) || m < 1 || m > n) {
+    throw new Error(`old size ${m} out of range for tree size ${n}`);
+  }
+  if (m === n) return [];
+  return subproof(m, leafHashes, true);
+}
+
+function subproof(m: number, leafHashes: Uint8Array[], complete: boolean): Uint8Array[] {
+  const n = leafHashes.length;
+  if (m === n) return complete ? [] : [merkleRoot(leafHashes)];
+  const k = split(n);
+  return m <= k
+    ? [...subproof(m, leafHashes.slice(0, k), complete), merkleRoot(leafHashes.slice(k))]
+    : [...subproof(m - k, leafHashes.slice(k), false), merkleRoot(leafHashes.slice(0, k))];
+}
+
+/** RFC 9162 §2.1.4.2. Pure; returns false on any malformed input. */
+export function verifyConsistency(
+  size1: number,
+  size2: number,
+  root1: Uint8Array,
+  root2: Uint8Array,
+  proof: Uint8Array[],
+): boolean {
+  if (!Number.isInteger(size1) || !Number.isInteger(size2) || size1 < 0 || size1 > size2) return false;
+  if (size1 === size2) return proof.length === 0 && eq(root1, root2);
+  if (size1 === 0) return proof.length === 0;
+  if (proof.length === 0) return false;
+
+  const path = [...proof];
+  // If size1 is an exact power of two, root1 is itself the first component.
+  if ((size1 & (size1 - 1)) === 0) path.unshift(root1);
+
+  let fn = size1 - 1;
+  let sn = size2 - 1;
+  while (fn % 2 === 1) {
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+
+  let fr = path[0]!;
+  let sr = path[0]!;
+  for (const c of path.slice(1)) {
+    if (c.length !== 32) return false;
+    if (sn === 0) return false;
+    if (fn % 2 === 1 || fn === sn) {
+      fr = nodeHash(c, fr);
+      sr = nodeHash(c, sr);
+      if (fn % 2 === 0) {
+        while (fn % 2 === 0 && fn !== 0) {
+          fn = Math.floor(fn / 2);
+          sn = Math.floor(sn / 2);
+        }
+      }
+    } else {
+      sr = nodeHash(sr, c);
+    }
+    fn = Math.floor(fn / 2);
+    sn = Math.floor(sn / 2);
+  }
+  return sn === 0 && eq(fr, root1) && eq(sr, root2);
+}

package/src/receipt.ts

@@ -0,0 +1,123 @@
+import { ed25519 } from '@noble/curves/ed25519';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { canonicalBytes, decodeSig, encodeSig, jcsHash } from './encoding.js';
+import { publicKeyFromDid } from './keys.js';
+import { scopesAllow, verifyChain, type DelegationCert } from './delegation.js';
+
+export interface Receipt {
+  v: 1;
+  agent_id: string;
+  delegation: DelegationCert[];
+  action: string;
+  target: string;
+  payload_hash: string;
+  ts: string;
+  prev: string | null;
+  sig: string;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  error?: string;
+}
+
+export function hashPayload(payload: Uint8Array | string): string {
+  const bytes = typeof payload === 'string' ? new TextEncoder().encode(payload) : payload;
+  return `sha256:${bytesToHex(sha256(bytes))}`;
+}
+
+export function createReceipt(
+  fields: {
+    agentId: string;
+    delegation: DelegationCert[];
+    action: string;
+    target: string;
+    payloadHash: string;
+    ts: string;
+    prev: string | null;
+  },
+  agentPrivateKey: Uint8Array,
+): Receipt {
+  if (Number.isNaN(Date.parse(fields.ts))) throw new Error(`invalid ts timestamp: ${fields.ts}`);
+  const unsigned = {
+    v: 1 as const,
+    agent_id: fields.agentId,
+    delegation: fields.delegation,
+    action: fields.action,
+    target: fields.target,
+    payload_hash: fields.payloadHash,
+    ts: fields.ts,
+    prev: fields.prev,
+  };
+  const sig = ed25519.sign(canonicalBytes(unsigned), agentPrivateKey);
+  return { ...unsigned, sig: encodeSig(sig) };
+}
+
+/** Hash of the full receipt (incl. sig) — what the next receipt's `prev` points to. */
+export function receiptHash(receipt: Receipt): string {
+  return jcsHash(receipt);
+}
+
+export function verifyReceiptSignature(receipt: Receipt): boolean {
+  const pub = publicKeyFromDid(receipt.agent_id);
+  const sig = decodeSig(receipt.sig);
+  if (!pub || !sig) return false;
+  const { sig: _omitted, ...unsigned } = receipt;
+  try {
+    return ed25519.verify(sig, canonicalBytes(unsigned), pub);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Full single-receipt verification per SPEC §4:
+ * signature → delegation chain (at receipt time) → scope covers target → prev linkage.
+ */
+export function verifyReceipt(
+  receipt: Receipt,
+  opts: { expectedOwner?: string; revoked?: Set<string>; expectedPrev?: string | null } = {},
+): VerifyResult {
+  if (receipt.v !== 1) return { ok: false, error: 'unsupported receipt version' };
+  if (!verifyReceiptSignature(receipt)) return { ok: false, error: 'bad receipt signature' };
+
+  const ts = new Date(receipt.ts);
+  if (Number.isNaN(ts.getTime())) return { ok: false, error: 'invalid ts' };
+
+  const chain = verifyChain(receipt.delegation, {
+    agentId: receipt.agent_id,
+    expectedRoot: opts.expectedOwner,
+    revoked: opts.revoked,
+    at: ts,
+  });
+  if (!chain.ok) return { ok: false, error: `delegation: ${chain.error}` };
+
+  if (!scopesAllow(chain.effectiveScopes!, receipt.target)) {
+    return { ok: false, error: `target ${receipt.target} outside effective scopes` };
+  }
+
+  if (opts.expectedPrev !== undefined && receipt.prev !== opts.expectedPrev) {
+    return { ok: false, error: 'prev hash does not match preceding receipt (chain broken)' };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Verify an agent's full receipt sequence: every receipt valid and hash-linked
+ * to the one before it. Returns the index of the first bad receipt on failure.
+ */
+export function verifyReceiptChain(
+  receipts: Receipt[],
+  opts: { expectedOwner?: string; revoked?: Set<string> } = {},
+): VerifyResult & { failedIndex?: number } {
+  let expectedPrev: string | null = null;
+  for (let i = 0; i < receipts.length; i++) {
+    const r = receipts[i]!;
+    const result = verifyReceipt(r, { ...opts, expectedPrev });
+    if (!result.ok) return { ok: false, error: `receipt ${i}: ${result.error}`, failedIndex: i };
+    expectedPrev = receiptHash(r);
+  }
+  return { ok: true };
+}

package/src/sth.ts

@@ -0,0 +1,35 @@
+import { ed25519 } from '@noble/curves/ed25519';
+import { canonicalBytes, decodeSig, encodeSig } from './encoding.js';
+import { publicKeyFromDid } from './keys.js';
+
+/** Signed Tree Head — the log's periodic, signed commitment to its state (SPEC §5). */
+export interface SignedTreeHead {
+  v: 1;
+  log_id: string;
+  size: number;
+  root: string;
+  ts: string;
+  sig: string;
+}
+
+export function createSTH(
+  fields: { logId: string; size: number; root: string; ts: string },
+  logPrivateKey: Uint8Array,
+): SignedTreeHead {
+  const unsigned = { v: 1 as const, log_id: fields.logId, size: fields.size, root: fields.root, ts: fields.ts };
+  const sig = ed25519.sign(canonicalBytes(unsigned), logPrivateKey);
+  return { ...unsigned, sig: encodeSig(sig) };
+}
+
+export function verifySTH(sth: SignedTreeHead): boolean {
+  if (sth.v !== 1 || !Number.isInteger(sth.size) || sth.size < 0) return false;
+  const pub = publicKeyFromDid(sth.log_id);
+  const sig = decodeSig(sth.sig);
+  if (!pub || !sig) return false;
+  const { sig: _omitted, ...unsigned } = sth;
+  try {
+    return ed25519.verify(sig, canonicalBytes(unsigned), pub);
+  } catch {
+    return false;
+  }
+}