@zanii/core 0.5.1 → 0.5.2

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';

package/src/receipt.ts

@@ -5,6 +5,27 @@ import { canonicalBytes, decodeSig, encodeSig, jcsHash } from './encoding.js';
 import { publicKeyFromDid } from './keys.js';
 import { scopesAllow, verifyChain, type DelegationCert } from './delegation.js';
 
+/**
+ * The target of a session-close receipt (SPEC §15). An agent records one when it ends a
+ * session deliberately, so a verifier can tell a run that finished from one that was cut
+ * off. The per-agent `prev` chain already proves nothing is missing between receipts;
+ * this marks where a session was declared over.
+ */
+export const SESSION_CLOSE_TARGET = 'zanii.session.close';
+
+/** True for a solo receipt that closes a session. */
+export function isSessionClose(receipt: unknown): boolean {
+  const r = receipt as { type?: string; target?: string; action?: string } | null;
+  return !!r && r.type === undefined && r.target === SESSION_CLOSE_TARGET && r.action === 'session.close';
+}
+
+/** What is at stake in an action (SPEC §3). A label the recorder sets, signed with the receipt: useful for policy and triage, and a control only where something independent of the agent enforces it. */
+export const RISK_LEVELS = ['low', 'medium', 'high', 'critical'] as const;
+export type RiskLevel = (typeof RISK_LEVELS)[number];
+export function isRiskLevel(v: unknown): v is RiskLevel {
+  return typeof v === 'string' && (RISK_LEVELS as readonly string[]).includes(v);
+}
+
 export interface Receipt {
   v: 1;
   agent_id: string;
@@ -30,6 +51,8 @@ export interface Receipt {
    * are checked with `verifyPayloadLegacy`, never with `verifyPayload`.
    */
   payload_encoding?: 'jcs';
+  /** What is at stake (SPEC §3). Signed; absent means the recorder did not say. */
+  risk?: RiskLevel;
   sig: string;
 }
 
@@ -59,6 +82,13 @@ function assertPayloadCanonicalizable(v: unknown, path = 'payload'): void {
           'would encode it differently. Use integer minor units (see @zanii/payments) or a string.',
       );
     }
+    if (!Number.isSafeInteger(v)) {
+      // JavaScript has already rounded it by now; another SDK would keep it exact.
+      throw new Error(
+        `${path}: integer ${v} is outside +/-(2^53-1): not every JSON implementation can ` +
+          'represent it exactly, so the SDKs would disagree on its bytes. Pass it as a string.',
+      );
+    }
     return;
   }
   if (Array.isArray(v)) {
@@ -216,10 +246,15 @@ export function createReceipt(
     subjectTag?: string;
     /** How `payloadHash` committed to the payload. Set `'jcs'` when it came from `payloadBytes`. */
     payloadEncoding?: 'jcs';
+    /** What is at stake. Signed into the receipt when set. */
+    risk?: RiskLevel;
   },
   agentPrivateKey: Uint8Array,
 ): Receipt {
   if (Number.isNaN(Date.parse(fields.ts))) throw new Error(`invalid ts timestamp: ${fields.ts}`);
+  if (fields.risk !== undefined && !isRiskLevel(fields.risk)) {
+    throw new Error(`invalid risk '${String(fields.risk)}': expected one of low, medium, high, critical`);
+  }
   const unsigned = {
     v: 1 as const,
     agent_id: fields.agentId,
@@ -234,6 +269,7 @@ export function createReceipt(
     ...(fields.manifestHash ? { manifest_hash: fields.manifestHash } : {}),
     ...(fields.subjectTag ? { subject_tag: fields.subjectTag } : {}),
     ...(fields.payloadEncoding ? { payload_encoding: fields.payloadEncoding } : {}),
+    ...(fields.risk ? { risk: fields.risk } : {}),
   };
   const sig = ed25519.sign(canonicalBytes(unsigned), agentPrivateKey);
   return { ...unsigned, sig: encodeSig(sig) };

package/src/swarm.ts

@@ -0,0 +1,102 @@
+/**
+ * N-party (swarm) receipts as they sit in the log (SPEC §14): the verification every
+ * consumer of the log needs — the bundle verifier included — so it lives in core.
+ * `@zanii/swarm` re-exports these, and adds the client-side building helpers.
+ */
+import { ed25519 } from '@noble/curves/ed25519';
+import { scopesAllow, verifyChain, type DelegationCert } from './delegation.js';
+import { canonicalBytes, decodeSig } from './encoding.js';
+import { publicKeyFromDid } from './keys.js';
+import type { VerifyResult } from './receipt.js';
+
+export interface SwarmBody {
+  v: 1;
+  type: 'swarm';
+  /** What the team did, e.g. `deploy.release`. */
+  task: string;
+  target: string;
+  /** Hash of the action payload (contents stay off-receipt). */
+  payload_hash?: string;
+  ts: string;
+  /** The team's `did:key`s — distinct, sorted (canonical). */
+  participants: string[];
+  /** M-of-N: how many of `participants` must sign for the receipt to be valid. */
+  threshold: number;
+}
+
+export interface SwarmSignerEnvelope {
+  agent_id: string;
+  /** The signer's delegation chain proving its owner authorized it for the target scope. */
+  delegation: DelegationCert[];
+  /** The signer's previous log head (`null` = genesis). */
+  prev: string | null;
+  /** `ed25519:<hex>` over the canonical body — same as `signSwarm`. */
+  sig: string;
+}
+
+export interface SwarmLedgerReceipt {
+  v: 1;
+  type: 'swarm';
+  body: SwarmBody;
+  signers: SwarmSignerEnvelope[];
+}
+
+/**
+ * Authority-complete verification of an on-ledger swarm receipt (SPEC §14) — the exact
+ * mirror of the server's `verify_swarm_receipt`. Every listed signer must be a distinct
+ * declared participant with a valid signature, an owner-rooted unrevoked/unexpired
+ * delegation, the target in scope, and `prev` matching its chain head. Then valid signers
+ * ≥ threshold, and (default) ≥ threshold DISTINCT owners — real segregation of duties, so
+ * one owner's N agents cannot fake an M-of-N. Any failure hard-rejects.
+ */
+export function verifySwarmReceipt(
+  receipt: SwarmLedgerReceipt | undefined,
+  opts: { revoked?: Set<string>; expectedPrevFor?: Record<string, string | null>; requireDistinctOwners?: boolean } = {},
+): VerifyResult {
+  const requireDistinctOwners = opts.requireDistinctOwners ?? true;
+  if (!receipt || receipt.v !== 1 || receipt.type !== 'swarm') return { ok: false, error: 'not a swarm receipt' };
+  const body = receipt.body;
+  if (!body || body.v !== 1 || body.type !== 'swarm') return { ok: false, error: 'invalid swarm body' };
+  const parts = body.participants;
+  const threshold = body.threshold;
+  const ts = new Date(body.ts);
+  if (!Array.isArray(parts) || parts.length < 3) return { ok: false, error: 'swarm needs at least 3 participants' };
+  if (new Set(parts).size !== parts.length) return { ok: false, error: 'participants must be distinct' };
+  if (!Number.isInteger(threshold) || threshold < 1 || threshold > parts.length) return { ok: false, error: 'invalid threshold' };
+  if (Number.isNaN(ts.getTime())) return { ok: false, error: 'invalid ts' };
+
+  const participantSet = new Set(parts);
+  const target = body.target ?? '';
+  const msg = canonicalBytes(body);
+  const signers = receipt.signers ?? [];
+  const seen = new Set<string>();
+  const owners: string[] = [];
+  for (const s of signers) {
+    const aid = s.agent_id;
+    if (!participantSet.has(aid)) return { ok: false, error: `signer ${aid} is not a declared participant` };
+    if (seen.has(aid)) return { ok: false, error: `signer ${aid} appears twice` };
+    seen.add(aid);
+    const pub = publicKeyFromDid(aid);
+    const sig = decodeSig(s.sig);
+    if (!pub || !sig) return { ok: false, error: `signer ${aid}: malformed key or signature` };
+    let sigOk = false;
+    try {
+      sigOk = ed25519.verify(sig, msg, pub);
+    } catch {
+      sigOk = false;
+    }
+    if (!sigOk) return { ok: false, error: `signer ${aid}: bad signature` };
+    const chain = verifyChain(s.delegation ?? [], { agentId: aid, revoked: opts.revoked, at: ts });
+    if (!chain.ok) return { ok: false, error: `signer ${aid} delegation: ${chain.error}` };
+    if (!scopesAllow(chain.effectiveScopes ?? [], target)) return { ok: false, error: `signer ${aid}: target ${target} outside effective scopes` };
+    const expected = opts.expectedPrevFor?.[aid];
+    if (expected !== undefined && s.prev !== expected) return { ok: false, error: `signer ${aid}: prev hash does not match chain head (chain broken)` };
+    const root = s.delegation?.[0]?.issuer;
+    if (root) owners.push(root);
+  }
+  if (seen.size < threshold) return { ok: false, error: `threshold not met: ${seen.size} valid of ${threshold} required` };
+  if (requireDistinctOwners && new Set(owners).size < threshold) {
+    return { ok: false, error: `distinct-owner threshold not met: ${new Set(owners).size} owners of ${threshold} required` };
+  }
+  return { ok: true };
+}