@zanii/sdk

Instrument any AI agent to emit signed, hash-chained action receipts to a Zanii transparency log — and verify those proofs with zero trust in the server. Every action carries the agent's did:key identity and a delegation chain proving it was authorized; every receipt is anchored in an RFC 6962 Merkle log.

npm install @zanii/sdk

Quickstart

import {
  ZaniiAgent,
  fetchAndVerifyProof,
  generateKeypair,
  createCert,
} from '@zanii/sdk';

// 1. Identities. The owner delegates a scoped, expiring capability to the agent.
const owner = generateKeypair();
const agent = generateKeypair();
const cert = createCert(
  { issuer: owner.did, subject: agent.did, scopes: ['crm.*'], exp: '2027-01-01T00:00:00Z' },
  owner.privateKey,
);

// 2. Instrument the agent. Signing is local; shipping is batched.
const zanii = new ZaniiAgent({
  serverUrl: 'https://ledger.zanii.agency',
  agentDid: agent.did,
  agentPrivateKey: agent.privateKey,
  delegation: [cert],
  // apiKey: 'zk_live_...',   // required when the log enforces write auth
});

// Wrap any tool so every call is receipted automatically:
const lookup = zanii.wrapTool('crm.lookup', (email: string) => crm.find(email));
await lookup('[email protected]');

// ...or record explicitly, then verify the proof offline:
const { hash } = await zanii.record({ target: 'crm.lookup', payload: { email: '[email protected]' } });
await zanii.flush();

const proof = await fetchAndVerifyProof('https://ledger.zanii.agency', hash);
if (!proof.ok) throw new Error(`unverifiable: ${proof.error}`);

What's included

• Delegation — scoped, expiring, revocable capability certificates.
• Cross-org receipts — two agents from different orgs co-sign a single A2A receipt, so a hand-off is provable by both sides.
• fetchAndVerifyProof() — pull a receipt and its Merkle inclusion proof and verify signatures, scope, and log membership without trusting the server.

For the pure, I/O-free protocol primitives (verify receipts and audit bundles with no client), see @zanii/core.

Links

• Docs & concepts — https://ledger.zanii.agency/docs
• Live transparency log — https://ledger.zanii.agency

Changelog

• 0.4.0 — record({ subjectTag }): stamp a pseudonymous data-subject tag on a receipt (per-subject auditability, @zanii/subject).
• 0.3.0 — record() salts the payload hash by default (privacy/PDPL; opt out with salt:false); nonceStore + MemoryNonceStore; optional provenance on record; re-exports saltedPayloadHash/verifyPayload.
• 0.2.1 — @zanii/sdk now re-exports the full verification + revocation surface from @zanii/core (verifyReceipt, verifyA2AReceipt, verifyAuditBundle, verifyRevocation, verifyChain, verifyCertSignature, verifySTH, verifyInclusion, verifyConsistency, createRevocation, + BundleReport/VerifyResult/ChainResult types) — a single @zanii/sdk install now builds and verifies.
• 0.2.0 — version bump in lockstep with the package family.
• 0.1.0 — initial release: ZaniiAgent (record / wrapTool / flush), delegation helpers, and fetchAndVerifyProof for zero-trust verification.

License

Apache-2.0.