@aip-protocol/aip

Status: v1.1.0 (wire-breaking alignment with the AIP whitepaper). The whitepaper is canonical. Anything tagged NORMATIVE in docs/aip-v1.0-spec.md is locked; the spec is the authority of record. See KNOWN-LIMITS.md for the documented v1.1.0 scope boundaries (Groth16 as a permitted proving-system variant, single-party ceremony PENDING, no production Halo2 tooling yet, aip-attest-v1 is a real Poseidon-Merkle-in-circuit).

The Agent Interoperability Protocol (AIP) is an open-source, embeddable set of primitives for cognitive workflows between software agents: W3C-style did:aip:<AGENT_TYPE>:<base32> identifiers, Ed25519 signing, a hash-chained signed audit log, a §4 MessageEnvelope contract, a §6 handshake (capability intersection), the §13 OPAL cycle (ORIENT → PLAN → EXECUTE → LEARN), and a §5.3 use-once ZK attestation (Halo2 / BN254 normative, Groth16 as a permitted variant).

The AIP module is brand-neutral at the contract level: it refuses to construct a DID, sign an envelope, or write an audit entry until the host application supplies a DIDProvider at startup. The brand-neutrality of the implementation is what makes the open-source protocol credible - any host, any deployment, any founder can use these primitives without leaking their identity.

---

What's new in v1.1.0

v1.1.0 is a wire-breaking release that aligns the code to the canonical AIP whitepaper. The v1.0.1 → v1.1.0 migration is summarized below; for the full list see CHANGELOG.md.

• Envelope wire format: messageId → envelopeId, sender.did → from, recipient.did → to, timestamp → issuedAt. New required fields: expiresAt (default: issuedAt + 5 min) and previousHash (SHA-256 chain anchor; null on the first envelope of a session).
• Audit entry wire format: auditId → entryId, actorDID → actorAgentType, timestamp → issuedAt, previousEntryHash → previousHash. New required field: aipVersion: "1.1.0".
• DID method: did:aip:<AGENT_TYPE>:<base32> (was the v1.0.1 did:aip:<namespace>:<uuid-prefix>). The AIP_NAMESPACE env var is gone.
• DID document: W3C verificationMethod (was v1.0.1 publicKey). The dropped v1.0.1 fields (version, owner, controller, delegationScope.allowedDelegators, auditEndpoint) are not in the whitepaper and are not in v1.1.0.
• Handshake state machine: INIT → OFFER_SENT → REPLY_SENT → ESTABLISHED → CLOSED (with OFFER_REJECTED branch). v1.0.1 collapsed REPLY_SENT into ESTABLISHED/REJECTED and did not have a CLOSED state. Body field renames: requestedCapabilities → requestedCaps, matchedCapabilities → matchedCaps, missingCapabilities → unsupportedCapabilities, sessionPurpose → purpose, principalProof → principalAttestation, agentDID → agentDid. Default rejection reason is AIP_ERR_021 CAPABILITY_VECTOR_MISMATCH (was CAPABILITY_NOT_MET).
• Trust levels: numeric 0..3 per spec §12.2 (SELF_DECLARED=0, HANDSHAKE_SIGNED=1, ZKP_ATTESTED=2, MULTI_ISSUER=3). v1.0.1's string enum is kept as TRUST_LEVEL_NAMES for one release.
• Workflow state machine: dropped v1.0.1's AWAITING_APPROVAL / VETOED (not in the spec). New canonical enum: PENDING → RUNNING → COMPLETE | FAILED | CANCELLED.
• Error codes: expanded from 26 to 50 per spec §16, with corrected names (e.g. AIP_ERR_001 HANDSHAKE_OFFER_EXPIRED).
• Defaults: MAX_DELEGATION_DEPTH 2 → 5; SESSION_TTL 3600s → 86400s; key-rotation grace 24h → 30d.
• Capability vectors: canonical <domain>.<verb>[.<modifier>] form per spec §12.1 (e.g. build.code, review.code, deploy.activate). v1.0.1's mixed forms (synthesize.code, analyze.code, delegate.activate) are gone.
• Env vars: removed AIP_NAMESPACE and AIP_CALLBACK_ENDPOINT from the AIP module. The module is fully brand-neutral; the host supplies these values via explicit parameters or the DIDProvider seam.

Upgrade path. v1.1.0 is not wire-compatible with v1.0.1. Host applications need to update their envelope/audit consumers to the v1.1.0 field names and to register a DIDProvider for the getOrCreateAgentDID calls. v1.0.1 audit logs can still be verified by verifyChain (it tolerates the legacy field names); v1.0.1 envelopes cannot be re-verified as v1.1.0.

---

Install

The package is not yet published to the public npm registry. Install directly from the source repository:

npm install github:githubscum/aip-protocol#v1.1.0

Or pin to a specific commit:

npm install github:githubscum/aip-protocol#<commit-sha>

Once the package is published to npm, replace with:

npm install @aip-protocol/aip

Quick start

import{setDIDProvider,getDIDProvider,createMessageEnvelope,verifyMessageEnvelope,writeAuditEntry,getOrCreateAgentDID,AIP_VERSION,}from'@aip-protocol/aip';// 1. Wire identity. The host application decides where keys live.setDIDProvider({getDID: (agentType)=>getOrCreateAgentDID(agentType),sign: (agentType,bytes)=>/* your local key */,verify: (agentType,sig,bytes)=>/* verify */,getPrincipal: ()=>({id: '...',commitment: '...'}),});// 2. Build a signed envelope.constenv=createMessageEnvelope({fromAgentType: 'BUILDER',toDid: 'did:aip:REVIEWER:abc...',sessionId: 'sess-001',messageType: 'TASK',body: {/* task body */},});// env now has: envelopeId, aipVersion='1.1.0', from, to, sessionId,// issuedAt, expiresAt (issuedAt+5min), body, signature,// previousHash (null on the first envelope of a session)// 3. Audit it.writeAuditEntry({sessionId: 'sess-001',eventType: 'TASK_SUBMITTED',actorAgentType: 'BUILDER',summary: 'sent TASK to reviewer-7',payload: {envelopeId: env.envelopeId},});

DIDProvider

The AIP module never reads host-prefixed environment variables or hardcodes a default controller. Identity comes from the host application via setDIDProvider({...}). The required shape:

typeDIDProvider={getDID(agentType: string): AgentDIDRecord;sign(agentType: string,payload: Buffer|Uint8Array|string): string;verify(agentType: string,sig: string,payload: Buffer|Uint8Array|string): boolean;getPrincipal?(): {id: string;commitment: string};};

getPrincipal() is optional. The handshake (§6) uses it to build the principalAttestation's public inputs; providers that don't need ZK attestation can omit it and the handshake falls back to the LIGHTWEIGHT_HANDSHAKE interop mode (§6.5).

DataStore (forward direction)

A DataStore seam is defined but optional. AIP modules currently write to package-internal JSONL/JSON paths. A future version will route all reads/writes through getDataStore().

Circuits

The aip-attest-v1 circuit (spec §5.3) ships as a real Poseidon- Merkle-in-circuit with 3 public inputs (commitmentRoot, nullifier, epoch) and 2 private inputs (principalId, nonce). Both hashes are constrained in-circuit - the verifier needs only the Groth16 proof check, not an external Poseidon re-computation. The trusted-setup transcript is at circuits/aip-attest-v1.pots-transcript.txt.

Hosts that want to pin their own build can override the artifacts directory:

import{setCircuitsDir}from'@aip-protocol/aip';setCircuitsDir('/path/to/host/circuits');// or via env: AIP_CIRCUITS_DIR=/path/to/host/circuits

If you override, you MUST also update EXPECTED_VKEY_SHA256 in src/attestation.js to the SHA-256 of your aip-attest-v1.verification_key.json. The fingerprint is checked lazily on the first attest() call; a mismatch throws a descriptive error instead of running a circuit you did not expect.

The package ships build outputs only (.wasm, .zkey, verification_key.json, .circom source, pots-transcript.txt). A rebuild-circuit script is included for hosts that want to re-run the trusted setup; see package.json.

Test

npm test# node:test - 24 cases (8 envelope + 5 audit + 5 handshake + 6 attestation)
npm run smoke # brand-neutrality + barrel-export + smoke

License

Apache License 2.0 - see LICENSE.

Spec

• docs/aip-v1.0-spec.md - the authoritative protocol specification (v1.0.1, normative).
• KNOWN-LIMITS.md - what is and is not in scope for v1.1.0.
• SECURITY.md - vulnerability disclosure policy.
• CONTRIBUTING.md - how to propose changes.
• CHANGELOG.md - per-release changes.

Spec sections: §3 conventions, §4 message envelope, §5 identity & attestation, §6 handshake & session lifecycle, §7 task envelopes, §8 result envelopes, §9 error envelopes, §10 audit log, §11 routing, §12 trust levels & capability vectors, §13 workflow & OPAL, §14 key management, §15 conformance, §16 error code registry, §17 change log.

Citation

If you use AIP in a paper, product, or downstream project, please cite the v1.1.0 release. Each GitHub release gets a Zenodo DOI; the v1.1.0 DOI is below.

@software{aip_v1_1_0,
author = {Liem, Isaac},
orcid = {0009-0006-2476-1615},
title = {{AIP v1.1.0: Privacy-first audit protocol for autonomous agents}},
version = {1.1.0},
month = jul,
year = 2026,
publisher = {Zenodo},
doi = {10.5281/zenodo.21267380},
url = {https://zenodo.org/records/21267380},
note = {Reference implementation of the Agent Interoperability Protocol. Wire-level primitives: did:aip identifiers, Ed25519 signing, hash-chained signed audit log, capability-based handshake, use-once ZK attestation.}
}

DOI badge: