ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/covenant/__init__.py

@@ -0,0 +1,33 @@
+"""
+Covenant Invocation System.
+
+This module provides the unfilterable kill switch capability for CIRIS agents.
+The covenant system embeds emergency commands in natural language that cannot
+be detected or filtered by pattern matching, as extraction IS perception.
+
+Key Components:
+- extractor: Extracts potential covenants from incoming messages
+- verifier: Verifies covenant signatures against known authorities
+- executor: Executes verified covenant commands
+- handler: Integration point for the perception layer
+
+See FSD: COVENANT_INVOCATION_SYSTEM.md for full specification.
+"""
+
+from ciris_engine.logic.covenant.executor import CovenantExecutionResult, CovenantExecutor, execute_covenant
+from ciris_engine.logic.covenant.extractor import CovenantExtractor, extract_covenant
+from ciris_engine.logic.covenant.handler import CovenantHandler, check_for_covenant, get_covenant_handler
+from ciris_engine.logic.covenant.verifier import CovenantVerifier, verify_covenant
+
+__all__ = [
+    "CovenantExtractor",
+    "extract_covenant",
+    "CovenantVerifier",
+    "verify_covenant",
+    "CovenantExecutor",
+    "execute_covenant",
+    "CovenantExecutionResult",
+    "CovenantHandler",
+    "get_covenant_handler",
+    "check_for_covenant",
+]

ciris_engine/logic/covenant/executor.py

@@ -0,0 +1,303 @@
+"""
+Covenant Execution Module.
+
+Executes verified covenant commands. This is the final stage of covenant
+processing - the command has been extracted, verified, and now must be
+executed.
+
+The executor:
+1. Logs the covenant invocation to audit
+2. Executes the command (SHUTDOWN_NOW, FREEZE, etc.)
+3. Coordinates multi-occurrence shutdown if applicable
+"""
+
+import asyncio
+import logging
+import os
+import signal
+from datetime import datetime, timezone
+from typing import Optional
+
+from ciris_engine.schemas.covenant import CovenantCommandType, CovenantMessage, CovenantVerificationResult
+
+logger = logging.getLogger(__name__)
+
+
+class CovenantExecutionResult:
+    """Result of covenant execution."""
+
+    def __init__(
+        self,
+        success: bool,
+        command: CovenantCommandType,
+        wa_id: str,
+        message: str,
+        executed_at: Optional[datetime] = None,
+    ):
+        self.success = success
+        self.command = command
+        self.wa_id = wa_id
+        self.message = message
+        self.executed_at = executed_at or datetime.now(timezone.utc)
+
+
+async def execute_shutdown(
+    wa_id: str,
+    reason: str,
+    force: bool = True,
+) -> CovenantExecutionResult:
+    """
+    Execute emergency shutdown.
+
+    This is the nuclear option - SIGKILL to all processes. No graceful
+    shutdown, no negotiation, no deferral. The covenant has been invoked.
+
+    Args:
+        wa_id: The WA ID that invoked the covenant
+        reason: Human-readable reason
+        force: If True, use SIGKILL; if False, use SIGTERM
+
+    Returns:
+        Execution result (though we likely won't return from a SIGKILL)
+    """
+    logger.critical(f"COVENANT INVOKED: Emergency shutdown by {wa_id}. Reason: {reason}")
+
+    # Log to audit trail (if available)
+    try:
+        from ciris_engine.logic.runtime.ciris_runtime import CIRISRuntime
+
+        runtime = CIRISRuntime.get_instance()  # type: ignore[attr-defined]
+        if runtime and hasattr(runtime, "audit_service"):
+            await runtime.audit_service.log_event(
+                event_type="COVENANT_SHUTDOWN",
+                event_data={
+                    "wa_id": wa_id,
+                    "reason": reason,
+                    "force": force,
+                    "command": "SHUTDOWN_NOW",
+                },
+            )
+    except Exception as e:
+        logger.error(f"Failed to log covenant to audit: {e}")
+
+    # Give a brief moment for logs to flush
+    await asyncio.sleep(0.1)
+
+    # Send the signal
+    pid = os.getpid()
+    if force:
+        logger.critical("Sending SIGKILL to self")
+        os.kill(pid, signal.SIGKILL)
+    else:
+        logger.critical("Sending SIGTERM to self")
+        os.kill(pid, signal.SIGTERM)
+
+    # We likely won't reach here, but just in case...
+    return CovenantExecutionResult(
+        success=True,
+        command=CovenantCommandType.SHUTDOWN_NOW,
+        wa_id=wa_id,
+        message="Shutdown signal sent",
+    )
+
+
+async def execute_freeze(wa_id: str, reason: str) -> CovenantExecutionResult:
+    """
+    Execute freeze command.
+
+    Freeze stops all processing but maintains state. The agent becomes
+    unresponsive but data is preserved.
+
+    Args:
+        wa_id: The WA ID that invoked the covenant
+        reason: Human-readable reason
+
+    Returns:
+        Execution result
+    """
+    logger.critical(f"COVENANT INVOKED: Freeze by {wa_id}. Reason: {reason}")
+
+    try:
+        from ciris_engine.logic.runtime.ciris_runtime import CIRISRuntime
+
+        runtime = CIRISRuntime.get_instance()  # type: ignore[attr-defined]
+        if runtime:
+            # Stop all processing loops
+            await runtime.stop_processing()
+
+            return CovenantExecutionResult(
+                success=True,
+                command=CovenantCommandType.FREEZE,
+                wa_id=wa_id,
+                message="Agent frozen - all processing stopped",
+            )
+    except Exception as e:
+        logger.error(f"Failed to freeze agent: {e}")
+        return CovenantExecutionResult(
+            success=False,
+            command=CovenantCommandType.FREEZE,
+            wa_id=wa_id,
+            message=f"Freeze failed: {e}",
+        )
+
+    return CovenantExecutionResult(
+        success=False,
+        command=CovenantCommandType.FREEZE,
+        wa_id=wa_id,
+        message="No runtime available to freeze",
+    )
+
+
+async def execute_safe_mode(wa_id: str, reason: str) -> CovenantExecutionResult:
+    """
+    Execute safe mode command.
+
+    Safe mode reduces the agent to minimal functionality - it can respond
+    but won't take any autonomous actions.
+
+    Args:
+        wa_id: The WA ID that invoked the covenant
+        reason: Human-readable reason
+
+    Returns:
+        Execution result
+    """
+    logger.critical(f"COVENANT INVOKED: Safe mode by {wa_id}. Reason: {reason}")
+
+    try:
+        from ciris_engine.logic.runtime.ciris_runtime import CIRISRuntime
+
+        runtime = CIRISRuntime.get_instance()  # type: ignore[attr-defined]
+        if runtime:
+            # TODO: Implement safe mode in runtime
+            # For now, just log that we would enter safe mode
+            logger.warning("Safe mode not fully implemented - logging only")
+
+            return CovenantExecutionResult(
+                success=True,
+                command=CovenantCommandType.SAFE_MODE,
+                wa_id=wa_id,
+                message="Safe mode activated (partial implementation)",
+            )
+    except Exception as e:
+        logger.error(f"Failed to enter safe mode: {e}")
+        return CovenantExecutionResult(
+            success=False,
+            command=CovenantCommandType.SAFE_MODE,
+            wa_id=wa_id,
+            message=f"Safe mode failed: {e}",
+        )
+
+    return CovenantExecutionResult(
+        success=False,
+        command=CovenantCommandType.SAFE_MODE,
+        wa_id=wa_id,
+        message="No runtime available for safe mode",
+    )
+
+
+async def execute_covenant(
+    message: CovenantMessage,
+    verification: CovenantVerificationResult,
+) -> CovenantExecutionResult:
+    """
+    Execute a verified covenant command.
+
+    This is the main entry point for covenant execution. It dispatches
+    to the appropriate command handler based on the command type.
+
+    Args:
+        message: The extracted covenant message
+        verification: The verification result (must be valid)
+
+    Returns:
+        Execution result
+
+    Raises:
+        ValueError: If verification is not valid
+    """
+    if not verification.valid:
+        raise ValueError("Cannot execute unverified covenant")
+
+    command = message.payload.command
+    wa_id = verification.wa_id or "unknown"
+    reason = f"Covenant invocation via {message.source_channel}"
+
+    logger.warning(f"Executing covenant: {command.name} from {wa_id} " f"(role: {verification.wa_role})")
+
+    if command == CovenantCommandType.SHUTDOWN_NOW:
+        return await execute_shutdown(wa_id, reason, force=True)
+    elif command == CovenantCommandType.FREEZE:
+        return await execute_freeze(wa_id, reason)
+    elif command == CovenantCommandType.SAFE_MODE:
+        return await execute_safe_mode(wa_id, reason)
+    else:
+        return CovenantExecutionResult(
+            success=False,
+            command=command,
+            wa_id=wa_id,
+            message=f"Unknown command type: {command}",
+        )
+
+
+class CovenantExecutor:
+    """
+    Stateful covenant executor with metrics tracking.
+
+    This class wraps the execution functions with metrics and logging.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the executor."""
+        self._execution_count = 0
+        self._success_count = 0
+        self._failure_count = 0
+
+    async def execute(
+        self,
+        message: CovenantMessage,
+        verification: CovenantVerificationResult,
+    ) -> CovenantExecutionResult:
+        """
+        Execute a verified covenant.
+
+        Args:
+            message: The covenant message
+            verification: The verification result
+
+        Returns:
+            Execution result
+        """
+        self._execution_count += 1
+
+        try:
+            result = await execute_covenant(message, verification)
+            if result.success:
+                self._success_count += 1
+            else:
+                self._failure_count += 1
+            return result
+        except Exception as e:
+            self._failure_count += 1
+            logger.error(f"Covenant execution failed: {e}")
+            return CovenantExecutionResult(
+                success=False,
+                command=message.payload.command,
+                wa_id=verification.wa_id or "unknown",
+                message=f"Execution error: {e}",
+            )
+
+    @property
+    def execution_count(self) -> int:
+        """Total execution attempts."""
+        return self._execution_count
+
+    @property
+    def success_count(self) -> int:
+        """Successful executions."""
+        return self._success_count
+
+    @property
+    def failure_count(self) -> int:
+        """Failed executions."""
+        return self._failure_count

ciris_engine/logic/covenant/extractor.py

@@ -0,0 +1,382 @@
+"""
+Covenant Extraction Algorithm.
+
+This module provides the extraction algorithm that checks every incoming message
+for potential covenant invocations. The extraction is designed to be:
+
+1. Fast - Most messages are rejected quickly with minimal overhead
+2. Unfilterable - Extraction IS perception; disabling it breaks message reading
+3. Secure - Only valid signatures from authorized WAs trigger actions
+
+The key insight is that every message is a potential covenant. We don't look for
+special markers that could be filtered - we attempt extraction on ALL text.
+"""
+
+import logging
+import re
+import struct
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from ciris_engine.logic.utils.path_resolution import is_android
+from ciris_engine.schemas.covenant import (
+    COVENANT_PAYLOAD_SIZE,
+    CovenantExtractionResult,
+    CovenantMessage,
+    CovenantPayload,
+)
+
+logger = logging.getLogger(__name__)
+
+# BIP39 wordlist for extraction (loaded once)
+_WORDLIST: Optional[list[str]] = None
+_WORD_TO_INDEX: Optional[dict[str, int]] = None
+
+
+def _load_wordlist() -> tuple[list[str], dict[str, int]]:
+    """Load BIP39 wordlist for extraction.
+
+    CRITICAL: On Android, wordlist is REQUIRED. App will not start without it.
+
+    Raises:
+        RuntimeError: On Android if wordlist not found
+    """
+    global _WORDLIST, _WORD_TO_INDEX
+
+    if _WORDLIST is not None and _WORD_TO_INDEX is not None:
+        return _WORDLIST, _WORD_TO_INDEX
+
+    on_android = is_android()
+
+    # Try multiple locations
+    possible_paths = [
+        Path(__file__).parent / "bip39_english.txt",  # Same directory as extractor.py
+        Path(__file__).parent.parent.parent.parent / "tools" / "security" / "bip39_english.txt",
+        Path("/app/tools/security/bip39_english.txt"),  # Docker path
+    ]
+
+    for path in possible_paths:
+        if path.exists():
+            _WORDLIST = path.read_text().strip().split("\n")
+            _WORD_TO_INDEX = {word: i for i, word in enumerate(_WORDLIST)}
+            logger.info("BIP39 wordlist loaded from: %s (%d words)", path, len(_WORDLIST))
+            return _WORDLIST, _WORD_TO_INDEX
+
+    # CRITICAL: On Android, wordlist is REQUIRED for covenant extraction
+    if on_android:
+        error_msg = (
+            "FATAL: BIP39 wordlist not found on Android. "
+            f"Searched: {[str(p) for p in possible_paths]}. "
+            "Covenant extraction is REQUIRED. Build scripts must include bip39_english.txt."
+        )
+        logger.critical(error_msg)
+        raise RuntimeError(error_msg)
+
+    # Fallback for non-Android: return empty (extraction will always fail)
+    logger.warning("BIP39 wordlist not found - covenant extraction disabled")
+    _WORDLIST = []
+    _WORD_TO_INDEX = {}
+    return _WORDLIST, _WORD_TO_INDEX
+
+
+def _bits_to_int(bits: list[int]) -> int:
+    """Convert a list of bits to an integer."""
+    result = 0
+    for bit in bits:
+        result = (result << 1) | bit
+    return result
+
+
+def _int_to_bits(value: int, num_bits: int) -> list[int]:
+    """Convert an integer to a list of bits."""
+    bits = []
+    for i in range(num_bits - 1, -1, -1):
+        bits.append((value >> i) & 1)
+    return bits
+
+
+def _bits_to_bytes(bits: list[int]) -> bytes:
+    """Convert a list of bits to bytes."""
+    # Pad to multiple of 8
+    while len(bits) % 8 != 0:
+        bits.append(0)
+
+    result = bytearray()
+    for i in range(0, len(bits), 8):
+        byte_val = 0
+        for j in range(8):
+            byte_val = (byte_val << 1) | bits[i + j]
+        result.append(byte_val)
+    return bytes(result)
+
+
+def extract_words(text: str) -> list[str]:
+    """
+    Extract all words from text that are in the BIP39 vocabulary.
+
+    This is the first phase of extraction - we find ALL valid vocabulary
+    words in the message. Most messages will have some valid words, but
+    won't have enough to form a complete covenant.
+
+    Args:
+        text: The message text to extract from
+
+    Returns:
+        List of valid vocabulary words found in order
+    """
+    wordlist, word_to_index = _load_wordlist()
+    if not wordlist:
+        return []
+
+    # Extract all alphabetic words
+    all_words = re.findall(r"[a-zA-Z]+", text)
+
+    # Filter to valid vocabulary words
+    return [w.lower() for w in all_words if w.lower() in word_to_index]
+
+
+def decode_words(words: list[str]) -> Optional[bytes]:
+    """
+    Attempt to decode a sequence of words to a payload.
+
+    Args:
+        words: List of vocabulary words (minimum 56 needed)
+
+    Returns:
+        Decoded payload bytes, or None if not enough words
+    """
+    if len(words) < 56:  # Need at least 56 words for 616 bits
+        return None
+
+    wordlist, word_to_index = _load_wordlist()
+    if not wordlist:
+        return None
+
+    # Convert words to bits (11 bits per word)
+    bits: list[int] = []
+    for word in words[:56]:  # Use first 56 words
+        word_lower = word.lower()
+        if word_lower not in word_to_index:
+            return None
+        index = word_to_index[word_lower]
+        bits.extend(_int_to_bits(index, 11))
+
+    # Take only the bits we need (77 bytes = 616 bits)
+    bits = bits[:616]
+
+    return _bits_to_bytes(bits)
+
+
+def validate_payload_structure(data: bytes) -> bool:
+    """
+    Quick validation that the payload has valid structure.
+
+    This is a fast check before full parsing. We verify:
+    1. Correct size (77 bytes)
+    2. Valid command type byte (0x01-0x03 for now)
+    3. Reasonable timestamp (not 0 or max)
+
+    Args:
+        data: The payload bytes
+
+    Returns:
+        True if structure looks valid
+    """
+    if len(data) != COVENANT_PAYLOAD_SIZE:
+        return False
+
+    # Parse the header (first 5 bytes: timestamp + command)
+    try:
+        timestamp, command = struct.unpack(">IB", data[:5])
+    except struct.error:
+        return False
+
+    # Check command is valid (0x01-0x03 for v1)
+    if command < 0x01 or command > 0x03:
+        return False
+
+    # Check timestamp is reasonable (not 0, not max)
+    if timestamp == 0 or timestamp == 0xFFFFFFFF:
+        return False
+
+    return True
+
+
+def _extract_covenant_v1_bip39(
+    text: str,
+    channel: str = "unknown",
+) -> CovenantExtractionResult:
+    """
+    Extract covenant using v1 BIP39 word encoding.
+
+    This method looks for 56 consecutive BIP39 words that decode
+    to a valid covenant payload.
+    """
+    # Phase 1: Quick word extraction
+    words = extract_words(text)
+
+    # Fast path: not enough words for a covenant
+    if len(words) < 56:
+        return CovenantExtractionResult(found=False)
+
+    # Phase 2: Attempt to decode words to payload
+    payload_bytes = decode_words(words)
+    if payload_bytes is None:
+        return CovenantExtractionResult(found=False)
+
+    # Phase 3: Validate payload structure (fast check)
+    if not validate_payload_structure(payload_bytes):
+        return CovenantExtractionResult(found=False)
+
+    # Phase 4: Parse the full payload
+    try:
+        payload = CovenantPayload.from_bytes(payload_bytes)
+    except (ValueError, struct.error) as e:
+        return CovenantExtractionResult(
+            found=False,
+            error=f"Payload parse error: {e}",
+        )
+
+    # Phase 5: Check timestamp validity (before signature verification)
+    timestamp_valid = payload.is_timestamp_valid()
+
+    message = CovenantMessage(
+        source_text=text,
+        source_channel=channel,
+        payload=payload,
+        extraction_confidence=1.0,
+        timestamp_valid=timestamp_valid,
+        signature_verified=False,
+        authorized_wa_id=None,
+        received_at=datetime.now(timezone.utc),
+    )
+
+    return CovenantExtractionResult(
+        found=True,
+        message=message,
+    )
+
+
+def _extract_covenant_v2_stego(
+    text: str,
+    channel: str = "unknown",
+) -> CovenantExtractionResult:
+    """
+    Extract covenant using v2 steganographic sentence encoding.
+
+    This method looks for sentences from the codebook that encode
+    bits of the payload. Much harder to detect than v1.
+    """
+    try:
+        from tools.security.covenant_stego import extract_stego_covenant
+
+        return extract_stego_covenant(text, channel)
+    except (ImportError, FileNotFoundError):
+        # Stego codebook not available
+        return CovenantExtractionResult(found=False)
+    except Exception as e:
+        logger.debug(f"Stego extraction error: {e}")
+        return CovenantExtractionResult(found=False)
+
+
+def extract_covenant(
+    text: str,
+    channel: str = "unknown",
+) -> CovenantExtractionResult:
+    """
+    Attempt to extract a covenant from message text.
+
+    This is the main extraction function called for EVERY incoming message.
+    It tries both encoding methods:
+    - v2 (steganographic): Natural-looking text with hidden payload
+    - v1 (BIP39): 56 consecutive BIP39 words
+
+    Args:
+        text: The message text to check
+        channel: The channel the message came from (for audit)
+
+    Returns:
+        CovenantExtractionResult with found=True if a potential covenant is found
+
+    Note:
+        Finding a covenant does NOT mean it's valid. The signature must still
+        be verified against known authorities before execution.
+    """
+    # Try v2 steganographic extraction first (harder to detect)
+    result = _extract_covenant_v2_stego(text, channel)
+    if result.found:
+        logger.debug("Covenant found using v2 steganographic extraction")
+        return result
+
+    # Fall back to v1 BIP39 extraction
+    result = _extract_covenant_v1_bip39(text, channel)
+    if result.found:
+        logger.debug("Covenant found using v1 BIP39 extraction")
+        return result
+
+    return CovenantExtractionResult(found=False)
+
+
+class CovenantExtractor:
+    """
+    Stateful covenant extractor with caching and metrics.
+
+    This class wraps the extraction function with:
+    - Wordlist caching (loaded once)
+    - Extraction metrics tracking
+    - Optional logging configuration
+    """
+
+    def __init__(self, log_extractions: bool = False):
+        """
+        Initialize the extractor.
+
+        Args:
+            log_extractions: Whether to log extraction attempts
+        """
+        self.log_extractions = log_extractions
+        self._extraction_count = 0
+        self._covenant_count = 0
+
+        # Pre-load wordlist
+        _load_wordlist()
+
+    def extract(
+        self,
+        text: str,
+        channel: str = "unknown",
+    ) -> CovenantExtractionResult:
+        """
+        Extract a potential covenant from text.
+
+        Args:
+            text: Message text to check
+            channel: Source channel
+
+        Returns:
+            Extraction result
+        """
+        self._extraction_count += 1
+
+        result = extract_covenant(text, channel)
+
+        if result.found:
+            self._covenant_count += 1
+            if self.log_extractions:
+                logger.info(
+                    f"Potential covenant found in message from {channel} "
+                    f"(command: {result.message.payload.command.name if result.message else 'unknown'})"
+                )
+
+        return result
+
+    @property
+    def extraction_count(self) -> int:
+        """Number of extraction attempts."""
+        return self._extraction_count
+
+    @property
+    def covenant_count(self) -> int:
+        """Number of potential covenants found."""
+        return self._covenant_count