superlocalmemory 3.8.13 → 4.0.0

package/src/superlocalmemory/server/routes/memories.py

@@ -114,6 +114,48 @@ def _mutation_runtime_or_missing_fact(
     raise HTTPException(503, detail="canonical mutation writer is not ready; retry shortly")
 
 
+def _admit_http_mutation(request: Request, operation: str) -> None:
+    """Route a memory HTTP mutation through OperationPolicyRegistry.evaluate().
+
+    Called from _authorize_memory_mutation after RBAC passes. Raises HTTP 403
+    if the policy registry denies the actor. Maps "delete" → FORGET,
+    "update" → CORRECT. Uses the server-derived principal and roles.
+    """
+    from fastapi import HTTPException as _HTTPException
+
+    from superlocalmemory.core.actor_context import Transport
+    from superlocalmemory.core.admission import AdmissionDenied, admit, resolve_actor
+    from superlocalmemory.core.operation_request import OperationKind
+    from superlocalmemory.server.rbac_enforce import (
+        resolve_actor_roles,
+        resolve_principal,
+    )
+
+    deployment = getattr(request.app.state, "deployment", None)
+    is_enterprise = bool(deployment and deployment.is_enterprise)
+    tier = "enterprise" if is_enterprise else "personal"
+    mode = "company" if is_enterprise else "local"
+
+    principal_info = resolve_principal(request)
+    principal = str(principal_info.get("user_id") or "")
+    actor_roles = resolve_actor_roles(request)
+    actor = resolve_actor(
+        Transport.HTTP,
+        tier=tier,
+        mode=mode,
+        principal=principal,
+        roles=actor_roles,
+    )
+    kind = OperationKind.FORGET if operation == "delete" else OperationKind.CORRECT
+    try:
+        admit(kind, actor, mode=mode)
+    except AdmissionDenied as exc:
+        raise _HTTPException(
+            status_code=403,
+            detail=f"Operation denied: {exc.decision.reason}",
+        ) from exc
+
+
 def _authorize_memory_mutation(
     request: Request,
     operation: str,
@@ -131,14 +173,15 @@ def _authorize_memory_mutation(
         actor_kind="dashboard",
     )
     # RBAC (C3): on top of machine auth, enforce the caller's role on the active
-    # profile. delete → DELETE; every other mutation → WRITE. A viewer (or an
-    # owner in require_login mode) is rejected here; owner/admin/member pass.
+    # profile. delete → DELETE; every other mutation → WRITE.
     from superlocalmemory.access.rbac import Permission as _Perm
     from superlocalmemory.server.rbac_enforce import require_permission as _rbac_require
     _rbac_require(
         request,
         _Perm.DELETE if operation == "delete" else _Perm.WRITE,
     )
+    # Phase 1: admission gateway — policy registry decision for this route.
+    _admit_http_mutation(request, operation)
     engine = _get_engine(request)
     if engine is None:
         raise HTTPException(503, detail="Engine not initialized")
@@ -1045,8 +1088,18 @@ async def delete_memory(request: Request, fact_id: str):
             idempotency_key=_mutation_idempotency_key(request),
         )
         if not result.get("ok"):
+            if result.get("retryable"):
+                raise HTTPException(
+                    status_code=503,
+                    detail="Erasure incomplete (projection residue); retry shortly",
+                )
             raise HTTPException(status_code=404, detail="Memory not found")
-        return {"success": True, "deleted": fact_id}
+        return {
+            "success": True,
+            "deleted": fact_id,
+            "erasure_verified": bool(result.get("erasure_verified", False)),
+            "erasure_state": result.get("erasure_state", "FAILED"),
+        }
     except HTTPException:
         raise
     except Exception as exc:

package/src/superlocalmemory/server/routes/mesh.py

@@ -112,7 +112,11 @@ def _get_broker(request: Request):
             )
             if not presented or not hmac.compare_digest(presented, secret):
                 raise HTTPException(401, detail="invalid or missing credential")
-            return broker
+        # TEST-1/SEC: When a fleet secret is configured, it is the primary auth
+        # mechanism. Loopback callers are trusted by transport and need no further
+        # proof. Only fall through to require_write_actor when NO secret is configured
+        # (install-token-only, single-machine mode).
+        return broker
 
     # Loopback is a transport property, not an identity.  Every mesh read and
     # write must prove the install/API/process capability because peer inboxes,
@@ -346,6 +350,83 @@ def send(req: SendRequest, request: Request):
     if not to_target:
         raise HTTPException(400, detail="'to' or 'to_peer' required")
     profile = _active_profile()
+
+    # 3a-1 + 3a-2: Apply signature verification and admission gate for non-loopback.
+    client_host = request.client.host if request.client else "127.0.0.1"
+    from superlocalmemory.server.loopback import is_loopback as _is_loopback_host
+    _is_lb = _is_loopback_host(client_host)
+
+    if not _is_lb:
+        from superlocalmemory.mesh.broker_security import (
+            check_mesh_message_signature,
+            is_strict_identity,
+        )
+        config = getattr(request.app.state, "config", None)
+        strict = is_strict_identity(config)
+        fleet_secret = getattr(broker, "_shared_secret", None)
+
+        # SEC-4 (hardened): identity resolution per mode.
+        #  - COMPAT (default): fleet secret verifies (or unsigned legacy accepted).
+        #  - STRICT: the sender MUST be a registered peer with its own per-peer key.
+        #    There is NO fleet-secret fallback in strict mode — unregistered
+        #    from_peer, a NULL peer_key, or a DB error all FAIL CLOSED. (The old
+        #    fleet fallback was an impersonation escape hatch: any fleet-secret
+        #    holder could claim an unregistered/legacy from_peer.)
+        verify_secret = fleet_secret
+        if strict:
+            if not req.from_peer:
+                raise HTTPException(401, detail="strict identity: from_peer required")
+            import sqlite3 as _sqlite3
+            try:
+                _conn = _sqlite3.connect(broker._db_path, timeout=3)
+                _conn.row_factory = _sqlite3.Row
+                _row = _conn.execute(
+                    "SELECT peer_key FROM mesh_peers WHERE peer_id=? LIMIT 1",
+                    (req.from_peer,),
+                ).fetchone()
+                _conn.close()
+            except _sqlite3.Error:
+                raise HTTPException(503, detail="strict identity: peer key lookup failed")
+            if not _row or not _row["peer_key"]:
+                raise HTTPException(
+                    401,
+                    detail="strict identity: from_peer is not a registered peer with a per-peer key",
+                )
+            verify_secret = str(_row["peer_key"])
+
+        sig_err = check_mesh_message_signature(
+            verify_secret,
+            req.from_peer,
+            to_target,
+            req.content,
+            request.headers.get("x-mesh-sig"),
+            request.headers.get("x-mesh-nonce"),
+            request.headers.get("x-mesh-ts"),
+            is_loopback=False,
+            strict=strict,
+        )
+        if sig_err is not None:
+            raise HTTPException(401, detail=sig_err.get("error", "signature error"))
+
+        # Admission gate parity (closes Wave-1 P1 bypass for inbound remote send).
+        try:
+            from superlocalmemory.core.admission import (
+                AdmissionDenied,
+                admit,
+                resolve_actor,
+            )
+            from superlocalmemory.core.actor_context import Transport
+            from superlocalmemory.core.operation_request import OperationKind
+        except ImportError:
+            AdmissionDenied = None  # type: ignore[assignment,misc]
+
+        if AdmissionDenied is not None:
+            try:
+                actor = resolve_actor(Transport.HTTP, client_host=client_host)
+                admit(OperationKind.MESH_SEND, actor)
+            except AdmissionDenied as exc:
+                raise HTTPException(403, detail=str(exc))
+
     # This sync FastAPI route already runs in the worker thread pool, so the
     # broker's SQLite retries and optional remote HTTP delivery cannot block
     # the daemon event loop.

package/src/superlocalmemory/server/routes/mesh_lock.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
+
+"""SLM Mesh — lock-delta HTTP route (3c-2).
+
+Exposes ``GET /mesh/lock/delta`` so remote peers can fetch this node's
+live advisory locks for convergence via ``LockCoordinator.resolve()``.
+
+Auth and broker resolution mirror ``routes/mesh.py``.
+Do NOT mount this router directly — the delivery lead wires it via
+``app.include_router(mesh_lock_routes.router)``.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+
+from superlocalmemory.mesh.lock_protocol import LockCoordinator
+from superlocalmemory.mesh.node_identity import get_node_id
+from superlocalmemory.server.routes.mesh import _get_broker
+from superlocalmemory.server.routes.helpers import get_active_profile
+
+router = APIRouter(prefix="/mesh/lock", tags=["mesh-lock"])
+
+
+@router.get("/delta")
+def lock_delta(
+    profile: str = "",
+    request: Request = None,  # type: ignore[assignment]
+) -> dict:
+    """Return this node's live advisory locks for a given tenant profile.
+
+    The response is designed for consumption by a remote peer's
+    ``LockCoordinator.resolve()`` call: it includes the raw lock records
+    plus the local ``node_id`` so the remote can apply the total-order
+    ``(fencing_token, node_id)`` comparison without a separate handshake.
+
+    Query params:
+        profile: Tenant profile id.  Falls back to the active profile
+                 from the request context var when omitted or blank.
+
+    Returns:
+        ``{"locks": [...], "node_id": "<hex>"}``
+        ``locks`` is the output of ``LockCoordinator.local_lock_delta()``.
+    """
+    broker = _get_broker(request)
+    profile_id: str = profile.strip() or get_active_profile()
+    coordinator = LockCoordinator(broker)
+    locks = coordinator.local_lock_delta(profile_id)
+    node_id = get_node_id(broker._db_path)
+    return {"locks": locks, "node_id": node_id}

package/src/superlocalmemory/server/routes/mesh_state.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
+
+"""SLM Mesh — state-sync delta endpoint (3c-1).
+
+Exposes a single GET route that returns the local ``mesh_state`` rows whose
+revision exceeds ``since``, suitable for pull-based LWW convergence.
+
+Mounted by the delivery lead (unified_daemon.py) via ``include_router``.
+Auth, broker access, and profile resolution all mirror ``routes/mesh.py``
+exactly — no new patterns are introduced.
+
+Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+
+from superlocalmemory.mesh.state_sync import StateSyncer
+
+# Re-use auth + broker helpers verbatim from the main mesh module so that
+# security properties (shared-secret, loopback trust, write-identity) apply
+# identically to this new endpoint.
+from superlocalmemory.server.routes.mesh import _active_profile, _get_broker
+
+router = APIRouter(prefix="/mesh", tags=["mesh-state-sync"])
+
+
+@router.get("/state/delta")
+def state_delta(
+    request: Request,
+    profile: str = "",
+    since: int = 0,
+) -> dict:
+    """Return local mesh_state rows with revision > ``since`` for LWW sync.
+
+    Query parameters
+    ----------------
+    profile : str, optional
+        Tenant profile id.  Defaults to the currently active profile when
+        omitted or empty.
+    since : int, optional
+        Only rows whose ``revision`` strictly exceeds this value are returned.
+        Pass ``0`` (default) to retrieve all rows.
+
+    Response
+    --------
+    ``{"entries": [...], "node_id": "<local_node_id>"}``
+
+    Each entry carries ``{key, value, set_by, updated_at, revision, node_id}``
+    where ``node_id`` is the effective origin node (resolved from
+    ``origin_node`` column; BC rows with ``origin_node=''`` resolve to the
+    local node's id).
+    """
+    broker = _get_broker(request)
+    resolved_profile = profile if profile else _active_profile()
+    syncer = StateSyncer(broker)
+    return {
+        "entries": syncer.local_delta(resolved_profile, since),
+        "node_id": syncer._node_id,
+    }

package/src/superlocalmemory/server/routes/v3_api.py

@@ -134,7 +134,10 @@ async def dashboard(request: Request):
             except Exception:
                 pass
 
-        return {
+        from superlocalmemory.core.modes import dashboard_mode_fields
+
+        # Mode record is the single source of truth for locality claims (F-03).
+        payload = {
             "mode": config.mode.value,
             "mode_name": {"a": "Local Guardian", "b": "Smart Local", "c": "Full Power"}.get(config.mode.value, "Unknown"),
             "provider": config.llm.provider or "none",
@@ -145,6 +148,8 @@ async def dashboard(request: Request):
             "base_dir": str(config.base_dir),
             "version": SLM_VERSION,
         }
+        payload.update(dashboard_mode_fields(config.mode))
+        return payload
     except Exception as e:
         return _internal_error()
 
@@ -589,41 +594,45 @@ def _validate_provider_url(url: str, client_host: str) -> str | None:
     are allowed for it. A NON-loopback caller may not make the server fetch
     private/loopback/link-local/reserved targets — that is the SSRF abuse.
     """
-    from urllib.parse import urlparse
-    import ipaddress
-    import socket
-    p = urlparse(url)
-    if p.scheme not in ("http", "https"):
-        return "Only http/https endpoints are supported"
-    host = p.hostname or ""
-    if host.lower() in ("169.254.169.254", "metadata.google.internal", "metadata"):
-        return "Cloud metadata endpoints are not allowed"
+    from superlocalmemory.server.egress_policy import (
+        EgressActor,
+        EgressVerdict,
+        validate_egress_url,
+    )
     from superlocalmemory.server.loopback import is_loopback as _is_loopback_host
 
-    if _is_loopback_host(client_host):
-        return None  # local dashboard may target its own local/LAN endpoints
+    is_local = _is_loopback_host(client_host)
     # SLM_REMOTE residue (#40): an allowlisted LAN dashboard is trusted exactly
     # like the loopback one and may probe its own LAN LLM endpoint. This does
     # NOT relax the SSRF guard for arbitrary remote callers —
     # is_lan_client_allowed is False unless remote mode is ON *and* the client
     # IP is in SLM_MCP_ALLOWED_HOSTS.
+    is_lan = False
     try:
         from superlocalmemory.core.remote_mode import is_lan_client_allowed
-        if is_lan_client_allowed(client_host):
-            return None
+        is_lan = bool(is_lan_client_allowed(client_host))
     except Exception:  # pragma: no cover — defensive, never weaken on import error
-        pass
-    try:
-        ip = ipaddress.ip_address(host)
-    except ValueError:
-        try:
-            ip = ipaddress.ip_address(socket.gethostbyname(host))
-        except Exception:
-            return None  # unresolvable — let the HTTP client fail normally
-    if (ip.is_private or ip.is_loopback or ip.is_link_local
-            or ip.is_reserved or ip.is_multicast):
-        return "Internal/private endpoints are not allowed from a remote client"
-    return None
+        is_lan = False
+
+    result = validate_egress_url(
+        url, EgressActor(is_local=is_local, is_lan=is_lan)
+    )
+
+    if result.verdict is EgressVerdict.ALLOW:
+        return None
+    if result.verdict is EgressVerdict.DENY_SCHEME:
+        return "Only http/https endpoints are supported"
+    if result.verdict is EgressVerdict.DENY_METADATA:
+        return "Cloud metadata endpoints are not allowed"
+    if result.verdict in (
+        EgressVerdict.DENY_CREDENTIALS,
+        EgressVerdict.DENY_FRAGMENT,
+    ):
+        return "Endpoint URL must not embed credentials or fragments"
+    if result.verdict is EgressVerdict.DENY_DNS_FAILURE:
+        return "Endpoint host could not be resolved"
+    # DENY_PRIVATE / DENY_MIXED_DNS / DENY_HOST
+    return "Internal/private endpoints are not allowed from a remote client"
 
 
 @router.post("/provider/test")
@@ -820,6 +829,17 @@ async def recall_trace(request: Request):
         query = body.get("query", "")
         limit = body.get("limit", 10)
         window = body.get("window", "") or ""
+        as_of_raw = (body.get("as_of", "") or "").strip()
+
+        # Normalize as_of at HTTP boundary. Invalid → 400.
+        _as_of: str | None = None
+        if as_of_raw:
+            from superlocalmemory.retrieval.temporal_utils import normalize_as_of
+            _as_of = normalize_as_of(as_of_raw)
+            if _as_of is None:
+                return JSONResponse(
+                    {"error": "invalid_as_of", "raw": as_of_raw}, status_code=400
+                )
 
         # Use daemon engine — already loaded, shares warm page cache.
         # run_in_executor keeps event loop alive so browser doesn't abort.
@@ -832,7 +852,10 @@ async def recall_trace(request: Request):
         t0 = _time.monotonic()
         response = await loop.run_in_executor(
             None,
-            lambda: engine.recall(query, limit=limit, fast=False, window=window or None),
+            lambda: engine.recall(
+                query, limit=limit, fast=False,
+                window=window or None, as_of=_as_of,
+            ),
         )
         elapsed_ms = round((_time.monotonic() - t0) * 1000, 1)
 

package/src/superlocalmemory/server/routes/ws.py

@@ -42,9 +42,95 @@ class ConnectionManager:
 manager = ConnectionManager()
 
 
+def _ws_origin_allowed(websocket: WebSocket) -> bool:
+    """Return True when the WebSocket upgrade Origin is permitted.
+
+    Non-browser clients (CLI, MCP tools) carry no Origin header and are
+    always allowed.  Browser-originated connections must come from a
+    loopback address or a host in the configured remote allowlist.
+    """
+    origin = websocket.headers.get("origin", "")
+    if not origin:
+        return True  # non-browser caller (CLI/MCP) — no origin to validate
+
+    try:
+        from superlocalmemory.server.origin import origin_is_loopback
+        if origin_is_loopback(origin):
+            return True
+    except Exception:
+        # If the helper is unavailable, fall through to the remote check.
+        if "127.0.0.1" in origin or "::1" in origin or "localhost" in origin:
+            return True
+
+    try:
+        from superlocalmemory.core.remote_mode import is_remote_origin_allowed
+        if is_remote_origin_allowed(origin):
+            return True
+    except Exception:
+        pass
+
+    return False
+
+
+def _ws_rbac_allowed(websocket: WebSocket, app_state) -> bool:
+    """Return True when the caller is authorised to open a WS connection.
+
+    Mirrors _rbac_read_gate in unified_daemon.py: no-op in single-operator
+    installations (zero RBAC users), requires a valid session in company /
+    require_login mode.  Fails closed on RBAC errors.
+    """
+    rbac = getattr(app_state, "rbac", None)
+    if rbac is None:
+        return True  # single-operator mode — no auth layer active
+
+    try:
+        active = rbac.user_count() > 0
+    except Exception:
+        logger.warning("ws: RBAC state unavailable — rejecting handshake (fail closed)")
+        return False  # fail closed
+
+    if not active:
+        return True  # no users registered — single-operator mode
+
+    token = (
+        websocket.headers.get("x-slm-user-session", "")
+        or websocket.cookies.get("slm_session", "")
+    )
+    user = rbac.resolve_session(token) if token else None
+
+    if user is None:
+        if rbac.require_login():
+            return False  # login required and no valid session
+        return True  # personal / owner mode — no session needed
+
+    try:
+        from superlocalmemory.access.rbac import Permission
+        from superlocalmemory.server.routes.helpers import get_active_profile
+        return rbac.has_permission(user["user_id"], get_active_profile(), Permission.READ)
+    except Exception:
+        logger.warning("ws: permission check failed — rejecting handshake (fail closed)")
+        return False
+
+
 @router.websocket("/ws/updates")
 async def websocket_updates(websocket: WebSocket):
     """WebSocket endpoint for real-time memory updates."""
+    app_state = getattr(websocket, "app", None)
+    app_state = getattr(app_state, "state", None)
+
+    # --- Reject disallowed origins before accepting the handshake. ---
+    if not _ws_origin_allowed(websocket):
+        logger.info("ws: rejected handshake from disallowed origin %s",
+                    websocket.headers.get("origin", ""))
+        await websocket.close(code=1008)  # 1008 = Policy Violation
+        return
+
+    # --- Reject unauthenticated callers when login is required. ---
+    if not _ws_rbac_allowed(websocket, app_state):
+        logger.info("ws: rejected unauthenticated or unauthorised handshake")
+        await websocket.close(code=4001)  # 4001 = custom: Unauthorized
+        return
+
     await manager.connect(websocket)
 
     try:

package/src/superlocalmemory/server/ui.py

@@ -72,8 +72,8 @@ UI_DIR = Path(__file__).resolve().parent.parent / "ui"
 def create_app() -> FastAPI:
     """Create and configure the FastAPI application."""
     application = FastAPI(
-        title="SuperLocalMemory V3 UI Server",
-        description="Memory Dashboard with V3 Engine, Trust, Learning, and Compliance",
+        title="SuperLocalMemory V4 UI Server",
+        description="Memory Dashboard with V4 Engine, Trust, Learning, and Compliance",
         version=SLM_VERSION,
         docs_url="/api/docs",
         redoc_url="/api/redoc",
@@ -224,9 +224,9 @@ def create_app() -> FastAPI:
         if not index_path.exists():
             return (
                 "<!DOCTYPE html><html><head>"
-                "<title>SuperLocalMemory V3</title></head>"
+                "<title>SuperLocalMemory V4</title></head>"
                 "<body style='font-family:Arial;padding:40px'>"
-                "<h1>SuperLocalMemory V3 UI Server Running</h1>"
+                "<h1>SuperLocalMemory V4 UI Server Running</h1>"
                 "<p>UI not found. Check ui/index.html</p>"
                 "<p><a href='/api/docs'>API Documentation</a></p>"
                 "</body></html>"
@@ -290,7 +290,7 @@ if __name__ == "__main__":
     import argparse
     import socket
 
-    parser = argparse.ArgumentParser(description="SuperLocalMemory V3 - Web Dashboard")
+    parser = argparse.ArgumentParser(description="SuperLocalMemory V4 - Web Dashboard")
     parser.add_argument("--port", type=int, default=8765, help="Port (default 8765)")
     parser.add_argument("--profile", type=str, default=None, help="Memory profile")
     args = parser.parse_args()
@@ -310,7 +310,7 @@ if __name__ == "__main__":
         print(f"\n  Port {args.port} in use -- using {ui_port} instead\n")
 
     print("=" * 70)
-    print("  SuperLocalMemory V3 - Web Dashboard")
+    print("  SuperLocalMemory V4 - Web Dashboard")
     print("  Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar")
     print("=" * 70)
     print(f"  Database:  {DB_PATH}")