superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/mcp/tools_v33.py

@@ -23,6 +23,8 @@ from mcp.types import ToolAnnotations
 
 logger = logging.getLogger(__name__)
 
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.infra.data_root import state_path
 from superlocalmemory.mcp.shared import authorize_mcp_mutation
 
@@ -75,8 +77,8 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # 1. forget — Ebbinghaus forgetting decay cycle
     # ------------------------------------------------------------------
     @server.tool(annotations=ToolAnnotations(destructiveHint=True))
+    @admits(OperationKind.FORGET)
     async def forget(
-        profile_id: str = "",
         dry_run: bool = True,
     ) -> dict:
         """Run Ebbinghaus forgetting decay cycle.
@@ -88,12 +90,11 @@ def register_v33_tools(server, get_engine: Callable) -> None:
         Run with dry_run=True first to preview changes.
 
         Args:
-            profile_id: Profile to process (default: active profile).
             dry_run: If True, compute stats but don't apply transitions.
         """
         try:
             engine = get_engine()
-            pid = profile_id or engine.profile_id
+            pid = engine.profile_id
 
             from superlocalmemory.math.ebbinghaus import EbbinghausCurve
             from superlocalmemory.learning.forgetting_scheduler import (
@@ -147,8 +148,8 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # 2. quantize — EAP embedding quantization cycle
     # ------------------------------------------------------------------
     @server.tool()
+    @admits(OperationKind.CONSOLIDATE)
     async def quantize(
-        profile_id: str = "",
         dry_run: bool = True,
     ) -> dict:
         """Run EAP quantization cycle.
@@ -160,12 +161,11 @@ def register_v33_tools(server, get_engine: Callable) -> None:
         Run with dry_run=True first to preview changes.
 
         Args:
-            profile_id: Profile to process (default: active profile).
             dry_run: If True, compute stats but don't apply changes.
         """
         try:
             engine = get_engine()
-            pid = profile_id or engine.profile_id
+            pid = engine.profile_id
 
             from superlocalmemory.math.ebbinghaus import EbbinghausCurve
             from superlocalmemory.math.polar_quant import PolarQuantEncoder
@@ -218,21 +218,17 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # 3. consolidate_cognitive — CCQ cognitive consolidation
     # ------------------------------------------------------------------
     @server.tool()
-    async def consolidate_cognitive(
-        profile_id: str = "",
-    ) -> dict:
+    @admits(OperationKind.CONSOLIDATE)
+    async def consolidate_cognitive() -> dict:
         """Run CCQ cognitive consolidation pipeline.
 
         Extracts patterns from cold/archive memories by clustering
         related facts, generating gist summaries, and compressing
         source embeddings. Like sleep-time memory consolidation.
-
-        Args:
-            profile_id: Profile to process (default: active profile).
         """
         try:
             engine = get_engine()
-            pid = profile_id or engine.profile_id
+            pid = engine.profile_id
 
             # v3.4.26: prefer the daemon's /consolidate/cognitive endpoint
             # so the heavy CognitiveConsolidator import stays out of the
@@ -292,21 +288,16 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # 4. get_soft_prompts — Retrieve active soft prompts
     # ------------------------------------------------------------------
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
-    async def get_soft_prompts(
-        profile_id: str = "",
-    ) -> dict:
+    async def get_soft_prompts() -> dict:
         """Get active soft prompts (auto-learned user patterns).
 
         Returns soft prompt templates generated from behavioral
         patterns. These are injected into conversation context to
         personalize AI responses.
-
-        Args:
-            profile_id: Profile to query (default: active profile).
         """
         try:
             engine = get_engine()
-            pid = profile_id or engine.profile_id
+            pid = engine.profile_id
 
             rows = engine._db.execute(
                 "SELECT prompt_id, category, content, confidence, "
@@ -346,6 +337,7 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # 5. reap_processes — Find and kill orphaned SLM processes
     # ------------------------------------------------------------------
     @server.tool()
+    @admits(OperationKind.CONSOLIDATE)
     async def reap_processes(
         dry_run: bool = True,
     ) -> dict:
@@ -394,22 +386,17 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # ------------------------------------------------------------------
     # 6. get_retention_stats — Memory retention zone distribution
     # ------------------------------------------------------------------
-    @server.tool()
-    async def get_retention_stats(
-        profile_id: str = "",
-    ) -> dict:
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def get_retention_stats() -> dict:
         """Get memory retention statistics (zone distribution, decay rates).
 
         Queries the fact_retention table for zone counts and average
         retention scores per zone. Shows how memories are distributed
         across the Ebbinghaus decay lifecycle.
-
-        Args:
-            profile_id: Profile to query (default: active profile).
         """
         try:
             engine = get_engine()
-            pid = profile_id or engine.profile_id
+            pid = engine.profile_id
 
             # Zone distribution counts
             rows = engine._db.execute(
@@ -451,19 +438,17 @@ def register_v33_tools(server, get_engine: Callable) -> None:
     # 7. run_maintenance — V3.3.12: Combined periodic maintenance cycle
     # ------------------------------------------------------------------
     @server.tool()
-    async def run_maintenance(profile_id: str = "") -> dict:
+    @admits(OperationKind.CONSOLIDATE)
+    async def run_maintenance() -> dict:
         """Run all periodic maintenance tasks in a single call.
 
         Combines Langevin dynamics stepping, Ebbinghaus forgetting decay,
         and behavioral pattern mining into one convenient maintenance cycle.
         Clients should call this periodically (e.g., at session end).
-
-        Args:
-            profile_id: Profile to maintain (default: active profile).
         """
         try:
             engine = get_engine()
-            pid = profile_id or engine.profile_id
+            pid = engine.profile_id
 
             # v3.4.26: prefer the daemon so ForgettingScheduler /
             # ConsolidationWorker / EbbinghausCurve don't load inside

package/src/superlocalmemory/mesh/broker.py

@@ -24,6 +24,10 @@ from typing import Any, Callable, TypeVar
 logger = logging.getLogger("superlocalmemory.mesh")
 import os as _os
 
+from .broker_security import (  # noqa: E501
+    apply_security_schema, check_cross_profile_sender, ensure_db_healthy, get_or_create_peer_key, reject_secret_state, scrub_message_content, seed_fencing_counter, _set_nonce_db_path, validate_lock_fence_query,  # noqa: E501
+)
+
 # Remote sync support (optional, try/except to avoid import issues)
 try:
     from .remote_sync import RemoteSyncClient
@@ -32,8 +36,6 @@ except ImportError:
 
 LOCAL_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
 
-
-
 MAX_MESSAGE_SIZE = 4096  # 4KB cap — mesh messages are notifications, not data dumps
 MESSAGE_TTL_HOURS = 48   # Offline messages expire after 48h
 LOCK_TTL_HOURS = 8       # M-02: file locks auto-expire so a crashed session can't deadlock a path
@@ -50,13 +52,7 @@ _WRITE_BUSY_TIMEOUT_MS = 2000
 
 
 class MeshBroker:
-    """Lightweight mesh broker for SLM's unified daemon.
-
-    Provides peer management, messaging, state, locks, and events.
-    v3.4.6: broadcast, project-based routing, offline message queue.
-    All methods are synchronous (called from FastAPI via run_in_executor
-    or directly for quick operations).
-    """
+    """Lightweight mesh broker — peer lifecycle, messaging, state, locks, events."""
 
     def __init__(self, db_path: str | Path):
         self._db_path = str(db_path)
@@ -72,11 +68,17 @@ class MeshBroker:
         self._remote_peers_lock = threading.RLock()
         self._peer_url: str | None = _os.environ.get("SLM_MESH_PEER_URL", "") or None
         self._sync_client: Any = None
+        self._degraded: bool = False
+        self._fencing_lock = threading.Lock()
+        self._fencing_counter: int = 0  # seeded below after schema is applied
         if self._is_remote and not self._shared_secret:
             raise RuntimeError(
                 "SLM_MESH_SHARED_SECRET is required when SLM_MESH_HOST is not localhost"
             )
-
+        self._ensure_db_healthy()
+        self._apply_schema_updates()
+        _set_nonce_db_path(self._db_path)  # SEC-3: wire SQLite nonce store for durability
+        self._fencing_counter = seed_fencing_counter(self._db_path)  # 3a-3: restart-safe fence
 
     # -- Remote / Multi-Machine support (v3.4.47) --
 
@@ -128,13 +130,31 @@ class MeshBroker:
         if self._sync_client:
             self._sync_client.stop()
 
+    # -- Startup safety helpers --
+
+    def _ensure_db_healthy(self) -> None:
+        """Quarantine a corrupt DB; set _degraded if recovery was needed."""
+        self._degraded = ensure_db_healthy(self._db_path)
+
+    def _apply_schema_updates(self) -> None:
+        """Apply idempotent schema additions (delegated to broker_security)."""
+        conn = self._conn()
+        try:
+            apply_security_schema(conn)
+        except sqlite3.Error as exc:
+            logger.debug("mesh schema update skipped: %s", exc)
+        finally:
+            conn.close()
+
+    def _next_fencing_token(self) -> int:
+        """Return the next monotonically-increasing fencing token."""
+        with self._fencing_lock:
+            self._fencing_counter += 1
+            return self._fencing_counter
+
     # -- Connection helper --
 
     def _conn(self) -> sqlite3.Connection:
-        # WAL is configured during database initialization and persists with the
-        # database. Reissuing journal_mode=WAL for every short-lived mesh
-        # connection is itself a schema-level write that can contend with the
-        # daemon. Mesh writes below use bounded whole-transaction retries.
         conn = sqlite3.connect(
             self._db_path,
             timeout=_WRITE_BUSY_TIMEOUT_MS / 1000,
@@ -148,17 +168,8 @@ class MeshBroker:
         message = str(exc).lower()
         return "database is locked" in message or "database is busy" in message
 
-    def _write_with_retry(
-        self,
-        operation: Callable[[sqlite3.Connection], _T],
-    ) -> _T:
-        """Run one idempotent mesh mutation with a bounded SQLite retry budget.
-
-        SQLite WAL lets reads continue while a write is in progress, but it
-        still permits a single writer. Retrying the entire short transaction on
-        a fresh connection avoids leaking a transient writer collision to an
-        agent heartbeat or mesh command.
-        """
+    def _write_with_retry(self, operation: Callable[[sqlite3.Connection], _T]) -> _T:
+        """Run one idempotent mesh mutation with a bounded SQLite retry budget."""
         last_error: sqlite3.OperationalError | None = None
         for attempt in range(_WRITE_RETRY_ATTEMPTS):
             conn = self._conn()
@@ -199,6 +210,7 @@ class MeshBroker:
             ).fetchone()
             if existing:
                 peer_id = existing["peer_id"]
+                is_new_peer = False
                 conn.execute(
                     "UPDATE mesh_peers SET summary=?, host=?, port=?, last_heartbeat=?, "
                     "status='active', project_path=?, agent_type=? "
@@ -208,6 +220,7 @@ class MeshBroker:
                 )
             else:
                 peer_id = str(uuid.uuid4())[:12]
+                is_new_peer = True
                 conn.execute(
                     "INSERT INTO mesh_peers (peer_id, session_id, summary, status, host, port, "
                     "registered_at, last_heartbeat, project_path, agent_type, profile_id) "
@@ -220,9 +233,17 @@ class MeshBroker:
             }, profile_id=profile_id)
             conn.commit()
 
+            # SEC-4 + P0: mint & RETURN the per-peer HMAC key ONLY on first
+            # registration. Re-registration MUST NOT re-export the key — otherwise
+            # a fleet-secret holder who learns a session_id (via /mesh/peers) could
+            # re-register as the victim and steal their peer_key (identity theft).
+            # The legitimate owner keeps the key it received at first registration.
             # v3.4.6: Deliver pending broadcast/project messages on registration
             pending = self._get_pending_for_peer(conn, peer_id, project_path, profile_id)
-            return {"peer_id": peer_id, "ok": True, "pending_messages": len(pending)}
+            result = {"peer_id": peer_id, "ok": True, "pending_messages": len(pending)}
+            if is_new_peer:
+                result["peer_key"] = get_or_create_peer_key(conn, peer_id, profile_id)
+            return result
 
         return self._write_with_retry(_register)
 
@@ -290,7 +311,8 @@ class MeshBroker:
 
     def send_message(self, from_peer: str, to_peer: str, content: str,
                      msg_type: str = "text", project_path: str = "",
-                     profile_id: str = "default") -> dict:
+                     profile_id: str = "default",
+                     operation_id: str | None = None) -> dict:
         # Guard: 4KB message size cap
         if len(content) > MAX_MESSAGE_SIZE:
             return {"ok": False, "error": f"message too large ({len(content)} bytes, max {MAX_MESSAGE_SIZE}). "
@@ -326,6 +348,20 @@ class MeshBroker:
             now = datetime.now(timezone.utc).isoformat()
             expires_at = self._compute_expires(now)
 
+            # Idempotency: return original result for a repeated operation_id.
+            if operation_id:
+                op = conn.execute(
+                    "SELECT message_id FROM mesh_sent_ops WHERE operation_id=?", (operation_id,)
+                ).fetchone()
+                if op:
+                    return {"ok": True, "id": op["message_id"],
+                            "idempotent": True, "operation_id": operation_id}
+
+            # Identity binding: cross-profile impersonation guard.
+            cross_profile_err = check_cross_profile_sender(conn, from_peer, profile_id)
+            if cross_profile_err is not None:
+                return cross_profile_err
+
             # Determine target type
             if _to_peer == "broadcast":
                 target_type = "broadcast"
@@ -361,18 +397,24 @@ class MeshBroker:
                          count - MAX_QUEUED_PER_TARGET + 1),
                     )
 
+            _content = scrub_message_content(content)  # 3a-2: redact before storage
             cursor = conn.execute(
                 "INSERT INTO mesh_messages (from_peer, to_peer, msg_type, content, read, "
                 "created_at, expires_at, target_type, project_path, profile_id) "
                 "VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?, ?)",
-                (from_peer, _to_peer, msg_type, content, now, expires_at,
+                (from_peer, _to_peer, msg_type, _content, now, expires_at,
                  target_type, _project_path, profile_id),
             )
-            self._log_event(conn, "message_sent", from_peer, {
+            msg_id = cursor.lastrowid
+
+            if operation_id:
+                conn.execute("INSERT OR IGNORE INTO mesh_sent_ops (operation_id, message_id, created_at) VALUES (?, ?, ?)", (operation_id, msg_id, now))
+
+            self._log_event(conn, "message_sent", from_peer or "system", {
                 "to": _to_peer, "target_type": target_type, "project": _project_path,
             }, profile_id=profile_id)
             conn.commit()
-            return {"ok": True, "id": cursor.lastrowid, "target_type": target_type,
+            return {"ok": True, "id": msg_id, "target_type": target_type,
                     "expires_at": expires_at}
 
         return self._write_with_retry(_send)
@@ -487,14 +529,36 @@ class MeshBroker:
             conn.close()
 
     def set_state(self, key: str, value: str, set_by: str,
-                  profile_id: str = "default") -> dict:
+                  profile_id: str = "default",
+                  expected_revision: int | None = None) -> dict:
+        """Set coordination state; rejects secrets and enforces optimistic revision."""
+        secret_err = reject_secret_state(key, value)
+        if secret_err is not None:
+            return secret_err
+
         def _set_state(conn: sqlite3.Connection) -> dict:
             now = datetime.now(timezone.utc).isoformat()
+            if expected_revision is not None:
+                row = conn.execute(
+                    "SELECT revision FROM mesh_state WHERE profile_id=? AND key=?",
+                    (profile_id, key),
+                ).fetchone()
+                current = row["revision"] if row else 0
+                if current != expected_revision:
+                    return {"ok": False,
+                            "error": f"revision mismatch: expected {expected_revision}, current {current}"}
             conn.execute(
-                "INSERT INTO mesh_state (profile_id, key, value, set_by, updated_at) "
-                "VALUES (?, ?, ?, ?, ?) "
-                "ON CONFLICT(profile_id, key) DO UPDATE SET value=excluded.value, "
-                "set_by=excluded.set_by, updated_at=excluded.updated_at",
+                "INSERT INTO mesh_state"
+                " (profile_id, key, value, set_by, updated_at, revision, origin_node)"
+                " VALUES (?, ?, ?, ?, ?, 1, '')"
+                " ON CONFLICT(profile_id, key) DO UPDATE SET value=excluded.value,"
+                " set_by=excluded.set_by, updated_at=excluded.updated_at,"
+                " revision=COALESCE(mesh_state.revision, 0) + 1,"
+                # 3c-1: a local write resets provenance to THIS node ('' = local).
+                # Without this, a local set_state after a remote merge would keep
+                # the remote's origin_node and re-export under the wrong identity
+                # → permanent same-(revision,node) divergence (audit P0-1).
+                " origin_node=''",
                 (profile_id, key, value, set_by, now),
             )
             conn.commit()
@@ -506,8 +570,9 @@ class MeshBroker:
         conn = self._conn()
         try:
             row = conn.execute(
-                "SELECT key, value, set_by, updated_at FROM mesh_state "
-                "WHERE profile_id=? AND key=?",
+                "SELECT key, value, set_by, updated_at, "
+                "COALESCE(revision, 0) AS revision "
+                "FROM mesh_state WHERE profile_id=? AND key=?",
                 (profile_id, key),
             ).fetchone()
             return dict(row) if row else None
@@ -522,12 +587,13 @@ class MeshBroker:
             conn = self._conn()
             try:
                 row = conn.execute(
-                    "SELECT locked_by, locked_at FROM mesh_locks "
-                    "WHERE profile_id=? AND file_path=?",
+                    "SELECT locked_by, locked_at, COALESCE(fencing_token, 0) AS fencing_token"
+                    " FROM mesh_locks WHERE profile_id=? AND file_path=?",
                     (profile_id, file_path),
                 ).fetchone()
                 if row:
-                    return {"locked": True, "by": row["locked_by"], "since": row["locked_at"]}
+                    return {"locked": True, "by": row["locked_by"],
+                            "since": row["locked_at"], "fencing_token": row["fencing_token"]}
                 return {"locked": False}
             finally:
                 conn.close()
@@ -557,15 +623,18 @@ class MeshBroker:
                 lock_expires = (
                     datetime.fromisoformat(now) + timedelta(hours=LOCK_TTL_HOURS)
                 ).isoformat()
+                token = self._next_fencing_token()
                 conn.execute(
-                    "INSERT INTO mesh_locks (profile_id, file_path, locked_by, locked_at, expires_at) "
-                    "VALUES (?, ?, ?, ?, ?) "
-                    "ON CONFLICT(profile_id, file_path) DO UPDATE SET locked_by=excluded.locked_by, "
-                    "locked_at=excluded.locked_at, expires_at=excluded.expires_at",
-                    (profile_id, file_path, locked_by, now, lock_expires),
+                    "INSERT INTO mesh_locks (profile_id, file_path, locked_by, locked_at,"
+                    " expires_at, fencing_token) VALUES (?, ?, ?, ?, ?, ?)"
+                    " ON CONFLICT(profile_id, file_path) DO UPDATE SET locked_by=excluded.locked_by,"
+                    " locked_at=excluded.locked_at, expires_at=excluded.expires_at,"
+                    " fencing_token=excluded.fencing_token",
+                    (profile_id, file_path, locked_by, now, lock_expires, token),
                 )
                 conn.commit()
-                return {"ok": True, "action": "acquired", "expires_at": lock_expires}
+                return {"ok": True, "action": "acquired",
+                        "expires_at": lock_expires, "fencing_token": token}
 
             elif action == "release":
                 # v3.6.12 (mesh-2): report whether we actually released. The
@@ -585,6 +654,15 @@ class MeshBroker:
 
         return self._write_with_retry(_lock_action)
 
+    def validate_lock_fence(self, file_path: str, fencing_token: int,
+                            profile_id: str = "default") -> dict:
+        """Reject a stale fencing token; allow the current one."""
+        conn = self._conn()
+        try:
+            return validate_lock_fence_query(conn, file_path, fencing_token, profile_id)
+        finally:
+            conn.close()
+
     # -- Helpers (v3.4.6) --
 
     @staticmethod