agentmesh-platform 1.0.0a1__py3-none-any.whl

agentmesh/identity/spiffe.py

@@ -0,0 +1,230 @@
+"""
+SPIFFE/SVID Integration
+
+Workload identity using SPIFFE (Secure Production Identity Framework
+for Everyone) and SVID (SPIFFE Verifiable Identity Documents).
+
+SPIFFE/SVID provides:
+- Mutual TLS for all agent transport
+- Zero cleartext traffic between agents
+- Standard workload identity
+"""
+
+from datetime import datetime, timedelta
+from typing import Optional, Literal
+from pydantic import BaseModel, Field
+import hashlib
+
+
+class SVID(BaseModel):
+    """
+    SPIFFE Verifiable Identity Document.
+    
+    An SVID is the document that carries the SPIFFE ID and can be
+    validated by a third party. AgentMesh uses X.509-SVID format.
+    """
+    
+    spiffe_id: str = Field(..., description="SPIFFE ID (spiffe://trust-domain/path)")
+    svid_type: Literal["x509", "jwt"] = Field(default="x509")
+    
+    # Certificate data (X.509-SVID)
+    certificate_chain: Optional[list[str]] = Field(None, description="PEM-encoded cert chain")
+    private_key_type: Optional[str] = Field(None, description="Key type (e.g., 'EC P-256')")
+    
+    # JWT-SVID fields
+    jwt_token: Optional[str] = Field(None, description="JWT-SVID token")
+    
+    # Metadata
+    trust_domain: str = Field(..., description="SPIFFE trust domain")
+    issued_at: datetime = Field(default_factory=datetime.utcnow)
+    expires_at: datetime = Field(...)
+    
+    # Agent binding
+    agent_did: str = Field(..., description="AgentMesh DID this SVID belongs to")
+    
+    @classmethod
+    def parse_spiffe_id(cls, spiffe_id: str) -> tuple[str, str]:
+        """
+        Parse a SPIFFE ID into trust domain and path.
+        
+        Format: spiffe://trust-domain/path
+        """
+        if not spiffe_id.startswith("spiffe://"):
+            raise ValueError(f"Invalid SPIFFE ID: {spiffe_id}")
+        
+        parts = spiffe_id[9:].split("/", 1)  # Remove "spiffe://"
+        trust_domain = parts[0]
+        path = "/" + parts[1] if len(parts) > 1 else "/"
+        
+        return trust_domain, path
+    
+    def is_valid(self) -> bool:
+        """Check if SVID is currently valid."""
+        now = datetime.utcnow()
+        return self.issued_at <= now < self.expires_at
+    
+    def time_remaining(self) -> timedelta:
+        """Get time remaining until expiration."""
+        return max(timedelta(0), self.expires_at - datetime.utcnow())
+
+
+class SPIFFEIdentity(BaseModel):
+    """
+    SPIFFE Identity for an agent.
+    
+    Maps AgentMesh identity to SPIFFE workload identity,
+    enabling mTLS with other SPIFFE-aware workloads.
+    """
+    
+    # AgentMesh identity
+    agent_did: str = Field(..., description="AgentMesh DID")
+    agent_name: str = Field(...)
+    
+    # SPIFFE identity
+    spiffe_id: str = Field(..., description="Full SPIFFE ID")
+    trust_domain: str = Field(...)
+    workload_path: str = Field(...)
+    
+    # Current SVID
+    current_svid: Optional[SVID] = Field(None)
+    
+    # Metadata
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    @classmethod
+    def create(
+        cls,
+        agent_did: str,
+        agent_name: str,
+        trust_domain: str = "agentmesh.local",
+        organization: Optional[str] = None,
+    ) -> "SPIFFEIdentity":
+        """
+        Create SPIFFE identity for an agent.
+        
+        SPIFFE ID format: spiffe://trust-domain/agentmesh/org/agent-name
+        """
+        # Build workload path
+        org_part = f"/{organization}" if organization else ""
+        workload_path = f"/agentmesh{org_part}/{agent_name}"
+        
+        spiffe_id = f"spiffe://{trust_domain}{workload_path}"
+        
+        return cls(
+            agent_did=agent_did,
+            agent_name=agent_name,
+            spiffe_id=spiffe_id,
+            trust_domain=trust_domain,
+            workload_path=workload_path,
+        )
+    
+    def issue_svid(
+        self,
+        ttl_hours: int = 1,
+        svid_type: Literal["x509", "jwt"] = "x509",
+    ) -> SVID:
+        """
+        Issue a new SVID for this identity.
+        
+        In production, this would request an SVID from the SPIRE server.
+        """
+        now = datetime.utcnow()
+        
+        svid = SVID(
+            spiffe_id=self.spiffe_id,
+            svid_type=svid_type,
+            trust_domain=self.trust_domain,
+            issued_at=now,
+            expires_at=now + timedelta(hours=ttl_hours),
+            agent_did=self.agent_did,
+        )
+        
+        self.current_svid = svid
+        return svid
+    
+    def get_valid_svid(self) -> Optional[SVID]:
+        """Get current SVID if valid, None otherwise."""
+        if self.current_svid and self.current_svid.is_valid():
+            return self.current_svid
+        return None
+    
+    def needs_rotation(self, threshold_minutes: int = 10) -> bool:
+        """Check if SVID needs rotation."""
+        if not self.current_svid:
+            return True
+        
+        remaining = self.current_svid.time_remaining()
+        return remaining < timedelta(minutes=threshold_minutes)
+
+
+class SPIFFERegistry:
+    """
+    Registry mapping AgentMesh identities to SPIFFE identities.
+    
+    In production, this would integrate with SPIRE.
+    """
+    
+    DEFAULT_TRUST_DOMAIN = "agentmesh.local"
+    
+    def __init__(self, trust_domain: Optional[str] = None):
+        self.trust_domain = trust_domain or self.DEFAULT_TRUST_DOMAIN
+        self._identities: dict[str, SPIFFEIdentity] = {}  # agent_did -> SPIFFEIdentity
+    
+    def register(
+        self,
+        agent_did: str,
+        agent_name: str,
+        organization: Optional[str] = None,
+    ) -> SPIFFEIdentity:
+        """Register an agent and create SPIFFE identity."""
+        if agent_did in self._identities:
+            return self._identities[agent_did]
+        
+        identity = SPIFFEIdentity.create(
+            agent_did=agent_did,
+            agent_name=agent_name,
+            trust_domain=self.trust_domain,
+            organization=organization,
+        )
+        
+        self._identities[agent_did] = identity
+        return identity
+    
+    def get(self, agent_did: str) -> Optional[SPIFFEIdentity]:
+        """Get SPIFFE identity for an agent."""
+        return self._identities.get(agent_did)
+    
+    def get_by_spiffe_id(self, spiffe_id: str) -> Optional[SPIFFEIdentity]:
+        """Get identity by SPIFFE ID."""
+        for identity in self._identities.values():
+            if identity.spiffe_id == spiffe_id:
+                return identity
+        return None
+    
+    def issue_svid(self, agent_did: str) -> Optional[SVID]:
+        """Issue an SVID for an agent."""
+        identity = self.get(agent_did)
+        if not identity:
+            return None
+        return identity.issue_svid()
+    
+    def validate_svid(self, svid: SVID) -> bool:
+        """
+        Validate an SVID.
+        
+        In production, would verify against SPIRE bundle.
+        """
+        # Check basic validity
+        if not svid.is_valid():
+            return False
+        
+        # Verify trust domain matches
+        if svid.trust_domain != self.trust_domain:
+            return False
+        
+        # Verify agent is registered
+        identity = self.get(svid.agent_did)
+        if not identity:
+            return False
+        
+        return True

agentmesh/identity/sponsor.py

@@ -0,0 +1,178 @@
+"""
+Human Sponsor
+
+Every agent identity is linked to a human sponsor who is accountable.
+The sponsor's credentials are cryptographically linked to the delegation chain.
+"""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field, EmailStr
+import hashlib
+import uuid
+
+
+class HumanSponsor(BaseModel):
+    """
+    Human sponsor responsible for an agent's actions.
+    
+    The sponsor is the accountability anchor - when an agent causes
+    damage, the sponsor is responsible.
+    """
+    
+    sponsor_id: str = Field(..., description="Unique sponsor identifier")
+    
+    # Identity
+    email: EmailStr = Field(..., description="Verified email address")
+    name: Optional[str] = Field(None, description="Human name")
+    
+    # Organization
+    organization_id: Optional[str] = Field(None)
+    organization_name: Optional[str] = Field(None)
+    department: Optional[str] = Field(None)
+    
+    # Verification
+    verified: bool = Field(default=False)
+    verified_at: Optional[datetime] = Field(None)
+    verification_method: Optional[str] = Field(None)  # "email", "sso", "manual"
+    
+    # Permissions
+    max_agents: int = Field(default=10, description="Max agents this sponsor can create")
+    max_delegation_depth: int = Field(default=3, description="Max delegation chain depth")
+    allowed_capabilities: list[str] = Field(default_factory=list)
+    
+    # Status
+    status: str = Field(default="active")  # active, suspended, revoked
+    
+    # Agents
+    agent_dids: list[str] = Field(default_factory=list, description="DIDs of sponsored agents")
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    last_activity_at: Optional[datetime] = Field(None)
+    
+    @classmethod
+    def create(
+        cls,
+        email: str,
+        name: Optional[str] = None,
+        organization: Optional[str] = None,
+        allowed_capabilities: Optional[list[str]] = None,
+    ) -> "HumanSponsor":
+        """Create a new human sponsor."""
+        sponsor_id = f"sponsor_{uuid.uuid4().hex[:16]}"
+        
+        return cls(
+            sponsor_id=sponsor_id,
+            email=email,
+            name=name,
+            organization_name=organization,
+            allowed_capabilities=allowed_capabilities or ["*"],  # Default: all capabilities
+        )
+    
+    def verify(self, method: str = "email") -> None:
+        """Mark sponsor as verified."""
+        self.verified = True
+        self.verified_at = datetime.utcnow()
+        self.verification_method = method
+    
+    def can_sponsor_agent(self) -> bool:
+        """Check if sponsor can create more agents."""
+        if self.status != "active":
+            return False
+        if not self.verified:
+            return False
+        return len(self.agent_dids) < self.max_agents
+    
+    def can_grant_capability(self, capability: str) -> bool:
+        """Check if sponsor can grant a specific capability."""
+        if "*" in self.allowed_capabilities:
+            return True
+        
+        if capability in self.allowed_capabilities:
+            return True
+        
+        # Check prefix matching
+        for allowed in self.allowed_capabilities:
+            if allowed.endswith(":*"):
+                prefix = allowed[:-2]
+                if capability.startswith(prefix + ":"):
+                    return True
+        
+        return False
+    
+    def add_agent(self, agent_did: str) -> None:
+        """Track a new agent sponsored by this human."""
+        if agent_did not in self.agent_dids:
+            self.agent_dids.append(agent_did)
+            self.last_activity_at = datetime.utcnow()
+    
+    def remove_agent(self, agent_did: str) -> None:
+        """Remove an agent from sponsorship."""
+        if agent_did in self.agent_dids:
+            self.agent_dids.remove(agent_did)
+    
+    def suspend(self, reason: Optional[str] = None) -> None:
+        """Suspend this sponsor (and all their agents should be suspended too)."""
+        self.status = "suspended"
+    
+    def reactivate(self) -> None:
+        """Reactivate a suspended sponsor."""
+        if self.status == "revoked":
+            raise ValueError("Cannot reactivate a revoked sponsor")
+        self.status = "active"
+
+
+class SponsorRegistry:
+    """
+    Registry for human sponsors.
+    
+    Tracks who is accountable for which agents.
+    """
+    
+    def __init__(self):
+        self._sponsors: dict[str, HumanSponsor] = {}
+        self._by_email: dict[str, str] = {}  # email -> sponsor_id
+    
+    def register(self, sponsor: HumanSponsor) -> None:
+        """Register a new sponsor."""
+        if sponsor.email in self._by_email:
+            raise ValueError(f"Sponsor already registered: {sponsor.email}")
+        
+        self._sponsors[sponsor.sponsor_id] = sponsor
+        self._by_email[sponsor.email] = sponsor.sponsor_id
+    
+    def get(self, sponsor_id: str) -> Optional[HumanSponsor]:
+        """Get sponsor by ID."""
+        return self._sponsors.get(sponsor_id)
+    
+    def get_by_email(self, email: str) -> Optional[HumanSponsor]:
+        """Get sponsor by email."""
+        sponsor_id = self._by_email.get(email)
+        if sponsor_id:
+            return self._sponsors.get(sponsor_id)
+        return None
+    
+    def get_or_create(
+        self,
+        email: str,
+        name: Optional[str] = None,
+        organization: Optional[str] = None,
+    ) -> HumanSponsor:
+        """Get existing sponsor or create new one."""
+        existing = self.get_by_email(email)
+        if existing:
+            return existing
+        
+        sponsor = HumanSponsor.create(email, name, organization)
+        self.register(sponsor)
+        return sponsor
+    
+    def suspend_all_for_org(self, organization_id: str) -> int:
+        """Suspend all sponsors in an organization."""
+        count = 0
+        for sponsor in self._sponsors.values():
+            if sponsor.organization_id == organization_id:
+                sponsor.suspend()
+                count += 1
+        return count

agentmesh/reward/__init__.py

@@ -0,0 +1,19 @@
+"""
+Reward & Learning Engine (Layer 4)
+
+Continuous behavioral feedback loop that scores every agent action
+against a multi-dimensional governance rubric.
+"""
+
+from .engine import RewardEngine
+from .scoring import TrustScore, RewardDimension, RewardSignal
+from .learning import AdaptiveLearner, WeightOptimizer
+
+__all__ = [
+    "RewardEngine",
+    "TrustScore",
+    "RewardDimension",
+    "RewardSignal",
+    "AdaptiveLearner",
+    "WeightOptimizer",
+]