@zanii/core 0.5.1 → 0.5.3

package/src/a2a.ts

@@ -1,139 +1,148 @@
-/**
- * Cross-org co-signed receipts — SPEC §9. One interaction, two signers, one
- * neutral proof that enters both agents' hash chains.
- */
-import { ed25519 } from '@noble/curves/ed25519';
-import { canonicalBytes, decodeSig, encodeSig, jcsHash } from './encoding.js';
-import { publicKeyFromDid } from './keys.js';
-import { scopesAllow, verifyChain, type DelegationCert } from './delegation.js';
-import type { VerifyResult } from './receipt.js';
-
-export interface A2AParty {
-  agent_id: string;
-  delegation: DelegationCert[];
-  prev: string | null;
-  sig: string;
-}
-
-export interface A2AReceipt {
-  v: 1;
-  type: 'a2a';
-  action: string;
-  target: string;
-  payload_hash: string;
-  ts: string;
-  initiator: A2AParty;
-  responder: A2AParty;
-}
-
-/** The body both parties sign: the receipt with both sig fields removed. */
-export type A2ABody = Omit<A2AReceipt, 'initiator' | 'responder'> & {
-  initiator: Omit<A2AParty, 'sig'>;
-  responder: Omit<A2AParty, 'sig'>;
-};
-
-export function buildA2ABody(fields: {
-  action: string;
-  target: string;
-  payloadHash: string;
-  ts: string;
-  initiator: Omit<A2AParty, 'sig'>;
-  responder: Omit<A2AParty, 'sig'>;
-}): A2ABody {
-  if (Number.isNaN(Date.parse(fields.ts))) throw new Error(`invalid ts timestamp: ${fields.ts}`);
-  if (fields.initiator.agent_id === fields.responder.agent_id) {
-    throw new Error('initiator and responder must be distinct agents');
-  }
-  return {
-    v: 1,
-    type: 'a2a',
-    action: fields.action,
-    target: fields.target,
-    payload_hash: fields.payloadHash,
-    ts: fields.ts,
-    initiator: fields.initiator,
-    responder: fields.responder,
-  };
-}
-
-/** Both parties sign the identical body — order-independent. */
-export function signA2ABody(body: A2ABody, privateKey: Uint8Array): string {
-  return encodeSig(ed25519.sign(canonicalBytes(body), privateKey));
-}
-
-export function assembleA2AReceipt(body: A2ABody, initiatorSig: string, responderSig: string): A2AReceipt {
-  return {
-    ...body,
-    initiator: { ...body.initiator, sig: initiatorSig },
-    responder: { ...body.responder, sig: responderSig },
-  };
-}
-
-/** Hash of the full receipt (both sigs) — what both agents' next `prev` points to. */
-export function a2aHash(receipt: A2AReceipt): string {
-  return jcsHash(receipt);
-}
-
-export function bodyOf(receipt: A2AReceipt): A2ABody {
-  const { sig: _i, ...initiator } = receipt.initiator;
-  const { sig: _r, ...responder } = receipt.responder;
-  return { ...receipt, initiator, responder };
-}
-
-function partySigOk(body: A2ABody, party: A2AParty): boolean {
-  const pub = publicKeyFromDid(party.agent_id);
-  const sig = decodeSig(party.sig);
-  if (!pub || !sig) return false;
-  try {
-    return ed25519.verify(sig, canonicalBytes(body), pub);
-  } catch {
-    return false;
-  }
-}
-
-/** Full A2A verification per SPEC §9. `expectedPrevFor` maps agent DID → required prev. */
-export function verifyA2AReceipt(
-  receipt: A2AReceipt,
-  opts: { revoked?: Set<string>; expectedPrevFor?: Record<string, string | null> } = {},
-): VerifyResult {
-  if (receipt.v !== 1 || receipt.type !== 'a2a') return { ok: false, error: 'not an a2a receipt' };
-  if (receipt.initiator.agent_id === receipt.responder.agent_id) {
-    return { ok: false, error: 'initiator and responder must be distinct' };
-  }
-  const ts = new Date(receipt.ts);
-  if (Number.isNaN(ts.getTime())) return { ok: false, error: 'invalid ts' };
-
-  const body = bodyOf(receipt);
-  for (const [role, party] of [['initiator', receipt.initiator], ['responder', receipt.responder]] as const) {
-    if (!partySigOk(body, party)) return { ok: false, error: `${role}: bad signature` };
-    const chain = verifyChain(party.delegation, { agentId: party.agent_id, revoked: opts.revoked, at: ts });
-    if (!chain.ok) return { ok: false, error: `${role} delegation: ${chain.error}` };
-    if (!scopesAllow(chain.effectiveScopes!, receipt.target)) {
-      return { ok: false, error: `${role}: target ${receipt.target} outside effective scopes` };
-    }
-    const expected = opts.expectedPrevFor?.[party.agent_id];
-    if (expected !== undefined && party.prev !== expected) {
-      return { ok: false, error: `${role}: prev hash does not match chain head (chain broken)` };
-    }
-  }
-  return { ok: true };
-}
-
-/** The DIDs participating in any log receipt (solo or a2a). */
-export function participantsOf(entry: { agent_id?: string; type?: string; initiator?: A2AParty; responder?: A2AParty }): string[] {
-  if (entry.type === 'a2a') return [entry.initiator!.agent_id, entry.responder!.agent_id];
-  return entry.agent_id ? [entry.agent_id] : [];
-}
-
-/** The `prev` a given participant declared in a log receipt, or undefined if not a party. */
-export function prevFor(
-  entry: { agent_id?: string; prev?: string | null; type?: string; initiator?: A2AParty; responder?: A2AParty },
-  agentId: string,
-): string | null | undefined {
-  if (entry.type === 'a2a') {
-    if (entry.initiator?.agent_id === agentId) return entry.initiator.prev;
-    if (entry.responder?.agent_id === agentId) return entry.responder.prev;
-    return undefined;
-  }
-  return entry.agent_id === agentId ? (entry.prev as string | null) : undefined;
-}
+/**
+ * Cross-org co-signed receipts — SPEC §9. One interaction, two signers, one
+ * neutral proof that enters both agents' hash chains.
+ */
+import { ed25519 } from '@noble/curves/ed25519';
+import { canonicalBytes, decodeSig, encodeSig, jcsHash } from './encoding.js';
+import { publicKeyFromDid } from './keys.js';
+import { scopesAllow, verifyChain, type DelegationCert } from './delegation.js';
+import type { VerifyResult } from './receipt.js';
+
+export interface A2AParty {
+  agent_id: string;
+  delegation: DelegationCert[];
+  prev: string | null;
+  sig: string;
+}
+
+export interface A2AReceipt {
+  v: 1;
+  type: 'a2a';
+  action: string;
+  target: string;
+  payload_hash: string;
+  ts: string;
+  initiator: A2AParty;
+  responder: A2AParty;
+}
+
+/** The body both parties sign: the receipt with both sig fields removed. */
+export type A2ABody = Omit<A2AReceipt, 'initiator' | 'responder'> & {
+  initiator: Omit<A2AParty, 'sig'>;
+  responder: Omit<A2AParty, 'sig'>;
+};
+
+export function buildA2ABody(fields: {
+  action: string;
+  target: string;
+  payloadHash: string;
+  ts: string;
+  initiator: Omit<A2AParty, 'sig'>;
+  responder: Omit<A2AParty, 'sig'>;
+}): A2ABody {
+  if (Number.isNaN(Date.parse(fields.ts))) throw new Error(`invalid ts timestamp: ${fields.ts}`);
+  if (fields.initiator.agent_id === fields.responder.agent_id) {
+    throw new Error('initiator and responder must be distinct agents');
+  }
+  return {
+    v: 1,
+    type: 'a2a',
+    action: fields.action,
+    target: fields.target,
+    payload_hash: fields.payloadHash,
+    ts: fields.ts,
+    initiator: fields.initiator,
+    responder: fields.responder,
+  };
+}
+
+/** Both parties sign the identical body — order-independent. */
+export function signA2ABody(body: A2ABody, privateKey: Uint8Array): string {
+  return encodeSig(ed25519.sign(canonicalBytes(body), privateKey));
+}
+
+export function assembleA2AReceipt(body: A2ABody, initiatorSig: string, responderSig: string): A2AReceipt {
+  return {
+    ...body,
+    initiator: { ...body.initiator, sig: initiatorSig },
+    responder: { ...body.responder, sig: responderSig },
+  };
+}
+
+/** Hash of the full receipt (both sigs) — what both agents' next `prev` points to. */
+export function a2aHash(receipt: A2AReceipt): string {
+  return jcsHash(receipt);
+}
+
+export function bodyOf(receipt: A2AReceipt): A2ABody {
+  const { sig: _i, ...initiator } = receipt.initiator;
+  const { sig: _r, ...responder } = receipt.responder;
+  return { ...receipt, initiator, responder };
+}
+
+function partySigOk(body: A2ABody, party: A2AParty): boolean {
+  const pub = publicKeyFromDid(party.agent_id);
+  const sig = decodeSig(party.sig);
+  if (!pub || !sig) return false;
+  try {
+    return ed25519.verify(sig, canonicalBytes(body), pub);
+  } catch {
+    return false;
+  }
+}
+
+/** Full A2A verification per SPEC §9. `expectedPrevFor` maps agent DID → required prev. */
+export function verifyA2AReceipt(
+  receipt: A2AReceipt,
+  opts: { revoked?: Set<string>; expectedPrevFor?: Record<string, string | null> } = {},
+): VerifyResult {
+  if (receipt.v !== 1 || receipt.type !== 'a2a') return { ok: false, error: 'not an a2a receipt' };
+  if (receipt.initiator.agent_id === receipt.responder.agent_id) {
+    return { ok: false, error: 'initiator and responder must be distinct' };
+  }
+  const ts = new Date(receipt.ts);
+  if (Number.isNaN(ts.getTime())) return { ok: false, error: 'invalid ts' };
+
+  const body = bodyOf(receipt);
+  for (const [role, party] of [['initiator', receipt.initiator], ['responder', receipt.responder]] as const) {
+    if (!partySigOk(body, party)) return { ok: false, error: `${role}: bad signature` };
+    const chain = verifyChain(party.delegation, { agentId: party.agent_id, revoked: opts.revoked, at: ts });
+    if (!chain.ok) return { ok: false, error: `${role} delegation: ${chain.error}` };
+    if (!scopesAllow(chain.effectiveScopes!, receipt.target)) {
+      return { ok: false, error: `${role}: target ${receipt.target} outside effective scopes` };
+    }
+    const expected = opts.expectedPrevFor?.[party.agent_id];
+    if (expected !== undefined && party.prev !== expected) {
+      return { ok: false, error: `${role}: prev hash does not match chain head (chain broken)` };
+    }
+  }
+  return { ok: true };
+}
+
+/** The DIDs participating in any log receipt (solo or a2a). */
+type SignerLike = { agent_id?: string; prev?: string | null };
+
+export function participantsOf(entry: { agent_id?: string; type?: string; initiator?: A2AParty; responder?: A2AParty; signers?: SignerLike[] }): string[] {
+  if (entry.type === 'a2a') return [entry.initiator!.agent_id, entry.responder!.agent_id];
+  // Attribute a swarm receipt to its actual co-signers, never to declared participants
+  // who did not sign (SPEC §14) — the same rule the log uses when it indexes one.
+  if (entry.type === 'swarm') return (entry.signers ?? []).map((s) => s.agent_id).filter((a): a is string => !!a);
+  return entry.agent_id ? [entry.agent_id] : [];
+}
+
+/** The `prev` a given participant declared in a log receipt, or undefined if not a party. */
+export function prevFor(
+  entry: { agent_id?: string; prev?: string | null; type?: string; initiator?: A2AParty; responder?: A2AParty; signers?: SignerLike[] },
+  agentId: string,
+): string | null | undefined {
+  if (entry.type === 'a2a') {
+    if (entry.initiator?.agent_id === agentId) return entry.initiator.prev;
+    if (entry.responder?.agent_id === agentId) return entry.responder.prev;
+    return undefined;
+  }
+  if (entry.type === 'swarm') {
+    const signer = (entry.signers ?? []).find((s) => s.agent_id === agentId);
+    return signer ? (signer.prev ?? null) : undefined;
+  }
+  return entry.agent_id === agentId ? (entry.prev as string | null) : undefined;
+}