superlocalmemory 3.6.22 → 3.7.0

package/src/superlocalmemory/infra/daemon_identity.py

@@ -0,0 +1,248 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Namespace-aware identity for the local SuperLocalMemory daemon.
+
+PID files and listening ports are liveness hints, not ownership credentials.
+This module binds a daemon process to one canonical SLM data root and one
+random process instance through a private, atomically written descriptor.
+"""
+
+from __future__ import annotations
+
+import getpass
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+import uuid
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+from superlocalmemory.infra.data_root import canonical_data_root
+
+DAEMON_DESCRIPTOR_SCHEMA = 1
+DAEMON_PROTOCOL = 1
+DAEMON_SERVICE = "superlocalmemory-daemon"
+_NAMESPACE_DOMAIN = b"superlocalmemory-daemon-namespace-v1\0"
+_CAPABILITY_DOMAIN = b"superlocalmemory-daemon-capability-v1\0"
+
+
+def _canonical_path(value: str | Path) -> Path:
+    expanded = Path(value).expanduser().resolve(strict=False)
+    return Path(os.path.normcase(str(expanded)))
+
+
+def namespace_id_for(data_root: str | Path) -> str:
+    """Return a stable, non-reversible identifier for a canonical data root."""
+    canonical = _canonical_path(data_root)
+    normalized = os.path.normcase(str(canonical)).encode("utf-8")
+    return hashlib.sha256(_NAMESPACE_DOMAIN + normalized).hexdigest()
+
+
+def capability_fingerprint(capability: str) -> str:
+    """Hash the private local capability before exposing it through health."""
+    return hashlib.sha256(_CAPABILITY_DOMAIN + capability.encode("utf-8")).hexdigest()
+
+
+def owner_id() -> str:
+    """Cross-platform local owner identifier used for accidental isolation."""
+    getuid = getattr(os, "getuid", None)
+    if getuid is not None:
+        return f"uid:{getuid()}"
+    return f"user:{getpass.getuser()}"
+
+
+def process_create_time_for(pid: int) -> float:
+    """Return OS process creation time, falling back only when unavailable."""
+    try:
+        import psutil
+
+        return float(psutil.Process(pid).create_time())
+    except Exception:
+        return time.time()
+
+
+@dataclass(frozen=True)
+class DaemonDescriptor:
+    schema: int
+    service: str
+    daemon_protocol: int
+    namespace_id: str
+    instance_id: str
+    capability: str
+    capability_fingerprint: str
+    owner_id: str
+    data_root: str
+    pid: int
+    process_create_time: float
+    port: int
+    state: str
+    version: str
+    started_at: float
+
+    def public_health_fields(self) -> dict[str, Any]:
+        """Identity fields safe to expose on the loopback health endpoint."""
+        return {
+            "service": self.service,
+            "daemon_protocol": self.daemon_protocol,
+            "namespace_id": self.namespace_id,
+            "instance_id": self.instance_id,
+            "capability_fingerprint": self.capability_fingerprint,
+            "owner_id": self.owner_id,
+            "pid": self.pid,
+            "port": self.port,
+            "state": self.state,
+            "version": self.version,
+        }
+
+
+def build_descriptor(
+    *,
+    data_root: str | Path | None = None,
+    port: int,
+    version: str,
+    pid: int | None = None,
+    process_create_time: float | None = None,
+    instance_id: str | None = None,
+    capability: str | None = None,
+    state: str = "starting",
+    started_at: float | None = None,
+) -> DaemonDescriptor:
+    """Build one daemon-process descriptor for the selected namespace."""
+    root = _canonical_path(data_root) if data_root is not None else canonical_data_root()
+    actual_pid = int(pid if pid is not None else os.getpid())
+    actual_capability = capability or secrets.token_urlsafe(32)
+    return DaemonDescriptor(
+        schema=DAEMON_DESCRIPTOR_SCHEMA,
+        service=DAEMON_SERVICE,
+        daemon_protocol=DAEMON_PROTOCOL,
+        namespace_id=namespace_id_for(root),
+        instance_id=instance_id or str(uuid.uuid4()),
+        capability=actual_capability,
+        capability_fingerprint=capability_fingerprint(actual_capability),
+        owner_id=owner_id(),
+        data_root=str(root),
+        pid=actual_pid,
+        process_create_time=float(
+            process_create_time
+            if process_create_time is not None
+            else process_create_time_for(actual_pid)
+        ),
+        port=int(port),
+        state=state,
+        version=version,
+        started_at=float(started_at if started_at is not None else time.time()),
+    )
+
+
+def descriptor_path(data_root: str | Path | None = None) -> Path:
+    root = _canonical_path(data_root) if data_root is not None else canonical_data_root()
+    return root / "daemon.json"
+
+
+def write_descriptor(
+    descriptor: DaemonDescriptor,
+    *,
+    data_root: str | Path | None = None,
+) -> Path:
+    """Atomically publish a mode-0600 descriptor in its owned namespace."""
+    root = _canonical_path(data_root or descriptor.data_root)
+    root.mkdir(parents=True, exist_ok=True)
+    destination = root / "daemon.json"
+    temporary = root / f".daemon.{os.getpid()}.{secrets.token_hex(8)}.tmp"
+    payload = json.dumps(asdict(descriptor), sort_keys=True, separators=(",", ":"))
+    fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            stream.write(payload)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, destination)
+        try:
+            os.chmod(destination, 0o600)
+        except OSError:
+            pass
+    finally:
+        temporary.unlink(missing_ok=True)
+    return destination
+
+
+def read_descriptor(
+    *, data_root: str | Path | None = None,
+) -> DaemonDescriptor | None:
+    """Read and validate the local descriptor; malformed state fails closed."""
+    path = descriptor_path(data_root)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        descriptor = DaemonDescriptor(**raw)
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        return None
+    if descriptor.schema != DAEMON_DESCRIPTOR_SCHEMA:
+        return None
+    if descriptor.service != DAEMON_SERVICE:
+        return None
+    if descriptor.daemon_protocol != DAEMON_PROTOCOL:
+        return None
+    expected_root = (
+        _canonical_path(data_root) if data_root is not None else canonical_data_root()
+    )
+    if Path(descriptor.data_root).resolve(strict=False) != expected_root:
+        return None
+    if descriptor.namespace_id != namespace_id_for(expected_root):
+        return None
+    if descriptor.capability_fingerprint != capability_fingerprint(
+        descriptor.capability
+    ):
+        return None
+    if descriptor.owner_id != owner_id():
+        return None
+    if not (1 <= descriptor.port <= 65535) or descriptor.pid <= 0:
+        return None
+    return descriptor
+
+
+def descriptor_matches_health(
+    descriptor: DaemonDescriptor,
+    health: Mapping[str, Any],
+) -> bool:
+    """Require exact owned-daemon identity before a client attaches."""
+    expected = descriptor.public_health_fields()
+    identity_keys = (
+        "service",
+        "daemon_protocol",
+        "namespace_id",
+        "instance_id",
+        "capability_fingerprint",
+        "owner_id",
+        "version",
+        "pid",
+        "port",
+    )
+    for key in identity_keys:
+        left = str(expected[key])
+        right = str(health.get(key, ""))
+        if not hmac.compare_digest(left, right):
+            return False
+    return True
+
+
+def clear_descriptor(
+    instance_id: str,
+    *,
+    data_root: str | Path | None = None,
+) -> bool:
+    """Delete the descriptor only when the caller still owns that instance."""
+    descriptor = read_descriptor(data_root=data_root)
+    if descriptor is None or not hmac.compare_digest(
+        descriptor.instance_id, instance_id
+    ):
+        return False
+    try:
+        descriptor_path(data_root).unlink()
+        return True
+    except OSError:
+        return False

package/src/superlocalmemory/infra/data_root.py

@@ -0,0 +1,199 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Single authority for SuperLocalMemory runtime-state paths.
+
+The resolver is intentionally stdlib-only so CLI, daemon, MCP, and hook entry
+points can use it before importing the engine. Environment selection is an
+explicit process contract and always wins over persisted configuration.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+DATA_ROOT_ALIASES = ("SLM_DATA_DIR", "SL_MEMORY_PATH", "SLM_HOME")
+_DURABLE_IDENTITY_NAMES = frozenset(
+    {
+        ".install_token",
+        ".signer_key",
+        "api_key",
+        "credentials.json",
+    },
+)
+
+
+class DataRootConflictError(RuntimeError):
+    """Raised when two state-bearing roots make startup ambiguous."""
+
+
+def _canonical_path(value: str | Path) -> Path:
+    expanded = Path(value).expanduser().resolve(strict=False)
+    return Path(os.path.normcase(str(expanded)))
+
+
+def environment_data_root() -> Path | None:
+    """Return the winning environment root, or ``None`` when none is set."""
+    for name in DATA_ROOT_ALIASES:
+        value = os.environ.get(name, "").strip()
+        if value:
+            return _canonical_path(value)
+    return None
+
+
+def _legacy_configured_root(default_root: Path) -> Path | None:
+    """Read the bounded legacy ``config.json:base_dir`` relocation hint.
+
+    Only an absolute path is accepted. Relative paths historically depended on
+    the caller's working directory and cannot safely identify a process
+    namespace. Corrupt or unreadable configuration never changes the root.
+    """
+    config_path = default_root / "config.json"
+    try:
+        payload = json.loads(config_path.read_text(encoding="utf-8"))
+        value = payload.get("base_dir") if isinstance(payload, dict) else None
+        if not isinstance(value, str) or not value.strip():
+            return None
+        candidate = Path(value).expanduser()
+        if not candidate.is_absolute():
+            return None
+        return _canonical_path(candidate)
+    except (OSError, ValueError, TypeError):
+        return None
+
+
+def canonical_data_root(
+    configured_base_dir: str | Path | None = None,
+    *,
+    home: str | Path | None = None,
+) -> Path:
+    """Resolve the one runtime-state namespace for the current process.
+
+    Precedence:
+      1. ``SLM_DATA_DIR``
+      2. ``SL_MEMORY_PATH`` (legacy input shim)
+      3. ``SLM_HOME`` (legacy input shim)
+      4. explicit configured base directory
+      5. legacy default-root ``config.json:base_dir``
+      6. ``~/.superlocalmemory``
+
+    The function performs no writes and never moves data.
+    """
+    selected = environment_data_root()
+    if selected is not None:
+        return selected
+    if configured_base_dir is not None:
+        return _canonical_path(configured_base_dir)
+    home_path = _canonical_path(home if home is not None else Path.home())
+    default_root = _canonical_path(home_path / ".superlocalmemory")
+    return _legacy_configured_root(default_root) or default_root
+
+
+def _durable_markers(root: Path) -> tuple[Path, ...]:
+    """Return bounded evidence that ``root`` contains durable SLM state.
+
+    The startup guard deliberately ignores ``config.json`` on its own because
+    the default-root file is the compatibility locator for legacy custom
+    roots. Database sidecars count even if the base file was lost.
+    """
+    try:
+        children = tuple(root.iterdir())
+    except FileNotFoundError:
+        return ()
+    except OSError as exc:
+        raise DataRootConflictError(
+            f"SuperLocalMemory cannot inspect possible state root {root}: {exc}. "
+            "Startup is blocked until the root is readable or explicitly resolved."
+        ) from exc
+    markers = []
+    for path in children:
+        name = path.name
+        if (
+            name in _DURABLE_IDENTITY_NAMES
+            or name.endswith((".db", ".db-wal", ".db-shm", ".sqlite", ".sqlite3"))
+        ):
+            markers.append(path)
+    return tuple(sorted(markers))
+
+
+def assert_no_durable_root_conflict(
+    *,
+    home: str | Path | None = None,
+) -> None:
+    """Refuse ambiguous startup when selected and default roots hold state.
+
+    This check never writes, copies, or deletes data. A default root that only
+    contains the legacy relocation config is safe and does not trigger it.
+    """
+    home_path = _canonical_path(home if home is not None else Path.home())
+    default_root = _canonical_path(home_path / ".superlocalmemory")
+    selected_root = canonical_data_root(home=home_path)
+    if selected_root == default_root:
+        return
+    selected_markers = _durable_markers(selected_root)
+    default_markers = _durable_markers(default_root)
+    if not selected_markers or not default_markers:
+        return
+    raise DataRootConflictError(
+        "Conflicting SuperLocalMemory state roots detected: "
+        f"selected={selected_root} and default={default_root}. "
+        "SuperLocalMemory will not merge or move either root automatically. "
+        "Stop both namespaces, back them up, and choose an explicit migration "
+        "or one SLM_DATA_DIR before starting the daemon."
+    )
+
+
+def state_path(
+    *parts: str | Path,
+    configured_base_dir: str | Path | None = None,
+    home: str | Path | None = None,
+) -> Path:
+    """Return a canonical child path without permitting root escape."""
+    relative = Path()
+    for raw_part in parts:
+        part = Path(raw_part)
+        if part.is_absolute() or ".." in part.parts:
+            raise ValueError(f"state path must remain relative: {raw_part!s}")
+        relative /= part
+    root = canonical_data_root(configured_base_dir, home=home)
+    destination = _canonical_path(root / relative)
+    try:
+        destination.relative_to(root)
+    except ValueError as exc:
+        raise ValueError("state path escapes the canonical data root") from exc
+    return destination
+
+
+class DynamicStatePath(os.PathLike[str]):
+    """Backward-compatible path proxy that never freezes the active root."""
+
+    __slots__ = ("_parts",)
+
+    def __init__(self, *parts: str | Path) -> None:
+        self._parts = parts
+
+    def _resolve(self) -> Path:
+        return state_path(*self._parts)
+
+    def __fspath__(self) -> str:
+        return str(self._resolve())
+
+    def __truediv__(self, other: str | Path) -> Path:
+        return self._resolve() / other
+
+    def __str__(self) -> str:
+        return str(self._resolve())
+
+    def __repr__(self) -> str:
+        return f"DynamicStatePath({self._parts!r})"
+
+    def __eq__(self, other: object) -> bool:
+        try:
+            return self._resolve() == Path(other)  # type: ignore[arg-type]
+        except TypeError:
+            return False
+
+    def __getattr__(self, name: str):
+        return getattr(self._resolve(), name)

package/src/superlocalmemory/infra/event_bus.py

@@ -16,6 +16,8 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
+from superlocalmemory.infra.data_root import state_path
+
 logger = logging.getLogger("superlocalmemory.events")
 
 # Default retention windows (hours)
@@ -66,7 +68,7 @@ class EventBus:
     def get_instance(cls, db_path: Optional[Path] = None) -> "EventBus":
         """Get or create the singleton EventBus for a database path."""
         if db_path is None:
-            db_path = Path.home() / ".superlocalmemory" / "memory.db"
+            db_path = state_path("memory.db")
 
         key = str(db_path)
         with cls._instances_lock: