@zanii/core 0.5.1 → 0.5.3

package/src/bundle.ts

@@ -1,176 +1,214 @@
-/**
- * Audit bundles — SPEC §8. A self-contained, offline-verifiable export of one
- * agent's complete action history: receipts, proofs, revocations, anchors.
- * verifyAuditBundle() is pure: no network, no trusted party.
- */
-import { hexToBytes } from '@noble/hashes/utils';
-import { canonicalBytes, jcsHash } from './encoding.js';
-import { certHash, verifyRevocation, type RevocationRecord } from './delegation.js';
-import { leafHash, verifyConsistency, verifyInclusion } from './merkle.js';
-import { verifySTH, type SignedTreeHead } from './sth.js';
-import { verifyReceipt, type Receipt } from './receipt.js';
-import { participantsOf, prevFor, verifyA2AReceipt, type A2AReceipt } from './a2a.js';
-
-export interface BundledReceipt {
-  receipt: Receipt | A2AReceipt;
-  hash: string;
-  index: number;
-  proof: string[];
-}
-
-export interface BundledRevocation {
-  revocation: RevocationRecord;
-  cert_hash: string;
-  index: number;
-  proof: string[];
-}
-
-export interface BundledAnchor {
-  sth: SignedTreeHead;
-  backend: string;
-  ref: string;
-  block?: number;
-  anchored_at: string;
-  /** Consistency proof from the anchored tree to this bundle's STH. */
-  consistency_proof: string[];
-}
-
-export interface AuditBundle {
-  v: 1;
-  bundle_type: 'zanii-audit-bundle';
-  generated_at: string;
-  log_id: string;
-  agent_id: string;
-  sth: SignedTreeHead;
-  receipts: BundledReceipt[];
-  revocations: BundledRevocation[];
-  anchors: BundledAnchor[];
-}
-
-export interface BundleCheck {
-  label: string;
-  ok: boolean;
-  detail?: string;
-}
-
-export interface BundleReport {
-  ok: boolean;
-  checks: BundleCheck[];
-  stats: {
-    receipts: number;
-    first_ts: string | null;
-    last_ts: string | null;
-    revoked_certs: number;
-    anchored_through: number | null;
-  };
-}
-
-const root = (sth: SignedTreeHead) => hexToBytes(sth.root.replace('sha256:', ''));
-
-/** Fully verify an audit bundle offline. Every failure is reported, none throws. */
-export function verifyAuditBundle(bundle: AuditBundle): BundleReport {
-  const checks: BundleCheck[] = [];
-  const push = (label: string, ok: boolean, detail?: string) => checks.push({ label, ok, detail });
-
-  try {
-    push('bundle format', bundle.v === 1 && bundle.bundle_type === 'zanii-audit-bundle');
-    push(
-      'signed tree head signature and log identity',
-      verifySTH(bundle.sth) && bundle.sth.log_id === bundle.log_id,
-      bundle.log_id,
-    );
-
-    // Receipts: signature/delegation/scope, identity, hash, inclusion, prev-chain continuity.
-    let receiptsOk = true;
-    let chainOk = true;
-    let expectedPrev: string | null = null;
-    const sorted = [...bundle.receipts].sort((a, b) => a.index - b.index);
-    for (const [i, br] of sorted.entries()) {
-      // revocation reported separately below
-      const check =
-        (br.receipt as A2AReceipt).type === 'a2a'
-          ? verifyA2AReceipt(br.receipt as A2AReceipt)
-          : verifyReceipt(br.receipt as Receipt);
-      const identityOk = participantsOf(br.receipt).includes(bundle.agent_id);
-      const hashOk = jcsHash(br.receipt) === br.hash;
-      const inclusionOk = verifyInclusion(
-        leafHash(canonicalBytes(br.receipt)),
-        br.index,
-        bundle.sth.size,
-        br.proof.map(hexToBytes),
-        root(bundle.sth),
-      );
-      if (!check.ok || !identityOk || !hashOk || !inclusionOk) {
-        receiptsOk = false;
-        push(`receipt #${i} (leaf ${br.index})`, false, check.error ?? 'hash/identity/inclusion mismatch');
-      }
-      if (prevFor(br.receipt, bundle.agent_id) !== expectedPrev) chainOk = false;
-      expectedPrev = br.hash;
-    }
-    push(`all ${sorted.length} receipts: signature, delegation, scope, hash, Merkle inclusion`, receiptsOk);
-    push('per-agent hash chain is complete and unbroken (full history, no gaps)', chainOk);
-
-    // Revocations: issuer-signed and present in the tree.
-    let revocationsOk = true;
-    for (const bv of bundle.revocations) {
-      const sigOk = verifyRevocation(bv.revocation) && certHash(bv.revocation.cert) === bv.cert_hash;
-      const inclusionOk = verifyInclusion(
-        leafHash(canonicalBytes(bv.revocation)),
-        bv.index,
-        bundle.sth.size,
-        bv.proof.map(hexToBytes),
-        root(bundle.sth),
-      );
-      if (!sigOk || !inclusionOk) {
-        revocationsOk = false;
-        push(`revocation of ${bv.cert_hash.slice(0, 24)}…`, false);
-      }
-    }
-    push(`all ${bundle.revocations.length} revocation records: issuer signature and Merkle inclusion`, revocationsOk);
-
-    // Anchors: each anchored STH verifies and the bundle tree is an append-only extension of it.
-    let anchorsOk = true;
-    let anchoredThrough: number | null = null;
-    for (const a of bundle.anchors) {
-      const sthOk = verifySTH(a.sth) && a.sth.log_id === bundle.log_id;
-      const consistent = verifyConsistency(
-        a.sth.size,
-        bundle.sth.size,
-        root(a.sth),
-        root(bundle.sth),
-        a.consistency_proof.map(hexToBytes),
-      );
-      if (!sthOk || !consistent) {
-        anchorsOk = false;
-        push(`anchor ${a.ref}`, false, 'STH signature or consistency proof failed');
-      } else {
-        anchoredThrough = Math.max(anchoredThrough ?? 0, a.sth.size);
-      }
-    }
-    push(
-      `all ${bundle.anchors.length} anchors: anchored STH valid, bundle tree is append-only extension`,
-      anchorsOk,
-      anchoredThrough !== null ? `history immutable through leaf ${anchoredThrough - 1}` : undefined,
-    );
-
-    const revokedCertHashes = new Set(bundle.revocations.map((r) => r.cert_hash));
-    return {
-      ok: checks.every((c) => c.ok),
-      checks,
-      stats: {
-        receipts: sorted.length,
-        first_ts: sorted[0]?.receipt.ts ?? null,
-        last_ts: sorted[sorted.length - 1]?.receipt.ts ?? null,
-        revoked_certs: revokedCertHashes.size,
-        anchored_through: anchoredThrough,
-      },
-    };
-  } catch (err) {
-    push('bundle parses and verifies without errors', false, String(err));
-    return {
-      ok: false,
-      checks,
-      stats: { receipts: 0, first_ts: null, last_ts: null, revoked_certs: 0, anchored_through: null },
-    };
-  }
-}
+/**
+ * Audit bundles — SPEC §8. A self-contained, offline-verifiable export of one
+ * agent's complete action history: receipts, proofs, revocations, anchors.
+ * verifyAuditBundle() is pure: no network, no trusted party.
+ */
+import { hexToBytes } from '@noble/hashes/utils';
+import { canonicalBytes, jcsHash } from './encoding.js';
+import { certHash, verifyRevocation, type RevocationRecord } from './delegation.js';
+import { leafHash, verifyConsistency, verifyInclusion } from './merkle.js';
+import { verifySTH, type SignedTreeHead } from './sth.js';
+import { isSessionClose, verifyReceipt, type Receipt } from './receipt.js';
+import { participantsOf, prevFor, verifyA2AReceipt, type A2AReceipt } from './a2a.js';
+import { verifySwarmReceipt, type SwarmLedgerReceipt } from './swarm.js';
+
+/** A receipt's timestamp: top-level on solo and a2a receipts, inside `body` on swarm ones. */
+function receiptTs(r: unknown): string | null {
+  const o = r as { ts?: unknown; body?: { ts?: unknown } };
+  if (typeof o?.ts === 'string') return o.ts;
+  return typeof o?.body?.ts === 'string' ? o.body.ts : null;
+}
+
+export interface BundledReceipt {
+  receipt: Receipt | A2AReceipt;
+  hash: string;
+  index: number;
+  proof: string[];
+}
+
+export interface BundledRevocation {
+  revocation: RevocationRecord;
+  cert_hash: string;
+  index: number;
+  proof: string[];
+}
+
+export interface BundledAnchor {
+  sth: SignedTreeHead;
+  backend: string;
+  ref: string;
+  block?: number;
+  anchored_at: string;
+  /** Consistency proof from the anchored tree to this bundle's STH. */
+  consistency_proof: string[];
+}
+
+export interface AuditBundle {
+  v: 1;
+  bundle_type: 'zanii-audit-bundle';
+  generated_at: string;
+  log_id: string;
+  agent_id: string;
+  sth: SignedTreeHead;
+  receipts: BundledReceipt[];
+  revocations: BundledRevocation[];
+  anchors: BundledAnchor[];
+}
+
+export interface BundleCheck {
+  label: string;
+  ok: boolean;
+  detail?: string;
+}
+
+export interface BundleReport {
+  ok: boolean;
+  checks: BundleCheck[];
+  stats: {
+    receipts: number;
+    first_ts: string | null;
+    last_ts: string | null;
+    revoked_certs: number;
+    anchored_through: number | null;
+    /** The newest receipt closes a session (SPEC §15). */
+    session_closed: boolean;
+    /** When the newest receipt closed its session, else null. */
+    closed_at: string | null;
+  };
+}
+
+const root = (sth: SignedTreeHead) => hexToBytes(sth.root.replace('sha256:', ''));
+
+/** Fully verify an audit bundle offline. Every failure is reported, none throws. */
+export function verifyAuditBundle(bundle: AuditBundle): BundleReport {
+  const checks: BundleCheck[] = [];
+  const push = (label: string, ok: boolean, detail?: string) => checks.push({ label, ok, detail });
+
+  try {
+    push('bundle format', bundle.v === 1 && bundle.bundle_type === 'zanii-audit-bundle');
+    push(
+      'signed tree head signature and log identity',
+      verifySTH(bundle.sth) && bundle.sth.log_id === bundle.log_id,
+      bundle.log_id,
+    );
+
+    // Receipts: signature/delegation/scope, identity, hash, inclusion, prev-chain continuity.
+    let receiptsOk = true;
+    let chainOk = true;
+    let expectedPrev: string | null = null;
+    const sorted = [...bundle.receipts].sort((a, b) => a.index - b.index);
+    for (const [i, br] of sorted.entries()) {
+      // revocation reported separately below
+      // Each receipt is checked by the rules of its own type. A swarm receipt checked as a
+      // solo one failed signature and chain checks, so an honest swarm participant's
+      // history was reported as broken.
+      const kind = (br.receipt as { type?: string }).type;
+      const check =
+        kind === 'a2a'
+          ? verifyA2AReceipt(br.receipt as A2AReceipt)
+          : kind === 'swarm'
+            ? verifySwarmReceipt(br.receipt as unknown as SwarmLedgerReceipt)
+            : verifyReceipt(br.receipt as Receipt);
+      const identityOk = participantsOf(br.receipt).includes(bundle.agent_id);
+      const hashOk = jcsHash(br.receipt) === br.hash;
+      const inclusionOk = verifyInclusion(
+        leafHash(canonicalBytes(br.receipt)),
+        br.index,
+        bundle.sth.size,
+        br.proof.map(hexToBytes),
+        root(bundle.sth),
+      );
+      if (!check.ok || !identityOk || !hashOk || !inclusionOk) {
+        receiptsOk = false;
+        push(`receipt #${i} (leaf ${br.index})`, false, check.error ?? 'hash/identity/inclusion mismatch');
+      }
+      if (prevFor(br.receipt, bundle.agent_id) !== expectedPrev) chainOk = false;
+      expectedPrev = br.hash;
+    }
+    push(`all ${sorted.length} receipts: signature, delegation, scope, hash, Merkle inclusion`, receiptsOk);
+    push('per-agent hash chain is complete and unbroken (full history, no gaps)', chainOk);
+
+    // Revocations: issuer-signed and present in the tree.
+    let revocationsOk = true;
+    for (const bv of bundle.revocations) {
+      const sigOk = verifyRevocation(bv.revocation) && certHash(bv.revocation.cert) === bv.cert_hash;
+      const inclusionOk = verifyInclusion(
+        leafHash(canonicalBytes(bv.revocation)),
+        bv.index,
+        bundle.sth.size,
+        bv.proof.map(hexToBytes),
+        root(bundle.sth),
+      );
+      if (!sigOk || !inclusionOk) {
+        revocationsOk = false;
+        push(`revocation of ${bv.cert_hash.slice(0, 24)}…`, false);
+      }
+    }
+    push(`all ${bundle.revocations.length} revocation records: issuer signature and Merkle inclusion`, revocationsOk);
+
+    // Anchors: each anchored STH verifies and the bundle tree is an append-only extension of it.
+    let anchorsOk = true;
+    let anchoredThrough: number | null = null;
+    for (const a of bundle.anchors) {
+      const sthOk = verifySTH(a.sth) && a.sth.log_id === bundle.log_id;
+      const consistent = verifyConsistency(
+        a.sth.size,
+        bundle.sth.size,
+        root(a.sth),
+        root(bundle.sth),
+        a.consistency_proof.map(hexToBytes),
+      );
+      if (!sthOk || !consistent) {
+        anchorsOk = false;
+        push(`anchor ${a.ref}`, false, 'STH signature or consistency proof failed');
+      } else {
+        anchoredThrough = Math.max(anchoredThrough ?? 0, a.sth.size);
+      }
+    }
+    push(
+      `all ${bundle.anchors.length} anchors: anchored STH valid, bundle tree is append-only extension`,
+      anchorsOk,
+      anchoredThrough !== null ? `history immutable through leaf ${anchoredThrough - 1}` : undefined,
+    );
+
+    // Session close (SPEC §15) is reported, never failed: an agent mid-session is normal.
+    // It is mentioned only for agents that use sessions, so a bundle from an agent that
+    // never closes one reads exactly as it always has.
+    const newest = sorted[sorted.length - 1]?.receipt;
+    const sessionClosed = newest !== undefined && isSessionClose(newest);
+    const closedAt = sessionClosed ? receiptTs(newest) : null;
+    if (sorted.some((br) => isSessionClose(br.receipt))) {
+      push(
+        sessionClosed
+          ? `the newest receipt closes a session (${closedAt})`
+          : 'the newest receipt is not a session close: the agent may still be running, or receipts after its last one were withheld',
+        true,
+      );
+    }
+
+    const revokedCertHashes = new Set(bundle.revocations.map((r) => r.cert_hash));
+    return {
+      ok: checks.every((c) => c.ok),
+      checks,
+      stats: {
+        receipts: sorted.length,
+        first_ts: sorted.length ? receiptTs(sorted[0]!.receipt) : null,
+        last_ts: sorted.length ? receiptTs(sorted[sorted.length - 1]!.receipt) : null,
+        revoked_certs: revokedCertHashes.size,
+        anchored_through: anchoredThrough,
+        session_closed: sessionClosed,
+        closed_at: closedAt,
+      },
+    };
+  } catch (err) {
+    push('bundle parses and verifies without errors', false, String(err));
+    return {
+      ok: false,
+      checks,
+      stats: {
+        receipts: 0, first_ts: null, last_ts: null, revoked_certs: 0, anchored_through: null,
+        session_closed: false, closed_at: null,
+      },
+    };
+  }
+}

package/src/index.ts

@@ -52,6 +52,11 @@ export {
   saltedPayloadHash,
   verifyPayload,
   verifyPayloadLegacy,
+  RISK_LEVELS,
+  SESSION_CLOSE_TARGET,
+  isSessionClose,
+  isRiskLevel,
+  type RiskLevel,
   type PayloadDialect,
   verifyReceipt,
   verifyReceiptSignature,
@@ -69,3 +74,4 @@ export {
   verifyCoSignature,
   type ReceiptCoSignature,
 } from './cosign.js';
+export { verifySwarmReceipt, type SwarmBody, type SwarmLedgerReceipt, type SwarmSignerEnvelope } from './swarm.js';