halyn 0.2.0__py3-none-any.whl

halyn/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""Halyn — NRP control plane with domain-scoped authorization."""
+
+__version__ = "0.2.0"
+__author__ = "Elmadani SALKA"
+__license__ = "MIT"

halyn/__main__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+from .cli import main
+main()

halyn/audit.py

@@ -0,0 +1,278 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Audit — Indestructible record of every action.
+
+Append-only audit log with SHA-256 hash chaining.
+Persisted via SQLite WAL. Tamper-detectable in O(n).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger("halyn.audit")
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp REAL NOT NULL,
+    tool TEXT NOT NULL,
+    node TEXT NOT NULL DEFAULT '',
+    args TEXT NOT NULL DEFAULT '{}',
+    result TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL DEFAULT 'ok',
+    duration_ms REAL NOT NULL DEFAULT 0,
+    user_id TEXT NOT NULL DEFAULT '',
+    llm_model TEXT NOT NULL DEFAULT '',
+    intent TEXT NOT NULL DEFAULT '',
+    domain TEXT NOT NULL DEFAULT '',
+    autonomy_level INTEGER NOT NULL DEFAULT -1,
+    decision TEXT NOT NULL DEFAULT '',
+    hash TEXT NOT NULL,
+    prev_hash TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_audit_ts ON audit_log(timestamp);
+CREATE INDEX IF NOT EXISTS idx_audit_tool ON audit_log(tool);
+CREATE INDEX IF NOT EXISTS idx_audit_node ON audit_log(node);
+CREATE INDEX IF NOT EXISTS idx_audit_status ON audit_log(status);
+CREATE INDEX IF NOT EXISTS idx_audit_user ON audit_log(user_id);
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class AuditEntry:
+    """One audited action. Immutable. Hashable."""
+    timestamp: float
+    tool: str
+    node: str
+    args: dict[str, Any]
+    result: str
+    status: str
+    duration_ms: float
+    user_id: str
+    llm_model: str
+    intent: str          # Why was this action taken?
+    domain: str          # Which domain policy applied?
+    autonomy_level: int  # What level authorized it?
+    decision: str        # allow / confirm / deny
+    hash: str
+    prev_hash: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "timestamp": self.timestamp,
+            "tool": self.tool,
+            "node": self.node,
+            "args": self.args,
+            "result": self.result[:500],
+            "status": self.status,
+            "duration_ms": self.duration_ms,
+            "user_id": self.user_id,
+            "llm_model": self.llm_model,
+            "intent": self.intent,
+            "domain": self.domain,
+            "autonomy_level": self.autonomy_level,
+            "decision": self.decision,
+            "hash": self.hash,
+            "prev_hash": self.prev_hash,
+        }
+
+
+class AuditStore:
+    """
+    Persistent, tamper-evident audit trail.
+
+    Every action is:
+    1. Written to disk BEFORE execution (WAL)
+    2. Hash-chained to the previous entry
+    3. Queryable by time, tool, node, user, status
+
+    Tampering breaks the chain. Detectable in O(n).
+    """
+
+    def __init__(self, db_path: str = "") -> None:
+        if not db_path:
+            data_dir = Path.home() / ".halyn"
+            data_dir.mkdir(parents=True, exist_ok=True)
+            db_path = str(data_dir / "audit.db")
+        self._db_path = db_path
+        self._lock = threading.Lock()
+        self._prev_hash = "GENESIS"
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA synchronous=NORMAL")
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+        self._restore_chain()
+        log.info("audit.init db=%s chain_tip=%s", db_path, self._prev_hash[:16])
+
+    def record(
+        self,
+        tool: str,
+        node: str = "",
+        args: dict[str, Any] | None = None,
+        result: str = "",
+        status: str = "ok",
+        duration_ms: float = 0.0,
+        user_id: str = "",
+        llm_model: str = "",
+        intent: str = "",
+        domain: str = "",
+        autonomy_level: int = -1,
+        decision: str = "",
+    ) -> AuditEntry:
+        """Record an action. Returns the entry with its hash."""
+        ts = time.time()
+        args = args or {}
+
+        entry_hash = self._compute_hash(
+            ts, tool, node, json.dumps(args, default=str, sort_keys=True),
+            result[:500], status, self._prev_hash,
+        )
+
+        entry = AuditEntry(
+            timestamp=ts, tool=tool, node=node, args=args,
+            result=result[:2000], status=status, duration_ms=duration_ms,
+            user_id=user_id, llm_model=llm_model, intent=intent,
+            domain=domain, autonomy_level=autonomy_level, decision=decision,
+            hash=entry_hash, prev_hash=self._prev_hash,
+        )
+
+        with self._lock:
+            self._conn.execute(
+                "INSERT INTO audit_log "
+                "(timestamp, tool, node, args, result, status, duration_ms, "
+                "user_id, llm_model, intent, domain, autonomy_level, decision, "
+                "hash, prev_hash) "
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                (ts, tool, node, json.dumps(args, default=str),
+                 result[:2000], status, duration_ms,
+                 user_id, llm_model, intent, domain, autonomy_level,
+                 decision, entry_hash, self._prev_hash),
+            )
+            self._conn.commit()
+            self._prev_hash = entry_hash
+
+        log.debug("audit.record tool=%s hash=%s", tool, entry_hash[:16])
+        return entry
+
+    def query(
+        self,
+        since: float = 0,
+        until: float = 0,
+        tool: str = "",
+        node: str = "",
+        user_id: str = "",
+        status: str = "",
+        limit: int = 100,
+    ) -> list[AuditEntry]:
+        """Query the audit trail with filters."""
+        conditions: list[str] = []
+        params: list[Any] = []
+
+        if since:
+            conditions.append("timestamp >= ?")
+            params.append(since)
+        if until:
+            conditions.append("timestamp <= ?")
+            params.append(until)
+        if tool:
+            conditions.append("tool LIKE ?")
+            params.append(f"%{tool}%")
+        if node:
+            conditions.append("node LIKE ?")
+            params.append(f"%{node}%")
+        if user_id:
+            conditions.append("user_id = ?")
+            params.append(user_id)
+        if status:
+            conditions.append("status = ?")
+            params.append(status)
+
+        where = " AND ".join(conditions) if conditions else "1=1"
+        sql = f"SELECT * FROM audit_log WHERE {where} ORDER BY timestamp DESC LIMIT ?"
+        params.append(limit)
+
+        with self._lock:
+            rows = self._conn.execute(sql, params).fetchall()
+
+        return [self._row_to_entry(r) for r in rows]
+
+    def verify_chain(self) -> tuple[bool, int, str]:
+        """
+        Verify the entire hash chain.
+        Returns: (valid, entries_checked, error_message)
+        """
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT timestamp, tool, node, args, result, status, hash, prev_hash "
+                "FROM audit_log ORDER BY id ASC"
+            ).fetchall()
+
+        prev = "GENESIS"
+        for i, row in enumerate(rows):
+            ts, tool, node, args_str, result, status, stored_hash, stored_prev = row
+            if stored_prev != prev:
+                return False, i, f"Chain broken at entry {i}: prev mismatch"
+            computed = self._compute_hash(ts, tool, node, args_str, result[:500], status, prev)
+            if computed != stored_hash:
+                return False, i, f"Tamper detected at entry {i}: hash mismatch"
+            prev = stored_hash
+
+        return True, len(rows), "Chain valid"
+
+    @property
+    def count(self) -> int:
+        with self._lock:
+            r = self._conn.execute("SELECT COUNT(*) FROM audit_log").fetchone()
+            return r[0] if r else 0
+
+    @property
+    def chain_tip(self) -> str:
+        return self._prev_hash
+
+    def export_jsonl(self, path: str) -> int:
+        """Export full audit trail to JSONL file."""
+        entries = self.query(limit=1_000_000)
+        with open(path, "w") as f:
+            for e in reversed(entries):
+                f.write(json.dumps(e.to_dict(), default=str) + "\n")
+        return len(entries)
+
+    def _restore_chain(self) -> None:
+        row = self._conn.execute(
+            "SELECT hash FROM audit_log ORDER BY id DESC LIMIT 1"
+        ).fetchone()
+        if row:
+            self._prev_hash = row[0]
+
+    @staticmethod
+    def _compute_hash(ts: float, tool: str, node: str, args: str,
+                      result: str, status: str, prev_hash: str) -> str:
+        payload = f"{ts}|{tool}|{node}|{args}|{result}|{status}|{prev_hash}"
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    def _row_to_entry(self, row: tuple) -> AuditEntry:
+        return AuditEntry(
+            timestamp=row[1], tool=row[2], node=row[3],
+            args=json.loads(row[4]) if row[4] else {},
+            result=row[5], status=row[6], duration_ms=row[7],
+            user_id=row[8], llm_model=row[9], intent=row[10],
+            domain=row[11], autonomy_level=row[12], decision=row[13],
+            hash=row[14], prev_hash=row[15],
+        )
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+

halyn/auth.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Auth — API authentication + rate limiting.
+
+Simple, effective, no framework dependency.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+import os
+import time
+from typing import Any
+
+from aiohttp import web
+
+log = logging.getLogger("jarvis.auth")
+
+
+class AuthMiddleware:
+    """API key authentication + rate limiting."""
+
+    def __init__(self, api_key: str = "", rate_limit: int = 60) -> None:
+        self.api_key = api_key or os.environ.get("JARVIS_API_KEY", "")
+        self.rate_limit = rate_limit  # requests per minute
+        self._requests: dict[str, list[float]] = {}  # ip -> timestamps
+        self.enabled = bool(self.api_key)
+
+        if not self.enabled:
+            log.warning("auth.disabled — set JARVIS_API_KEY to enable")
+
+    def check(self, request: web.Request) -> str | None:
+        """Returns error message if denied, None if allowed."""
+        # Health endpoint is always public
+        if request.path == "/health":
+            return None
+
+        # Auth check
+        if self.enabled:
+            key = (
+                request.headers.get("X-API-Key", "")
+                or request.headers.get("Authorization", "").removeprefix("Bearer ")
+            )
+            if not self._verify_key(key):
+                log.warning("auth.denied ip=%s path=%s", request.remote, request.path)
+                return "invalid or missing API key"
+
+        # Rate limit check
+        ip = request.remote or "unknown"
+        now = time.monotonic()
+        timestamps = self._requests.get(ip, [])
+        # Clean old entries (older than 60s)
+        timestamps = [t for t in timestamps if now - t < 60]
+        if len(timestamps) >= self.rate_limit:
+            log.warning("auth.rate_limited ip=%s count=%d", ip, len(timestamps))
+            return "rate limit exceeded"
+        timestamps.append(now)
+        self._requests[ip] = timestamps
+
+        return None
+
+    def _verify_key(self, provided: str) -> bool:
+        """Constant-time comparison to prevent timing attacks."""
+        if not provided or not self.api_key:
+            return False
+        return hmac.compare_digest(provided.encode(), self.api_key.encode())
+
+
+def create_auth_middleware(api_key: str = "", rate_limit: int = 60):
+    """Create aiohttp middleware for auth."""
+    auth = AuthMiddleware(api_key, rate_limit)
+
+    @web.middleware
+    async def middleware(request: web.Request, handler: Any) -> web.Response:
+        error = auth.check(request)
+        if error:
+            return web.Response(
+                text=f'{{"ok":false,"error":"{error}"}}',
+                content_type="application/json",
+                status=401 if "API key" in error else 429,
+            )
+        return await handler(request)
+
+    return middleware
+

halyn/autonomy.py

@@ -0,0 +1,262 @@
+# Copyright (c) 2026 Elmadani SALKA. All rights reserved.
+# Licensed under the MIT License. See LICENSE file.
+"""
+Autonomy — The human always controls.
+
+Domain-scoped authorization with 5 configurable trust levels.
+Rate limiting, time-of-day restrictions, and per-command policies.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Any, Callable, Awaitable
+
+from .types import Action, ActionStatus, ToolCategory
+
+log = logging.getLogger("halyn.autonomy")
+
+
+class Level(IntEnum):
+    """How much freedom the AI has."""
+    MANUAL = 0       # AI proposes. Human approves EVERY action.
+    SUPERVISED = 1   # AI reads alone. Asks before writing/acting.
+    GUIDED = 2       # Safe actions alone. Dangerous = confirm.
+    AUTONOMOUS = 3   # Does everything. Human can interrupt.
+    FULL_AUTO = 4    # Handles routine. Reports daily.
+
+
+@dataclass(slots=True)
+class DomainPolicy:
+    """Policy for one domain (physical, financial, infra, etc.)."""
+    name: str
+    level: Level = Level.SUPERVISED
+    node_patterns: list[str] = field(default_factory=lambda: ["*"])
+    hours: tuple[int, int] | None = None  # (start_hour, end_hour) or None=always
+    max_actions_per_hour: int = 1000
+    blocked_commands: list[str] = field(default_factory=list)
+    confirm_commands: list[str] = field(default_factory=list)
+
+    def matches_node(self, node_name: str) -> bool:
+        import fnmatch
+        return any(fnmatch.fnmatch(node_name, p) for p in self.node_patterns)
+
+    def is_active_now(self) -> bool:
+        if self.hours is None:
+            return True
+        hour = time.localtime().tm_hour
+        start, end = self.hours
+        if start <= end:
+            return start <= hour < end
+        return hour >= start or hour < end  # Overnight range
+
+
+@dataclass(slots=True)
+class ConfirmationRequest:
+    """A pending action waiting for human approval."""
+    request_id: str
+    action: Action
+    reason: str
+    domain: str
+    created_at: float = field(default_factory=time.time)
+    expires_at: float = 0.0  # 0 = no expiry
+    status: str = "pending"  # pending, approved, denied, expired
+
+    def __post_init__(self) -> None:
+        if self.expires_at == 0.0:
+            self.expires_at = self.created_at + 300  # 5 min default
+
+    @property
+    def expired(self) -> bool:
+        return time.time() > self.expires_at and self.status == "pending"
+
+
+class AutonomyController:
+    """
+    The gatekeeper. Every action passes through here.
+
+    Decides: execute immediately, ask for confirmation, or deny.
+    Based on: domain policy, action category, time of day, rate limits.
+    """
+
+    __slots__ = ("_domains", "_pending", "_action_counts", "_default_level")
+
+    def __init__(self, default_level: Level = Level.SUPERVISED) -> None:
+        self._domains: dict[str, DomainPolicy] = {}
+        self._pending: dict[str, ConfirmationRequest] = {}
+        self._action_counts: dict[str, list[float]] = {}  # domain -> timestamps
+        self._default_level = default_level
+
+    def add_domain(self, policy: DomainPolicy) -> None:
+        self._domains[policy.name] = policy
+        log.info("autonomy.domain name=%s level=%s nodes=%s",
+                 policy.name, Level(policy.level).name, policy.node_patterns)
+
+    def check(self, action: Action, tool_category: ToolCategory,
+              tool_dangerous: bool) -> tuple[str, str]:
+        """
+        Check if an action should proceed.
+
+        Returns: (decision, reason)
+          decision: "allow", "confirm", "deny"
+          reason: human-readable explanation
+        """
+        # Find matching domain
+        domain = self._find_domain(action.node)
+        if domain is None:
+            domain = DomainPolicy(name="default", level=self._default_level)
+
+        # Check if domain is active
+        if not domain.is_active_now():
+            return "deny", f"Domain '{domain.name}' not active at this hour"
+
+        # Check rate limit
+        if not self._check_rate(domain):
+            return "deny", f"Rate limit exceeded for domain '{domain.name}'"
+
+        # Check blocked commands
+        cmd = action.tool + " " + action.args.get("command", "")
+        for blocked in domain.blocked_commands:
+            if blocked.lower() in cmd.lower():
+                return "deny", f"Command blocked by domain policy: {blocked}"
+
+        # Check confirm commands
+        for confirm_pattern in domain.confirm_commands:
+            if confirm_pattern.lower() in cmd.lower():
+                return "confirm", f"Requires confirmation: matches '{confirm_pattern}'"
+
+        # Apply autonomy level
+        level = domain.level
+
+        if level == Level.MANUAL:
+            return "confirm", "Level MANUAL: all actions require approval"
+
+        if level == Level.SUPERVISED:
+            if tool_category == ToolCategory.OBSERVER:
+                self._record_action(domain.name)
+                return "allow", "Level SUPERVISED: observe allowed"
+            return "confirm", "Level SUPERVISED: action requires approval"
+
+        if level == Level.GUIDED:
+            if tool_dangerous:
+                return "confirm", f"Level GUIDED: dangerous action requires approval"
+            self._record_action(domain.name)
+            return "allow", "Level GUIDED: safe action allowed"
+
+        if level == Level.AUTONOMOUS:
+            self._record_action(domain.name)
+            return "allow", "Level AUTONOMOUS: action allowed (interruptible)"
+
+        if level == Level.FULL_AUTO:
+            self._record_action(domain.name)
+            return "allow", "Level FULL_AUTO: autonomous execution"
+
+        return "confirm", "Unknown level: defaulting to confirm"
+
+    # ─── Confirmation management ────────────────────
+
+    def request_confirmation(self, request_id: str, action: Action,
+                             reason: str, domain: str = "") -> ConfirmationRequest:
+        req = ConfirmationRequest(
+            request_id=request_id, action=action,
+            reason=reason, domain=domain,
+        )
+        self._pending[request_id] = req
+        log.info("autonomy.confirm_requested id=%s tool=%s reason=%s",
+                 request_id, action.tool, reason)
+        return req
+
+    def approve(self, request_id: str) -> bool:
+        req = self._pending.get(request_id)
+        if req and req.status == "pending" and not req.expired:
+            req.status = "approved"
+            log.info("autonomy.approved id=%s", request_id)
+            return True
+        return False
+
+    def deny(self, request_id: str) -> bool:
+        req = self._pending.get(request_id)
+        if req and req.status == "pending":
+            req.status = "denied"
+            log.info("autonomy.denied id=%s", request_id)
+            return True
+        return False
+
+    def get_pending(self) -> list[ConfirmationRequest]:
+        self._clean_expired()
+        return [r for r in self._pending.values() if r.status == "pending"]
+
+    def get_request(self, request_id: str) -> ConfirmationRequest | None:
+        return self._pending.get(request_id)
+
+    # ─── Internal ──────────────────────────────────
+
+    def _find_domain(self, node: str) -> DomainPolicy | None:
+        for domain in self._domains.values():
+            if domain.matches_node(node):
+                return domain
+        return None
+
+    def _check_rate(self, domain: DomainPolicy) -> bool:
+        now = time.time()
+        timestamps = self._action_counts.get(domain.name, [])
+        timestamps = [t for t in timestamps if now - t < 3600]
+        self._action_counts[domain.name] = timestamps
+        return len(timestamps) < domain.max_actions_per_hour
+
+    def _record_action(self, domain_name: str) -> None:
+        if domain_name not in self._action_counts:
+            self._action_counts[domain_name] = []
+        self._action_counts[domain_name].append(time.time())
+
+    def _clean_expired(self) -> None:
+        for req_id, req in list(self._pending.items()):
+            if req.expired:
+                req.status = "expired"
+                log.info("autonomy.expired id=%s", req_id)
+
+
+# ─── Default domain presets ─────────────────────────
+
+PRESET_DOMAINS = {
+    "physical": DomainPolicy(
+        name="physical",
+        level=Level.SUPERVISED,
+        node_patterns=["robot/*", "drone/*", "arm/*", "vehicle/*"],
+        confirm_commands=["emergency_stop", "move", "pick", "deploy"],
+    ),
+    "financial": DomainPolicy(
+        name="financial",
+        level=Level.MANUAL,
+        node_patterns=["finance/*", "bank/*", "payment/*"],
+        blocked_commands=["delete", "drop"],
+    ),
+    "infrastructure": DomainPolicy(
+        name="infrastructure",
+        level=Level.GUIDED,
+        node_patterns=["server/*", "cloud/*", "docker/*"],
+        confirm_commands=["restart", "deploy", "delete"],
+    ),
+    "monitoring": DomainPolicy(
+        name="monitoring",
+        level=Level.FULL_AUTO,
+        node_patterns=["sensor/*", "monitor/*", "metric/*"],
+        max_actions_per_hour=10000,
+    ),
+    "home": DomainPolicy(
+        name="home",
+        level=Level.AUTONOMOUS,
+        node_patterns=["home/*"],
+        blocked_commands=["unlock_door"],
+    ),
+    "communication": DomainPolicy(
+        name="communication",
+        level=Level.SUPERVISED,
+        node_patterns=["email/*", "slack/*", "telegram/*"],
+        confirm_commands=["send", "post", "reply"],
+    ),
+}
+