agentmesh-platform 1.0.0a1__py3-none-any.whl

agentmesh/identity/agent_id.py

@@ -0,0 +1,319 @@
+"""
+Agent Identity
+
+Every agent gets a unique, cryptographically bound identity issued by AgentMesh CA.
+Identity persists across restarts; revocation propagates in ≤5s.
+"""
+
+from datetime import datetime
+from typing import Optional, Literal
+from pydantic import BaseModel, Field, field_validator
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from cryptography.hazmat.primitives import serialization
+import hashlib
+import uuid
+import base64
+
+
+class AgentDID(BaseModel):
+    """
+    Decentralized Identifier for an agent.
+    
+    Format: did:mesh:<unique-id>
+    """
+    
+    method: Literal["mesh"] = "mesh"
+    unique_id: str = Field(..., description="Unique identifier within the mesh")
+    
+    @classmethod
+    def generate(cls, name: str, org: Optional[str] = None) -> "AgentDID":
+        """Generate a new DID for an agent."""
+        # Create deterministic but unique ID
+        seed = f"{name}:{org or 'default'}:{uuid.uuid4().hex[:8]}"
+        unique_id = hashlib.sha256(seed.encode()).hexdigest()[:32]
+        return cls(unique_id=unique_id)
+    
+    @classmethod
+    def from_string(cls, did_string: str) -> "AgentDID":
+        """Parse a DID string."""
+        if not did_string.startswith("did:mesh:"):
+            raise ValueError(f"Invalid AgentMesh DID: {did_string}")
+        unique_id = did_string[9:]  # Remove "did:mesh:"
+        return cls(unique_id=unique_id)
+    
+    def __str__(self) -> str:
+        return f"did:{self.method}:{self.unique_id}"
+    
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+
+class AgentIdentity(BaseModel):
+    """
+    First-class identity for an AI agent.
+    
+    Unlike service accounts, agent identities:
+    - Are linked to a human sponsor
+    - Have ephemeral credentials
+    - Support delegation chains
+    - Are continuously risk-scored
+    """
+    
+    did: AgentDID = Field(..., description="Decentralized identifier")
+    name: str = Field(..., description="Human-readable agent name")
+    description: Optional[str] = Field(None, description="Agent description")
+    
+    # Cryptographic identity
+    public_key: str = Field(..., description="Ed25519 public key (base64)")
+    verification_key_id: str = Field(..., description="Key ID for verification")
+    
+    # Human sponsor (accountability)
+    sponsor_email: str = Field(..., description="Human sponsor email")
+    sponsor_verified: bool = Field(default=False, description="Whether sponsor is verified")
+    
+    # Organization
+    organization: Optional[str] = Field(None, description="Organization name")
+    organization_id: Optional[str] = Field(None, description="Organization identifier")
+    
+    # Capabilities (what this agent is allowed to do)
+    capabilities: list[str] = Field(default_factory=list)
+    
+    # Metadata
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    expires_at: Optional[datetime] = Field(None, description="Identity expiration")
+    
+    # Status
+    status: Literal["active", "suspended", "revoked"] = Field(default="active")
+    revocation_reason: Optional[str] = Field(None)
+    
+    # Delegation
+    parent_did: Optional[str] = Field(None, description="Parent agent DID if delegated")
+    delegation_depth: int = Field(default=0, description="Depth in delegation chain")
+    
+    # Private key stored separately (not serialized)
+    _private_key: Optional[ed25519.Ed25519PrivateKey] = None
+    
+    model_config = {"arbitrary_types_allowed": True}
+    
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        sponsor: str,
+        capabilities: Optional[list[str]] = None,
+        organization: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> "AgentIdentity":
+        """
+        Create a new agent identity.
+        
+        This is the primary factory method for creating governed agents.
+        """
+        # Generate keypair
+        private_key = ed25519.Ed25519PrivateKey.generate()
+        public_key = private_key.public_key()
+        
+        # Encode public key
+        public_key_bytes = public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+        public_key_b64 = base64.b64encode(public_key_bytes).decode()
+        
+        # Generate DID
+        did = AgentDID.generate(name, organization)
+        
+        # Create key ID
+        key_id = f"key-{hashlib.sha256(public_key_bytes).hexdigest()[:16]}"
+        
+        identity = cls(
+            did=did,
+            name=name,
+            description=description,
+            public_key=public_key_b64,
+            verification_key_id=key_id,
+            sponsor_email=sponsor,
+            organization=organization,
+            capabilities=capabilities or [],
+        )
+        
+        # Store private key (not serialized)
+        identity._private_key = private_key
+        
+        return identity
+    
+    def sign(self, data: bytes) -> str:
+        """Sign data with this agent's private key."""
+        if self._private_key is None:
+            raise ValueError("Private key not available for signing")
+        
+        signature = self._private_key.sign(data)
+        return base64.b64encode(signature).decode()
+    
+    def verify_signature(self, data: bytes, signature: str) -> bool:
+        """Verify a signature against this agent's public key."""
+        try:
+            public_key_bytes = base64.b64decode(self.public_key)
+            public_key = ed25519.Ed25519PublicKey.from_public_bytes(public_key_bytes)
+            signature_bytes = base64.b64decode(signature)
+            public_key.verify(signature_bytes, data)
+            return True
+        except Exception:
+            return False
+    
+    def delegate(
+        self,
+        name: str,
+        capabilities: list[str],
+        description: Optional[str] = None,
+    ) -> "AgentIdentity":
+        """
+        Delegate to a child agent with narrowed capabilities.
+        
+        The child agent's capabilities MUST be a subset of the parent's.
+        This is enforced cryptographically - delegation chains can only narrow.
+        """
+        # Validate capabilities are a subset
+        for cap in capabilities:
+            if cap not in self.capabilities:
+                raise ValueError(
+                    f"Cannot delegate capability '{cap}' - not in parent's capabilities"
+                )
+        
+        # Create child identity
+        child = AgentIdentity.create(
+            name=name,
+            sponsor=self.sponsor_email,
+            capabilities=capabilities,
+            organization=self.organization,
+            description=description,
+        )
+        
+        # Set delegation metadata
+        child.parent_did = str(self.did)
+        child.delegation_depth = self.delegation_depth + 1
+        
+        return child
+    
+    def revoke(self, reason: str) -> None:
+        """Revoke this identity."""
+        self.status = "revoked"
+        self.revocation_reason = reason
+        self.updated_at = datetime.utcnow()
+    
+    def suspend(self, reason: str) -> None:
+        """Temporarily suspend this identity."""
+        self.status = "suspended"
+        self.revocation_reason = reason
+        self.updated_at = datetime.utcnow()
+    
+    def reactivate(self) -> None:
+        """Reactivate a suspended identity."""
+        if self.status == "revoked":
+            raise ValueError("Cannot reactivate a revoked identity")
+        self.status = "active"
+        self.revocation_reason = None
+        self.updated_at = datetime.utcnow()
+    
+    def is_active(self) -> bool:
+        """Check if identity is active and not expired."""
+        if self.status != "active":
+            return False
+        if self.expires_at and datetime.utcnow() > self.expires_at:
+            return False
+        return True
+    
+    def has_capability(self, capability: str) -> bool:
+        """Check if this agent has a specific capability."""
+        # Support wildcard matching
+        for cap in self.capabilities:
+            if cap == "*":
+                return True
+            if cap == capability:
+                return True
+            # Support prefix matching (e.g., "read:*" matches "read:data")
+            if cap.endswith(":*"):
+                prefix = cap[:-2]
+                if capability.startswith(prefix + ":"):
+                    return True
+        return False
+    
+    def to_did_document(self) -> dict:
+        """Export as a DID Document (W3C format)."""
+        return {
+            "@context": ["https://www.w3.org/ns/did/v1"],
+            "id": str(self.did),
+            "verificationMethod": [
+                {
+                    "id": f"{self.did}#{self.verification_key_id}",
+                    "type": "Ed25519VerificationKey2020",
+                    "controller": str(self.did),
+                    "publicKeyBase64": self.public_key,
+                }
+            ],
+            "authentication": [f"{self.did}#{self.verification_key_id}"],
+            "service": [
+                {
+                    "id": f"{self.did}#agentmesh",
+                    "type": "AgentMeshIdentity",
+                    "serviceEndpoint": "https://mesh.agentmesh.dev/v1",
+                }
+            ],
+        }
+
+
+class IdentityRegistry:
+    """
+    Registry for agent identities.
+    
+    In production, this would be backed by a database and the AgentMesh CA.
+    """
+    
+    def __init__(self):
+        self._identities: dict[str, AgentIdentity] = {}
+        self._by_sponsor: dict[str, list[str]] = {}  # sponsor -> list of DIDs
+    
+    def register(self, identity: AgentIdentity) -> None:
+        """Register an identity."""
+        did_str = str(identity.did)
+        
+        if did_str in self._identities:
+            raise ValueError(f"Identity already registered: {did_str}")
+        
+        self._identities[did_str] = identity
+        
+        # Index by sponsor
+        if identity.sponsor_email not in self._by_sponsor:
+            self._by_sponsor[identity.sponsor_email] = []
+        self._by_sponsor[identity.sponsor_email].append(did_str)
+    
+    def get(self, did: str | AgentDID) -> Optional[AgentIdentity]:
+        """Get an identity by DID."""
+        did_str = str(did) if isinstance(did, AgentDID) else did
+        return self._identities.get(did_str)
+    
+    def revoke(self, did: str | AgentDID, reason: str) -> bool:
+        """Revoke an identity and all its delegates."""
+        identity = self.get(did)
+        if not identity:
+            return False
+        
+        identity.revoke(reason)
+        
+        # Revoke all children
+        for child_did, child in self._identities.items():
+            if child.parent_did == str(did):
+                self.revoke(child_did, f"Parent revoked: {reason}")
+        
+        return True
+    
+    def get_by_sponsor(self, sponsor_email: str) -> list[AgentIdentity]:
+        """Get all identities for a sponsor."""
+        dids = self._by_sponsor.get(sponsor_email, [])
+        return [self._identities[did] for did in dids if did in self._identities]
+    
+    def list_active(self) -> list[AgentIdentity]:
+        """List all active identities."""
+        return [i for i in self._identities.values() if i.is_active()]

agentmesh/identity/credentials.py

@@ -0,0 +1,323 @@
+"""
+Ephemeral Credentials
+
+Credentials with configurable TTL (default 15 min).
+Expired credentials are rejected; rotation is automatic and zero-downtime.
+"""
+
+from datetime import datetime, timedelta
+from typing import Optional, Literal
+from pydantic import BaseModel, Field
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from cryptography.hazmat.primitives import serialization
+import hashlib
+import uuid
+import base64
+import secrets
+
+
+class Credential(BaseModel):
+    """
+    Short-lived credential for agent authentication.
+    
+    Unlike long-lived service account keys:
+    - Default TTL is 15 minutes
+    - Auto-rotates before expiration
+    - Instantly revocable
+    - Capability-scoped
+    """
+    
+    credential_id: str = Field(..., description="Unique credential identifier")
+    agent_did: str = Field(..., description="DID of the agent this credential belongs to")
+    
+    # Token
+    token: str = Field(..., description="Bearer token")
+    token_hash: str = Field(..., description="SHA-256 hash of token for verification")
+    
+    # Scope
+    capabilities: list[str] = Field(default_factory=list, description="Scoped capabilities")
+    resources: list[str] = Field(default_factory=list, description="Accessible resources")
+    
+    # Timing
+    issued_at: datetime = Field(default_factory=datetime.utcnow)
+    expires_at: datetime = Field(..., description="When credential expires")
+    ttl_seconds: int = Field(default=900, description="TTL in seconds (default 15 min)")
+    
+    # Status
+    status: Literal["active", "rotated", "revoked", "expired"] = Field(default="active")
+    revoked_at: Optional[datetime] = Field(None)
+    revocation_reason: Optional[str] = Field(None)
+    
+    # Rotation
+    previous_credential_id: Optional[str] = Field(None, description="Previous credential if rotated")
+    rotation_count: int = Field(default=0)
+    
+    # Context
+    issued_for: Optional[str] = Field(None, description="Purpose/context for issuance")
+    client_ip: Optional[str] = Field(None, description="IP address of requester")
+    
+    @classmethod
+    def issue(
+        cls,
+        agent_did: str,
+        capabilities: Optional[list[str]] = None,
+        resources: Optional[list[str]] = None,
+        ttl_seconds: int = 900,  # 15 minutes default
+        issued_for: Optional[str] = None,
+    ) -> "Credential":
+        """
+        Issue a new credential for an agent.
+        
+        Args:
+            agent_did: The agent's DID
+            capabilities: Scoped capabilities (subset of agent's capabilities)
+            resources: Specific resources this credential can access
+            ttl_seconds: Time-to-live in seconds (default 15 min)
+            issued_for: Context/purpose for the credential
+        """
+        # Generate secure token
+        token = secrets.token_urlsafe(32)
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
+        
+        # Generate credential ID
+        credential_id = f"cred_{uuid.uuid4().hex[:16]}"
+        
+        now = datetime.utcnow()
+        
+        return cls(
+            credential_id=credential_id,
+            agent_did=agent_did,
+            token=token,
+            token_hash=token_hash,
+            capabilities=capabilities or [],
+            resources=resources or [],
+            issued_at=now,
+            expires_at=now + timedelta(seconds=ttl_seconds),
+            ttl_seconds=ttl_seconds,
+            issued_for=issued_for,
+        )
+    
+    def is_valid(self) -> bool:
+        """Check if credential is valid (active and not expired)."""
+        if self.status != "active":
+            return False
+        return datetime.utcnow() < self.expires_at
+    
+    def is_expiring_soon(self, threshold_seconds: int = 60) -> bool:
+        """Check if credential is about to expire."""
+        return datetime.utcnow() > (self.expires_at - timedelta(seconds=threshold_seconds))
+    
+    def verify_token(self, token: str) -> bool:
+        """Verify a token matches this credential."""
+        return hashlib.sha256(token.encode()).hexdigest() == self.token_hash
+    
+    def revoke(self, reason: str) -> None:
+        """Revoke this credential immediately."""
+        self.status = "revoked"
+        self.revoked_at = datetime.utcnow()
+        self.revocation_reason = reason
+    
+    def rotate(self) -> "Credential":
+        """
+        Rotate this credential, creating a new one.
+        
+        The old credential is marked as rotated but remains valid
+        for a brief overlap period to allow zero-downtime rotation.
+        """
+        # Mark current as rotated
+        self.status = "rotated"
+        
+        # Create new credential
+        new_cred = Credential.issue(
+            agent_did=self.agent_did,
+            capabilities=self.capabilities,
+            resources=self.resources,
+            ttl_seconds=self.ttl_seconds,
+            issued_for=self.issued_for,
+        )
+        
+        new_cred.previous_credential_id = self.credential_id
+        new_cred.rotation_count = self.rotation_count + 1
+        
+        return new_cred
+    
+    def has_capability(self, capability: str) -> bool:
+        """Check if this credential has a specific capability."""
+        if not self.capabilities:
+            return False
+        
+        for cap in self.capabilities:
+            if cap == "*":
+                return True
+            if cap == capability:
+                return True
+            if cap.endswith(":*"):
+                prefix = cap[:-2]
+                if capability.startswith(prefix + ":"):
+                    return True
+        return False
+    
+    def can_access_resource(self, resource: str) -> bool:
+        """Check if this credential can access a specific resource."""
+        if not self.resources:
+            return True  # No resource restrictions
+        
+        return resource in self.resources or "*" in self.resources
+    
+    def time_remaining(self) -> timedelta:
+        """Get time remaining until expiration."""
+        return max(timedelta(0), self.expires_at - datetime.utcnow())
+    
+    def to_bearer_token(self) -> str:
+        """Get the bearer token for Authorization header."""
+        return f"Bearer {self.token}"
+
+
+class CredentialManager:
+    """
+    Manages credential lifecycle.
+    
+    Handles:
+    - Credential issuance
+    - Validation
+    - Rotation
+    - Revocation propagation
+    """
+    
+    DEFAULT_TTL = 900  # 15 minutes
+    ROTATION_THRESHOLD = 60  # Start rotation 1 minute before expiry
+    REVOCATION_PROPAGATION_TARGET = 5  # Target: propagate in ≤5 seconds
+    
+    def __init__(self, default_ttl: int = DEFAULT_TTL):
+        self.default_ttl = default_ttl
+        self._credentials: dict[str, Credential] = {}
+        self._by_agent: dict[str, list[str]] = {}  # agent_did -> list of credential_ids
+        self._revocation_callbacks: list[callable] = []
+    
+    def issue(
+        self,
+        agent_did: str,
+        capabilities: Optional[list[str]] = None,
+        resources: Optional[list[str]] = None,
+        ttl_seconds: Optional[int] = None,
+        issued_for: Optional[str] = None,
+    ) -> Credential:
+        """Issue a new credential."""
+        cred = Credential.issue(
+            agent_did=agent_did,
+            capabilities=capabilities,
+            resources=resources,
+            ttl_seconds=ttl_seconds or self.default_ttl,
+            issued_for=issued_for,
+        )
+        
+        self._store(cred)
+        return cred
+    
+    def validate(self, token: str) -> Optional[Credential]:
+        """
+        Validate a token and return the credential if valid.
+        
+        Returns None if token is invalid, expired, or revoked.
+        """
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
+        
+        for cred in self._credentials.values():
+            if cred.token_hash == token_hash:
+                if cred.is_valid():
+                    return cred
+                return None  # Found but invalid
+        
+        return None  # Not found
+    
+    def rotate(self, credential_id: str) -> Optional[Credential]:
+        """Rotate a credential."""
+        cred = self._credentials.get(credential_id)
+        if not cred or not cred.is_valid():
+            return None
+        
+        new_cred = cred.rotate()
+        self._store(new_cred)
+        
+        return new_cred
+    
+    def rotate_if_needed(self, credential_id: str) -> Credential:
+        """Rotate credential if it's expiring soon."""
+        cred = self._credentials.get(credential_id)
+        if not cred:
+            raise ValueError(f"Credential not found: {credential_id}")
+        
+        if cred.is_expiring_soon(self.ROTATION_THRESHOLD):
+            return self.rotate(credential_id)
+        
+        return cred
+    
+    def revoke(self, credential_id: str, reason: str) -> bool:
+        """
+        Revoke a credential.
+        
+        Propagation target: ≤5 seconds to all systems.
+        """
+        cred = self._credentials.get(credential_id)
+        if not cred:
+            return False
+        
+        cred.revoke(reason)
+        
+        # Trigger revocation callbacks
+        for callback in self._revocation_callbacks:
+            try:
+                callback(cred)
+            except Exception:
+                pass  # Don't let callback failures block revocation
+        
+        return True
+    
+    def revoke_all_for_agent(self, agent_did: str, reason: str) -> int:
+        """Revoke all credentials for an agent."""
+        count = 0
+        cred_ids = self._by_agent.get(agent_did, [])
+        
+        for cred_id in cred_ids:
+            if self.revoke(cred_id, reason):
+                count += 1
+        
+        return count
+    
+    def get_active_for_agent(self, agent_did: str) -> list[Credential]:
+        """Get all active credentials for an agent."""
+        cred_ids = self._by_agent.get(agent_did, [])
+        return [
+            self._credentials[cid]
+            for cid in cred_ids
+            if cid in self._credentials and self._credentials[cid].is_valid()
+        ]
+    
+    def cleanup_expired(self) -> int:
+        """Remove expired credentials from memory."""
+        expired = [
+            cid for cid, cred in self._credentials.items()
+            if not cred.is_valid() and cred.status != "active"
+        ]
+        
+        for cid in expired:
+            cred = self._credentials.pop(cid, None)
+            if cred:
+                # Remove from agent index
+                agent_creds = self._by_agent.get(cred.agent_did, [])
+                if cid in agent_creds:
+                    agent_creds.remove(cid)
+        
+        return len(expired)
+    
+    def on_revocation(self, callback: callable) -> None:
+        """Register a callback for revocation events."""
+        self._revocation_callbacks.append(callback)
+    
+    def _store(self, cred: Credential) -> None:
+        """Store a credential in the index."""
+        self._credentials[cred.credential_id] = cred
+        
+        if cred.agent_did not in self._by_agent:
+            self._by_agent[cred.agent_did] = []
+        self._by_agent[cred.agent_did].append(cred.credential_id)