Home /Modules/http-3.0/os_floor_registry.py

os_floor_registry.py

http-3.0/os_floor_registry.py · 241 line(s) · py

"""os_floor_registry.py -- SLeeLa install-time "tidiest fit" OS-floor discovery.

When a SLeeLa executable installs on a host, it wants the *tidiest fit*: it
looks at the operating-system "floor" it landed on (OS + filesystem), confers
with any capability responder present (TAC3 or another, via the bonding collar),
and records what it found. Over time SLeeLa keeps a growing **registry of OS
floors / filesystems** it has seen, with rollup statistics, and can *advance*
new or updated discoveries to a known GitHub endpoint (see os_floor_report.py).

DESIGN STANCE (matches the bonding collar):
  - Observe, don't misrepresent. A floor's bonded tier is exactly what the
    collar attested -- never guessed.
  - Fail closed / no leakage. Detection makes no privileged calls and records
    only non-identifying descriptors (OS name, filesystem hint, bonded tier,
    a derived fingerprint). No secrets, no user PII, no host-proprietary
    internals (the collar already guarantees the last point).
  - Portable. Uses only the standard library so it runs on any host SLeeLa
    reaches, including a new/unknown OS.
"""
from __future__ import annotations

import hashlib
import json
import os
import platform
import time
from dataclasses import dataclass, field, asdict
from typing import Dict, List, Optional

from bonding_collar import (
    BondingCollar, CollarOffer, probe_env_responder,
    CAP_ALL, tier_name, MAC_KEY_BYTES,
)

REGISTRY_VERSION = 1


def _now_iso() -> str:
    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())


# --------------------------------------------------------------------------
# A single observed OS floor
# --------------------------------------------------------------------------
@dataclass
class OsFloor:
    """One OS/filesystem floor SLeeLa has landed on, and the advantage it confers."""
    floor_id: str                 # stable fingerprint (dedupe key)
    os_name: str                  # e.g. "Linux", "Darwin", "Windows", or "Unknown"
    os_release: str               # kernel/OS release string (non-identifying)
    filesystem: str               # detected/declared fs hint, or "unknown"
    bonded_tier: int              # bonding-collar tier (0 = NONE / unknown)
    bonded_tier_name: str
    responder: str                # "tac3", "generic", or "none"
    first_seen: str = ""
    last_seen: str = ""
    seen_count: int = 0
    notes: str = ""

    def to_dict(self) -> dict:
        return asdict(self)


def _fingerprint(os_name: str, os_release: str, filesystem: str, responder: str) -> str:
    """Stable, non-identifying dedupe key for a floor (12 hex chars)."""
    h = hashlib.sha256(f"{os_name}|{os_release}|{filesystem}|{responder}".encode("utf-8"))
    return "floor-" + h.hexdigest()[:12]


def detect_filesystem_hint() -> str:
    """A conservative, non-privileged guess at the host filesystem 'floor'.

    Reads only what the platform readily exposes; never mounts, never calls a
    privileged tool. Returns "unknown" when nothing safe is available.
    """
    # A host (or a responder like TAC3) may declare the floor explicitly.
    declared = os.environ.get("SLEELA_FS_FLOOR")
    if declared:
        return declared.strip()[:64]
    sysname = platform.system()
    if sysname == "Linux":
        # /proc/mounts is world-readable and non-privileged where present.
        try:
            root_fs = None
            with open("/proc/mounts", "r", encoding="utf-8", errors="replace") as fh:
                for line in fh:
                    parts = line.split()
                    if len(parts) >= 3 and parts[1] == "/":
                        root_fs = parts[2]
                        break
            if root_fs:
                return root_fs
        except OSError:
            pass
    elif sysname == "Darwin":
        return "apfs?"       # best-effort hint without privileged calls
    elif sysname == "Windows":
        return "ntfs?"
    return "unknown"


def confer_with_host(key: bytes, *, env: Optional[dict] = None) -> tuple:
    """Confer via the bonding collar. Returns (bonded_tier, tier_name, responder).

    responder is "tac3" when the host declares SLEELA_OS_RESPONDER=tac3 alongside
    a valid attestation, "generic" for any other attested responder, else "none".
    """
    e = env if env is not None else os.environ
    collar = BondingCollar(local_caps=CAP_ALL, key=key)
    offer = probe_env_responder(key, env=e)
    result = collar.confer(offer)
    if not result.bonded:
        return (result.tier, result.tier_name, "none")
    responder = (e.get("SLEELA_OS_RESPONDER") or "generic").strip().lower()[:32]
    if responder not in ("tac3", "generic"):
        responder = "generic"
    return (result.tier, result.tier_name, responder)


def observe_current_floor(key: bytes, *, env: Optional[dict] = None) -> OsFloor:
    """Detect the current OS floor and confer for its bonded advantage tier."""
    e = env if env is not None else os.environ
    os_name = platform.system() or "Unknown"
    os_release = (platform.release() or "")[:96]
    fs_hint = detect_filesystem_hint()
    tier, tname, responder = confer_with_host(key, env=e)
    fid = _fingerprint(os_name, os_release, fs_hint, responder)
    now = _now_iso()
    return OsFloor(
        floor_id=fid, os_name=os_name, os_release=os_release, filesystem=fs_hint,
        bonded_tier=tier, bonded_tier_name=tname, responder=responder,
        first_seen=now, last_seen=now, seen_count=1,
    )


# --------------------------------------------------------------------------
# The registry (deduplicated, persistent)
# --------------------------------------------------------------------------
class OsFloorRegistry:
    """A growing, deduplicated list of OS floors/filesystems SLeeLa has seen."""

    def __init__(self, path: Optional[str] = None) -> None:
        self.path = path
        self._floors: Dict[str, OsFloor] = {}
        if path and os.path.exists(path):
            self.load(path)

    # ---- persistence ----
    def load(self, path: Optional[str] = None) -> None:
        p = path or self.path
        with open(p, "r", encoding="utf-8") as fh:
            doc = json.load(fh)
        self._floors = {}
        for entry in doc.get("floors", []):
            f = OsFloor(**entry)
            self._floors[f.floor_id] = f

    def save(self, path: Optional[str] = None) -> None:
        p = path or self.path
        if not p:
            raise ValueError("no path to save to")
        tmp = p + ".tmp"
        with open(tmp, "w", encoding="utf-8") as fh:
            fh.write(self.to_json())
        os.replace(tmp, p)

    # ---- mutation ----
    def record(self, floor: OsFloor) -> tuple:
        """Add or update a floor. Returns (floor, is_new).

        Dedupe key is floor_id. On re-observation we bump seen_count/last_seen
        and upgrade the bonded tier if the host now attests to a higher one.
        """
        existing = self._floors.get(floor.floor_id)
        if existing is None:
            self._floors[floor.floor_id] = floor
            return (floor, True)
        existing.seen_count += 1
        existing.last_seen = floor.last_seen
        if floor.bonded_tier > existing.bonded_tier:
            existing.bonded_tier = floor.bonded_tier
            existing.bonded_tier_name = floor.bonded_tier_name
            existing.responder = floor.responder
        return (existing, False)

    # ---- access ----
    def floors(self) -> List[OsFloor]:
        return sorted(self._floors.values(), key=lambda f: (-f.bonded_tier, f.floor_id))

    def get(self, floor_id: str) -> Optional[OsFloor]:
        return self._floors.get(floor_id)

    def stats(self) -> dict:
        """Rollup statistics over the registry (non-identifying)."""
        floors = list(self._floors.values())
        by_tier: Dict[str, int] = {}
        by_os: Dict[str, int] = {}
        by_fs: Dict[str, int] = {}
        by_responder: Dict[str, int] = {}
        total_observations = 0
        bonded = 0
        for f in floors:
            by_tier[f.bonded_tier_name] = by_tier.get(f.bonded_tier_name, 0) + 1
            by_os[f.os_name] = by_os.get(f.os_name, 0) + 1
            by_fs[f.filesystem] = by_fs.get(f.filesystem, 0) + 1
            by_responder[f.responder] = by_responder.get(f.responder, 0) + 1
            total_observations += f.seen_count
            if f.bonded_tier > 0:
                bonded += 1
        return {
            "distinct_floors": len(floors),
            "total_observations": total_observations,
            "bonded_floors": bonded,
            "unbonded_floors": len(floors) - bonded,
            "by_tier": by_tier,
            "by_os": by_os,
            "by_filesystem": by_fs,
            "by_responder": by_responder,
        }

    def to_json(self, *, indent: int = 2) -> str:
        doc = {
            "registry_version": REGISTRY_VERSION,
            "generated": _now_iso(),
            "floor_count": len(self._floors),
            "stats": self.stats(),
            "floors": [f.to_dict() for f in self.floors()],
        }
        return json.dumps(doc, indent=indent)


if __name__ == "__main__":
    # No-network self-demo: observe this host's floor and print it.
    key = b"\x3c" * MAC_KEY_BYTES
    reg = OsFloorRegistry()
    floor = observe_current_floor(key)
    f, is_new = reg.record(floor)
    print(f"observed floor: {f.os_name} / {f.filesystem} -> tier={f.bonded_tier_name} "
          f"responder={f.responder} (new={is_new})")
    print(reg.to_json())