@zanii/core 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zanii/core",
+  "version": "0.1.0",
+  "description": "Zanii protocol: verifiable identity, signed action receipts, Merkle transparency-log proofs. Pure, no I/O.",
+  "license": "Apache-2.0",
+  "homepage": "https://ledger.zanii.agency",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.8.1",
+    "@noble/hashes": "^1.7.1",
+    "@scure/base": "^1.2.4",
+    "canonicalize": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "demo": "tsx demo.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/a2a.ts

@@ -0,0 +1,139 @@
+/**
+ * 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;
+}

package/src/bundle.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 },
+    };
+  }
+}

package/src/delegation.ts

@@ -0,0 +1,134 @@
+import { ed25519 } from '@noble/curves/ed25519';
+import { canonicalBytes, decodeSig, encodeSig, jcsHash } from './encoding.js';
+import { publicKeyFromDid } from './keys.js';
+
+export interface DelegationCert {
+  v: 1;
+  issuer: string;
+  subject: string;
+  scopes: string[];
+  exp: string;
+  sig: string;
+}
+
+export interface ChainResult {
+  ok: boolean;
+  error?: string;
+  /** Only set when ok. Scopes the final subject may act under. */
+  effectiveScopes?: string[];
+}
+
+export function createCert(
+  fields: { issuer: string; subject: string; scopes: string[]; exp: string },
+  issuerPrivateKey: Uint8Array,
+): DelegationCert {
+  if (fields.scopes.length === 0) throw new Error('cert must grant at least one scope');
+  if (Number.isNaN(Date.parse(fields.exp))) throw new Error(`invalid exp timestamp: ${fields.exp}`);
+  const unsigned = { v: 1 as const, ...fields };
+  const sig = ed25519.sign(canonicalBytes(unsigned), issuerPrivateKey);
+  return { ...unsigned, sig: encodeSig(sig) };
+}
+
+/** Hash of the full cert (incl. sig) — the revocation identifier. */
+export function certHash(cert: DelegationCert): string {
+  return jcsHash(cert);
+}
+
+/** Does `scope` cover `target`? `a.*` covers `a`, `a.b`, `a.b.c`, `a.*`; `*` covers all. */
+export function scopeCovers(scope: string, target: string): boolean {
+  if (scope === '*') return true;
+  if (scope === target) return true;
+  if (scope.endsWith('.*')) {
+    const prefix = scope.slice(0, -2);
+    return target === prefix || target.startsWith(prefix + '.');
+  }
+  return false;
+}
+
+export function scopesAllow(scopes: string[], target: string): boolean {
+  return scopes.some((s) => scopeCovers(s, target));
+}
+
+/** In-log revocation record — SPEC §6. Only the cert's issuer can revoke it. */
+export interface RevocationRecord {
+  v: 1;
+  type: 'revocation';
+  cert: DelegationCert;
+  ts: string;
+  sig: string;
+}
+
+export function createRevocation(cert: DelegationCert, ts: string, issuerPrivateKey: Uint8Array): RevocationRecord {
+  if (Number.isNaN(Date.parse(ts))) throw new Error(`invalid ts timestamp: ${ts}`);
+  const unsigned = { v: 1 as const, type: 'revocation' as const, cert, ts };
+  const sig = ed25519.sign(canonicalBytes(unsigned), issuerPrivateKey);
+  return { ...unsigned, sig: encodeSig(sig) };
+}
+
+/** Valid iff the embedded cert verifies AND the record is signed by the cert's issuer. */
+export function verifyRevocation(record: RevocationRecord): boolean {
+  if (record.v !== 1 || record.type !== 'revocation') return false;
+  if (!record.cert || !verifyCertSignature(record.cert)) return false;
+  const pub = publicKeyFromDid(record.cert.issuer);
+  const sig = decodeSig(record.sig);
+  if (!pub || !sig) return false;
+  const { sig: _omitted, ...unsigned } = record;
+  try {
+    return ed25519.verify(sig, canonicalBytes(unsigned), pub);
+  } catch {
+    return false;
+  }
+}
+
+export function verifyCertSignature(cert: DelegationCert): boolean {
+  const pub = publicKeyFromDid(cert.issuer);
+  const sig = decodeSig(cert.sig);
+  if (!pub || !sig) return false;
+  const { sig: _omitted, ...unsigned } = cert;
+  try {
+    return ed25519.verify(sig, canonicalBytes(unsigned), pub);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate a delegation chain (root first) per SPEC §2.
+ * `at` defaults to now; `revoked` is a set of cert hashes.
+ */
+export function verifyChain(
+  chain: DelegationCert[],
+  opts: { agentId: string; expectedRoot?: string; revoked?: Set<string>; at?: Date },
+): ChainResult {
+  if (!Array.isArray(chain) || chain.length === 0) return { ok: false, error: 'empty delegation chain' };
+  const at = opts.at ?? new Date();
+  const root = chain[0]!;
+
+  if (opts.expectedRoot && root.issuer !== opts.expectedRoot) {
+    return { ok: false, error: `root issuer ${root.issuer} is not expected owner ${opts.expectedRoot}` };
+  }
+  if (chain[chain.length - 1]!.subject !== opts.agentId) {
+    return { ok: false, error: 'chain does not terminate at the agent' };
+  }
+
+  // Fold scopes down the chain: a delegate can only narrow, never widen.
+  // ponytail: widening scopes are silently dropped, not rejected — reject-on-widen when policy UX exists (Phase 2)
+  let effectiveScopes: string[] = [];
+  for (let i = 0; i < chain.length; i++) {
+    const cert = chain[i]!;
+    if (cert.v !== 1) return { ok: false, error: `cert ${i}: unsupported version` };
+    if (i > 0 && cert.issuer !== chain[i - 1]!.subject) {
+      return { ok: false, error: `cert ${i}: issuer does not match previous subject` };
+    }
+    const exp = Date.parse(cert.exp);
+    if (Number.isNaN(exp)) return { ok: false, error: `cert ${i}: invalid exp` };
+    if (at.getTime() >= exp) return { ok: false, error: `cert ${i}: expired` };
+    if (opts.revoked?.has(certHash(cert))) return { ok: false, error: `cert ${i}: revoked` };
+    if (!verifyCertSignature(cert)) return { ok: false, error: `cert ${i}: bad signature` };
+
+    effectiveScopes = i === 0 ? [...cert.scopes] : cert.scopes.filter((s) => scopesAllow(effectiveScopes, s));
+  }
+
+  if (effectiveScopes.length === 0) return { ok: false, error: 'chain grants no effective scopes' };
+  return { ok: true, effectiveScopes };
+}

package/src/encoding.ts

@@ -0,0 +1,30 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
+import canonicalizeImport from 'canonicalize';
+
+// canonicalize is CJS (`module.exports = fn`) with a .d.ts that hides the call signature
+const canonicalizeJson = canonicalizeImport as unknown as (o: unknown) => string | undefined;
+
+/** RFC 8785 canonical JSON, UTF-8 bytes. Throws on non-serializable input. */
+export function canonicalBytes(obj: unknown): Uint8Array {
+  const s = canonicalizeJson(obj);
+  if (typeof s !== 'string') throw new Error('value is not canonicalizable JSON');
+  return new TextEncoder().encode(s);
+}
+
+/** `sha256:<hex>` of the JCS form of obj. */
+export function jcsHash(obj: unknown): string {
+  return `sha256:${bytesToHex(sha256(canonicalBytes(obj)))}`;
+}
+
+export function encodeSig(sig: Uint8Array): string {
+  return `ed25519:${bytesToHex(sig)}`;
+}
+
+/** Returns null instead of throwing: verification paths must not crash on malformed input. */
+export function decodeSig(s: string): Uint8Array | null {
+  if (typeof s !== 'string' || !s.startsWith('ed25519:')) return null;
+  const hex = s.slice('ed25519:'.length);
+  if (!/^[0-9a-f]{128}$/.test(hex)) return null;
+  return hexToBytes(hex);
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+export { generateKeypair, didFromPublicKey, publicKeyFromDid, type Keypair } from './keys.js';
+export { canonicalBytes, jcsHash } from './encoding.js';
+export {
+  createCert,
+  certHash,
+  createRevocation,
+  verifyRevocation,
+  verifyCertSignature,
+  verifyChain,
+  scopeCovers,
+  scopesAllow,
+  type DelegationCert,
+  type RevocationRecord,
+  type ChainResult,
+} from './delegation.js';
+export {
+  leafHash,
+  merkleRoot,
+  inclusionProof,
+  verifyInclusion,
+  consistencyProof,
+  verifyConsistency,
+} from './merkle.js';
+export { createSTH, verifySTH, type SignedTreeHead } from './sth.js';
+export {
+  buildA2ABody,
+  signA2ABody,
+  assembleA2AReceipt,
+  a2aHash,
+  bodyOf,
+  verifyA2AReceipt,
+  participantsOf,
+  prevFor,
+  type A2AReceipt,
+  type A2ABody,
+  type A2AParty,
+} from './a2a.js';
+export {
+  verifyAuditBundle,
+  type AuditBundle,
+  type BundledReceipt,
+  type BundledRevocation,
+  type BundledAnchor,
+  type BundleReport,
+  type BundleCheck,
+} from './bundle.js';
+export {
+  createReceipt,
+  receiptHash,
+  hashPayload,
+  verifyReceipt,
+  verifyReceiptSignature,
+  verifyReceiptChain,
+  type Receipt,
+  type VerifyResult,
+} from './receipt.js';

package/src/keys.ts

@@ -0,0 +1,38 @@
+import { ed25519 } from '@noble/curves/ed25519';
+import { base58 } from '@scure/base';
+
+const ED25519_MULTICODEC = Uint8Array.from([0xed, 0x01]);
+const DID_PREFIX = 'did:key:z';
+
+export interface Keypair {
+  privateKey: Uint8Array;
+  publicKey: Uint8Array;
+  did: string;
+}
+
+export function generateKeypair(): Keypair {
+  const privateKey = ed25519.utils.randomPrivateKey();
+  const publicKey = ed25519.getPublicKey(privateKey);
+  return { privateKey, publicKey, did: didFromPublicKey(publicKey) };
+}
+
+export function didFromPublicKey(publicKey: Uint8Array): string {
+  if (publicKey.length !== 32) throw new Error('ed25519 public key must be 32 bytes');
+  const prefixed = new Uint8Array(2 + 32);
+  prefixed.set(ED25519_MULTICODEC);
+  prefixed.set(publicKey, 2);
+  return DID_PREFIX + base58.encode(prefixed);
+}
+
+/** Returns null instead of throwing: verification paths must not crash on malformed input. */
+export function publicKeyFromDid(did: string): Uint8Array | null {
+  if (typeof did !== 'string' || !did.startsWith(DID_PREFIX)) return null;
+  let decoded: Uint8Array;
+  try {
+    decoded = base58.decode(did.slice(DID_PREFIX.length));
+  } catch {
+    return null;
+  }
+  if (decoded.length !== 34 || decoded[0] !== 0xed || decoded[1] !== 0x01) return null;
+  return decoded.slice(2);
+}