@zanii/core 0.5.1 → 0.5.3

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 };
+}