ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/protocols/services/governance/wa_auth.py

@@ -0,0 +1,192 @@
+"""
+WA Authentication Protocol Interfaces.
+
+IMPORTANT: This is NOT a separate service - these are protocols/interfaces!
+
+This file contains protocol definitions used by the WiseAuthorityService and
+AuthenticationService. There is no separate "wa_auth" service in the 22 core services.
+
+The protocols defined here are:
+- WAStore: Interface for WA certificate storage (implemented by AuthenticationService)
+- JWTService: Interface for JWT operations (implemented by AuthenticationService)
+- OAuthGateway: Interface for OAuth operations (implemented by AuthenticationService)
+- WAMintProtocol: Interface for WA certificate minting operations
+
+These protocols support the Wise Authority system as specified in FSD/AUTHENTICATION.md
+section 11, but they are NOT a standalone service.
+
+The 22 core services include:
+- WiseAuthorityService (authorization, deferrals, guidance)
+- AuthenticationService (authentication, WA certificates, JWT, OAuth)
+
+But there is no separate "wa_auth" service.
+"""
+
+from abc import abstractmethod
+from typing import Any, Dict, List, Optional, Protocol, Tuple
+
+from ciris_engine.schemas.infrastructure.oauth import OAuthCallbackResponse, OAuthProviderConfig
+from ciris_engine.schemas.services.authority.jwt import JWTClaims
+from ciris_engine.schemas.services.authority.wa_updates import WACertificateUpdate
+from ciris_engine.schemas.services.authority_core import AuthorizationContext, WACertificate
+
+
+class WAStore(Protocol):
+    """Protocol for WA certificate storage operations."""
+
+    @abstractmethod
+    async def get_wa_cert(self, wa_id: str) -> Optional[WACertificate]:
+        """Get WA certificate by ID."""
+        ...
+
+    @abstractmethod
+    async def get_wa_cert_by_pubkey(self, pubkey: str) -> Optional[WACertificate]:
+        """Get WA certificate by public key."""
+        ...
+
+    @abstractmethod
+    async def get_wa_cert_by_channel(self, channel_id: str) -> Optional[WACertificate]:
+        """Get WA certificate by channel ID."""
+        ...
+
+    @abstractmethod
+    async def create_wa_cert(self, _: WACertificate) -> bool:
+        """Create new WA certificate."""
+        ...
+
+    @abstractmethod
+    async def update_wa_cert(self, wa_id: str, updates: WACertificateUpdate) -> bool:
+        """Update existing WA certificate."""
+        ...
+
+    @abstractmethod
+    async def list_wa_certs(self, active_only: bool = True) -> List[WACertificate]:
+        """List all WA certificates."""
+        ...
+
+    @abstractmethod
+    async def revoke_wa_cert(self, wa_id: str) -> bool:
+        """Revoke a WA certificate."""
+        ...
+
+
+class JWTService(Protocol):
+    """Protocol for JWT operations."""
+
+    @abstractmethod
+    def issue_token(self, sub: str, sub_type: str, name: str, scope: List[str], **kwargs: Any) -> str:
+        """Issue a JWT token."""
+        ...
+
+    @abstractmethod
+    def verify_token(self, token: str) -> Optional[JWTClaims]:
+        """Verify and decode a JWT token."""
+        ...
+
+    @abstractmethod
+    def get_gateway_secret(self) -> bytes:
+        """Get or generate gateway secret for HS256 signing."""
+        ...
+
+
+class WACrypto(Protocol):
+    """Protocol for cryptographic operations."""
+
+    @abstractmethod
+    def generate_keypair(self) -> Tuple[bytes, bytes]:
+        """Generate Ed25519 keypair (private, public)."""
+        ...
+
+    @abstractmethod
+    def sign_message(self, message: bytes, private_key: bytes) -> bytes:
+        """Sign a message with Ed25519 private key."""
+        ...
+
+    @abstractmethod
+    def verify_signature(self, message: bytes, signature: bytes, public_key: bytes) -> bool:
+        """Verify Ed25519 signature."""
+        ...
+
+    @abstractmethod
+    def save_private_key(self, wa_id: str, private_key: bytes) -> bool:
+        """Save private key to secure storage."""
+        ...
+
+    @abstractmethod
+    def load_private_key(self, wa_id: str) -> Optional[bytes]:
+        """Load private key from secure storage."""
+        ...
+
+    @abstractmethod
+    def hash_password(self, password: str) -> str:
+        """Hash password using PBKDF2."""
+        ...
+
+    @abstractmethod
+    def verify_password(self, password: str, password_hash: str) -> bool:
+        """Verify password against hash."""
+        ...
+
+    @abstractmethod
+    def generate_api_key(self, wa_id: str) -> str:
+        """Generate API key for WA."""
+        ...
+
+
+class WAAuthMiddleware(Protocol):
+    """Protocol for authentication middleware operations."""
+
+    @abstractmethod
+    async def authenticate(self, token: Optional[str]) -> Optional[AuthorizationContext]:
+        """Authenticate request and return auth context."""
+        ...
+
+    @abstractmethod
+    async def authorize(self, context: AuthorizationContext, _: List[str]) -> bool:
+        """Check if context has required scopes."""
+        ...
+
+    @abstractmethod
+    def extract_token(self, authorization: Optional[str]) -> Optional[str]:
+        """Extract token from Authorization header."""
+        ...
+
+
+class OAuthService(Protocol):
+    """Protocol for OAuth operations."""
+
+    @abstractmethod
+    async def get_oauth_providers(self) -> Dict[str, OAuthProviderConfig]:
+        """Get configured OAuth providers."""
+        ...
+
+    @abstractmethod
+    async def save_oauth_provider(self, provider: str, config: OAuthProviderConfig) -> bool:
+        """Save OAuth provider configuration."""
+        ...
+
+    @abstractmethod
+    async def get_oauth_url(self, provider: str, state: str) -> str:
+        """Get OAuth authorization URL."""
+        ...
+
+    @abstractmethod
+    async def handle_oauth_callback(self, provider: str, code: str, state: str) -> Optional[OAuthCallbackResponse]:
+        """Handle OAuth callback and return token + profile."""
+        ...
+
+    @abstractmethod
+    async def create_oauth_wa(
+        self, provider: str, external_id: str, profile: Dict[str, Any]
+    ) -> Optional[WACertificate]:
+        """Create WA certificate from OAuth profile."""
+        ...
+
+
+__all__ = [
+    "WAStore",
+    "JWTService",
+    "WACrypto",
+    "WAAuthMiddleware",
+    "OAuthService",
+]

ciris_engine/protocols/services/governance/wise_authority.py

@@ -0,0 +1,75 @@
+"""Wise Authority Service Protocol.
+
+Handles authorization, deferrals, and decision guidance.
+Authorization = "What can you do?"
+"""
+
+from abc import abstractmethod
+from typing import List, Optional, Protocol
+
+from ciris_engine.schemas.services.authority.wise_authority import PendingDeferral
+from ciris_engine.schemas.services.authority_core import (
+    DeferralApprovalContext,
+    DeferralRequest,
+    DeferralResponse,
+    GuidanceRequest,
+    GuidanceResponse,
+    WAPermission,
+)
+from ciris_engine.schemas.services.context import GuidanceContext
+
+from ...runtime.base import ServiceProtocol
+
+
+class WiseAuthorityServiceProtocol(ServiceProtocol, Protocol):
+    """Protocol for wise authority service - authorization and guidance."""
+
+    @abstractmethod
+    async def check_authorization(self, wa_id: str, action: str, resource: Optional[str] = None) -> bool:
+        """Check if a WA is authorized for an action on a resource."""
+        ...
+
+    @abstractmethod
+    async def request_approval(self, action: str, context: DeferralApprovalContext) -> bool:
+        """Request approval for an action - may defer to human."""
+        ...
+
+    @abstractmethod
+    async def get_guidance(self, request: GuidanceRequest) -> GuidanceResponse:
+        """Get guidance for a situation."""
+        ...
+
+    @abstractmethod
+    async def send_deferral(self, deferral: DeferralRequest) -> str:
+        """Send a decision deferral to human WAs."""
+        ...
+
+    @abstractmethod
+    async def get_pending_deferrals(self, wa_id: Optional[str] = None) -> List[PendingDeferral]:
+        """Get pending deferrals (optionally filtered by WA)."""
+        ...
+
+    @abstractmethod
+    async def resolve_deferral(self, deferral_id: str, response: DeferralResponse) -> bool:
+        """Resolve a deferred decision."""
+        ...
+
+    @abstractmethod
+    async def grant_permission(self, wa_id: str, permission: str, resource: Optional[str] = None) -> bool:
+        """Grant a permission to a WA."""
+        ...
+
+    @abstractmethod
+    async def revoke_permission(self, wa_id: str, permission: str, resource: Optional[str] = None) -> bool:
+        """Revoke a permission from a WA."""
+        ...
+
+    @abstractmethod
+    async def list_permissions(self, wa_id: str) -> List[WAPermission]:
+        """List all permissions for a WA."""
+        ...
+
+    @abstractmethod
+    async def fetch_guidance(self, context: GuidanceContext) -> Optional[str]:
+        """Fetch guidance from WAs (WiseBus-compatible method)."""
+        ...

ciris_engine/protocols/services/graph/__init__.py

@@ -0,0 +1,19 @@
+"""Graph service protocols."""
+
+from .audit import AuditServiceProtocol
+from .config import GraphConfigServiceProtocol  # Alias for backward compatibility
+from .config import GraphConfigServiceProtocol as ConfigServiceProtocol
+from .incident_management import IncidentManagementServiceProtocol
+from .memory import MemoryServiceProtocol
+from .telemetry import TelemetryServiceProtocol
+from .tsdb_consolidation import TSDBConsolidationServiceProtocol
+
+__all__ = [
+    "MemoryServiceProtocol",
+    "AuditServiceProtocol",
+    "TelemetryServiceProtocol",
+    "GraphConfigServiceProtocol",
+    "ConfigServiceProtocol",  # Alias
+    "TSDBConsolidationServiceProtocol",
+    "IncidentManagementServiceProtocol",
+]

ciris_engine/protocols/services/graph/audit.py

@@ -0,0 +1,92 @@
+"""Audit Service Protocol."""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, List, Optional, Protocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.audit.core import EventPayload, AuditLogEntry
+    from ciris_engine.schemas.audit.hash_chain import AuditEntryResult
+
+from ciris_engine.schemas.runtime.audit import AuditActionContext
+from ciris_engine.schemas.runtime.enums import HandlerActionType
+from ciris_engine.schemas.services.graph.audit import AuditQuery, VerificationReport
+from ciris_engine.schemas.services.nodes import AuditEntry
+
+from ...runtime.base import GraphServiceProtocol
+
+
+class AuditServiceProtocol(GraphServiceProtocol, Protocol):
+    """Protocol for audit service."""
+
+    @abstractmethod
+    async def log_action(
+        self, action_type: HandlerActionType, context: AuditActionContext, outcome: Optional[str] = None
+    ) -> "AuditEntryResult":
+        """Log an action to the audit trail.
+
+        Returns:
+            AuditEntryResult with entry_id and hash chain data (REQUIRED)
+        """
+        ...
+
+    @abstractmethod
+    async def log_event(self, event_type: str, event_data: "EventPayload", **kwargs: object) -> "AuditEntryResult":
+        """Log a general audit event.
+
+        Returns:
+            AuditEntryResult with entry_id and hash chain data (if hash chain enabled)
+        """
+        ...
+
+    @abstractmethod
+    async def log_conscience_event(
+        self, thought_id: str, decision: str, reasoning: str, metadata: Optional["EventPayload"] = None
+    ) -> None:
+        """Log a conscience decision event."""
+        ...
+
+    @abstractmethod
+    async def get_audit_trail(
+        self, entity_id: Optional[str] = None, hours: int = 24, action_types: Optional[List[str]] = None
+    ) -> List[AuditEntry]:
+        """Get audit trail for an entity."""
+        ...
+
+    @abstractmethod
+    async def query_audit_trail(self, query: AuditQuery) -> List[AuditEntry]:
+        """Query audit trail with advanced filters."""
+        ...
+
+    @abstractmethod
+    async def verify_audit_integrity(self) -> VerificationReport:
+        """Verify audit trail integrity."""
+        ...
+
+    @abstractmethod
+    async def get_verification_report(self) -> VerificationReport:
+        """Get detailed verification report."""
+        ...
+
+    @abstractmethod
+    async def export_audit_data(
+        self, start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, format: str = "jsonl"
+    ) -> str:
+        """Export audit data."""
+        ...
+
+    @abstractmethod
+    async def query_events(
+        self,
+        event_type: Optional[str] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: int = 100,
+    ) -> List["AuditLogEntry"]:
+        """Query audit events."""
+        ...
+
+    @abstractmethod
+    async def get_event_by_id(self, event_id: str) -> Optional["AuditLogEntry"]:
+        """Get specific audit event."""
+        ...

ciris_engine/protocols/services/graph/config.py

@@ -0,0 +1,54 @@
+"""Configuration Service Protocol."""
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Protocol, Union
+
+from ciris_engine.schemas.services.graph_core import GraphScope
+from ciris_engine.schemas.types import ConfigValue
+
+from ...runtime.base import GraphServiceProtocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.services.nodes import ConfigNode
+
+
+class GraphConfigServiceProtocol(GraphServiceProtocol, Protocol):
+    """Protocol for graph configuration service."""
+
+    @abstractmethod
+    async def get_config(self, key: str) -> Optional["ConfigNode"]:
+        """Get configuration value."""
+        ...
+
+    @abstractmethod
+    async def set_config(
+        self,
+        key: str,
+        value: ConfigValue,
+        updated_by: str,
+        scope: GraphScope = GraphScope.LOCAL,
+    ) -> None:
+        """Set configuration value.
+
+        Args:
+            key: Configuration key
+            value: Configuration value
+            updated_by: Who is making the update
+            scope: Graph scope (LOCAL for agent-modifiable, IDENTITY for WA-protected)
+        """
+        ...
+
+    @abstractmethod
+    async def list_configs(self, prefix: Optional[str] = None) -> Dict[str, ConfigValue]:
+        """List all configurations with optional prefix filter."""
+        ...
+
+    @abstractmethod
+    def register_config_listener(self, key_pattern: str, callback: Callable[..., Any]) -> None:
+        """Register a callback for config changes matching the key pattern."""
+        ...
+
+    @abstractmethod
+    def unregister_config_listener(self, key_pattern: str, callback: Callable[..., Any]) -> None:
+        """Unregister a config change callback."""
+        ...

ciris_engine/protocols/services/graph/incident_management.py

@@ -0,0 +1,103 @@
+"""
+Protocol for Incident Management Service.
+
+ITIL-aligned incident processing for agent self-improvement through
+pattern detection and insight generation.
+"""
+
+from typing import TYPE_CHECKING, List, Protocol, runtime_checkable
+
+from ...runtime.base import GraphServiceProtocol
+
+# Import forward references
+if TYPE_CHECKING:
+    from ciris_engine.schemas.services.core import ServiceCapabilities, ServiceStatus
+    from ciris_engine.schemas.services.graph.incident import IncidentInsightNode
+    from ciris_engine.schemas.services.graph_core import GraphNode
+    from ciris_engine.schemas.services.operations import MemoryQuery
+
+
+@runtime_checkable
+class IncidentManagementServiceProtocol(GraphServiceProtocol, Protocol):
+    """Protocol for incident management service.
+
+    Processes incidents from logs, detects patterns, identifies problems,
+    and generates insights for continuous self-improvement.
+    """
+
+    async def process_recent_incidents(self, hours: int = 24) -> "IncidentInsightNode":
+        """Process recent incidents to identify patterns and generate insights.
+
+        Called during dream cycle for self-improvement analysis.
+
+        Args:
+            hours: Number of hours of incidents to analyze
+
+        Returns:
+            IncidentInsightNode with analysis results and recommendations
+        """
+        ...
+
+    # Required methods from GraphServiceProtocol
+    def get_node_type(self) -> str:
+        """Get the type of nodes this service manages.
+
+        Returns:
+            Node type string
+        """
+        ...
+
+    async def store_in_graph(self, node: "GraphNode") -> str:
+        """Store a node in the graph.
+
+        Args:
+            node: GraphNode to store
+
+        Returns:
+            Node ID
+        """
+        ...
+
+    async def query_graph(self, query: "MemoryQuery") -> List["GraphNode"]:
+        """Query the graph.
+
+        Args:
+            query: Memory query
+
+        Returns:
+            List of matching GraphNodes
+        """
+        ...
+
+    # Required methods from ServiceProtocol
+    async def start(self) -> None:
+        """Start the incident management service."""
+        ...
+
+    async def stop(self) -> None:
+        """Stop the incident management service."""
+        ...
+
+    def get_capabilities(self) -> "ServiceCapabilities":
+        """Return service capabilities.
+
+        Returns:
+            ServiceCapabilities object
+        """
+        ...
+
+    def get_status(self) -> "ServiceStatus":
+        """Get service status.
+
+        Returns:
+            ServiceStatus object
+        """
+        ...
+
+    async def is_healthy(self) -> bool:
+        """Check if service is healthy.
+
+        Returns:
+            True if service is healthy
+        """
+        ...

ciris_engine/protocols/services/graph/memory.py

@@ -0,0 +1,110 @@
+"""Memory Service Protocol."""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING, Dict, List, Optional, Protocol
+
+from ciris_engine.schemas.runtime.memory import TimeSeriesDataPoint
+from ciris_engine.schemas.services.graph.memory import MemorySearchFilter
+from ciris_engine.schemas.services.graph_core import GraphEdge, GraphNode, GraphScope
+from ciris_engine.schemas.services.operations import MemoryOpResult, MemoryQuery
+
+from ...runtime.base import GraphServiceProtocol
+
+if TYPE_CHECKING:
+    from ciris_engine.schemas.services.operations import MemoryOpResult
+
+
+class MemoryServiceProtocol(GraphServiceProtocol, Protocol):
+    """Protocol for memory service - the three universal memory verbs."""
+
+    @abstractmethod
+    async def memorize(self, node: GraphNode) -> "MemoryOpResult[GraphNode]":
+        """
+        MEMORIZE - Store a graph node in memory.
+
+        Returns:
+            MemoryOpResult[GraphNode] with the stored node in data field
+        """
+        ...
+
+    @abstractmethod
+    async def recall(self, recall_query: MemoryQuery) -> List[GraphNode]:
+        """
+        RECALL - Retrieve nodes matching query.
+
+        Returns:
+            List of GraphNodes matching the query (empty list if none found)
+        """
+        ...
+
+    @abstractmethod
+    async def forget(self, node: GraphNode) -> "MemoryOpResult[GraphNode]":
+        """
+        FORGET - Remove a specific node from memory.
+
+        Returns:
+            MemoryOpResult[GraphNode] with the forgotten node in data field
+        """
+        ...
+
+    @abstractmethod
+    async def memorize_metric(
+        self, metric_name: str, value: float, tags: Optional[Dict[str, str]] = None, scope: str = "local"
+    ) -> "MemoryOpResult[GraphNode]":
+        """
+        Memorize a metric value (convenience for telemetry).
+
+        Returns:
+            MemoryOpResult[GraphNode] with the metric node in data field
+        """
+        ...
+
+    @abstractmethod
+    async def memorize_log(
+        self, log_message: str, log_level: str = "INFO", tags: Optional[Dict[str, str]] = None, scope: str = "local"
+    ) -> "MemoryOpResult[GraphNode]":
+        """
+        Memorize a log entry (convenience for logging).
+
+        Returns:
+            MemoryOpResult[GraphNode] with the log node in data field
+        """
+        ...
+
+    @abstractmethod
+    async def recall_timeseries(
+        self,
+        scope: str = "default",
+        hours: int = 24,
+        correlation_types: Optional[List[str]] = None,
+        start_time: Optional["datetime"] = None,
+        end_time: Optional["datetime"] = None,
+    ) -> List[TimeSeriesDataPoint]:
+        """Recall time-series data."""
+        ...
+
+    @abstractmethod
+    async def export_identity_context(self) -> str:
+        """Export identity nodes as string representation."""
+        ...
+
+    @abstractmethod
+    async def search(self, query: str, filters: Optional["MemorySearchFilter"] = None) -> List[GraphNode]:
+        """Search memories using text query."""
+        ...
+
+    @abstractmethod
+    async def create_edge(self, edge: "GraphEdge") -> "MemoryOpResult[GraphEdge]":
+        """
+        Create an edge between two nodes in the memory graph.
+
+        Returns:
+            MemoryOpResult[GraphEdge] with the created edge in data field
+        """
+        ...
+
+    @abstractmethod
+    async def get_node_edges(self, node_id: str, scope: "GraphScope") -> List["GraphEdge"]:
+        """Get all edges connected to a node."""
+        ...