Component Model

The cA2A runtime is a set of small, composable modules under src/. Each maps to one primitive in How It Works. This page describes what each component is, what it exposes, and whether it is implemented today or a placeholder for pending Tier 2/Tier 3 work. Nothing here describes behavior that is not in the source.

Components

delegation

ca2a_runtime.delegation.credential holds the credential model and the offline chain verifier. DelegationCredential is a frozen dataclass with a signed body() (everything but the signature) and a detached Ed25519 signature. new_keypair() returns a fresh Ed25519PrivateKey and its raw-hex public key. verify_chain(chain, *, max_depth=8) walks a root-to-leaf list and raises the specific error for the first failed invariant: signature, continuity, attenuation, depth, and anti-replay. This is the implemented core. See delegation chain.

provenance

ca2a_runtime.provenance is the runtime-evidence side. DelegationRecord is a frozen dataclass whose record_hash() is a SHA-256 over its canonical body, so any field change breaks a child's link. record_for(credential, record_id, parent_record_hash) builds the record a hop emits. verify_dag(records) confirms a root-to-leaf provenance chain (root has no parent link, each later record's parent_record_hash equals the recomputed hash of the previous record, no repeated record_id). cross_check_chain(records, chain) ties provenance to authority: record i must reference credential i and carry the same subject. Implemented. The full TRACE binding lands with Tier 2. See TRACE A2A profile and provenance DAG.

verify

ca2a_verify.verify is a thin offline wrapper over the delegation verifier. verify_delegation_chain(chain, *, trusted_root_issuers, max_depth=8) returns a ChainResult (hops, root_issuer, leaf_subject, leaf_scope); verify_chain_file(path, *, trusted_root_issuers, max_depth=8) loads a chain from JSON (a list, or {"chain": [...]}) and verifies it. The explicit local root trust set is mandatory: signatures alone establish consistency, not authorization. VerificationError is re-exported as CA2AError so callers catch one type. Implemented. See verification library.

channel

ca2a_runtime.channel.sealed defines SealedChannel, the measurement-bound peer channel. Instantiation is allowed so the runtime can be wired against the interface, but seal() and open() fail closed with SEALED_CHANNEL_ERROR today. This is Tier 2 and not yet implemented; do not send confidential payloads across a trust boundary and assume they are protected. See sealed channel and LIMITATIONS.md.

tee

ca2a_runtime.tee.base defines the provider interface and evidence model. AttestationReport is a frozen dataclass binding a public_key to a measurement under a nonce on a named platform, plus four optional evidence fields (raw_evidence, quote_signature, attestation_key_pem, attestation_key_chain_pem) that make those claims checkable. BaseProvider is an ABC with detect() and attest(public_key, nonce), and the two must agree: detect() is True only where attest() works. TPM, SEV-SNP and TDX all have collectors, the latter two through the kernel configfs-TSM interface; OPAQUE has a verifier but no collector, so its attest() raises and verification fails closed. See attestation.

config

ca2a_runtime.config holds Ca2aConfig, a frozen dataclass validated by from_dict() / load(): provider (from VALID_PROVIDERS), enforcement_mode (from VALID_ENFORCEMENT), max_delegation_depth, policy_bundle_path, local_policy, and listen_addr. Invalid values raise CONFIG_ERROR. ca2a_runtime.bootstrap turns a validated config into a running PeerNode: it resolves the policy from local_policy or policy_bundle_path and the provider from provider, both fail-closed. enforcement_mode is still only recorded; the peer path always fails closed on a denial.

errors

ca2a_runtime.errors is the central registry. Every error is a CA2AError subclass carrying a stable code and an http_status: CONFIG_ERROR, INVALID_CREDENTIAL, SCOPE_ESCALATION, BROKEN_DELEGATION_LINK, DELEGATION_DEPTH_EXCEEDED, CREDENTIAL_REPLAY, ATTESTATION_UNSUPPORTED, ATTESTATION_FAILED, SEALED_CHANNEL_ERROR, PROVENANCE_LINK_BROKEN. See error codes.

cli

ca2a_runtime.cli exposes the ca2a command. validate-config --config loads and validates a Ca2aConfig, verify-chain --chain --trusted-root-issuer [--max-depth] calls verify_chain_file, and verify-dag --dag [--chain --trusted-root-issuer] verifies a provenance DAG; all three operate offline. start --config is the one online command: it builds a PeerNode through ca2a_runtime.bootstrap and serves it with ca2a_runtime.transport.server.

Component map

Component	Module	Key API	Status
delegation	ca2a_runtime.delegation.credential	DelegationCredential, new_keypair, verify_chain	Implemented
provenance	ca2a_runtime.provenance	DelegationRecord, record_for, verify_dag, cross_check_chain	Implemented
verify	ca2a_verify.verify	verify_delegation_chain, verify_chain_file, ChainResult	Implemented
config	ca2a_runtime.config	Ca2aConfig	Implemented
bootstrap	ca2a_runtime.bootstrap	load_policy, select_provider, build_peer_node	Implemented
errors	ca2a_runtime.errors	CA2AError and subclasses	Implemented
cli	ca2a_runtime.cli	ca2a validate-config, ca2a verify-chain, ca2a verify-dag, ca2a start	Implemented
channel	ca2a_runtime.channel.sealed	SealedChannel	Placeholder, fails closed (Tier 2)
tee	ca2a_runtime.tee.base	BaseProvider, AttestationReport	Interface only; hardware backends pending (Tier 3)

How they compose on an inbound peer call

The intended peer path threads these components together. Steps 2 through 5 below are the target composition; the implemented parts today are the chain and provenance verification an offline verifier can run over signed evidence.

1. A hands B a child credential with scope ⊆ A's scope. This is the delegation model, implemented.
2. Before B accepts, the runtime verifies the chain with verify_chain and intersects the delegated scope with a local Cedar policy under B's enforcement_mode. Chain verification is implemented; runtime enforcement and Cedar scope intersection are Tier 2 and not yet built. See Cedar policy.
3. B's tee provider produces an AttestationReport; the runtime checks the measurement. The interface exists, but no hardware backend verifies a quote yet (Tier 3), so this fails closed. See attestation.
4. The task payload is sealed to B's measurement through SealedChannel. Tier 2, fails closed today. See sealed channel.
5. B emits a DelegationRecord linking to A's record via record_for, and any verifier can later run verify_dag and cross_check_chain offline. Implemented. See TRACE A2A profile.

What ships today is the offline path: given signed credentials and records, ca2a_verify and provenance reconstruct and check the delegation tree without trusting the operators that produced it. The runtime peer enforcement, sealed channel, Cedar intersection, and hardware attestation that would gate a live call are pending. See failure modes, ROADMAP.md, and LIMITATIONS.md.