superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/infra/daemon_identity.py

@@ -1,300 +0,0 @@
-# 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 logging
-import os
-import secrets
-import subprocess
-import sys
-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
-from superlocalmemory.infra.process_identity import process_start_token_for
-
-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"
-
-logger = logging.getLogger(__name__)
-
-
-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
-    # Clock-independent process identity. Optional and defaulted so a
-    # descriptor written by an older release still parses; platforms without a
-    # boot-relative start time (Windows) legitimately store None and fall back
-    # to the creation-time comparison. See infra/process_identity.py.
-    process_start_token: str | None = None
-
-    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,
-    process_start_token: str | 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()),
-        process_start_token=(
-            process_start_token
-            if process_start_token is not None
-            else process_start_token_for(actual_pid)
-        ),
-    )
-
-
-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 _restrict_to_owner(path: Path) -> None:
-    """Restrict a sensitive file to the current user on every platform.
-
-    ``daemon.json`` holds the capability token that authorizes write requests.
-    POSIX gets a 0600 chmod. On Windows chmod is a no-op, so use icacls to strip
-    inherited ACEs and grant the current user only — otherwise the token can be
-    read by other local accounts (privilege escalation on shared machines).
-    Files under %USERPROFILE% usually inherit user-only ACLs already; this is
-    defense-in-depth. Fail-soft — a hardening failure warns, never crashes.
-    """
-    if sys.platform == "win32":
-        try:
-            user = getpass.getuser()
-            subprocess.run(
-                ["icacls", str(path), "/inheritance:r"],
-                check=False, capture_output=True,
-            )
-            if user:
-                subprocess.run(
-                    ["icacls", str(path), "/grant:r", f"{user}:F"],
-                    check=False, capture_output=True,
-                )
-        except Exception as exc:  # noqa: BLE001
-            logger.warning(
-                "could not restrict ACL on %s (%s); the capability token may be "
-                "readable by other local users", path, exc,
-            )
-    else:
-        try:
-            os.chmod(path, 0o600)
-        except OSError as exc:
-            logger.warning("could not chmod %s to 0600: %s", path, exc)
-
-
-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)
-        _restrict_to_owner(destination)
-    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
-    if descriptor.process_start_token is not None and not isinstance(
-        descriptor.process_start_token, str
-    ):
-        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

@@ -1,238 +0,0 @@
-# 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 logging
-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",
-    },
-)
-
-logger = logging.getLogger(__name__)
-
-
-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 two state roots make the live namespace unclear.
-
-    The root actually selected for this process is always inspected: an
-    unreadable selected root fails closed. Beyond that, a conflict is only raised
-    when the selection was *implicit* — resolved from the legacy
-    ``config.json:base_dir`` relocation hint — and a separately-populated default
-    root leaves it genuinely ambiguous which namespace is live.
-
-    An explicit environment selection (``SLM_DATA_DIR`` / ``SL_MEMORY_PATH`` /
-    ``SLM_HOME``) is an unambiguous operator contract: a separately-populated
-    default root is then a deliberate multi-root / per-team / second-instance
-    layout, not an ambiguity, so startup proceeds. If the explicitly chosen root
-    is empty while the old default still holds data, that likely-mistyped path is
-    surfaced as a warning rather than a hard block.
-
-    This check never writes, copies, or deletes data.
-    """
-    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
-
-    # The root about to be used must be inspectable regardless of how it was
-    # chosen; an unreadable selected root fails closed inside _durable_markers.
-    selected_markers = _durable_markers(selected_root)
-
-    if environment_data_root() is not None:
-        # Explicit selection wins; a populated default root is a deliberate
-        # multi-root layout, not an ambiguity. Only warn on the "empty new root
-        # while the old default still holds data" case so a wrong SLM_DATA_DIR
-        # stays visible. Inspection of the unused default never blocks startup.
-        if not selected_markers:
-            try:
-                default_has_data = bool(_durable_markers(default_root))
-            except DataRootConflictError:
-                default_has_data = False
-            if default_has_data:
-                logger.warning(
-                    "SLM_DATA_DIR selects an empty state root (%s) while the "
-                    "default root (%s) still holds data; starting with the empty "
-                    "root as explicitly requested.",
-                    selected_root,
-                    default_root,
-                )
-        return
-
-    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)