superlocalmemory 2.8.6 → 3.0.1

package/src/superlocalmemory/compliance/abac.py

@@ -0,0 +1,204 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Attribute-Based Access Control for memory operations.
+
+Evaluates policies: (agent_id, profile_id, action) -> allow/deny.
+Default: allow all (open access). Policies restrict specific agents.
+
+Actions: "read", "write", "delete", "admin".
+Policies are stored in-memory (loaded from DB on init).
+Simple deny-list approach: if a deny policy matches, access is blocked.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# Valid ABAC actions
+VALID_ACTIONS = frozenset({"read", "write", "delete", "admin"})
+
+_POLICY_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS abac_policies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id TEXT NOT NULL,
+    agent_id TEXT NOT NULL,
+    action TEXT NOT NULL,
+    deny INTEGER NOT NULL DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+"""
+
+
+class AccessDenied(PermissionError):
+    """Raised when ABAC denies an operation."""
+
+
+class ABACEngine:
+    """Attribute-Based Access Control for memory operations.
+
+    Evaluates policies: (agent_id, profile_id, action) -> allow/deny.
+    Default: allow all (open access). Deny policies restrict specific
+    agent+profile+action combinations.
+    """
+
+    def __init__(self, db: Optional[sqlite3.Connection] = None) -> None:
+        self._policies: list[dict[str, Any]] = []
+        self._db = db
+        if db is not None:
+            self._load_policies_from_db(db)
+
+    # ------------------------------------------------------------------
+    # Policy loading
+    # ------------------------------------------------------------------
+
+    def _load_policies_from_db(self, db: sqlite3.Connection) -> None:
+        """Load policies from the abac_policies table."""
+        try:
+            db.execute(_POLICY_TABLE_SQL)
+            db.commit()
+            rows = db.execute(
+                "SELECT profile_id, agent_id, action, deny "
+                "FROM abac_policies"
+            ).fetchall()
+            for row in rows:
+                self._policies.append({
+                    "profile_id": row[0],
+                    "agent_id": row[1],
+                    "action": row[2],
+                    "deny": bool(row[3]),
+                })
+            logger.info("Loaded %d ABAC policies from DB", len(self._policies))
+        except sqlite3.OperationalError as exc:
+            logger.warning("Failed to load ABAC policies: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Policy management
+    # ------------------------------------------------------------------
+
+    def add_policy(
+        self,
+        profile_id: str,
+        agent_id: str,
+        action: str,
+        deny: bool = True,
+    ) -> None:
+        """Add an access control policy.
+
+        Args:
+            profile_id: Profile this policy applies to.
+            agent_id: Agent this policy applies to.
+            action: The action to control (read/write/delete/admin).
+            deny: If True, this is a deny policy. Default True.
+        """
+        if action not in VALID_ACTIONS:
+            raise ValueError(f"Invalid action '{action}'. Must be one of {VALID_ACTIONS}")
+        policy = {
+            "profile_id": profile_id,
+            "agent_id": agent_id,
+            "action": action,
+            "deny": deny,
+        }
+        self._policies.append(policy)
+        self._persist_policy(policy)
+
+    def remove_policy(
+        self,
+        profile_id: str,
+        agent_id: str,
+        action: str,
+    ) -> None:
+        """Remove a policy matching profile_id + agent_id + action."""
+        self._policies = [
+            p for p in self._policies
+            if not (
+                p["profile_id"] == profile_id
+                and p["agent_id"] == agent_id
+                and p["action"] == action
+            )
+        ]
+        if self._db is not None:
+            try:
+                self._db.execute(
+                    "DELETE FROM abac_policies WHERE profile_id = ? AND agent_id = ? AND action = ?",
+                    (profile_id, agent_id, action),
+                )
+                self._db.commit()
+            except sqlite3.OperationalError:
+                pass
+
+    def _persist_policy(self, policy: dict[str, Any]) -> None:
+        """Write a policy to DB so it survives restart."""
+        if self._db is None:
+            return
+        try:
+            self._db.execute(
+                "INSERT INTO abac_policies (profile_id, agent_id, action, deny) "
+                "VALUES (?, ?, ?, ?)",
+                (policy["profile_id"], policy["agent_id"], policy["action"], int(policy["deny"])),
+            )
+            self._db.commit()
+        except sqlite3.OperationalError as exc:
+            logger.warning("Failed to persist ABAC policy: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Access evaluation
+    # ------------------------------------------------------------------
+
+    def check(self, agent_id: str, profile_id: str, action: str) -> bool:
+        """Evaluate access. Returns True if allowed, False if denied.
+
+        Default: allow if no deny policy matches the request.
+        Deny-first semantics: any matching deny policy blocks access.
+        """
+        for policy in self._policies:
+            if not policy.get("deny", True):
+                continue
+            if (
+                policy["agent_id"] == agent_id
+                and policy["profile_id"] == profile_id
+                and policy["action"] == action
+            ):
+                return False
+        return True
+
+    def check_or_raise(
+        self,
+        agent_id: str,
+        profile_id: str,
+        action: str,
+    ) -> None:
+        """Like check() but raises AccessDenied if denied."""
+        if not self.check(agent_id, profile_id, action):
+            raise AccessDenied(
+                f"Agent '{agent_id}' denied '{action}' "
+                f"on profile '{profile_id}'"
+            )
+
+    # ------------------------------------------------------------------
+    # Policy listing
+    # ------------------------------------------------------------------
+
+    def list_policies(
+        self,
+        profile_id: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        """List all policies, optionally filtered by profile.
+
+        Args:
+            profile_id: If provided, only return policies for this profile.
+
+        Returns:
+            List of policy dicts with keys: profile_id, agent_id, action, deny.
+        """
+        if profile_id is None:
+            return [dict(p) for p in self._policies]
+        return [
+            dict(p) for p in self._policies
+            if p["profile_id"] == profile_id
+        ]

package/src/superlocalmemory/compliance/audit.py

@@ -0,0 +1,314 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Tamper-proof hash-chain audit log for compliance.
+
+Every operation is logged with a SHA-256 hash that includes the previous
+entry's hash, creating a chain. Tampering with any entry breaks the chain
+and is detectable via verify_integrity().
+
+The audit chain uses its OWN sqlite3 connection (not shared DB manager)
+for independence — audit must survive even if the main DB is corrupted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+_GENESIS_HASH = "genesis"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit_chain (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    agent_id TEXT DEFAULT '',
+    profile_id TEXT DEFAULT '',
+    content_hash TEXT DEFAULT '',
+    prev_hash TEXT DEFAULT '',
+    event_hash TEXT NOT NULL,
+    metadata TEXT DEFAULT '{}'
+);
+"""
+
+
+def _compute_hash(
+    prev_hash: str,
+    operation: str,
+    agent_id: str,
+    profile_id: str,
+    content_hash: str,
+    timestamp: str,
+) -> str:
+    """Compute SHA-256 hash for an audit entry.
+
+    The hash incorporates: prev_hash + operation + agent_id +
+    profile_id + content_hash + timestamp.
+    """
+    payload = (
+        f"{prev_hash}{operation}{agent_id}"
+        f"{profile_id}{content_hash}{timestamp}"
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+class AuditChain:
+    """Tamper-proof hash-chain audit log for compliance.
+
+    Every operation is logged with a hash that includes the previous hash,
+    creating a chain. Tampering with any entry breaks the chain.
+
+    Uses its own SQLite connection for independence from main DB.
+    """
+
+    def __init__(self, db_path: Optional[Union[str, Path]] = None) -> None:
+        self._db_path = str(db_path) if db_path else ":memory:"
+        self._is_memory = self._db_path == ":memory:"
+        self._lock = threading.Lock()
+        # For in-memory DBs, keep a persistent connection (each connect()
+        # to ":memory:" creates a separate empty database).
+        self._persistent_conn: Optional[sqlite3.Connection] = None
+        if self._is_memory:
+            self._persistent_conn = self._make_conn()
+        self._init_db()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _make_conn_from_path(path: str) -> sqlite3.Connection:
+        """Create a configured SQLite connection."""
+        conn = sqlite3.connect(path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _make_conn(self) -> sqlite3.Connection:
+        """Create a new configured connection to the audit database."""
+        return self._make_conn_from_path(self._db_path)
+
+    def _get_conn(self) -> sqlite3.Connection:
+        """Get a connection to the audit database.
+
+        For in-memory databases, returns the persistent connection.
+        For file databases, creates a new connection each time.
+        """
+        if self._is_memory and self._persistent_conn is not None:
+            return self._persistent_conn
+        return self._make_conn()
+
+    def _release_conn(self, conn: sqlite3.Connection) -> None:
+        """Release a connection. Only closes file-based connections."""
+        if not self._is_memory:
+            conn.close()
+
+    def _init_db(self) -> None:
+        """Initialize the audit_chain table."""
+        conn = self._get_conn()
+        try:
+            conn.executescript(_SCHEMA)
+            conn.commit()
+        finally:
+            self._release_conn(conn)
+
+    def _get_last_hash(self, conn: sqlite3.Connection) -> str:
+        """Get the hash of the most recent entry, or genesis."""
+        row = conn.execute(
+            "SELECT event_hash FROM audit_chain "
+            "ORDER BY id DESC LIMIT 1"
+        ).fetchone()
+        return row["event_hash"] if row else _GENESIS_HASH
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def log(
+        self,
+        operation: str,
+        agent_id: str = "",
+        profile_id: str = "",
+        content_hash: str = "",
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """Log an audit event. Returns the event hash.
+
+        Args:
+            operation: Type of operation (store, recall, delete, etc.).
+            agent_id: ID of the agent performing the operation.
+            profile_id: ID of the profile being accessed.
+            content_hash: Hash of the content involved (optional).
+            metadata: Additional metadata dict (optional).
+
+        Returns:
+            The SHA-256 event hash for this entry.
+        """
+        ts = datetime.now(timezone.utc).isoformat()
+        metadata_str = json.dumps(metadata or {}, sort_keys=True)
+
+        with self._lock:
+            conn = self._get_conn()
+            try:
+                prev_hash = self._get_last_hash(conn)
+                event_hash = _compute_hash(
+                    prev_hash, operation, agent_id,
+                    profile_id, content_hash, ts,
+                )
+                conn.execute(
+                    "INSERT INTO audit_chain "
+                    "(timestamp, operation, agent_id, profile_id, "
+                    " content_hash, prev_hash, event_hash, metadata) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        ts, operation, agent_id, profile_id,
+                        content_hash, prev_hash, event_hash, metadata_str,
+                    ),
+                )
+                conn.commit()
+                return event_hash
+            finally:
+                self._release_conn(conn)
+
+    def query(
+        self,
+        profile_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        operation: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Query audit events with filters.
+
+        Args:
+            profile_id: Filter by profile ID.
+            agent_id: Filter by agent ID.
+            operation: Filter by operation type.
+            start_date: ISO date string for range start.
+            end_date: ISO date string for range end.
+            limit: Maximum number of events to return.
+
+        Returns:
+            List of event dicts ordered by id descending.
+        """
+        clauses: list[str] = []
+        params: list[Any] = []
+
+        if profile_id is not None:
+            clauses.append("profile_id = ?")
+            params.append(profile_id)
+        if agent_id is not None:
+            clauses.append("agent_id = ?")
+            params.append(agent_id)
+        if operation is not None:
+            clauses.append("operation = ?")
+            params.append(operation)
+        if start_date is not None:
+            clauses.append("timestamp >= ?")
+            params.append(start_date)
+        if end_date is not None:
+            clauses.append("timestamp <= ?")
+            params.append(end_date)
+
+        where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+        sql = (
+            f"SELECT id, timestamp, operation, agent_id, profile_id, "
+            f"content_hash, prev_hash, event_hash, metadata "
+            f"FROM audit_chain {where} "
+            f"ORDER BY id DESC LIMIT ?"
+        )
+        params.append(limit)
+
+        with self._lock:
+            conn = self._get_conn()
+            try:
+                rows = conn.execute(sql, params).fetchall()
+                return [dict(r) for r in rows]
+            finally:
+                self._release_conn(conn)
+
+    def verify_integrity(self) -> bool:
+        """Verify the entire hash chain. Returns True if chain is intact.
+
+        Walks every entry in order, recomputes each hash, and verifies
+        it matches the stored hash. Any mismatch means tampering.
+        """
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(
+                "SELECT id, timestamp, operation, agent_id, profile_id, "
+                "content_hash, prev_hash, event_hash "
+                "FROM audit_chain ORDER BY id"
+            ).fetchall()
+        finally:
+            self._release_conn(conn)
+
+        if not rows:
+            return True
+
+        expected_prev = _GENESIS_HASH
+        for row in rows:
+            row_dict = dict(row)
+
+            # Check the prev_hash link
+            if row_dict["prev_hash"] != expected_prev:
+                logger.warning(
+                    "Audit chain prev_hash mismatch at entry %d",
+                    row_dict["id"],
+                )
+                return False
+
+            # Recompute the entry hash
+            computed = _compute_hash(
+                row_dict["prev_hash"],
+                row_dict["operation"],
+                row_dict["agent_id"],
+                row_dict["profile_id"],
+                row_dict["content_hash"],
+                row_dict["timestamp"],
+            )
+            if computed != row_dict["event_hash"]:
+                logger.warning(
+                    "Audit chain event_hash mismatch at entry %d",
+                    row_dict["id"],
+                )
+                return False
+
+            expected_prev = row_dict["event_hash"]
+
+        return True
+
+    def get_stats(self) -> dict[str, int]:
+        """Get audit statistics (event counts by operation type).
+
+        Returns:
+            Dict mapping operation names to their counts, plus
+            a 'total' key with the chain length.
+        """
+        conn = self._get_conn()
+        try:
+            rows = conn.execute(
+                "SELECT operation, COUNT(*) AS cnt "
+                "FROM audit_chain GROUP BY operation"
+            ).fetchall()
+            stats: dict[str, int] = {}
+            total = 0
+            for row in rows:
+                count = row["cnt"]
+                stats[row["operation"]] = count
+                total += count
+            stats["total"] = total
+            return stats
+        finally:
+            self._release_conn(conn)

package/src/superlocalmemory/compliance/eu_ai_act.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3 — EU AI Act Compliance Verification.
+
+Verifies that each operating mode meets EU AI Act requirements.
+Mode A and B: FULL compliance (zero cloud, zero generative AI / local only).
+Mode C: NOT compliant (cloud LLM processing).
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from superlocalmemory.core.modes import get_capabilities
+from superlocalmemory.storage.models import Mode
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ComplianceReport:
+    """EU AI Act compliance assessment for a specific mode."""
+
+    mode: Mode
+    compliant: bool
+    risk_category: str          # "minimal" / "limited" / "high" / "unacceptable"
+    data_stays_local: bool
+    uses_generative_ai: bool
+    transparency_met: bool
+    human_oversight: bool
+    findings: list[str]
+    timestamp: str
+
+
+class EUAIActChecker:
+    """Verify EU AI Act compliance for each operating mode.
+
+    EU AI Act (effective Aug 2025) classifies AI systems by risk:
+    - Minimal risk: No obligations (most AI systems)
+    - Limited risk: Transparency obligations
+    - High risk: Strict requirements (biometric, critical infra)
+    - Unacceptable: Banned
+
+    Memory systems are generally "minimal risk" UNLESS they process
+    personal data via cloud AI services (then "limited risk" with
+    transparency obligations).
+    """
+
+    def check_compliance(self, mode: Mode) -> ComplianceReport:
+        """Generate compliance report for a mode."""
+        caps = get_capabilities(mode)
+        findings: list[str] = []
+
+        # Data locality
+        data_local = caps.data_stays_local
+        if not data_local:
+            findings.append(
+                "Data leaves device for cloud LLM processing. "
+                "Requires Data Processing Agreement (DPA) with provider."
+            )
+
+        # Generative AI usage
+        uses_gen_ai = caps.llm_fact_extraction or caps.llm_answer_generation
+        local_gen_ai = uses_gen_ai and data_local
+
+        if uses_gen_ai and not data_local:
+            findings.append(
+                "Uses cloud generative AI. EU AI Act Art. 52 requires "
+                "transparency: users must be informed AI generates content."
+            )
+
+        # Transparency
+        transparency = True  # We always disclose AI usage
+        findings.append("Transparency requirement MET: system identifies as AI-assisted.")
+
+        # Human oversight
+        human_oversight = True  # User controls all memory operations
+        findings.append("Human oversight MET: user controls store/recall/delete.")
+
+        # Risk classification
+        if not uses_gen_ai:
+            risk = "minimal"
+            findings.append("Minimal risk: no generative AI, local processing only.")
+        elif local_gen_ai:
+            risk = "minimal"
+            findings.append("Minimal risk: generative AI is local-only (Ollama).")
+        else:
+            risk = "limited"
+            findings.append(
+                "Limited risk: cloud generative AI requires transparency "
+                "disclosure and DPA with cloud provider."
+            )
+
+        compliant = caps.eu_ai_act_compliant
+        if not compliant:
+            findings.append(
+                "Mode C is NOT EU AI Act compliant by design. "
+                "Use Mode A or B for EU-compliant deployments."
+            )
+
+        return ComplianceReport(
+            mode=mode,
+            compliant=compliant,
+            risk_category=risk,
+            data_stays_local=data_local,
+            uses_generative_ai=uses_gen_ai,
+            transparency_met=transparency,
+            human_oversight=human_oversight,
+            findings=findings,
+            timestamp=datetime.now(UTC).isoformat(),
+        )
+
+    def verify_all_modes(self) -> dict[str, ComplianceReport]:
+        """Generate compliance reports for all three modes."""
+        return {
+            mode.value: self.check_compliance(mode)
+            for mode in Mode
+        }
+
+    def get_compliant_modes(self) -> list[Mode]:
+        """Return list of EU AI Act compliant modes."""
+        return [
+            mode for mode in Mode
+            if get_capabilities(mode).eu_ai_act_compliant
+        ]