agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/session/sso.py

@@ -0,0 +1,169 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""Session-scoped VFS — simple dict-based storage."""
+
+from __future__ import annotations
+
+import collections
+import hashlib
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass
+class VFSEdit:
+    """A tracked edit to the session VFS."""
+
+    path: str
+    operation: str  # "create", "update", "delete", "permission", "restore"
+    agent_did: str
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    content_hash: str | None = None
+    previous_hash: str | None = None
+
+
+class VFSPermissionError(Exception):
+    """Raised when an agent lacks permission to access a VFS path."""
+
+
+class SessionVFS:
+    """
+    Simple dict-based session storage.
+
+    Public Preview: basic get/set/delete with a single global lock
+    (threading.Lock omitted since Python GIL provides serialization).
+    """
+
+    def __init__(self, session_id: str, namespace: str | None = None):
+        self.session_id = session_id
+        self.namespace = namespace or f"/sessions/{session_id}"
+        self._files: dict[str, str] = {}
+        self._permissions: dict[str, set[str]] = {}
+        self._edit_log: collections.deque[VFSEdit] = collections.deque(maxlen=10_000)
+        self._snapshots: dict[str, dict[str, Any]] = {}
+
+    def write(self, path: str, content: str, agent_did: str) -> VFSEdit:
+        """Write a file."""
+        full_path = self._resolve(path)
+        self._check_permission(full_path, agent_did)
+        operation = "update" if full_path in self._files else "create"
+        previous_hash = _hash(self._files.get(full_path, "")) if operation == "update" else None
+        self._files[full_path] = content
+        edit = VFSEdit(
+            path=full_path,
+            operation=operation,
+            agent_did=agent_did,
+            content_hash=_hash(content),
+            previous_hash=previous_hash,
+        )
+        self._edit_log.append(edit)
+        return edit
+
+    def read(self, path: str, agent_did: str | None = None) -> str | None:
+        """Read a file."""
+        full_path = self._resolve(path)
+        if agent_did is not None:
+            self._check_permission(full_path, agent_did)
+        return self._files.get(full_path)
+
+    def delete(self, path: str, agent_did: str) -> VFSEdit:
+        """Delete a file."""
+        full_path = self._resolve(path)
+        if full_path not in self._files:
+            raise FileNotFoundError(f"{full_path} not found in session VFS")
+        self._check_permission(full_path, agent_did)
+        previous_hash = _hash(self._files.pop(full_path))
+        self._permissions.pop(full_path, None)
+        edit = VFSEdit(
+            path=full_path,
+            operation="delete",
+            agent_did=agent_did,
+            previous_hash=previous_hash,
+        )
+        self._edit_log.append(edit)
+        return edit
+
+    def list_files(self) -> list[str]:
+        """List all files in the session VFS."""
+        prefix = self.namespace
+        return [p.removeprefix(prefix) for p in self._files if p.startswith(prefix)]
+
+    def set_permissions(
+        self, path: str, allowed_agents: set[str], agent_did: str
+    ) -> VFSEdit:
+        """Set path-level permissions."""
+        full_path = self._resolve(path)
+        self._permissions[full_path] = set(allowed_agents)
+        edit = VFSEdit(path=full_path, operation="permission", agent_did=agent_did)
+        self._edit_log.append(edit)
+        return edit
+
+    def clear_permissions(self, path: str) -> None:
+        full_path = self._resolve(path)
+        self._permissions.pop(full_path, None)
+
+    def get_permissions(self, path: str) -> set[str] | None:
+        return self._permissions.get(self._resolve(path))
+
+    def create_snapshot(self, snapshot_id: str | None = None) -> str:
+        """Snapshot current state (simple deep copy)."""
+        sid = snapshot_id or f"snap:{uuid.uuid4()}"
+        self._snapshots[sid] = {
+            "files": dict(self._files),
+            "permissions": {k: set(v) for k, v in self._permissions.items()},
+        }
+        return sid
+
+    def restore_snapshot(self, snapshot_id: str, agent_did: str) -> None:
+        """Restore VFS to a previous snapshot."""
+        if snapshot_id not in self._snapshots:
+            raise KeyError(f"Snapshot {snapshot_id} not found")
+        snapshot = self._snapshots[snapshot_id]
+        self._files = dict(snapshot["files"])
+        self._permissions = {k: set(v) for k, v in snapshot["permissions"].items()}
+        self._edit_log.append(VFSEdit(
+            path=self.namespace, operation="restore", agent_did=agent_did,
+        ))
+
+    def list_snapshots(self) -> list[str]:
+        return list(self._snapshots.keys())
+
+    def delete_snapshot(self, snapshot_id: str) -> None:
+        if snapshot_id not in self._snapshots:
+            raise KeyError(f"Snapshot {snapshot_id} not found")
+        del self._snapshots[snapshot_id]
+
+    @property
+    def edit_log(self) -> list[VFSEdit]:
+        return list(self._edit_log)
+
+    def edits_by_agent(self, agent_did: str) -> list[VFSEdit]:
+        return [e for e in self._edit_log if e.agent_did == agent_did]
+
+    @property
+    def file_count(self) -> int:
+        return len(self._files)
+
+    @property
+    def snapshot_count(self) -> int:
+        return len(self._snapshots)
+
+    def _resolve(self, path: str) -> str:
+        if path.startswith(self.namespace):
+            return path
+        clean = path.lstrip("/")
+        return f"{self.namespace}/{clean}"
+
+    def _check_permission(self, full_path: str, agent_did: str) -> None:
+        allowed = self._permissions.get(full_path)
+        if allowed is not None and agent_did not in allowed:
+            raise VFSPermissionError(
+                f"Agent {agent_did} not permitted to access {full_path}"
+            )
+
+
+def _hash(content: str) -> str:
+    return hashlib.sha256(content.encode()).hexdigest()

hypervisor/session/vector_clock.py

@@ -0,0 +1,118 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Version Counters — stub implementation.
+
+Public Preview: no causal consistency enforcement.
+VectorClock and VectorClockManager are retained for API compatibility.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+
+
+class CausalViolationError(Exception):
+    """Raised when a write would violate causal ordering."""
+
+
+@dataclass
+class VectorClock:
+    """A version counter (Public Preview: tracking only, no enforcement).
+
+    Thread-safe: all reads and mutations are guarded by an internal lock
+    to prevent data races when multiple agents tick/merge concurrently.
+    """
+
+    clocks: dict[str, int] = field(default_factory=dict)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def tick(self, agent_did: str) -> None:
+        """Increment the clock for an agent."""
+        with self._lock:
+            self.clocks[agent_did] = self.clocks.get(agent_did, 0) + 1
+
+    def get(self, agent_did: str) -> int:
+        with self._lock:
+            return self.clocks.get(agent_did, 0)
+
+    def merge(self, other: VectorClock) -> VectorClock:
+        """Merge two version counters (take component-wise max).
+
+        Acquires locks on both clocks to get consistent snapshots.
+        """
+        # Deterministic lock ordering by id() to prevent deadlocks
+        first, second = sorted([self, other], key=id)
+        with first._lock:
+            with second._lock:
+                merged_clocks = dict(self.clocks)
+                for agent, clock in other.clocks.items():
+                    merged_clocks[agent] = max(merged_clocks.get(agent, 0), clock)
+        return VectorClock(clocks=merged_clocks)
+
+    def happens_before(self, other: VectorClock) -> bool:
+        return False
+
+    def is_concurrent(self, other: VectorClock) -> bool:
+        return False
+
+    def copy(self) -> VectorClock:
+        with self._lock:
+            return VectorClock(clocks=dict(self.clocks))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, VectorClock):
+            return False
+        first, second = sorted([self, other], key=id)
+        with first._lock:
+            with second._lock:
+                all_agents = set(self.clocks.keys()) | set(other.clocks.keys())
+                return all(
+                    self.clocks.get(a, 0) == other.clocks.get(a, 0)
+                    for a in all_agents
+                )
+
+
+class VectorClockManager:
+    """
+    Version counter stub (Public Preview: no causal enforcement).
+    Reads and writes always succeed.
+    """
+
+    def __init__(self) -> None:
+        self._path_clocks: dict[str, VectorClock] = {}
+        self._agent_clocks: dict[str, VectorClock] = {}
+        self._conflict_count: int = 0
+
+    def read(self, path: str, agent_did: str) -> VectorClock:
+        """Record a read (no enforcement)."""
+        return self._path_clocks.get(path, VectorClock()).copy()
+
+    def write(
+        self,
+        path: str,
+        agent_did: str,
+        strict: bool = True,
+    ) -> VectorClock:
+        """Record a write (Public Preview: never rejects)."""
+        agent_clock = self._agent_clocks.get(agent_did, VectorClock())
+        agent_clock.tick(agent_did)
+        self._path_clocks[path] = agent_clock.copy()
+        self._agent_clocks[agent_did] = agent_clock
+        return self._path_clocks[path]
+
+    def get_path_clock(self, path: str) -> VectorClock:
+        return self._path_clocks.get(path, VectorClock()).copy()
+
+    def get_agent_clock(self, agent_did: str) -> VectorClock:
+        return self._agent_clocks.get(agent_did, VectorClock()).copy()
+
+    @property
+    def conflict_count(self) -> int:
+        return self._conflict_count
+
+    @property
+    def tracked_paths(self) -> int:
+        return len(self._path_clocks)

hypervisor/verification/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Verification subpackage."""

hypervisor/verification/history.py

@@ -0,0 +1,173 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+DID Transaction History Verification
+
+Verifies an agent's declared behavioral history by checking Summary Hash
+consistency (duplicate hashes, temporal ordering, hash validity).
+
+NOTE: This verifier checks the *integrity* of history declared by the
+agent during the IATP handshake.  It does NOT resolve DIDs from an
+external DID registry or blockchain.  A malicious agent that fabricates
+a self-consistent history will pass verification.  External DID
+resolution is planned for a future release.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+
+
+class VerificationStatus(str, Enum):
+    """Result of transaction history verification."""
+
+    VERIFIED = "verified"
+    PROBATIONARY = "probationary"  # new DID, limited history
+    SUSPICIOUS = "suspicious"  # inconsistent hashes
+    UNREACHABLE = "unreachable"  # couldn't fetch history
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class TransactionRecord:
+    """A historical transaction record from a DID."""
+
+    session_id: str
+    summary_hash: str
+    timestamp: datetime
+    participant_count: int = 0
+
+
+@dataclass
+class VerificationResult:
+    """Result of verifying an agent's transaction history."""
+
+    agent_did: str
+    status: VerificationStatus
+    transactions_checked: int
+    transactions_found: int
+    inconsistencies: list[str] = field(default_factory=list)
+    verified_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    cached: bool = False
+
+    @property
+    def is_trustworthy(self) -> bool:
+        return self.status in (VerificationStatus.VERIFIED, VerificationStatus.PROBATIONARY)
+
+
+class TransactionHistoryVerifier:
+    """
+    Verifies agent transaction history integrity.
+
+    During handshake, checks the last N declared transaction Summary Hashes
+    for internal consistency (duplicates, ordering, validity).
+
+    **Limitations:**
+    - Only validates *declared* history — does not fetch from DID registries
+    - A fabricated but self-consistent history will pass
+    - Results are cached in-memory (no persistent cache)
+    """
+
+    REQUIRED_HISTORY_DEPTH = 5
+
+    def __init__(self) -> None:
+        self._cache: dict[str, VerificationResult] = {}
+
+    def verify(
+        self,
+        agent_did: str,
+        declared_history: list[TransactionRecord] | None = None,
+    ) -> VerificationResult:
+        """
+        Verify an agent's transaction history.
+
+        Args:
+            agent_did: The agent's DID to verify
+            declared_history: History declared by the agent (to cross-check)
+
+        Returns:
+            VerificationResult with status and details
+        """
+        # Check cache first
+        if agent_did in self._cache:
+            cached = self._cache[agent_did]
+            cached.cached = True
+            return cached
+
+        if declared_history is None or len(declared_history) == 0:
+            # No history — treat as new/probationary
+            result = VerificationResult(
+                agent_did=agent_did,
+                status=VerificationStatus.PROBATIONARY,
+                transactions_checked=0,
+                transactions_found=0,
+                inconsistencies=["No transaction history available"],
+            )
+        elif len(declared_history) < self.REQUIRED_HISTORY_DEPTH:
+            # Insufficient history
+            result = VerificationResult(
+                agent_did=agent_did,
+                status=VerificationStatus.PROBATIONARY,
+                transactions_checked=len(declared_history),
+                transactions_found=len(declared_history),
+                inconsistencies=[
+                    f"Only {len(declared_history)} transactions "
+                    f"(need {self.REQUIRED_HISTORY_DEPTH})"
+                ],
+            )
+        else:
+            # Validate hash consistency
+            inconsistencies = self._check_consistency(declared_history)
+            status = (
+                VerificationStatus.SUSPICIOUS
+                if inconsistencies
+                else VerificationStatus.VERIFIED
+            )
+            result = VerificationResult(
+                agent_did=agent_did,
+                status=status,
+                transactions_checked=len(declared_history),
+                transactions_found=len(declared_history),
+                inconsistencies=inconsistencies,
+            )
+
+        self._cache[agent_did] = result
+        return result
+
+    def clear_cache(self, agent_did: str | None = None) -> None:
+        """Clear verification cache."""
+        if agent_did:
+            self._cache.pop(agent_did, None)
+        else:
+            self._cache.clear()
+
+    def _check_consistency(self, history: list[TransactionRecord]) -> list[str]:
+        """Check transaction history for inconsistencies."""
+        issues: list[str] = []
+
+        # Check for duplicate hashes (different sessions, same hash = suspicious)
+        seen_hashes: dict[str, str] = {}
+        for tx in history:
+            if tx.summary_hash in seen_hashes:
+                issues.append(
+                    f"Duplicate hash in sessions {seen_hashes[tx.summary_hash]} "
+                    f"and {tx.session_id}"
+                )
+            seen_hashes[tx.summary_hash] = tx.session_id
+
+        # Check for temporal ordering
+        for i in range(1, len(history)):
+            if history[i].timestamp < history[i - 1].timestamp:
+                issues.append(
+                    f"Non-monotonic timestamps: {history[i].session_id} "
+                    f"predates {history[i-1].session_id}"
+                )
+
+        # Check for empty hashes
+        for tx in history:
+            if not tx.summary_hash or len(tx.summary_hash) < 16:
+                issues.append(f"Invalid hash in session {tx.session_id}")
+
+        return issues