devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/audit/signing.py

@@ -0,0 +1,127 @@
+"""Optional asymmetric signing of exported audit reports.
+
+The existing ``devtorch_core.signing`` module signs individual event-log lines
+with HMAC-SHA256. This module is for exported JSON/PDF audit reports: it uses
+asymmetric Ed25519 so anyone with the public key can verify the report without
+accessing the private signing key.
+
+``cryptography`` is an optional dependency. If it is unavailable, signing
+functions raise ``AuditSignatureError``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class AuditSignatureError(RuntimeError):
+    """Raised when signing or verification cannot proceed."""
+
+
+class ExportSigner:
+    """Ed25519 signer for exported audit JSON."""
+
+    ALGORITHM = "ed25519"
+
+    def __init__(self) -> None:
+        self._cryptography = self._load_cryptography()
+
+    @staticmethod
+    def _load_cryptography():
+        try:
+            import cryptography  # noqa: F401
+            from cryptography.hazmat.primitives.asymmetric import ed25519
+            from cryptography.hazmat.primitives import serialization
+            return (ed25519, serialization)
+        except ImportError as exc:
+            raise AuditSignatureError(
+                "cryptography is required for export signing; install devtorch-core[audit]"
+            ) from exc
+
+    def generate_keypair(self) -> tuple[bytes, bytes]:
+        """Return (private_key_pem, public_key_pem) as bytes."""
+        ed25519, serialization = self._cryptography
+        private_key = ed25519.Ed25519PrivateKey.generate()
+        private_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        public_pem = private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        return private_pem, public_pem
+
+    def save_key(self, path: Path, key_pem: bytes) -> None:
+        """Persist a PEM key with restrictive permissions."""
+        path.write_bytes(key_pem)
+        try:
+            path.chmod(0o600)
+        except (OSError, NotImplementedError):
+            pass
+
+    def load_private_key(self, path: Path):
+        """Load an Ed25519 private key from a PEM file."""
+        _, serialization = self._cryptography
+        data = path.read_bytes()
+        return serialization.load_pem_private_key(data, password=None)
+
+    def load_public_key(self, path: Path):
+        """Load an Ed25519 public key from a PEM file."""
+        _, serialization = self._cryptography
+        data = path.read_bytes()
+        return serialization.load_pem_public_key(data)
+
+    def sign(self, data: bytes, private_key) -> bytes:
+        """Sign bytes and return a base64-encoded signature."""
+        signature = private_key.sign(data)
+        return base64.b64encode(signature)
+
+    def verify(self, data: bytes, signature_b64: bytes, public_key) -> bool:
+        """Verify a base64-encoded signature against data."""
+        try:
+            signature = base64.b64decode(signature_b64)
+            public_key.verify(signature, data)
+            return True
+        except Exception:
+            return False
+
+    def sign_json(self, data: Dict[str, Any], private_key) -> Dict[str, Any]:
+        """Return a signed envelope wrapping the JSON data."""
+        payload_bytes = json.dumps(data, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        signature = self.sign(payload_bytes, private_key)
+        return {
+            "algorithm": self.ALGORITHM,
+            "payload": data,
+            "signature": signature.decode("utf-8"),
+        }
+
+    def verify_json(self, envelope: Dict[str, Any], public_key) -> bool:
+        """Verify a signed envelope."""
+        if envelope.get("algorithm") != self.ALGORITHM:
+            return False
+        payload = envelope.get("payload")
+        if payload is None:
+            return False
+        signature_b64 = envelope.get("signature", "").encode("utf-8")
+        payload_bytes = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        return self.verify(payload_bytes, signature_b64, public_key)
+
+    def sign_file(self, input_path: Path, output_path: Path, private_key_path: Path) -> None:
+        """Sign a JSON file and write a signed envelope to ``output_path``."""
+        data = json.loads(input_path.read_text(encoding="utf-8"))
+        private_key = self.load_private_key(private_key_path)
+        envelope = self.sign_json(data, private_key)
+        output_path.write_text(json.dumps(envelope, indent=2), encoding="utf-8")
+
+    def verify_file(self, envelope_path: Path, public_key_path: Path) -> bool:
+        """Verify a signed envelope file."""
+        envelope = json.loads(envelope_path.read_text(encoding="utf-8"))
+        public_key = self.load_public_key(public_key_path)
+        return self.verify_json(envelope, public_key)
+
+

devtorch_core/broadcast/__init__.py

@@ -0,0 +1,4 @@
+from .broadcaster import EventBroadcaster, create_broadcast_app
+from .watcher import GCCWatcher
+
+__all__ = ["EventBroadcaster", "create_broadcast_app", "GCCWatcher"]

devtorch_core/broadcast/broadcaster.py

@@ -0,0 +1,100 @@
+"""
+Local SSE broadcaster for DevTorch coordination events.
+
+Agents subscribe to GET /events/stream and receive coordination-relevant
+events as they are appended to .GCC/events.log.jsonl.
+
+Only broadcasts events whose event_type contains one of:
+DIVERGENCE, CONSOLIDATION, HITL, CONSENSUS
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from pathlib import Path
+from typing import List, Optional, Set
+
+COORDINATION_TYPES: Set[str] = {"DIVERGENCE", "CONSOLIDATION", "HITL", "CONSENSUS"}
+
+
+def _is_coordination_event(event_type: str) -> bool:
+    """Return True if any coordination keyword appears in the event_type string."""
+    upper = event_type.upper()
+    return any(kw in upper for kw in COORDINATION_TYPES)
+
+
+class EventBroadcaster:
+    """Thread-safe in-process event broadcaster backed by asyncio queues."""
+
+    def __init__(self) -> None:
+        self._queues: List[asyncio.Queue] = []
+        self._lock = threading.Lock()
+
+    def subscribe(self) -> asyncio.Queue:
+        # asyncio.Queue.put_nowait() and get_nowait() are safe to call from threads
+        # under CPython's GIL (deque operations are atomic). The async await q.get()
+        # path in create_broadcast_app is only reached from within the FastAPI event loop.
+        q: asyncio.Queue = asyncio.Queue()
+        with self._lock:
+            self._queues.append(q)
+        return q
+
+    def unsubscribe(self, q: asyncio.Queue) -> None:
+        with self._lock:
+            try:
+                self._queues.remove(q)
+            except ValueError:
+                pass
+
+    def publish(self, event: dict) -> None:
+        """Publish event to all subscriber queues (non-blocking)."""
+        event_type = event.get("event_type", "")
+        if not _is_coordination_event(event_type):
+            return
+        with self._lock:
+            targets = list(self._queues)
+        for q in targets:
+            try:
+                q.put_nowait(event)
+            except asyncio.QueueFull:
+                pass
+
+
+def create_broadcast_app(broadcaster: EventBroadcaster):
+    """
+    Build a FastAPI app exposing GET /events/stream (SSE).
+    Returns None if FastAPI is not installed.
+    """
+    try:
+        from fastapi import FastAPI
+        from fastapi.responses import StreamingResponse
+    except ImportError:
+        return None
+
+    app = FastAPI(title="DevTorch Event Broadcaster", version="0.1.0")
+
+    @app.get("/events/stream")
+    async def event_stream():
+        q = broadcaster.subscribe()
+
+        async def generate():
+            try:
+                # Send keepalive immediately
+                yield "data: {\"type\": \"connected\"}\n\n"
+                while True:
+                    try:
+                        event = await asyncio.wait_for(q.get(), timeout=30.0)
+                        yield f"data: {json.dumps(event)}\n\n"
+                    except asyncio.TimeoutError:
+                        yield ": keepalive\n\n"
+            finally:
+                broadcaster.unsubscribe(q)
+
+        return StreamingResponse(generate(), media_type="text/event-stream")
+
+    @app.get("/events/health")
+    def health():
+        return {"status": "ok", "subscribers": len(broadcaster._queues)}
+
+    return app

devtorch_core/broadcast/watcher.py

@@ -0,0 +1,71 @@
+"""
+File watcher that monitors .GCC/events.log.jsonl for new lines
+and publishes coordination events to an EventBroadcaster.
+
+Uses watchdog if available; falls back to polling.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+from .broadcaster import EventBroadcaster
+
+
+class GCCWatcher:
+    """
+    Watches .GCC/events.log.jsonl for new lines and publishes
+    coordination-relevant events to the broadcaster.
+    """
+
+    def __init__(self, gcc_dir: Path, broadcaster: EventBroadcaster,
+                 poll_interval: float = 0.5) -> None:
+        self._log_path = gcc_dir / "events.log.jsonl"
+        self._broadcaster = broadcaster
+        self._poll_interval = poll_interval
+        self._offset: int = 0
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+
+    def _read_new_lines(self) -> None:
+        """Read any new lines appended since last check and publish them."""
+        if not self._log_path.exists():
+            return
+        try:
+            with self._log_path.open("r", encoding="utf-8") as f:
+                f.seek(self._offset)
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        event = json.loads(line)
+                        self._broadcaster.publish(event)
+                    except json.JSONDecodeError:
+                        pass
+                self._offset = f.tell()
+        except OSError:
+            pass
+
+    def _poll_loop(self) -> None:
+        while not self._stop_event.is_set():
+            self._read_new_lines()
+            self._stop_event.wait(self._poll_interval)
+
+    def start(self) -> None:
+        """Start the watcher background thread."""
+        if self._log_path.exists():
+            self._offset = self._log_path.stat().st_size
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._poll_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the watcher background thread."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None