Portable, non-authorizing charter-agreement format and verification protocol for bilateral commercial agreements. CAP verifies signed, byte-exact evidence of what two parties agreed, which revision governed a given instant, and which agreement state governed a signed action — without a central authority, and without ever making the decision for you.
CAP verifies. It never authorizes. Every facts record carries a closed
twelve-item not_verified floor — authority, execution, billing, term
satisfaction, legal validity, and more — that no API can shrink. Hosts read
the evidence and decide.
What it does
| Artifact | Form | Proves |
|---|---|---|
| Party Descriptor | signed JWS (cap+party) | A party's Ed25519 key history with predecessor-bound transitions and fork evidence |
| Charter Revision | canonical JSON | Agreed terms: parties, roles, legal-text digest, precedence, effective window, termination reasons, exact deployment bindings |
| Acceptance | signed JWS (cap+acceptance) | Bilateral signed assent to exact revision bytes |
| Termination Notice | signed JWS (cap+termination) | Signed closure of the charter at a pure UTC instant |
| Receipt | signed JWS (cap+receipt) | A signed action bound to exact revision coordinates, deployment digest, and grant evidence |
Set-level verification composes the artifacts into structural facts:
verify_chain/5 re-verifies everything from raw bytes;
governing_revision/2 answers "which revision governed at this instant" with
a digest, :contested, or :none — never a silent tie-break. Same-signer
equivocation is retained as signed evidence with no winner. The only repair
for a contested view is a countersigned supersession revision.
The foundation is byte-exact by construction: strict unpadded base64url, deterministic tagged JSON decoding, RFC 8785 canonicalization, and domain-separated SHA-256 digests. A certified 85-case corpus runs through a pure Elixir runner and a builtins-only Node TypeScript verifier that must produce byte-identical canonical reports — two independent implementations, zero shared code.
When to use it — and when not
Use CAP when two independent parties need portable, re-verifiable agreement evidence exchanged as bytes: agent commerce charters, bilateral supplier terms, key-history continuity proofs, action receipts for audit.
Do not use CAP for authorization decisions, live revocation checks, term
evaluation (CAP leaves term_satisfaction in its omission floor), legal
adjudication, or single-party self-attestation — every one of those is
explicitly outside what verification proves. See the
security model for the full proves/never-proves
table.
Quick start
Elixir ~> 1.20; zero runtime dependencies (OTP :crypto only):
{:charter_agreement_protocol, "~> 0.1.0"}Then verify the shipped, certified corpus from your dependent project:
$ mix run -e 'CharterAgreementProtocol.Conformance.Cli.run(["--corpus", "deps/charter_agreement_protocol/priv/conformance"])'
The command prints the canonical JSON report; a returned status of 0 means
all 85 certified cases recomputed and agreed. Full walkthrough:
Getting started.
Try it
- Runnable notebooks: charter tour and fork repair — a complete bilateral charter with real Ed25519 signatures, and a manufactured equivocation with its countersigned repair.
- Repository demo:
mix run examples/supplier_fork_demo.exs— equivocation evidence, contested governing view, an action receipt inside the fork, and the repair, in nine lines of output.
Guarantees at the call boundary
- Failures are typed and value-free — closed error codes, protocol-owned subjects, never rejected input — so verification failures are safe to log.
- Facts implement redacted inspection — retained signed artifacts never appear in logs.
- Verification is pure: no clock, filesystem, network, or environment. Callers supply time, limits, trust anchors, and keys.
- Key custody stays outside the protocol: CAP builds the exact RFC 7515
signing input, you sign it,
assemble_compact/2accepts only an external raw 64-byte signature, and hosts post-verify before serving the compact.
Guides
- Overview — the problem, the artifact family, the design principles
- Getting started — install, first verification, first signature
- Artifacts — every artifact's wire shape and closed claim set
- Verification semantics — forks, contested views, supersession, governing computation
- Receipts — binding actions to agreements; ABP and BAP identity composition
- Extensions and profiles — the registry, criticality, quarantine
- Security model — proves / never proves, the omission floor, architecture enforcement
- Recipes — end-to-end integration patterns
- Conformance — the certified corpus, the gate battery, the certified identities
- FAQ
- Protocol foundation — the normative specification
- Indexed-price profile, errata policy, ADRs: no version tokens in identifiers, conformance and release-candidate boundary
Status
The approved protocol core, normative specification set, certified corpus
with four recorded identities, independent second verifier, mutation
battery, and release-candidate gates are implemented and green in CI. The
0.2.0 package adds protocol_revision 2 (the RFC 9864 alg-name bundle —
Ed25519 emission, dual-name acceptance, the per-artifact binding rule);
0.1.0 artifacts remain verifiable. Building an archive remains
verification evidence only — never authority to publish.
Development
mix deps.get
mix qualitymix quality is the complete gate — audits, formatting, warnings-as-errors
compile, strict credo, the full test suite with its coverage threshold,
certified-conformance verification and regeneration identity, all 22 named
source mutations, Elixir/TypeScript verifier agreement over repository and
unpacked-package corpora, dialyzer, docs, and the reproducible
release-candidate archive. Contribution bar and invariants:
CONTRIBUTING.md.
License
Apache-2.0 — see LICENSE.