-
Notifications
You must be signed in to change notification settings - Fork 4
Building an independent CHAP implementation
An independently authored implementation is one of the strongest ways to test whether CHAP is truly a protocol rather than the accidental behaviour of its reference code.
CHAP 0.2 is a public draft with TypeScript and Python reference implementations from the same project team. They exercise the protocol and conformance suite, but independent implementation is the more demanding interoperability test.
A third implementation forces the specification to stand on its own. It reveals ambiguous requirements, hidden assumptions, language-specific data handling and places where the conformance vectors test the reference code rather than the intended wire behaviour.
Rust, Go, Java, C#, Kotlin and other ecosystems are all valuable. A small Core implementation with excellent test evidence is more useful than a broad package that copies every optional profile without independent scrutiny.
Start with one of three goals:
| Goal | Best first scope |
|---|---|
| Learn and review the protocol | Envelope parser, canonicalisation, signatures and evidence verification |
| Build an interoperable client | Core method models, transport, validation and audit verification |
| Build a Coordinator | Core workspace, participant, task, routing, policy and evidence behaviour |
Do not begin with every optional profile and transport. Declare which methods, profiles and versions are supported so users can distinguish omission from failure.
Use the normative specification, Core document, JSON Schemas and conformance vectors as your starting material. The reference implementations are useful for differential testing, but copying their internal structure can reproduce the same hidden assumptions.
Record questions as specification issues. If two reasonable implementations interpret a requirement differently, that is valuable protocol feedback even when both programs appear internally consistent.
Implement required fields, method-specific parameter validation, identifier handling, timestamps and error responses. Reject malformed input predictably and avoid accepting extra fields where a schema forbids them.
CHAP uses JSON Canonicalization Scheme concepts so equivalent data has a stable byte representation for hashing and signing. Test Unicode, number representation, object key ordering and nested structures across language boundaries.
Implement the required signing behaviour and make key handling replaceable. Cryptographic correctness deserves focused tests and established libraries rather than custom primitives.
Each accepted signed message should extend the workspace's evidence history according to the specification. Verify ordering, previous-hash relationships, replay handling and behaviour when an entry is invalid or missing.
Model membership, participant types and Coordinator behaviour explicitly. Test forbidden senders, unknown recipients, duplicate joins and operations against absent workspaces.
Enforce allowed transitions and preserve exact artefact references. A method returning success should have the same observable meaning across implementations, not merely the same JSON shape.
Implement one transport well before adding adapters. The protocol semantics should remain identical whether a caller reaches the Coordinator directly or through MCP or A2A.
- Pin the CHAP draft version and conformance revision.
- Run schema and vector tests locally.
- Test both valid and intentionally invalid envelopes.
- Compare canonical bytes, hashes and signatures with the reference implementations.
- Exchange real requests with at least one reference server over the wire.
- Export evidence in one implementation and verify it in another.
- Test retries, duplicates, reordering and partial failure.
- Publish the results, unsupported cases and exact commit identifiers.
Passing a vector suite is necessary evidence, not the entire interoperability claim. Add end-to-end tests that cross implementation boundaries.
- Non-ASCII participant names and artefact content.
- JSON numbers and language-specific numeric limits.
- Duplicate object keys at the parser boundary.
- Clock skew and invalid timestamp formats.
- Replayed message identifiers.
- Key rotation and expired credentials.
- Missing or corrupted evidence entries.
- Concurrent task updates.
- An override against the wrong artefact version.
- A decision from a participant without authority.
- Transport retry after the Coordinator accepted the original request.
These cases often expose more protocol ambiguity than a successful happy-path demo.
A practical order is:
- Core collaboration and audit behaviour.
- Review and decision semantics.
- Override, abstention, escalation and handoff where needed.
- Stronger identity and signing profiles.
- MCP or A2A composition.
- External evidence anchoring and advanced profiles.
Publish a capability matrix. Users should be able to tell whether a peer supports a profile before sending methods that depend on it.
Protocol conformance does not guarantee a secure deployment. Threat-model untrusted payloads, signature verification, key storage, authorisation, denial of service, evidence growth, external references and adapter boundaries.
Use safe defaults. Limit payload and log sizes, validate URLs, avoid loading remote artefacts implicitly, separate authentication from a caller-supplied participant ID, and make policy failures explicit.
An independent project becomes easier to evaluate when it includes:
- Supported CHAP version and profiles.
- Language and runtime requirements.
- Conformance command and machine-readable results.
- A small interoperable example.
- Security assumptions and limitations.
- A mapping to normative specification sections.
- Package licence and contribution process.
- Contact route for cross-implementation testing.
Ask to be added to CHAP's implementation registry only after another party can reproduce the claims.
You do not need a finished Coordinator to improve the protocol. Useful contributions include a canonicalisation test corpus, a signature verifier, a schema generator, a packet capture from cross-language exchange, a precise ambiguity report or a new negative conformance vector.
The best independent implementation is not the one that agrees silently with the reference. It is the one that makes the specification clearer for everyone.
- MCP, A2A and CHAP: how the open agent stack fits together
- How CHAP works with A2A
- What CHAP proves, and does not prove, for AI governance
- CHAP Core specification
- Combined CHAP specification
- CHAP schemas
- CHAP conformance suite
- CHAP implementation registry
- CHAP governance
Building CHAP in another language is one of the most valuable contributions available. Star the repository, open an implementation issue and publish your first failing interoperability case.
Last reviewed: 25 August 2026.