superlocalmemory 2.7.5 → 2.8.0

package/src/compliance/abac_engine.py

@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Attribute-Based Access Control policy evaluation.
+
+Evaluates access requests against JSON-defined policies using
+subject, resource, and action attributes. Deny-first semantics
+ensure any matching deny policy blocks access regardless of
+allow policies. When no policies exist, all access is permitted
+(backward compatible with v2.7 default-allow behavior).
+
+Policy format:
+    {
+        "name": str,          # Human-readable policy name
+        "effect": str,        # "allow" or "deny"
+        "subjects": dict,     # Attribute constraints on the requester
+        "resources": dict,    # Attribute constraints on the resource
+        "actions": list[str]  # Actions this policy applies to
+    }
+
+Matching rules:
+    - "*" matches any value for that attribute
+    - Specific values require exact match
+    - All attributes in the policy must match for the policy to apply
+"""
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ABACEngine:
+    """Evaluates ABAC policies for memory access control.
+
+    Deny-first evaluation: if ANY deny policy matches the request,
+    access is denied. If no deny matches, access is allowed
+    (default-allow preserves v2.7 backward compatibility).
+    """
+
+    def __init__(self, config_path: Optional[str] = None) -> None:
+        self._config_path = config_path
+        self.policies: List[Dict[str, Any]] = []
+        if config_path:
+            self._load_policies(config_path)
+
+    def _load_policies(self, path: str) -> None:
+        """Load policies from a JSON file. Graceful on missing/invalid."""
+        try:
+            raw = Path(path).read_text(encoding="utf-8")
+            data = json.loads(raw)
+            if isinstance(data, list):
+                self.policies = data
+                logger.info("Loaded %d ABAC policies from %s", len(data), path)
+            else:
+                logger.warning("ABAC policy file is not a list: %s", path)
+        except FileNotFoundError:
+            logger.debug("No ABAC policy file at %s — default allow", path)
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("Failed to parse ABAC policies: %s", exc)
+
+    def evaluate(
+        self,
+        subject: Dict[str, Any],
+        resource: Dict[str, Any],
+        action: str,
+    ) -> Dict[str, Any]:
+        """Evaluate an access request against loaded policies.
+
+        Args:
+            subject:  Attributes of the requester (e.g. agent_id).
+            resource: Attributes of the target resource.
+            action:   The action being requested (read/write/delete).
+
+        Returns:
+            Dict with keys: allowed (bool), reason (str),
+            and policy_name (str) when a specific policy decided.
+        """
+        if not self.policies:
+            return {"allowed": True, "reason": "no_policies_loaded"}
+
+        # Phase 1: check all deny policies first
+        for policy in self.policies:
+            if policy.get("effect") != "deny":
+                continue
+            if self._matches(policy, subject, resource, action):
+                return {
+                    "allowed": False,
+                    "reason": "denied_by_policy",
+                    "policy_name": policy.get("name", "unnamed"),
+                }
+
+        # Phase 2: check allow policies
+        for policy in self.policies:
+            if policy.get("effect") != "allow":
+                continue
+            if self._matches(policy, subject, resource, action):
+                return {
+                    "allowed": True,
+                    "reason": "allowed_by_policy",
+                    "policy_name": policy.get("name", "unnamed"),
+                }
+
+        # Phase 3: no matching policy — default allow (backward compat)
+        return {"allowed": True, "reason": "no_matching_policy"}
+
+    # ------------------------------------------------------------------
+    # Internal matching helpers
+    # ------------------------------------------------------------------
+
+    def _matches(
+        self,
+        policy: Dict[str, Any],
+        subject: Dict[str, Any],
+        resource: Dict[str, Any],
+        action: str,
+    ) -> bool:
+        """Return True if policy matches the request."""
+        if not self._action_matches(policy.get("actions", []), action):
+            return False
+        if not self._attrs_match(policy.get("subjects", {}), subject):
+            return False
+        if not self._attrs_match(policy.get("resources", {}), resource):
+            return False
+        return True
+
+    @staticmethod
+    def _action_matches(policy_actions: List[str], action: str) -> bool:
+        """Check if the requested action is in the policy's action list."""
+        if "*" in policy_actions:
+            return True
+        return action in policy_actions
+
+    @staticmethod
+    def _attrs_match(
+        policy_attrs: Dict[str, Any],
+        request_attrs: Dict[str, Any],
+    ) -> bool:
+        """Check if all policy attribute constraints are satisfied.
+
+        Every key in policy_attrs must either be "*" (match anything)
+        or exactly equal the corresponding value in request_attrs.
+        """
+        for key, expected in policy_attrs.items():
+            if expected == "*":
+                continue
+            if request_attrs.get(key) != expected:
+                return False
+        return True

package/src/compliance/abac_middleware.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""ABAC middleware for MCP tool integration.
+
+Provides a simple interface for MCP tools to check access before
+executing memory operations. Delegates to ABACEngine for policy
+evaluation.
+"""
+import threading
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .abac_engine import ABACEngine
+
+
+class ABACMiddleware:
+    """Thin middleware between MCP tools and ABAC policy engine.
+
+    Usage from MCP tools:
+        mw = ABACMiddleware(db_path)
+        result = mw.check_access(agent_id="agent_1", action="read",
+                                 resource={"access_level": "private"})
+        if not result["allowed"]:
+            return error_response(result["reason"])
+    """
+
+    def __init__(
+        self,
+        db_path: Optional[str] = None,
+        policy_path: Optional[str] = None,
+    ) -> None:
+        if db_path is None:
+            db_path = str(Path.home() / ".claude-memory" / "memory.db")
+        self._db_path = str(db_path)
+
+        if policy_path is None:
+            policy_path = str(
+                Path(self._db_path).parent / "abac_policies.json"
+            )
+
+        self._lock = threading.Lock()
+        self.denied_count = 0
+        self.allowed_count = 0
+
+        try:
+            self._engine = ABACEngine(config_path=policy_path)
+        except Exception:
+            self._engine = None
+
+    def check_access(
+        self,
+        agent_id: str,
+        action: str,
+        resource: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Check if an agent has access to perform an action.
+
+        Args:
+            agent_id: Identifier for the requesting agent.
+            action: The action being performed (read, write, delete).
+            resource: Resource attributes (access_level, project, tags).
+
+        Returns:
+            Dict with ``allowed`` (bool), ``reason`` (str), and
+            optionally ``policy_name``.
+        """
+        if self._engine is None:
+            return {
+                "allowed": True,
+                "reason": "ABAC engine unavailable — default allow",
+            }
+
+        subject = {"agent_id": agent_id}
+        result = self._engine.evaluate(
+            subject=subject,
+            resource=resource or {},
+            action=action,
+        )
+
+        with self._lock:
+            if result["allowed"]:
+                self.allowed_count += 1
+            else:
+                self.denied_count += 1
+
+        return result
+
+    def build_agent_context(
+        self,
+        agent_id: str = "user",
+        protocol: str = "mcp",
+    ) -> Dict[str, Any]:
+        """Build an agent context dict for passing to MemoryStoreV2.
+
+        Args:
+            agent_id: Agent identifier.
+            protocol: Access protocol (mcp, cli, dashboard).
+
+        Returns:
+            Dict suitable for ``MemoryStoreV2.search(agent_context=...)``.
+        """
+        return {
+            "agent_id": agent_id,
+            "protocol": protocol,
+        }
+
+    def get_status(self) -> Dict[str, Any]:
+        """Return middleware status."""
+        return {
+            "engine_available": self._engine is not None,
+            "policies_loaded": (
+                len(self._engine.policies) if self._engine else 0
+            ),
+            "allowed_count": self.allowed_count,
+            "denied_count": self.denied_count,
+        }

package/src/compliance/audit_db.py

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Audit database management with hash chain tamper detection.
+
+Provides a tamper-evident audit trail stored in a separate audit.db.
+Each entry's hash incorporates the previous entry's hash, forming a
+chain that can detect any modification to historical records.
+"""
+import hashlib
+import json
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+_GENESIS = "genesis"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit_events (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    event_type TEXT NOT NULL,
+    actor TEXT NOT NULL,
+    resource_id INTEGER,
+    details TEXT DEFAULT '{}',
+    prev_hash TEXT NOT NULL,
+    entry_hash TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+"""
+
+
+def _compute_hash(
+    event_type: str,
+    actor: str,
+    resource_id: Optional[int],
+    details: str,
+    prev_hash: str,
+    created_at: str,
+) -> str:
+    """Compute SHA-256 hash for an audit entry."""
+    payload = (
+        f"{event_type}{actor}{resource_id}{details}{prev_hash}{created_at}"
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+class AuditDB:
+    """Manages audit.db -- tamper-evident compliance audit trail.
+
+    The hash chain guarantees that any modification to a stored event
+    will be detected by verify_chain(). The first entry uses a fixed
+    genesis value as its previous hash.
+    """
+
+    def __init__(self, db_path: Optional[str] = None):
+        self._db_path = db_path
+        self._lock = threading.Lock()
+        if db_path:
+            self._init_db()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA foreign_keys=ON")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        conn = self._get_conn()
+        try:
+            conn.executescript(_SCHEMA)
+            conn.commit()
+        finally:
+            conn.close()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def log_event(
+        self,
+        event_type: str,
+        actor: str = "system",
+        resource_id: Optional[int] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """Append an event to the audit trail and return its row id."""
+        details_str = json.dumps(details or {}, sort_keys=True)
+        created_at = datetime.now(timezone.utc).isoformat()
+
+        with self._lock:
+            conn = self._get_conn()
+            try:
+                # Fetch the hash of the most recent entry (or genesis)
+                row = conn.execute(
+                    "SELECT entry_hash FROM audit_events "
+                    "ORDER BY id DESC LIMIT 1"
+                ).fetchone()
+                prev_hash = row["entry_hash"] if row else _GENESIS
+
+                entry_hash = _compute_hash(
+                    event_type, actor, resource_id,
+                    details_str, prev_hash, created_at,
+                )
+
+                cursor = conn.execute(
+                    "INSERT INTO audit_events "
+                    "(event_type, actor, resource_id, details, "
+                    " prev_hash, entry_hash, created_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        event_type, actor, resource_id,
+                        details_str, prev_hash, entry_hash, created_at,
+                    ),
+                )
+                conn.commit()
+                return cursor.lastrowid
+            finally:
+                conn.close()
+
+    def query_events(
+        self,
+        event_type: Optional[str] = None,
+        actor: Optional[str] = None,
+        resource_id: Optional[int] = None,
+        limit: int = 100,
+    ) -> List[Dict[str, Any]]:
+        """Query audit events with optional filters."""
+        clauses: List[str] = []
+        params: List[Any] = []
+
+        if event_type is not None:
+            clauses.append("event_type = ?")
+            params.append(event_type)
+        if actor is not None:
+            clauses.append("actor = ?")
+            params.append(actor)
+        if resource_id is not None:
+            clauses.append("resource_id = ?")
+            params.append(resource_id)
+
+        where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+        sql = (
+            f"SELECT id, event_type, actor, resource_id, details, "
+            f"prev_hash, entry_hash, created_at "
+            f"FROM audit_events {where} "
+            f"ORDER BY id DESC LIMIT ?"
+        )
+        params.append(limit)
+
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(sql, params).fetchall()
+            return [dict(r) for r in rows]
+        finally:
+            conn.close()
+
+    def verify_chain(self) -> Dict[str, Any]:
+        """Verify the integrity of the entire hash chain.
+
+        Returns a dict with:
+            valid            -- bool, True if chain is intact
+            entries_checked  -- int, number of entries verified
+            error            -- str or None, description of first failure
+        """
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(
+                "SELECT id, event_type, actor, resource_id, details, "
+                "prev_hash, entry_hash, created_at "
+                "FROM audit_events ORDER BY id"
+            ).fetchall()
+        finally:
+            conn.close()
+
+        if not rows:
+            return {"valid": True, "entries_checked": 0, "error": None}
+
+        expected_prev = _GENESIS
+        for row in rows:
+            row = dict(row)
+            # Check the prev_hash link
+            if row["prev_hash"] != expected_prev:
+                return {
+                    "valid": False,
+                    "entries_checked": row["id"],
+                    "error": f"prev_hash mismatch at entry {row['id']}",
+                }
+            # Recompute the entry hash
+            computed = _compute_hash(
+                row["event_type"],
+                row["actor"],
+                row["resource_id"],
+                row["details"],
+                row["prev_hash"],
+                row["created_at"],
+            )
+            if computed != row["entry_hash"]:
+                return {
+                    "valid": False,
+                    "entries_checked": row["id"],
+                    "error": f"entry_hash mismatch at entry {row['id']}",
+                }
+            expected_prev = row["entry_hash"]
+
+        return {
+            "valid": True,
+            "entries_checked": len(rows),
+            "error": None,
+        }

package/src/compliance/audit_logger.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""EventBus listener that writes all events to audit.db.
+
+Bridges the EventBus (real-time event emission) with AuditDB (tamper-evident
+audit trail). Every event that passes through the EventBus gets persisted
+into audit.db with full hash-chain integrity.
+
+Thread-safe: handle_event() runs on the emitter's thread and must be fast.
+Graceful: malformed events are logged defensively, never crash the caller.
+"""
+import json
+import logging
+import threading
+from typing import Any, Dict, Optional
+
+from .audit_db import AuditDB
+
+logger = logging.getLogger("superlocalmemory.compliance.audit_logger")
+
+
+class AuditLogger:
+    """Listens to EventBus events and writes them to audit.db.
+
+    Usage:
+        audit_logger = AuditLogger("/path/to/audit.db")
+        audit_logger.register_with_eventbus()  # auto-subscribe
+
+    Or manually:
+        event_bus.add_listener(audit_logger.handle_event)
+    """
+
+    def __init__(self, audit_db_path: str):
+        self._audit_db = AuditDB(audit_db_path)
+        self._lock = threading.Lock()
+        self._events_logged: int = 0
+        self._errors: int = 0
+        self._registered: bool = False
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def events_logged(self) -> int:
+        """Total number of events successfully written to audit.db."""
+        return self._events_logged
+
+    def handle_event(self, event: Dict[str, Any]) -> None:
+        """Process a single EventBus event and write it to audit.db.
+
+        Extracts event_type, source_agent (actor), memory_id (resource_id),
+        and payload (details) from the event dict, then delegates to
+        AuditDB.log_event().
+
+        This method MUST NOT raise — it runs on the emitter's thread.
+        Any failure is caught, logged, and counted in self._errors.
+
+        Args:
+            event: Dict emitted by EventBus. Expected keys:
+                   event_type, source_agent, memory_id, payload, timestamp.
+                   All keys are optional for graceful degradation.
+        """
+        try:
+            if not isinstance(event, dict):
+                logger.warning("AuditLogger received non-dict event: %s", type(event))
+                return
+
+            event_type = event.get("event_type", "unknown")
+            actor = event.get("source_agent", "system")
+            resource_id = event.get("memory_id")
+            payload = event.get("payload", {})
+
+            # Build details dict including any extra context
+            details = {}
+            if isinstance(payload, dict):
+                details.update(payload)
+            else:
+                details["raw_payload"] = str(payload)
+
+            # Include timestamp from event if present
+            ts = event.get("timestamp")
+            if ts:
+                details["event_timestamp"] = ts
+
+            with self._lock:
+                self._audit_db.log_event(
+                    event_type=event_type,
+                    actor=actor,
+                    resource_id=resource_id,
+                    details=details,
+                )
+                self._events_logged += 1
+
+        except Exception as exc:
+            self._errors += 1
+            logger.error(
+                "AuditLogger failed to log event: %s (event=%s)",
+                exc,
+                _safe_repr(event),
+            )
+
+    def register_with_eventbus(self) -> bool:
+        """Register this logger as an EventBus listener.
+
+        Attempts to find the EventBus singleton and subscribe
+        handle_event as a listener. Returns True on success,
+        False if EventBus is unavailable.
+
+        Graceful: never raises; returns False on any failure.
+        """
+        try:
+            from event_bus import EventBus as EB
+
+            bus = EB.get_instance()
+            bus.add_listener(self.handle_event)
+            self._registered = True
+            logger.info("AuditLogger registered with EventBus")
+            return True
+        except Exception as exc:
+            logger.warning("AuditLogger could not register with EventBus: %s", exc)
+            self._registered = False
+            return False
+
+    def get_status(self) -> Dict[str, Any]:
+        """Return diagnostic status of this audit logger.
+
+        Returns:
+            Dict with keys: events_logged, errors, registered.
+        """
+        return {
+            "events_logged": self._events_logged,
+            "errors": self._errors,
+            "registered": self._registered,
+        }
+
+
+# ------------------------------------------------------------------
+# Internal helpers
+# ------------------------------------------------------------------
+
+def _safe_repr(obj: Any, max_len: int = 200) -> str:
+    """Safe repr that truncates and never raises."""
+    try:
+        r = repr(obj)
+        return r[:max_len] + "..." if len(r) > max_len else r
+    except Exception:
+        return "<unrepresentable>"