cmcp-runtime 0.1.0__py3-none-any.whl

cmcp_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""cMCP Runtime — hardware-attested MCP runtime."""
+
+__version__ = "0.1.0"

cmcp_runtime/audit/__init__.py

@@ -0,0 +1 @@
+"""Audit package — implemented in subsequent issues."""

cmcp_runtime/audit/chain.py

@@ -0,0 +1,245 @@
+"""Audit chain — append-only hash-chained log inside the enclave. Implements issue #47."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from typing import Literal
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+EntryType = Literal[
+    "session_start",
+    "session_end",
+    "session_reset",
+    "tool_call",
+    "egress_denied",
+    "attestation_refresh",
+    "policy_load",
+    "catalog_load",
+    "fault",
+    "suspicious_call_sequence",
+    "attestation_stale",
+    "catalog_drift",
+    "break_glass_used",
+]
+
+PolicyDecision = Literal["allow", "deny", "redact", "advisory_deny", "fault", "n/a"]
+
+InspectionResult = Literal[
+    "pass", "injection_detected", "schema_violation", "surplus_stripped", "size_exceeded", "n/a"
+]
+
+
+@dataclass
+class AuditEntry:
+    """Single entry in the append-only audit chain."""
+
+    entry_id: str
+    sequence_number: int
+    timestamp_utc: str
+    session_id: str
+    call_id: str | None
+    entry_type: EntryType
+    tool_name: str | None
+    server_identity: str | None
+    policy_decision: PolicyDecision | None
+    policy_rule_matched: str | None
+    latency_us: int | None
+    request_payload_hash: str | None  # SHA-256 of canonical request; NOT the payload
+    response_payload_hash: str | None
+    response_inspection_result: InspectionResult | None
+    session_sensitivity_before: str | None
+    session_sensitivity_after: str | None
+    detail: dict[str, str | int | float] | None  # optional structured detail (e.g. suspicious_call_sequence)
+    workflow_id: str | None
+    prev_entry_hash: str  # "genesis" for first entry
+    entry_hash: str = field(default="")  # computed after construction
+
+    def _canonical_body(self) -> bytes:
+        """Deterministic JSON of all fields except entry_hash, for hashing."""
+        d = asdict(self)
+        d.pop("entry_hash")
+        return json.dumps(d, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode()
+
+    def compute_hash(self) -> str:
+        """SHA-256 of the canonical body, hex-encoded."""
+        return hashlib.sha256(self._canonical_body()).hexdigest()
+
+
+class AuditChain:
+    """
+    Append-only hash-chained audit log maintained inside the enclave.
+
+    Every call, denial, session event, and fault produces one entry.
+    chain_root is the hash of the first entry; chain_tip is the hash
+    of the most recent entry. Any tampering breaks the hash chain.
+
+    AUDIT-002: to prevent chain substitution, the caller must call
+    set_tee_anchor(chain_root) immediately after session start.  The anchor
+    is the chain_root committed into the TEE attestation nonce so that an
+    attacker who discards _entries and re-builds a fresh chain will get a
+    different root that will not match the externally-witnessed value.
+
+    When a TEE anchor is set, verify_chain() also checks that the current
+    chain_root equals the anchored value.  In dev / Level-0 mode where no
+    TEE is available, anchoring is skipped and a warning is emitted — the
+    internal hash-chain check still runs.
+    """
+
+    def __init__(self, session_id: str) -> None:
+        self._session_id = session_id
+        self._entries: list[AuditEntry] = []
+        # AUDIT-002: TEE-anchored chain root.  None until set_tee_anchor() is called.
+        self._tee_anchor: str | None = None
+        self._append_session_start()
+
+    def _append_session_start(self) -> None:
+        self.append(
+            entry_type="session_start",
+            call_id=None,
+            tool_name=None,
+            server_identity=None,
+            policy_decision="n/a",
+            policy_rule_matched=None,
+            latency_us=None,
+            request_payload_hash=None,
+            response_payload_hash=None,
+            response_inspection_result="n/a",
+            session_sensitivity_before=None,
+            session_sensitivity_after="public",
+            workflow_id=None,
+        )
+
+    def set_tee_anchor(self, anchor: str) -> None:
+        """
+        AUDIT-002: commit the chain root into an external anchor.
+
+        anchor must equal chain_root at the time of the call (i.e. the value
+        that was measured into the TEE attestation report nonce).  Raises
+        ValueError if anchor does not match the current chain_root — this
+        would indicate a programming error in the caller.
+
+        Once set, verify_chain() will reject any chain whose root no longer
+        matches this anchored value, preventing silent chain substitution.
+        """
+        if anchor != self.chain_root:
+            raise ValueError(
+                f"TEE anchor '{anchor[:16]}...' does not match current chain_root "
+                f"'{self.chain_root[:16]}...'. Anchor must be set to the chain_root "
+                "immediately after session start."
+            )
+        self._tee_anchor = anchor
+
+    @property
+    def tee_anchor(self) -> str | None:
+        """The TEE-committed chain root, or None if not yet anchored (dev/Level-0 mode)."""
+        return self._tee_anchor
+
+    def append(
+        self,
+        entry_type: EntryType,
+        *,
+        call_id: str | None = None,
+        tool_name: str | None = None,
+        server_identity: str | None = None,
+        policy_decision: PolicyDecision | None = None,
+        policy_rule_matched: str | None = None,
+        latency_us: int | None = None,
+        request_payload_hash: str | None = None,
+        response_payload_hash: str | None = None,
+        response_inspection_result: InspectionResult | None = None,
+        session_sensitivity_before: str | None = None,
+        session_sensitivity_after: str | None = None,
+        detail: dict[str, str | int | float] | None = None,
+        workflow_id: str | None = None,
+    ) -> AuditEntry:
+        prev_hash = self._entries[-1].entry_hash if self._entries else "genesis"
+        now = datetime.now(tz=UTC)
+        if self._entries:
+            prev_ts = datetime.fromisoformat(self._entries[-1].timestamp_utc)
+            if now < prev_ts:
+                now = prev_ts
+        entry = AuditEntry(
+            entry_id=str(uuid4()),
+            sequence_number=len(self._entries),
+            timestamp_utc=now.isoformat(),
+            session_id=self._session_id,
+            call_id=call_id,
+            entry_type=entry_type,
+            tool_name=tool_name,
+            server_identity=server_identity,
+            policy_decision=policy_decision,
+            policy_rule_matched=policy_rule_matched,
+            latency_us=latency_us,
+            request_payload_hash=request_payload_hash,
+            response_payload_hash=response_payload_hash,
+            response_inspection_result=response_inspection_result,
+            session_sensitivity_before=session_sensitivity_before,
+            session_sensitivity_after=session_sensitivity_after,
+            detail=detail,
+            workflow_id=workflow_id,
+            prev_entry_hash=prev_hash,
+        )
+        entry.entry_hash = entry.compute_hash()
+        self._entries.append(entry)
+        return entry
+
+    @property
+    def chain_root(self) -> str:
+        """SHA-256 hash of the first entry (session_start)."""
+        return self._entries[0].entry_hash
+
+    @property
+    def chain_tip(self) -> str:
+        """SHA-256 hash of the most recent entry."""
+        return self._entries[-1].entry_hash
+
+    @property
+    def length(self) -> int:
+        return len(self._entries)
+
+    @property
+    def entries(self) -> list[AuditEntry]:
+        return list(self._entries)
+
+    def verify_chain(self) -> bool:
+        """
+        Re-compute all hashes and verify internal consistency.
+
+        AUDIT-002: if a TEE anchor has been set, also verify that the current
+        chain_root matches the externally-committed value.  A chain that was
+        silently replaced by an attacker will have a different root and fail
+        this check even if its internal hash links are self-consistent.
+
+        If no anchor is set (dev / Level-0 mode), emit a warning but do not
+        fail — the caller should ensure set_tee_anchor() is called in
+        production.
+        """
+        if not self._entries:
+            return True
+        if self._entries[0].prev_entry_hash != "genesis":
+            return False
+        for i, entry in enumerate(self._entries):
+            expected = entry.compute_hash()
+            if entry.entry_hash != expected:
+                return False
+            if i > 0 and entry.prev_entry_hash != self._entries[i - 1].entry_hash:
+                return False
+
+        # AUDIT-002: external anchor check.
+        if self._tee_anchor is None:
+            logger.warning(
+                "AUDIT-002: audit chain has no TEE anchor — chain substitution cannot be "
+                "detected. Call set_tee_anchor() at session start in production. "
+                "session_id=%s",
+                self._session_id,
+            )
+        elif self.chain_root != self._tee_anchor:
+            return False
+
+        return True

cmcp_runtime/audit/keys.py

@@ -0,0 +1,48 @@
+"""Ed25519 signing key management — implements issue #46."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    PublicFormat,
+)
+
+
+class SigningKey:
+    """
+    Ephemeral Ed25519 keypair generated at gateway startup.
+
+    The private key is held only in memory and never written to disk or logged.
+    Every gateway restart produces a different keypair (conformance: ATTEST-004).
+    The public key is embedded in every TRACE Claim so verifiers can check
+    signatures without trusting the operator.
+    """
+
+    def __init__(self) -> None:
+        self._private: Ed25519PrivateKey = Ed25519PrivateKey.generate()
+        self._public: Ed25519PublicKey = self._private.public_key()
+        self._public_bytes: bytes = self._public.public_bytes(
+            encoding=Encoding.Raw,
+            format=PublicFormat.Raw,
+        )
+
+    @property
+    def public_key_hex(self) -> str:
+        """32-byte Ed25519 public key, hex-encoded — included in every TRACE Claim."""
+        return self._public_bytes.hex()
+
+    @property
+    def public_key_bytes(self) -> bytes:
+        """Raw 32-byte public key bytes."""
+        return self._public_bytes
+
+    def sign(self, data: bytes) -> bytes:
+        """Sign data with the private key. Returns 64-byte Ed25519 signature."""
+        return self._private.sign(data)
+
+    def __repr__(self) -> str:
+        return f"SigningKey(public={self.public_key_hex[:16]}...)"

cmcp_runtime/audit/trace_claim.py

@@ -0,0 +1,342 @@
+"""TRACE Claim (cmcp profile) — RuntimeClaim envelope wrapping canonical TRACE fields."""
+
+from __future__ import annotations
+
+import base64
+import importlib.metadata
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Annotated, Any, Literal
+
+from agentrust_trace.models import JWK, ConfirmationKey, PolicyInfo, RuntimeInfo, ToolTranscript
+from pydantic import BaseModel, ConfigDict, Field
+
+try:
+    _RUNTIME_VERSION: str = importlib.metadata.version("cmcp-runtime")  # was cmcp-gateway
+except importlib.metadata.PackageNotFoundError:
+    _RUNTIME_VERSION = "unknown"
+
+# ── Provider → canonical platform mapping ─────────────────────────────────────
+
+_PROVIDER_MAP: dict[str, str] = {
+    "sev-snp": "amd-sev-snp",
+    "tdx": "intel-tdx",
+    "opaque": "intel-tdx",
+    "tpm": "tpm2",
+    "software-only": "tpm2",
+}
+
+_SW_ONLY_MEASUREMENT = "sha256:" + "0" * 64
+_SW_ONLY_FIRMWARE = "software-only-dev-mode"
+
+# ── Input DTOs (unchanged interface for callers) ───────────────────────────────
+
+
+@dataclass
+class CallGraphSummary:
+    compliance_domains_touched: list[str]
+    cross_boundary_events: list[dict[str, Any]]
+    #: Clarifies that edges are temporal adjacency, not data provenance (issue #94).
+    edges_represent: str | None = None
+
+
+@dataclass
+class CallSummary:
+    tool_calls_total: int
+    tool_calls_allowed: int
+    tool_calls_denied: int
+    tool_calls_faulted: int
+    tools_invoked: list[str]
+    session_max_sensitivity: str
+    call_graph_summary: CallGraphSummary
+
+
+@dataclass
+class PolicyBundleInfo:
+    hash: str
+    enforcement_mode: str
+    policy_version: str
+
+
+@dataclass
+class ToolCatalogInfo:
+    hash: str
+    drift_detected: bool = False
+
+
+@dataclass
+class AttestationReportInfo:
+    provider: str
+    measurement: str
+    report_data: str
+    attestation_generated_at: str
+    attestation_validity_seconds: int
+    measurement_note: str | None = None
+    raw_evidence: str | None = None
+
+
+# ── Pydantic output models ─────────────────────────────────────────────────────
+
+
+class CallGraphOut(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    compliance_domains_touched: list[str]
+    cross_boundary_events: list[dict[str, Any]]
+    #: Clarifies that edges are temporal adjacency, not data provenance (issue #94).
+    edges_represent: str | None = None
+
+
+class CallSummaryOut(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tool_calls_total: int
+    tool_calls_allowed: int
+    tool_calls_denied: int
+    tool_calls_faulted: int
+    tools_invoked: list[str]
+    session_max_sensitivity: str
+    call_graph_summary: CallGraphOut
+
+
+class AuditChainSummary(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    root: str
+    tip: str
+    length: int
+
+
+class CatalogSummary(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    hash: str
+    drift_detected: bool = False
+
+
+class GatewayTrace(BaseModel):
+    """Phase 1 TRACE fields applicable to the cmcp runtime context."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    eat_profile: Literal["tag:agentrust.io,2026:trace-v0.1"]
+    iat: Annotated[int, Field(ge=1700000000)]
+    subject: Annotated[str, Field(pattern=r"^spiffe://")]
+    runtime: RuntimeInfo
+    policy: PolicyInfo
+    data_class: str
+    tool_transcript: ToolTranscript | None = None
+    cnf: ConfirmationKey
+
+
+class CallLogSummary(BaseModel):
+    """Per-session call log summary included in the gateway addenda."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    total_calls: int
+    tools_called: list[str]
+    suspicious_sequences_detected: int
+
+
+class GatewayAddenda(BaseModel):
+    """cmcp-specific fields outside the canonical TRACE spec."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    session_id: str
+    gateway_version: str
+    sequence_number: int  # AUDIT-005: monotonically increasing across all claims from this instance
+    prev_claim_hash: str | None = None  # AUDIT-005: sha256 of previous claim's canonical JSON
+    audit_chain: AuditChainSummary
+    call_summary: CallSummaryOut
+    catalog: CatalogSummary
+    attestation_generated_at: str
+    attestation_validity_seconds: int
+    attestation_stale: bool
+    catalog_exceptions: list[dict[str, str]] = Field(default_factory=list)
+    call_log_summary: CallLogSummary | None = None
+
+
+class RuntimeClaim(BaseModel):
+    """cmcp TRACE profile — canonical trust fields nested inside a gateway envelope."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    cmcp_version: str = "1.0"
+    trace: GatewayTrace
+    gateway: GatewayAddenda
+    signature: str = ""
+
+
+# ── Serialization and signing ──────────────────────────────────────────────────
+
+
+def _to_dict(claim: RuntimeClaim) -> dict[str, Any]:
+    return claim.model_dump(exclude_none=True)
+
+
+def canonical_json(claim_dict: dict[str, Any]) -> bytes:
+    """Canonical serialization for signing: sorted keys, no whitespace, UTF-8.
+
+    The 'signature' field is excluded from the body being signed.
+    """
+    body = {k: v for k, v in claim_dict.items() if k != "signature"}
+    return json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode()
+
+
+def sign_trace_claim(claim: RuntimeClaim, signing_key: Any) -> str:
+    """Sign the RuntimeClaim with the TEE-sealed Ed25519 private key.
+
+    Returns base64url-encoded signature (no padding).
+    """
+    claim_dict = _to_dict(claim)
+    body = canonical_json(claim_dict)
+    raw_sig = signing_key.sign(body)
+    return base64.urlsafe_b64encode(raw_sig).rstrip(b"=").decode()
+
+
+# ── Builder helpers ────────────────────────────────────────────────────────────
+
+
+def _build_runtime(report: AttestationReportInfo) -> RuntimeInfo:
+    provider = report.provider
+    if provider not in _PROVIDER_MAP:
+        raise ValueError(
+            f"Attestation provider '{provider}' is not in the allowed set "
+            f"{sorted(_PROVIDER_MAP.keys())}. "
+            "Rejecting claim construction to prevent spoofed attestation reports."
+        )
+    platform = _PROVIDER_MAP[provider]
+
+    if provider == "software-only":
+        return RuntimeInfo(
+            platform=platform,  # type: ignore[arg-type]
+            measurement=_SW_ONLY_MEASUREMENT,
+            firmware_version=_SW_ONLY_FIRMWARE,
+        )
+
+    measurement = (
+        report.measurement
+        if report.measurement.startswith(("sha256:", "sha384:"))
+        else f"sha256:{report.measurement}"
+    )
+    # CRYPTO-003: raise on malformed report_data instead of silently dropping the nonce.
+    # A missing nonce removes the binding between the attestation report and the session;
+    # a malformed report_data indicates a broken or compromised TEE shim.
+    try:
+        nonce = base64.urlsafe_b64encode(bytes.fromhex(report.report_data)).rstrip(b"=").decode()
+    except ValueError as exc:
+        raise ValueError(
+            f"TEE attestation report contains malformed report_data: {exc!r}. "
+            "The nonce binding to the session cannot be established. "
+            "Check the TEE provider implementation."
+        ) from exc
+
+    return RuntimeInfo(platform=platform, measurement=measurement, nonce=nonce)  # type: ignore[arg-type]
+
+
+def _build_policy(bundle: PolicyBundleInfo) -> PolicyInfo:
+    mode_map = {"enforcing": "enforce", "advisory": "advisory", "silent": "silent"}
+    return PolicyInfo(
+        bundle_hash=bundle.hash,
+        enforcement_mode=mode_map.get(bundle.enforcement_mode, "advisory"),  # type: ignore[arg-type]
+        version=bundle.policy_version,
+    )
+
+
+def _build_cnf(signing_key: Any) -> ConfirmationKey:
+    pub_hex: str = signing_key.public_key_hex
+    x = base64.urlsafe_b64encode(bytes.fromhex(pub_hex)).rstrip(b"=").decode()
+    kid = f"cmcp-{pub_hex[:8]}"
+    return ConfirmationKey(jwk=JWK(kty="OKP", crv="Ed25519", x=x, kid=kid))
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+
+def generate_trace_claim(
+    *,
+    session_id: str,
+    signing_key: Any,
+    attestation_report: AttestationReportInfo,
+    policy_bundle: PolicyBundleInfo,
+    tool_catalog: ToolCatalogInfo,
+    call_summary: CallSummary,
+    audit_chain_root: str,
+    audit_chain_tip: str,
+    audit_chain_length: int,
+    attestation_stale: bool = False,
+    catalog_exceptions: list[dict[str, str]] | None = None,
+    call_log_summary: CallLogSummary | None = None,
+    sequence_number: int = 1,
+    prev_claim_hash: str | None = None,
+    do_sign: bool = True,
+) -> RuntimeClaim:
+    """Generate a RuntimeClaim from session data, validate it via Pydantic, and optionally sign it.
+
+    signing_key must be a SigningKey instance (audit/keys.py) — it is always required
+    to build the JWK confirmation key in trace.cnf.  Set do_sign=False to produce an
+    unsigned claim (e.g. in tests).
+    """
+    tool_transcript_hash = (
+        audit_chain_tip
+        if audit_chain_tip.startswith(("sha256:", "sha384:"))
+        else f"sha256:{audit_chain_tip}"
+    )
+
+    trace = GatewayTrace(
+        eat_profile="tag:agentrust.io,2026:trace-v0.1",
+        iat=int(datetime.now(tz=UTC).timestamp()),
+        subject=f"spiffe://cmcp.gateway/session/{session_id}",
+        runtime=_build_runtime(attestation_report),
+        policy=_build_policy(policy_bundle),
+        data_class=call_summary.session_max_sensitivity,
+        tool_transcript=ToolTranscript(
+            hash=tool_transcript_hash,
+            call_count=call_summary.tool_calls_total,
+        ),
+        cnf=_build_cnf(signing_key),
+    )
+
+    gateway = GatewayAddenda(
+        session_id=session_id,
+        gateway_version=_RUNTIME_VERSION,
+        sequence_number=sequence_number,
+        prev_claim_hash=prev_claim_hash,
+        audit_chain=AuditChainSummary(
+            root=audit_chain_root,
+            tip=audit_chain_tip,
+            length=audit_chain_length,
+        ),
+        call_summary=CallSummaryOut(
+            tool_calls_total=call_summary.tool_calls_total,
+            tool_calls_allowed=call_summary.tool_calls_allowed,
+            tool_calls_denied=call_summary.tool_calls_denied,
+            tool_calls_faulted=call_summary.tool_calls_faulted,
+            tools_invoked=call_summary.tools_invoked,
+            session_max_sensitivity=call_summary.session_max_sensitivity,
+            call_graph_summary=CallGraphOut(
+                compliance_domains_touched=call_summary.call_graph_summary.compliance_domains_touched,
+                cross_boundary_events=call_summary.call_graph_summary.cross_boundary_events,
+                edges_represent=call_summary.call_graph_summary.edges_represent,
+            ),
+        ),
+        catalog=CatalogSummary(
+            hash=tool_catalog.hash,
+            drift_detected=tool_catalog.drift_detected,
+        ),
+        attestation_generated_at=attestation_report.attestation_generated_at,
+        attestation_validity_seconds=attestation_report.attestation_validity_seconds,
+        attestation_stale=attestation_stale,
+        catalog_exceptions=catalog_exceptions or [],
+        call_log_summary=call_log_summary,
+    )
+
+    claim = RuntimeClaim(trace=trace, gateway=gateway)
+
+    if do_sign:
+        claim.signature = sign_trace_claim(claim, signing_key)
+
+    return claim