agentmesh-platform 1.0.0a1__py3-none-any.whl

agentmesh/identity/delegation.py

@@ -0,0 +1,281 @@
+"""
+Delegation Chains
+
+Cryptographic delegation chains that ensure sub-agents can never
+have more capabilities than their parent. Scope always narrows.
+"""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+import hashlib
+import json
+
+
+class DelegationLink(BaseModel):
+    """
+    A single link in a delegation chain.
+    
+    Each link represents a parent granting capabilities to a child.
+    The child's capabilities MUST be a subset of the parent's.
+    """
+    
+    link_id: str = Field(..., description="Unique link identifier")
+    
+    # Chain position
+    depth: int = Field(..., ge=0, description="Depth in chain (0 = root)")
+    
+    # Agents
+    parent_did: str = Field(..., description="DID of parent agent")
+    child_did: str = Field(..., description="DID of child agent")
+    
+    # Capability narrowing
+    parent_capabilities: list[str] = Field(..., description="Parent's capabilities at delegation time")
+    delegated_capabilities: list[str] = Field(..., description="Capabilities granted to child")
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    expires_at: Optional[datetime] = Field(None)
+    
+    # Cryptographic binding
+    parent_signature: str = Field(..., description="Parent's signature on this delegation")
+    link_hash: str = Field(..., description="Hash of this link for chain verification")
+    previous_link_hash: Optional[str] = Field(None, description="Hash of previous link in chain")
+    
+    def verify_capability_narrowing(self) -> bool:
+        """Verify that delegated capabilities are a subset of parent's."""
+        for cap in self.delegated_capabilities:
+            if cap not in self.parent_capabilities:
+                # Check for wildcard narrowing (e.g., read:* -> read:data)
+                if not self._is_narrower_capability(cap, self.parent_capabilities):
+                    return False
+        return True
+    
+    def _is_narrower_capability(self, cap: str, parent_caps: list[str]) -> bool:
+        """Check if a capability is a narrowed version of a parent capability."""
+        for parent_cap in parent_caps:
+            if parent_cap == "*":
+                return True
+            if parent_cap.endswith(":*"):
+                prefix = parent_cap[:-2]
+                if cap.startswith(prefix + ":"):
+                    return True
+        return False
+    
+    def compute_hash(self) -> str:
+        """Compute hash of this link for chain verification."""
+        data = {
+            "link_id": self.link_id,
+            "depth": self.depth,
+            "parent_did": self.parent_did,
+            "child_did": self.child_did,
+            "delegated_capabilities": sorted(self.delegated_capabilities),
+            "created_at": self.created_at.isoformat(),
+            "previous_link_hash": self.previous_link_hash,
+        }
+        canonical = json.dumps(data, sort_keys=True)
+        return hashlib.sha256(canonical.encode()).hexdigest()
+    
+    def is_valid(self) -> bool:
+        """Check if this link is valid."""
+        # Check expiration
+        if self.expires_at and datetime.utcnow() > self.expires_at:
+            return False
+        
+        # Verify capability narrowing
+        if not self.verify_capability_narrowing():
+            return False
+        
+        # Verify hash
+        if self.link_hash != self.compute_hash():
+            return False
+        
+        return True
+
+
+class DelegationChain(BaseModel):
+    """
+    Complete delegation chain from root sponsor to current agent.
+    
+    Properties:
+    - Immutable once created
+    - Each link narrows capabilities
+    - Cryptographically verifiable
+    - Traceable to human sponsor
+    """
+    
+    chain_id: str = Field(..., description="Unique chain identifier")
+    
+    # Root (human sponsor)
+    root_sponsor_email: str = Field(..., description="Human sponsor at chain root")
+    root_sponsor_verified: bool = Field(default=False)
+    root_capabilities: list[str] = Field(..., description="Capabilities granted by sponsor")
+    
+    # Chain links
+    links: list[DelegationLink] = Field(default_factory=list)
+    
+    # Final agent
+    leaf_did: str = Field(..., description="DID of the agent at end of chain")
+    leaf_capabilities: list[str] = Field(..., description="Final effective capabilities")
+    
+    # Chain metadata
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    total_depth: int = Field(default=0)
+    
+    # Verification
+    chain_hash: str = Field(default="", description="Hash of entire chain")
+    
+    def add_link(self, link: DelegationLink) -> None:
+        """
+        Add a link to the chain.
+        
+        Validates that:
+        1. Link connects to current leaf
+        2. Capabilities are properly narrowed
+        3. Link hash is correct
+        """
+        if self.links:
+            last_link = self.links[-1]
+            if link.parent_did != last_link.child_did:
+                raise ValueError("Link does not connect to chain")
+            if link.previous_link_hash != last_link.link_hash:
+                raise ValueError("Link hash does not match previous link")
+        else:
+            # First link - parent should be root
+            if link.depth != 0:
+                raise ValueError("First link must have depth 0")
+        
+        # Verify capability narrowing
+        if not link.verify_capability_narrowing():
+            raise ValueError("Link does not properly narrow capabilities")
+        
+        self.links.append(link)
+        self.total_depth = len(self.links)
+        self.leaf_did = link.child_did
+        self.leaf_capabilities = link.delegated_capabilities
+        self._update_chain_hash()
+    
+    def verify(self) -> tuple[bool, Optional[str]]:
+        """
+        Verify the entire chain.
+        
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not self.links:
+            return True, None
+        
+        previous_hash = None
+        previous_capabilities = self.root_capabilities
+        
+        for i, link in enumerate(self.links):
+            # Verify depth
+            if link.depth != i:
+                return False, f"Invalid depth at link {i}"
+            
+            # Verify hash chain
+            if link.previous_link_hash != previous_hash:
+                return False, f"Hash chain broken at link {i}"
+            
+            # Verify capability narrowing against actual previous capabilities
+            for cap in link.delegated_capabilities:
+                if cap not in previous_capabilities:
+                    if not link._is_narrower_capability(cap, previous_capabilities):
+                        return False, f"Capability escalation at link {i}: {cap}"
+            
+            # Verify link hash
+            if link.link_hash != link.compute_hash():
+                return False, f"Invalid link hash at link {i}"
+            
+            previous_hash = link.link_hash
+            previous_capabilities = link.delegated_capabilities
+        
+        return True, None
+    
+    def get_effective_capabilities(self) -> list[str]:
+        """Get the effective capabilities at the end of the chain."""
+        if self.links:
+            return self.links[-1].delegated_capabilities
+        return self.root_capabilities
+    
+    def trace_capability(self, capability: str) -> list[dict]:
+        """
+        Trace how a capability was granted through the chain.
+        
+        Returns list of grants/narrowings from root to leaf.
+        """
+        trace = []
+        
+        # Check root
+        if capability in self.root_capabilities or "*" in self.root_capabilities:
+            trace.append({
+                "level": "root",
+                "grantor": self.root_sponsor_email,
+                "capability": capability,
+                "source_capabilities": self.root_capabilities,
+            })
+        
+        # Check each link
+        for link in self.links:
+            if capability in link.delegated_capabilities:
+                trace.append({
+                    "level": f"depth_{link.depth}",
+                    "grantor": link.parent_did,
+                    "grantee": link.child_did,
+                    "capability": capability,
+                    "parent_capabilities": link.parent_capabilities,
+                    "delegated_capabilities": link.delegated_capabilities,
+                })
+        
+        return trace
+    
+    def _update_chain_hash(self) -> None:
+        """Update the overall chain hash."""
+        data = {
+            "chain_id": self.chain_id,
+            "root_sponsor": self.root_sponsor_email,
+            "links": [link.link_hash for link in self.links],
+        }
+        canonical = json.dumps(data, sort_keys=True)
+        self.chain_hash = hashlib.sha256(canonical.encode()).hexdigest()
+    
+    @classmethod
+    def create_root(
+        cls,
+        sponsor_email: str,
+        root_agent_did: str,
+        capabilities: list[str],
+        sponsor_verified: bool = False,
+    ) -> tuple["DelegationChain", DelegationLink]:
+        """
+        Create a new chain with a root sponsor.
+        
+        Returns the chain and the first link to be signed.
+        """
+        import uuid
+        
+        chain_id = f"chain_{uuid.uuid4().hex[:16]}"
+        
+        chain = cls(
+            chain_id=chain_id,
+            root_sponsor_email=sponsor_email,
+            root_sponsor_verified=sponsor_verified,
+            root_capabilities=capabilities,
+            leaf_did=root_agent_did,
+            leaf_capabilities=capabilities,
+        )
+        
+        # Create first link (sponsor -> root agent)
+        link = DelegationLink(
+            link_id=f"link_{uuid.uuid4().hex[:12]}",
+            depth=0,
+            parent_did=f"did:mesh:sponsor:{sponsor_email}",
+            child_did=root_agent_did,
+            parent_capabilities=capabilities,
+            delegated_capabilities=capabilities,
+            parent_signature="",  # To be signed
+            link_hash="",  # To be computed after signing
+        )
+        link.link_hash = link.compute_hash()
+        
+        return chain, link

agentmesh/identity/risk.py

@@ -0,0 +1,279 @@
+"""
+Continuous Risk Scoring
+
+Updates trust score every ≤30s based on agent behavior.
+Score visible in dashboard; configurable alert thresholds.
+"""
+
+from datetime import datetime, timedelta
+from typing import Optional, Literal
+from pydantic import BaseModel, Field
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RiskSignal:
+    """A single risk signal contributing to the score."""
+    
+    signal_type: str
+    severity: Literal["critical", "high", "medium", "low", "info"]
+    value: float  # 0.0 to 1.0
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    source: Optional[str] = None
+    details: Optional[str] = None
+    
+    @property
+    def weight(self) -> float:
+        """Get weight based on severity."""
+        weights = {
+            "critical": 1.0,
+            "high": 0.75,
+            "medium": 0.5,
+            "low": 0.25,
+            "info": 0.1,
+        }
+        return weights.get(self.severity, 0.1)
+
+
+class RiskScore(BaseModel):
+    """
+    Comprehensive risk score for an agent.
+    
+    Score ranges from 0 (highest risk) to 1000 (lowest risk).
+    Inverted from trust score for clarity: lower = more risky.
+    """
+    
+    agent_did: str
+    
+    # Overall score (0-1000, higher = safer)
+    total_score: int = Field(default=500, ge=0, le=1000)
+    risk_level: Literal["critical", "high", "medium", "low", "minimal"] = "medium"
+    
+    # Component scores (0-100 each)
+    identity_score: int = Field(default=50, ge=0, le=100)
+    behavior_score: int = Field(default=50, ge=0, le=100)
+    network_score: int = Field(default=50, ge=0, le=100)
+    compliance_score: int = Field(default=50, ge=0, le=100)
+    
+    # Signals
+    active_signals: int = Field(default=0)
+    critical_signals: int = Field(default=0)
+    
+    # Timestamps
+    calculated_at: datetime = Field(default_factory=datetime.utcnow)
+    next_update_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    @classmethod
+    def get_risk_level(cls, score: int) -> str:
+        """Convert score to risk level."""
+        if score >= 800:
+            return "minimal"
+        elif score >= 600:
+            return "low"
+        elif score >= 400:
+            return "medium"
+        elif score >= 200:
+            return "high"
+        else:
+            return "critical"
+    
+    def update(
+        self,
+        identity: int,
+        behavior: int,
+        network: int,
+        compliance: int,
+        active_signals: int = 0,
+        critical_signals: int = 0,
+    ) -> None:
+        """Update component scores and recalculate total."""
+        self.identity_score = max(0, min(100, identity))
+        self.behavior_score = max(0, min(100, behavior))
+        self.network_score = max(0, min(100, network))
+        self.compliance_score = max(0, min(100, compliance))
+        
+        # Weighted total (behavior and compliance weighted higher)
+        self.total_score = int(
+            self.identity_score * 2 +
+            self.behavior_score * 3 +
+            self.network_score * 2 +
+            self.compliance_score * 3
+        )  # Max: 1000
+        
+        self.risk_level = self.get_risk_level(self.total_score)
+        self.active_signals = active_signals
+        self.critical_signals = critical_signals
+        self.calculated_at = datetime.utcnow()
+        self.next_update_at = datetime.utcnow() + timedelta(seconds=30)
+
+
+class RiskScorer:
+    """
+    Continuous risk scoring engine.
+    
+    Updates trust score every ≤30s based on:
+    - Identity verification status
+    - Behavioral patterns
+    - Network activity
+    - Compliance violations
+    """
+    
+    UPDATE_INTERVAL = 30  # seconds
+    
+    # Alert thresholds
+    CRITICAL_THRESHOLD = 200
+    HIGH_THRESHOLD = 400
+    ALERT_THRESHOLD = 600
+    
+    def __init__(self):
+        self._scores: dict[str, RiskScore] = {}
+        self._signals: dict[str, list[RiskSignal]] = {}  # agent_did -> signals
+        self._alert_callbacks: list[callable] = []
+    
+    def get_score(self, agent_did: str) -> RiskScore:
+        """Get current risk score for an agent."""
+        if agent_did not in self._scores:
+            self._scores[agent_did] = RiskScore(agent_did=agent_did)
+        return self._scores[agent_did]
+    
+    def add_signal(self, agent_did: str, signal: RiskSignal) -> None:
+        """Add a risk signal for an agent."""
+        if agent_did not in self._signals:
+            self._signals[agent_did] = []
+        
+        self._signals[agent_did].append(signal)
+        
+        # Trigger immediate recalculation for critical signals
+        if signal.severity == "critical":
+            self.recalculate(agent_did)
+    
+    def recalculate(self, agent_did: str) -> RiskScore:
+        """
+        Recalculate risk score based on current signals.
+        
+        This is called every ≤30s or immediately on critical signals.
+        """
+        score = self.get_score(agent_did)
+        signals = self._signals.get(agent_did, [])
+        
+        # Filter to recent signals (last 24 hours)
+        cutoff = datetime.utcnow() - timedelta(hours=24)
+        recent_signals = [s for s in signals if s.timestamp > cutoff]
+        
+        # Calculate component scores
+        identity_score = self._calculate_identity_score(recent_signals)
+        behavior_score = self._calculate_behavior_score(recent_signals)
+        network_score = self._calculate_network_score(recent_signals)
+        compliance_score = self._calculate_compliance_score(recent_signals)
+        
+        # Count signals
+        active = len(recent_signals)
+        critical = len([s for s in recent_signals if s.severity == "critical"])
+        
+        # Update score
+        old_level = score.risk_level
+        score.update(
+            identity=identity_score,
+            behavior=behavior_score,
+            network=network_score,
+            compliance=compliance_score,
+            active_signals=active,
+            critical_signals=critical,
+        )
+        
+        # Check for alerts
+        self._check_alerts(agent_did, score, old_level)
+        
+        return score
+    
+    def _calculate_identity_score(self, signals: list[RiskSignal]) -> int:
+        """Calculate identity component score."""
+        base = 80  # Start at 80
+        
+        for signal in signals:
+            if signal.signal_type.startswith("identity."):
+                base -= int(signal.value * signal.weight * 20)
+        
+        return max(0, min(100, base))
+    
+    def _calculate_behavior_score(self, signals: list[RiskSignal]) -> int:
+        """Calculate behavior component score."""
+        base = 70
+        
+        for signal in signals:
+            if signal.signal_type.startswith("behavior."):
+                base -= int(signal.value * signal.weight * 25)
+        
+        return max(0, min(100, base))
+    
+    def _calculate_network_score(self, signals: list[RiskSignal]) -> int:
+        """Calculate network component score."""
+        base = 75
+        
+        for signal in signals:
+            if signal.signal_type.startswith("network."):
+                base -= int(signal.value * signal.weight * 20)
+        
+        return max(0, min(100, base))
+    
+    def _calculate_compliance_score(self, signals: list[RiskSignal]) -> int:
+        """Calculate compliance component score."""
+        base = 85  # Start higher - compliance is important
+        
+        for signal in signals:
+            if signal.signal_type.startswith("compliance."):
+                base -= int(signal.value * signal.weight * 30)
+        
+        return max(0, min(100, base))
+    
+    def _check_alerts(
+        self,
+        agent_did: str,
+        score: RiskScore,
+        old_level: str,
+    ) -> None:
+        """Check if alerts should be triggered."""
+        # Alert on level change
+        if score.risk_level != old_level:
+            for callback in self._alert_callbacks:
+                try:
+                    callback({
+                        "type": "risk_level_change",
+                        "agent_did": agent_did,
+                        "old_level": old_level,
+                        "new_level": score.risk_level,
+                        "score": score.total_score,
+                    })
+                except Exception:
+                    pass
+        
+        # Alert on threshold breach
+        if score.total_score < self.CRITICAL_THRESHOLD:
+            for callback in self._alert_callbacks:
+                try:
+                    callback({
+                        "type": "critical_risk",
+                        "agent_did": agent_did,
+                        "score": score.total_score,
+                        "action": "immediate_review_required",
+                    })
+                except Exception:
+                    pass
+    
+    def on_alert(self, callback: callable) -> None:
+        """Register an alert callback."""
+        self._alert_callbacks.append(callback)
+    
+    def get_high_risk_agents(self, threshold: Optional[int] = None) -> list[RiskScore]:
+        """Get all agents above risk threshold."""
+        thresh = threshold or self.HIGH_THRESHOLD
+        return [
+            score for score in self._scores.values()
+            if score.total_score < thresh
+        ]
+    
+    def clear_signals(self, agent_did: str) -> None:
+        """Clear all signals for an agent (e.g., after remediation)."""
+        if agent_did in self._signals:
+            self._signals[agent_did] = []
+        self.recalculate(agent_did)