ca2a-runtime 0.1.0a1__py3-none-any.whl

ca2a_runtime/delegation/credential.py

@@ -0,0 +1,176 @@
+"""Delegation credential model, canonicalization, and chain verification.
+
+A delegation credential is a signed statement that ``issuer`` grants ``subject``
+a set of capability strings (``scope``), optionally as a child of ``parent_id``.
+A chain is a list of credentials ordered from root to leaf. Verification enforces
+four invariants:
+
+1. Signature: each credential verifies against its issuer's Ed25519 public key.
+2. Continuity: each hop's issuer is the previous hop's subject.
+3. Attenuation: each hop's scope is a subset of its parent's scope.
+4. Anti-replay: parent_id links to the previous credential_id and every
+   credential_id in the chain is unique.
+
+Canonicalization uses RFC 8785 (JSON Canonicalization Scheme), so the signed
+byte string is identical across conforming implementations and cA2A signatures
+are cross-verifiable with agent-manifest. See ca2a_runtime.canonical.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from ca2a_runtime.canonical import canonicalize
+from ca2a_runtime.errors import (
+    BrokenDelegationLink,
+    CredentialReplay,
+    DelegationDepthExceeded,
+    InvalidCredential,
+    ScopeEscalation,
+)
+
+
+def new_keypair() -> tuple[Ed25519PrivateKey, str]:
+    """Return a fresh Ed25519 private key and its public key as raw hex."""
+    priv = Ed25519PrivateKey.generate()
+    pub_hex = priv.public_key().public_bytes_raw().hex()
+    return priv, pub_hex
+
+
+def canonical_bytes(payload: dict[str, Any]) -> bytes:
+    """RFC 8785 (JCS) canonical byte encoding of a credential body.
+
+    This is the stable byte string signed and verified; using JCS makes cA2A
+    signatures cross-verifiable with agent-manifest and any other conforming
+    implementation. See ca2a_runtime.canonical.
+    """
+    return canonicalize(payload)
+
+
+@dataclass(frozen=True)
+class DelegationCredential:
+    """A single signed delegation hop."""
+
+    credential_id: str
+    issuer: str  # Ed25519 public key, raw hex
+    subject: str  # Ed25519 public key, raw hex
+    scope: frozenset[str]
+    depth: int
+    parent_id: str | None = None
+    signature: str = ""  # Ed25519 signature over canonical_bytes(body), hex
+
+    def body(self) -> dict[str, Any]:
+        """The signed portion of the credential (everything but the signature)."""
+        return {
+            "credential_id": self.credential_id,
+            "issuer": self.issuer,
+            "subject": self.subject,
+            "scope": sorted(self.scope),
+            "depth": self.depth,
+            "parent_id": self.parent_id,
+        }
+
+    def sign(self, private_key: Ed25519PrivateKey) -> DelegationCredential:
+        """Return a copy signed by ``private_key`` (must match ``issuer``)."""
+        expected = private_key.public_key().public_bytes_raw().hex()
+        if expected != self.issuer:
+            raise InvalidCredential(
+                "signing key does not match credential issuer",
+                detail=f"issuer={self.issuer} key={expected}",
+            )
+        sig = private_key.sign(canonical_bytes(self.body())).hex()
+        return DelegationCredential(
+            credential_id=self.credential_id,
+            issuer=self.issuer,
+            subject=self.subject,
+            scope=self.scope,
+            depth=self.depth,
+            parent_id=self.parent_id,
+            signature=sig,
+        )
+
+    def verify_signature(self) -> None:
+        """Raise InvalidCredential if the signature does not verify."""
+        if not self.signature:
+            raise InvalidCredential("credential is unsigned")
+        try:
+            pub = Ed25519PublicKey.from_public_bytes(bytes.fromhex(self.issuer))
+            pub.verify(bytes.fromhex(self.signature), canonical_bytes(self.body()))
+        except (InvalidSignature, ValueError) as exc:
+            raise InvalidCredential(
+                "credential signature failed to verify", detail=str(exc)
+            ) from exc
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DelegationCredential:
+        try:
+            return cls(
+                credential_id=str(data["credential_id"]),
+                issuer=str(data["issuer"]),
+                subject=str(data["subject"]),
+                scope=frozenset(str(s) for s in data["scope"]),
+                depth=int(data["depth"]),
+                parent_id=(None if data.get("parent_id") is None else str(data["parent_id"])),
+                signature=str(data.get("signature", "")),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise InvalidCredential("malformed credential", detail=str(exc)) from exc
+
+
+def verify_chain(
+    chain: list[DelegationCredential], *, max_depth: int = 8
+) -> None:
+    """Verify a root-to-leaf delegation chain, raising on the first violation.
+
+    A well-formed chain of length N delegates from the root issuer down to the
+    leaf subject with monotonically narrowing scope. Raises the specific
+    CA2AError subtype for the invariant that failed.
+    """
+    if not chain:
+        raise BrokenDelegationLink("empty delegation chain")
+
+    seen_ids: set[str] = set()
+    prev: DelegationCredential | None = None
+
+    for i, cred in enumerate(chain):
+        cred.verify_signature()
+
+        if cred.credential_id in seen_ids:
+            raise CredentialReplay(f"duplicate credential_id at hop {i}: {cred.credential_id}")
+        seen_ids.add(cred.credential_id)
+
+        if cred.depth > max_depth:
+            raise DelegationDepthExceeded(
+                f"hop {i} depth {cred.depth} exceeds max {max_depth}"
+            )
+
+        if prev is None:
+            if cred.parent_id is not None:
+                raise BrokenDelegationLink("root credential must not name a parent")
+            if cred.depth != 0:
+                raise BrokenDelegationLink("root credential must have depth 0")
+        else:
+            if cred.parent_id != prev.credential_id:
+                raise BrokenDelegationLink(
+                    f"hop {i} parent_id does not match previous credential_id"
+                )
+            if cred.issuer != prev.subject:
+                raise BrokenDelegationLink(
+                    f"hop {i} issuer is not the previous hop's subject"
+                )
+            if cred.depth != prev.depth + 1:
+                raise BrokenDelegationLink(f"hop {i} depth is not previous + 1")
+            if not cred.scope.issubset(prev.scope):
+                escalated = sorted(cred.scope - prev.scope)
+                raise ScopeEscalation(
+                    f"hop {i} scope exceeds parent grant", detail=f"added: {escalated}"
+                )
+
+        prev = cred

ca2a_runtime/errors.py

@@ -0,0 +1,83 @@
+"""Central error code registry - mirrors docs/spec/error-codes semantics."""
+
+from __future__ import annotations
+
+
+class CA2AError(Exception):
+    """Base class for all ca2a-runtime errors."""
+
+    code: str = "CA2A_ERROR"
+    http_status: int = 500
+
+    def __init__(self, message: str, *, detail: str | None = None) -> None:
+        super().__init__(message)
+        self.detail = detail
+
+
+class ConfigError(CA2AError):
+    code = "CONFIG_ERROR"
+    http_status = 500
+
+
+class InvalidCredential(CA2AError):
+    """A delegation credential is malformed or its signature does not verify."""
+
+    code = "INVALID_CREDENTIAL"
+    http_status = 400
+
+
+class ScopeEscalation(CA2AError):
+    """A child grant claims authority its parent did not hold."""
+
+    code = "SCOPE_ESCALATION"
+    http_status = 403
+
+
+class BrokenDelegationLink(CA2AError):
+    """A hop does not chain to its stated parent, or continuity is broken."""
+
+    code = "BROKEN_DELEGATION_LINK"
+    http_status = 409
+
+
+class DelegationDepthExceeded(CA2AError):
+    code = "DELEGATION_DEPTH_EXCEEDED"
+    http_status = 403
+
+
+class CredentialReplay(CA2AError):
+    """A credential id appears more than once in a chain."""
+
+    code = "CREDENTIAL_REPLAY"
+    http_status = 409
+
+
+class AttestationUnsupported(CA2AError):
+    code = "ATTESTATION_UNSUPPORTED"
+    http_status = 500
+
+
+class AttestationFailed(CA2AError):
+    code = "ATTESTATION_FAILED"
+    http_status = 412
+
+
+class SealedChannelError(CA2AError):
+    code = "SEALED_CHANNEL_ERROR"
+    http_status = 500
+
+
+class ProvenanceLinkBroken(CA2AError):
+    """A delegation record does not chain to its stated parent record, or a
+    record has been tampered with so its hash no longer matches a child's link."""
+
+    code = "PROVENANCE_LINK_BROKEN"
+    http_status = 409
+
+
+class ScopeNotPermitted(CA2AError):
+    """A requested capability is not in the effective scope (the delegated
+    scope intersected with the callee's local policy)."""
+
+    code = "SCOPE_NOT_PERMITTED"
+    http_status = 403

ca2a_runtime/peer.py

@@ -0,0 +1,142 @@
+"""Inbound peer-call enforcement: the decision the callee makes before it acts.
+
+When a peer presents a delegation chain and requests a capability, the callee:
+
+1. verifies the chain (signature, continuity, attenuation, depth, replay);
+2. computes the effective scope as the leaf's delegated scope intersected with
+   the callee's local policy;
+3. enforces: the requested capability must be in the effective scope;
+4. emits a provenance record for the accepted hop, linked to its parent.
+
+`enforce_peer_call` is the enforcement decision core. `handle_peer_request`
+composes it into the full transport-agnostic inbound pipeline: verify, enforce,
+open any sealed payload with the enclave key, and emit a provenance record. A
+transport (an A2A server) parses its wire format into a `PeerRequest` and calls
+this; cA2A does not define the transport itself, only what the peer does with a
+parsed request.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+
+from ca2a_runtime.channel import open_sealed
+from ca2a_runtime.delegation.credential import DelegationCredential, verify_chain
+from ca2a_runtime.errors import ScopeNotPermitted, SealedChannelError
+from ca2a_runtime.policy import Policy
+from ca2a_runtime.provenance import DelegationRecord, record_for
+
+
+def effective_scope(
+    chain: list[DelegationCredential], policy: Policy, *, max_depth: int = 8
+) -> frozenset[str]:
+    """Verify the chain and return the effective scope (delegated ∩ local policy).
+
+    Raises the relevant CA2AError if the chain does not verify.
+    """
+    verify_chain(chain, max_depth=max_depth)
+    return policy.intersect(chain[-1].scope)
+
+
+@dataclass(frozen=True)
+class PeerDecision:
+    """The result of an accepted peer call."""
+
+    effective_scope: frozenset[str]
+    granted_capability: str
+    record: DelegationRecord
+
+
+def enforce_peer_call(
+    chain: list[DelegationCredential],
+    requested_capability: str,
+    *,
+    policy: Policy,
+    record_id: str,
+    parent_record_hash: str | None = None,
+    max_depth: int = 8,
+) -> PeerDecision:
+    """Verify, intersect with local policy, enforce, and emit a provenance record.
+
+    Raises ScopeNotPermitted if the requested capability is not in the effective
+    scope, and the underlying CA2AError if the chain does not verify. On accept,
+    returns a PeerDecision carrying the linked provenance record.
+    """
+    effective = effective_scope(chain, policy, max_depth=max_depth)
+    if requested_capability not in effective:
+        raise ScopeNotPermitted(
+            f"capability {requested_capability!r} is not in the effective scope",
+            detail=f"effective={sorted(effective)}",
+        )
+    record = record_for(chain[-1], record_id=record_id, parent_record_hash=parent_record_hash)
+    return PeerDecision(
+        effective_scope=effective,
+        granted_capability=requested_capability,
+        record=record,
+    )
+
+
+@dataclass(frozen=True)
+class PeerRequest:
+    """A transport-agnostic inbound peer request.
+
+    A transport (an A2A server) parses its wire format into this shape and hands
+    it to ``handle_peer_request``. cA2A does not define the transport; it defines
+    what a peer does with the request once parsed.
+    """
+
+    chain: list[DelegationCredential]
+    requested_capability: str
+    record_id: str
+    sealed_payload: bytes | None = None
+    parent_record_hash: str | None = None
+
+
+@dataclass(frozen=True)
+class PeerResult:
+    """The outcome of handling an accepted peer request."""
+
+    effective_scope: frozenset[str]
+    granted_capability: str
+    record: DelegationRecord
+    payload: bytes | None
+
+
+def handle_peer_request(
+    request: PeerRequest,
+    *,
+    policy: Policy,
+    enclave_private_key: X25519PrivateKey | None = None,
+    max_depth: int = 8,
+) -> PeerResult:
+    """Run the full inbound pipeline for a parsed peer request.
+
+    Verifies the delegation chain, intersects the delegated scope with the local
+    policy and enforces the requested capability, opens any sealed payload with
+    the enclave-bound key, and emits a linked provenance record. Fails closed:
+    any verification or authorization failure raises the relevant CA2AError and
+    no payload is returned.
+    """
+    decision = enforce_peer_call(
+        request.chain,
+        request.requested_capability,
+        policy=policy,
+        record_id=request.record_id,
+        parent_record_hash=request.parent_record_hash,
+        max_depth=max_depth,
+    )
+
+    payload: bytes | None = None
+    if request.sealed_payload is not None:
+        if enclave_private_key is None:
+            raise SealedChannelError("a sealed payload was sent but no enclave key is available")
+        payload = open_sealed(request.sealed_payload, enclave_private_key)
+
+    return PeerResult(
+        effective_scope=decision.effective_scope,
+        granted_capability=decision.granted_capability,
+        record=decision.record,
+        payload=payload,
+    )

ca2a_runtime/policy.py

@@ -0,0 +1,48 @@
+"""Local peer policy for scope intersection.
+
+A callee constrains what an inbound peer may do with a set of allowed
+capabilities. The effective permission on a peer call is the delegated scope
+intersected with this allow set, so a peer can never exercise more than both
+its grant and the callee's local policy permit.
+
+The intersection semantics here are policy-language-agnostic. Binding a full
+Cedar policy engine (as cMCP does) is tracked separately; this allow-set model
+is the enforcement primitive the peer path uses today.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Policy(Protocol):
+    """A local policy the peer path intersects a delegated scope against.
+
+    Implemented by ``LocalPolicy`` (a capability allow set) and by
+    ``ca2a_runtime.cedar.CedarPolicy`` (a real Cedar policy engine).
+    """
+
+    def intersect(self, delegated: frozenset[str]) -> frozenset[str]:
+        """Return the effective scope: the delegated capabilities this policy allows."""
+        ...
+
+
+@dataclass(frozen=True)
+class LocalPolicy:
+    """A callee's local capability allow set."""
+
+    allow: frozenset[str]
+
+    @classmethod
+    def of(cls, caps: Iterable[str]) -> LocalPolicy:
+        return cls(allow=frozenset(caps))
+
+    def intersect(self, delegated: frozenset[str]) -> frozenset[str]:
+        """Return the effective scope: delegated capabilities this policy allows."""
+        return delegated & self.allow
+
+    def permits(self, capability: str) -> bool:
+        return capability in self.allow

ca2a_runtime/provenance.py

@@ -0,0 +1,115 @@
+"""Delegation provenance: linked records forming a tamper-evident delegation DAG.
+
+Each delegation hop emits a ``DelegationRecord`` that references its parent
+record by hash and names the credential it acted under. A chain of records is
+verifiable offline: the parent link is the hash of the parent record's canonical
+body, so tampering with any record (its scope, subject, or its own parent link)
+changes its hash and breaks the child's link. This is the runtime-evidence side
+of the cA2A profile (see docs/spec/trace-a2a-profile.md); the full TRACE binding
+lands with the Tier 2 provenance work.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any
+
+from ca2a_runtime.delegation.credential import DelegationCredential, canonical_bytes
+from ca2a_runtime.errors import ProvenanceLinkBroken
+
+
+@dataclass(frozen=True)
+class DelegationRecord:
+    """A provenance record for a single delegation hop."""
+
+    record_id: str
+    credential_id: str
+    subject: str
+    scope: frozenset[str]
+    parent_record_hash: str | None = None
+
+    def body(self) -> dict[str, Any]:
+        """The hashed portion of the record."""
+        return {
+            "record_id": self.record_id,
+            "credential_id": self.credential_id,
+            "subject": self.subject,
+            "scope": sorted(self.scope),
+            "parent_record_hash": self.parent_record_hash,
+        }
+
+    def record_hash(self) -> str:
+        """SHA-256 over the canonical body. Any field change changes this value."""
+        return hashlib.sha256(canonical_bytes(self.body())).hexdigest()
+
+
+def record_for(
+    credential: DelegationCredential,
+    record_id: str,
+    parent_record_hash: str | None,
+) -> DelegationRecord:
+    """Build the provenance record a hop emits for a delegation credential."""
+    return DelegationRecord(
+        record_id=record_id,
+        credential_id=credential.credential_id,
+        subject=credential.subject,
+        scope=credential.scope,
+        parent_record_hash=parent_record_hash,
+    )
+
+
+def verify_dag(records: list[DelegationRecord]) -> list[DelegationRecord]:
+    """Verify a root-to-leaf provenance chain and return it in order.
+
+    Raises ProvenanceLinkBroken on the first violation:
+
+    - the first record must be a root (no parent link);
+    - every later record's parent_record_hash must equal the recomputed hash of
+      the immediately preceding record (so a tampered or reparented record is
+      detected because its hash no longer matches the stored link);
+    - no record_id may repeat.
+    """
+    if not records:
+        raise ProvenanceLinkBroken("empty provenance chain")
+
+    seen_ids: set[str] = set()
+    prev: DelegationRecord | None = None
+
+    for i, rec in enumerate(records):
+        if rec.record_id in seen_ids:
+            raise ProvenanceLinkBroken(f"duplicate record_id at position {i}: {rec.record_id}")
+        seen_ids.add(rec.record_id)
+
+        if prev is None:
+            if rec.parent_record_hash is not None:
+                raise ProvenanceLinkBroken("root record must not reference a parent")
+        else:
+            expected = prev.record_hash()
+            if rec.parent_record_hash != expected:
+                raise ProvenanceLinkBroken(
+                    f"record {i} parent link does not match the previous record's hash",
+                    detail="a tampered or reparented record was detected",
+                )
+        prev = rec
+
+    return records
+
+
+def cross_check_chain(
+    records: list[DelegationRecord], chain: list[DelegationCredential]
+) -> None:
+    """Confirm a verified provenance chain lines up with a delegation chain.
+
+    Ties provenance to authority: record ``i`` must reference credential ``i``
+    and carry the same subject. Raises ProvenanceLinkBroken on any mismatch.
+    """
+    if len(records) != len(chain):
+        raise ProvenanceLinkBroken(
+            f"provenance length {len(records)} does not match chain length {len(chain)}"
+        )
+    for i, (rec, cred) in enumerate(zip(records, chain, strict=True)):
+        if rec.credential_id != cred.credential_id:
+            raise ProvenanceLinkBroken(f"record {i} credential_id does not match the chain")
+        if rec.subject != cred.subject:
+            raise ProvenanceLinkBroken(f"record {i} subject does not match the chain")

ca2a_runtime/tee/__init__.py

@@ -0,0 +1,22 @@
+"""TEE provider abstraction for peer attestation.
+
+cA2A reuses the pluggable provider model from cmcp: a provider produces an
+attestation report that binds a public key to a hardware measurement. Real
+hardware backends are Tier 3 (see ROADMAP.md) and fail closed until implemented.
+"""
+
+from ca2a_runtime.tee.base import AttestationReport, BaseProvider
+from ca2a_runtime.tee.sev_snp import SevSnpProvider, SevSnpReport
+from ca2a_runtime.tee.tdx import TdxProvider, TdxQuote
+from ca2a_runtime.tee.tpm import TpmProvider, TpmQuote
+
+__all__ = [
+    "AttestationReport",
+    "BaseProvider",
+    "SevSnpProvider",
+    "SevSnpReport",
+    "TdxProvider",
+    "TdxQuote",
+    "TpmProvider",
+    "TpmQuote",
+]

ca2a_runtime/tee/base.py

@@ -0,0 +1,36 @@
+"""Base TEE provider interface and attestation report model."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AttestationReport:
+    """An attestation report binding a public key to a hardware measurement."""
+
+    platform: str
+    measurement: str
+    public_key: str  # raw hex of the key bound to this measurement
+    nonce: str
+
+
+class BaseProvider(ABC):
+    """Normalized interface every TEE provider implements.
+
+    Real hardware providers (TPM, SEV-SNP, TDX, OPAQUE) are Tier 3 and are not
+    implemented in this release; ``detect`` returns False for them so they are
+    never selected automatically.
+    """
+
+    platform: str = "base"
+
+    @classmethod
+    @abstractmethod
+    def detect(cls) -> bool:
+        """Return True if this provider is available on the current host."""
+
+    @abstractmethod
+    def attest(self, public_key: str, nonce: str) -> AttestationReport:
+        """Produce an attestation report binding ``public_key`` under ``nonce``."""