Developer documentation

Architecture

Last reviewed 31 August 2026

Architecture

You do not need this page to use CAIN. cain init and cain protect work

without it. Read it when you want to know why the pieces are where they are.

One platform, two deployments

CAIN Trust Fabric is the platform. It has two deployment models and they are

the same architecture:

CAIN Studio -- hosted. We operate the control plane and the enforcement

boundary; you use one API key.

MCPGate -- self-hosted. The same architecture inside your own network under

a perpetual licence. Neither traffic nor evidence leaves your infrastructure,

and no call has to reach us for a decision to be made.

A licence on either unlocks the other.

The core flow

AGENT -> CAIN -> IDENTITY -> POLICY -> AUTHORIZATION -> RISK -> VERIFICATION
      -> MCPGate -> MCP/API/TOOL -> REAL-WORLD ACTION -> EVIDENCE

Or as a sentence:

> The agent proposes. CAIN decides. MCPGate enforces. The system executes.

> Evidence remembers.

The critical property is that enforcement is in the call path, not a report

written afterwards. A blocked call never reaches the upstream service.

The principle

NO AUTHORIZATION -> NO EXECUTION.

Concretely, and testable with cain test --suite failure:

every stage returns a typed verdict, never a bare boolean
a stage that could not run returns unavailable, never a silent allow
UNKNOWN and ERROR are never converted to ALLOW
an unrecognised verdict from a newer server becomes UNKNOWN at an older client
an unreachable fabric is ERROR, and ERROR is not permission

The 7-Moat Trust Control System

CAIN is organized into seven defensive moats. Each is an independent security layer.

No single moat grants authorization; every moat enforces its own boundaries.

The Canonical Trust Loop

WHO → AUTHORITY → INTENT → SECURITY CONTEXT → POLICY → RISK → TRUST →
PREDICTION → DECISION → ENFORCEMENT → EXECUTION → EFFECT → EVIDENCE →
CAUSALITY → COUNTERFACTUAL → OUTCOME → TRUST UPDATE → NEXT DECISION

The Seven Moats

#	Moat	Status	Core Question
1	Trust State	✅ Implemented	"WHO DO WE TRUST RIGHT NOW?"
2	Security-Context Continuity	✅ Implemented	"DOES AUTHORITY SURVIVE EVERY BOUNDARY?"
3	Trust Graph	✅ Implemented	"HOW IS EVERYTHING CONNECTED?"
4	Execution Provenance & Attestation	✅ Implemented	"CAN WE PROVE WHAT ACTUALLY HAPPENED?"
5	Predictive Trust & Blast Radius	✅ Implemented	"WHAT COULD HAPPEN BEFORE WE LET IT HAPPEN?"
6	Adversarial Trust Engine	🔄 In Development	"CAN CAIN BREAK ITS OWN TRUST GUARANTEES?"
7	Autonomous Trust Control Loop	✅ Implemented	"CAN VERIFIED EXPERIENCE CHANGE FUTURE TRUST?"

See [Full 7-Moat Documentation](docs/architecture/CAIN-7-MOATS.md) for complete details.

Where trust is anchored

The tenant is resolved server-side from the credential, never from anything

the caller sends. Spend caps, call budgets and containment thresholds are held

server-side. An agent cannot raise its own ceiling. cain test --suite redteam

attempts to break this via six different headers.

Honest limits

See what CAIN does not do yet. Short

version: no third-party certification, no independent penetration test, single

region for the hosted deployment, and enforcement is opt-in per deployment.