ca2a-runtime 0.1.0a1__py3-none-any.whl

ca2a_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""cA2A Runtime: confidential agent-to-agent delegation on top of A2A."""
+
+__version__ = "0.1.0"

ca2a_runtime/benchmarks.py

@@ -0,0 +1,69 @@
+"""Delegation-chain verification microbenchmark.
+
+Software-only path: measures per-hop verify latency so CI can gate regressions.
+Real attestation and sealed-channel costs are added once Tier 2/3 land.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from pathlib import Path
+
+from ca2a_runtime.delegation import DelegationCredential, new_keypair, verify_chain
+
+
+def _build_chain(hops: int) -> list[DelegationCredential]:
+    scope = frozenset(f"cap:{i}" for i in range(16))
+    priv, pub = new_keypair()
+    chain: list[DelegationCredential] = []
+    parent_id: str | None = None
+    for depth in range(hops):
+        next_priv, next_pub = new_keypair()
+        cred = DelegationCredential(
+            credential_id=f"cred-{depth}",
+            issuer=pub,
+            subject=next_pub,
+            scope=scope,
+            depth=depth,
+            parent_id=parent_id,
+        ).sign(priv)
+        chain.append(cred)
+        parent_id = cred.credential_id
+        priv, pub = next_priv, next_pub
+    return chain
+
+
+def run(hops: int, out: Path | None) -> dict[str, float]:
+    latencies: list[float] = []
+    for _ in range(hops):
+        chain = _build_chain(2)
+        start = time.perf_counter()
+        verify_chain(chain, max_depth=64)
+        latencies.append((time.perf_counter() - start) * 1000.0)
+    latencies.sort()
+    p99 = latencies[min(len(latencies) - 1, int(len(latencies) * 0.99))]
+    result = {"hops": float(hops), "p99_ms": p99, "mean_ms": sum(latencies) / len(latencies)}
+    if out is not None:
+        out.mkdir(parents=True, exist_ok=True)
+        (out / "delegation-verify.json").write_text(json.dumps(result, indent=2))
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="ca2a-benchmarks")
+    parser.add_argument("--provider", default="software-only")
+    parser.add_argument("--hops", type=int, default=10000)
+    parser.add_argument("--out", type=Path, default=None)
+    args = parser.parse_args(argv)
+    result = run(args.hops, args.out)
+    print(json.dumps(result))
+    if result["p99_ms"] >= 5.0:
+        print("p99 gate exceeded (>= 5ms)")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ca2a_runtime/canonical.py

@@ -0,0 +1,69 @@
+"""RFC 8785 JSON Canonicalization Scheme (JCS) for the value types cA2A signs.
+
+Credentials and provenance records are signed over the canonical byte encoding
+of a JSON object. RFC 8785 fixes that encoding so any conforming implementation
+(here and in agent-manifest) produces identical bytes and therefore
+cross-verifiable signatures.
+
+This implements JCS for the JSON value types cA2A uses: objects, arrays,
+strings, integers, booleans, and null. Object keys are sorted by their UTF-16
+code units, strings use JCS minimal escaping (control characters only; non-ASCII
+is emitted literally as UTF-8), and integers serialize as their shortest decimal
+form. Floating-point numbers are not part of the cA2A data model and are
+rejected rather than serialized approximately.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# JCS short escapes for control characters (RFC 8785 section 3.2.2.2).
+_SHORT_ESCAPES = {
+    0x08: "\\b",
+    0x09: "\\t",
+    0x0A: "\\n",
+    0x0C: "\\f",
+    0x0D: "\\r",
+    0x22: '\\"',
+    0x5C: "\\\\",
+}
+
+
+def _escape_string(s: str) -> str:
+    out: list[str] = ['"']
+    for ch in s:
+        code = ord(ch)
+        if code in _SHORT_ESCAPES:
+            out.append(_SHORT_ESCAPES[code])
+        elif code < 0x20:
+            out.append(f"\\u{code:04x}")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _serialize(value: Any) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        return _escape_string(value)
+    if isinstance(value, int):  # bool already handled above
+        return str(value)
+    if isinstance(value, float):
+        raise TypeError("RFC 8785 canonicalization of floats is not supported in cA2A")
+    if isinstance(value, list):
+        return "[" + ",".join(_serialize(v) for v in value) + "]"
+    if isinstance(value, dict):
+        items = sorted(value.items(), key=lambda kv: str(kv[0]).encode("utf-16-be"))
+        return "{" + ",".join(f"{_escape_string(str(k))}:{_serialize(v)}" for k, v in items) + "}"
+    raise TypeError(f"unsupported type for canonicalization: {type(value).__name__}")
+
+
+def canonicalize(value: Any) -> bytes:
+    """Return the RFC 8785 canonical UTF-8 encoding of ``value``."""
+    return _serialize(value).encode("utf-8")

ca2a_runtime/cedar.py

@@ -0,0 +1,46 @@
+"""A local policy backed by a real Cedar policy engine.
+
+`CedarPolicy` evaluates the callee's Cedar policy to decide which capabilities a
+peer may exercise. It satisfies the `ca2a_runtime.policy.Policy` protocol, so it
+is a drop-in for `LocalPolicy` in the peer path: the effective scope on an
+inbound call is the delegated leaf scope intersected with what Cedar permits.
+
+Each capability is evaluated as a Cedar authorization request whose action id is
+the capability name; a capability is permitted iff Cedar returns Allow. This
+reuses the same policy engine cMCP runs (see docs/spec/cedar-policy.md).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from cedarpy import Decision, is_authorized
+
+
+@dataclass(frozen=True)
+class CedarPolicy:
+    """A local policy backed by a Cedar policy set."""
+
+    policies: str
+    principal_type: str = "Agent"
+    principal_id: str = "peer"
+    resource_type: str = "Task"
+    resource_id: str = "task"
+
+    def _request(self, capability: str) -> dict[str, Any]:
+        return {
+            "principal": {"type": self.principal_type, "id": self.principal_id},
+            "action": {"type": "Action", "id": capability},
+            "resource": {"type": self.resource_type, "id": self.resource_id},
+            "context": {},
+        }
+
+    def permits(self, capability: str) -> bool:
+        """Return True iff Cedar authorizes an action of this capability's name."""
+        result = is_authorized(self._request(capability), self.policies, [])
+        return bool(result.decision == Decision.Allow)
+
+    def intersect(self, delegated: frozenset[str]) -> frozenset[str]:
+        """Return the effective scope: delegated capabilities Cedar permits."""
+        return frozenset(cap for cap in delegated if self.permits(cap))

ca2a_runtime/channel/__init__.py

@@ -0,0 +1,14 @@
+"""Sealed peer channel: seal a task payload to a peer's attested key.
+
+HPKE-style X25519 -> HKDF-SHA256 -> ChaCha20-Poly1305. Only the holder of the
+private key bound to the peer's attested measurement can open a sealed payload.
+See docs/spec/sealed-channel.md.
+"""
+
+from ca2a_runtime.channel.sealed import (
+    SealedChannel,
+    generate_channel_keypair,
+    open_sealed,
+)
+
+__all__ = ["SealedChannel", "generate_channel_keypair", "open_sealed"]

ca2a_runtime/channel/sealed.py

@@ -0,0 +1,97 @@
+"""Sealed peer channel: seal a task payload to a peer's attested key.
+
+The channel binds a payload to the X25519 public key that a peer's attestation
+report vouches for (see docs/spec/attestation.md). The scheme is HPKE-style:
+an ephemeral X25519 ECDH to the peer key, HKDF-SHA256 to derive a symmetric
+key, and ChaCha20-Poly1305 AEAD over the payload. Only the holder of the
+private key can open the result.
+
+Confidentiality of the payload rests on that private key. On real hardware the
+key is generated and held inside the peer's enclave and never leaves it, so the
+payload decrypts only inside the attested measurement. This module implements
+the cryptography; the guarantee that the private key is enclave-bound is what
+attestation establishes, and driving the seal off a verified report on a live
+call is tracked as runtime wiring (see ROADMAP.md).
+"""
+
+from __future__ import annotations
+
+import os
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+from cryptography.hazmat.primitives.hashes import SHA256
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from ca2a_runtime.errors import SealedChannelError
+
+_VERSION = 1
+_HKDF_INFO = b"ca2a/sealed-channel/v1"
+_EPH_LEN = 32
+_NONCE_LEN = 12
+_HEADER_LEN = 1 + _EPH_LEN + _NONCE_LEN
+
+
+def generate_channel_keypair() -> tuple[X25519PrivateKey, str]:
+    """Return an enclave channel keypair and its public key as raw hex.
+
+    On hardware this runs inside the peer's enclave and the public key is bound
+    into the attestation report; the private key never leaves the enclave.
+    """
+    priv = X25519PrivateKey.generate()
+    pub_hex = priv.public_key().public_bytes_raw().hex()
+    return priv, pub_hex
+
+
+def _derive_key(shared: bytes, eph_pub: bytes, peer_pub: bytes) -> bytes:
+    return HKDF(algorithm=SHA256(), length=32, salt=None, info=_HKDF_INFO).derive(
+        eph_pub + peer_pub + shared
+    )
+
+
+class SealedChannel:
+    """Sender side: seals payloads to a peer's attested X25519 public key."""
+
+    def __init__(self, peer_public_key: str) -> None:
+        try:
+            self._peer_pub = X25519PublicKey.from_public_bytes(bytes.fromhex(peer_public_key))
+        except ValueError as exc:
+            raise SealedChannelError("invalid peer public key", detail=str(exc)) from exc
+        self.peer_public_key = peer_public_key
+
+    def seal(self, payload: bytes, *, aad: bytes = b"") -> bytes:
+        """Seal ``payload`` to the peer key. The result is opaque to anyone
+        without the peer's private key; ``aad`` is authenticated, not encrypted."""
+        eph_priv = X25519PrivateKey.generate()
+        eph_pub = eph_priv.public_key().public_bytes_raw()
+        peer_pub_raw = self._peer_pub.public_bytes_raw()
+        shared = eph_priv.exchange(self._peer_pub)
+        key = _derive_key(shared, eph_pub, peer_pub_raw)
+        nonce = os.urandom(_NONCE_LEN)
+        ct = ChaCha20Poly1305(key).encrypt(nonce, payload, aad)
+        return bytes([_VERSION]) + eph_pub + nonce + ct
+
+
+def open_sealed(blob: bytes, private_key: X25519PrivateKey, *, aad: bytes = b"") -> bytes:
+    """Open a sealed payload with the enclave-bound private key.
+
+    Fails closed with SealedChannelError on a malformed blob, a wrong key, or a
+    tampered ciphertext (AEAD authentication failure); it never returns
+    unauthenticated plaintext.
+    """
+    if len(blob) < _HEADER_LEN or blob[0] != _VERSION:
+        raise SealedChannelError("malformed or unsupported sealed payload")
+    eph_pub = blob[1 : 1 + _EPH_LEN]
+    nonce = blob[1 + _EPH_LEN : _HEADER_LEN]
+    ct = blob[_HEADER_LEN:]
+    try:
+        peer_pub_raw = private_key.public_key().public_bytes_raw()
+        shared = private_key.exchange(X25519PublicKey.from_public_bytes(eph_pub))
+        key = _derive_key(shared, eph_pub, peer_pub_raw)
+        return ChaCha20Poly1305(key).decrypt(nonce, ct, aad)
+    except (InvalidTag, ValueError) as exc:
+        raise SealedChannelError("sealed payload failed to open", detail=str(exc)) from exc

ca2a_runtime/cli.py

@@ -0,0 +1,144 @@
+"""ca2a command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ca2a_runtime import __version__
+from ca2a_runtime.config import Ca2aConfig
+from ca2a_runtime.delegation import DelegationCredential, verify_chain
+from ca2a_runtime.errors import CA2AError, InvalidCredential, ProvenanceLinkBroken
+from ca2a_runtime.provenance import DelegationRecord, cross_check_chain, verify_dag
+from ca2a_verify import verify_chain_file
+
+
+def _cmd_validate_config(args: argparse.Namespace) -> int:
+    try:
+        cfg = Ca2aConfig.load(args.config)
+    except CA2AError as exc:
+        print(f"invalid config: {exc}", file=sys.stderr)
+        return 1
+    print(f"ok: provider={cfg.provider} enforcement={cfg.enforcement_mode}")
+    return 0
+
+
+def _cmd_verify_chain(args: argparse.Namespace) -> int:
+    try:
+        result = verify_chain_file(Path(args.chain), max_depth=args.max_depth)
+    except CA2AError as exc:
+        print(json.dumps({"verified": False, "code": exc.code, "error": str(exc)}))
+        return 1
+    print(json.dumps({"verified": True, "hops": result.hops, "leaf_scope": result.leaf_scope}))
+    return 0
+
+
+def _load_chain(path: str) -> list[DelegationCredential]:
+    p = Path(path)
+    if not p.is_file():
+        raise InvalidCredential(f"chain file not found: {p}")
+    try:
+        data: Any = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise InvalidCredential(f"invalid JSON in {p}", detail=str(exc)) from exc
+    if isinstance(data, dict) and "chain" in data:
+        data = data["chain"]
+    if not isinstance(data, list):
+        raise InvalidCredential('chain document must be a list or {"chain": [...]}')
+    return [DelegationCredential.from_dict(item) for item in data]
+
+
+def _load_records(path: str) -> list[DelegationRecord]:
+    p = Path(path)
+    if not p.is_file():
+        raise ProvenanceLinkBroken(f"dag file not found: {p}")
+    try:
+        data: Any = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ProvenanceLinkBroken(f"invalid JSON in {p}", detail=str(exc)) from exc
+    if isinstance(data, dict) and "records" in data:
+        data = data["records"]
+    if not isinstance(data, list):
+        raise ProvenanceLinkBroken('dag document must be a list or {"records": [...]}')
+    records: list[DelegationRecord] = []
+    for item in data:
+        try:
+            records.append(
+                DelegationRecord(
+                    record_id=str(item["record_id"]),
+                    credential_id=str(item["credential_id"]),
+                    subject=str(item["subject"]),
+                    scope=frozenset(str(s) for s in item["scope"]),
+                    parent_record_hash=(
+                        None
+                        if item.get("parent_record_hash") is None
+                        else str(item["parent_record_hash"])
+                    ),
+                )
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ProvenanceLinkBroken("malformed provenance record", detail=str(exc)) from exc
+    return records
+
+
+def _cmd_verify_dag(args: argparse.Namespace) -> int:
+    try:
+        records = verify_dag(_load_records(args.dag))
+        cross_checked = False
+        if args.chain:
+            chain = _load_chain(args.chain)
+            verify_chain(chain, max_depth=args.max_depth)
+            cross_check_chain(records, chain)
+            cross_checked = True
+    except CA2AError as exc:
+        print(json.dumps({"verified": False, "code": exc.code, "error": str(exc)}))
+        return 1
+    out = {
+        "verified": True,
+        "records": len(records),
+        "leaf_scope": sorted(records[-1].scope),
+    }
+    if args.chain:
+        out["cross_checked"] = cross_checked
+    print(json.dumps(out))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ca2a", description="Confidential agent-to-agent")
+    parser.add_argument("--version", action="version", version=f"ca2a {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    vc = sub.add_parser("validate-config", help="Validate a ca2a config file")
+    vc.add_argument("--config", required=True)
+    vc.set_defaults(func=_cmd_validate_config)
+
+    vch = sub.add_parser("verify-chain", help="Verify a delegation chain offline")
+    vch.add_argument("--chain", required=True)
+    vch.add_argument("--max-depth", type=int, default=8)
+    vch.set_defaults(func=_cmd_verify_chain)
+
+    vd = sub.add_parser("verify-dag", help="Verify a provenance DAG offline")
+    vd.add_argument("--dag", required=True)
+    vd.add_argument(
+        "--chain",
+        help="Optional delegation chain to cross-check the DAG against",
+    )
+    vd.add_argument("--max-depth", type=int, default=8)
+    vd.set_defaults(func=_cmd_verify_dag)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    result: int = args.func(args)
+    return result
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ca2a_runtime/config.py

@@ -0,0 +1,73 @@
+"""Runtime configuration for the cA2A peer runtime.
+
+The runtime peer path is under construction (see ROADMAP.md); this module
+defines and validates the configuration surface it will consume.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ca2a_runtime.errors import ConfigError
+
+VALID_PROVIDERS = frozenset(
+    {"auto", "tpm", "sev-snp", "tdx", "opaque", "software-only"}
+)
+VALID_ENFORCEMENT = frozenset({"enforcing", "advisory", "silent"})
+
+
+@dataclass(frozen=True)
+class Ca2aConfig:
+    """Validated cA2A runtime configuration."""
+
+    provider: str = "auto"
+    enforcement_mode: str = "enforcing"
+    max_delegation_depth: int = 8
+    policy_bundle_path: str | None = None
+    listen_addr: str = "0.0.0.0:8443"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Ca2aConfig:
+        attestation = data.get("attestation", {}) or {}
+        provider = attestation.get("provider", "auto")
+        enforcement = attestation.get("enforcement_mode", "enforcing")
+
+        if provider not in VALID_PROVIDERS:
+            raise ConfigError(
+                f"unknown attestation provider: {provider!r}",
+                detail=f"expected one of {sorted(VALID_PROVIDERS)}",
+            )
+        if enforcement not in VALID_ENFORCEMENT:
+            raise ConfigError(
+                f"unknown enforcement_mode: {enforcement!r}",
+                detail=f"expected one of {sorted(VALID_ENFORCEMENT)}",
+            )
+
+        depth = data.get("max_delegation_depth", 8)
+        if not isinstance(depth, int) or depth < 1:
+            raise ConfigError("max_delegation_depth must be a positive integer")
+
+        return cls(
+            provider=provider,
+            enforcement_mode=enforcement,
+            max_delegation_depth=depth,
+            policy_bundle_path=data.get("policy_bundle_path"),
+            listen_addr=data.get("listen_addr", "0.0.0.0:8443"),
+        )
+
+    @classmethod
+    def load(cls, path: str | Path) -> Ca2aConfig:
+        p = Path(path)
+        if not p.is_file():
+            raise ConfigError(f"config file not found: {p}")
+        try:
+            data = yaml.safe_load(p.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError as exc:
+            raise ConfigError(f"invalid YAML in {p}", detail=str(exc)) from exc
+        if not isinstance(data, dict):
+            raise ConfigError(f"config root must be a mapping, got {type(data).__name__}")
+        return cls.from_dict(data)

ca2a_runtime/delegation/__init__.py

@@ -0,0 +1,20 @@
+"""Attenuated delegation: signed credentials whose scope narrows at each hop.
+
+The semantics here mirror the signed A2A delegation chain implemented and
+tested in agent-manifest (https://github.com/agentrust-io/agent-manifest);
+this package is the runtime-side model and verifier the cA2A peer path calls.
+"""
+
+from ca2a_runtime.delegation.credential import (
+    DelegationCredential,
+    canonical_bytes,
+    new_keypair,
+    verify_chain,
+)
+
+__all__ = [
+    "DelegationCredential",
+    "canonical_bytes",
+    "new_keypair",
+    "verify_chain",
+]