muxplex 0.1.0__py3-none-any.whl

muxplex/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running muxplex as: python -m muxplex"""
+
+from muxplex.cli import main
+
+main()

muxplex/auth.py

@@ -0,0 +1,232 @@
+"""
+muxplex authentication — password and signing secret file management.
+"""
+
+import base64
+import hmac
+import logging
+import secrets
+from pathlib import Path
+
+from itsdangerous import BadSignature, SignatureExpired, TimestampSigner
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse, Response
+
+_log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Config directory
+# ---------------------------------------------------------------------------
+
+
+def _config_dir() -> Path:
+    """Return ~/.config/muxplex, creating it (mode 0700) if needed."""
+    d = Path.home() / ".config" / "muxplex"
+    d.mkdir(mode=0o700, parents=True, exist_ok=True)
+    return d
+
+
+# ---------------------------------------------------------------------------
+# Password file management
+# ---------------------------------------------------------------------------
+
+
+def get_password_path() -> Path:
+    """Return the path to the password file: ~/.config/muxplex/password."""
+    return Path.home() / ".config" / "muxplex" / "password"
+
+
+def load_password() -> str | None:
+    """Read the password file if it exists, return None otherwise."""
+    path = get_password_path()
+    if not path.exists():
+        return None
+    return path.read_text().strip()
+
+
+def generate_and_save_password() -> str:
+    """Generate a random password, write it to the password file (0600), return it."""
+    pw = secrets.token_urlsafe(20)
+    path = get_password_path()
+    _config_dir()  # ensures dir exists with mode 0700
+    path.write_text(pw + "\n")
+    path.chmod(0o600)
+    return pw
+
+
+# ---------------------------------------------------------------------------
+# Secret (signing key) management
+# ---------------------------------------------------------------------------
+
+
+def get_secret_path() -> Path:
+    """Return the path to the signing secret file: ~/.config/muxplex/secret."""
+    return Path.home() / ".config" / "muxplex" / "secret"
+
+
+def load_or_create_secret() -> str:
+    """Load the signing secret from file, or create one if it doesn't exist."""
+    path = get_secret_path()
+    if path.exists():
+        return path.read_text().strip()
+    secret = secrets.token_urlsafe(32)
+    _config_dir()  # ensures dir exists with mode 0700, consistent with generate_and_save_password()
+    path.write_text(secret + "\n")
+    path.chmod(0o600)
+    return secret
+
+
+# ---------------------------------------------------------------------------
+# Session cookie signing / verification
+# ---------------------------------------------------------------------------
+
+
+def create_session_cookie(secret: str, ttl_seconds: int) -> str:
+    """Create a signed, timestamped session cookie value."""
+    signer = TimestampSigner(secret)
+    # ttl_seconds is not used at signing time; the timestamp is embedded in
+    # the signed value and checked against ttl_seconds during verification.
+    return signer.sign("muxplex-session").decode()
+
+
+def verify_session_cookie(secret: str, cookie: str, ttl_seconds: int) -> bool:
+    """Verify a session cookie's signature and expiry. Returns True/False.
+
+    ttl_seconds=0 means session cookie — no server-side expiry check.
+    """
+    signer = TimestampSigner(secret)
+    try:
+        max_age = ttl_seconds if ttl_seconds > 0 else None
+        signer.unsign(cookie, max_age=max_age)
+        return True
+    except (BadSignature, SignatureExpired):
+        return False
+
+
+# ---------------------------------------------------------------------------
+# PAM authentication
+# ---------------------------------------------------------------------------
+
+
+def pam_available() -> bool:
+    """Check whether the python-pam module is importable."""
+    try:
+        import pam  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def authenticate_pam(username: str, password: str) -> bool:
+    """Authenticate via PAM. Username must match the running process owner."""
+    import os
+    import pwd
+
+    import pam
+
+    running_user = pwd.getpwuid(os.getuid()).pw_name
+    if username != running_user:
+        return False
+    return pam.authenticate(username, password, service="login")
+
+
+# ---------------------------------------------------------------------------
+# Auth middleware
+# ---------------------------------------------------------------------------
+
+# Paths that bypass auth (login page itself, static assets it needs)
+_AUTH_EXEMPT_PATHS = {"/login", "/auth/mode", "/auth/logout", "/api/instance-info"}
+
+# File extensions that are always served without auth — the login page needs
+# its own CSS, JS, images, and fonts before the user has a session cookie.
+_STATIC_EXTENSIONS = {
+    ".css",
+    ".js",
+    ".svg",
+    ".png",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".map",
+}
+
+# Socket-level localhost addresses — cannot be forged via HTTP headers
+_LOCALHOST_ADDRS = {"127.0.0.1", "::1"}
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    """FastAPI middleware that enforces authentication on non-localhost requests."""
+
+    def __init__(
+        self,
+        app,
+        auth_mode: str,
+        secret: str,
+        ttl_seconds: int,
+        password: str = "",
+        federation_key: str = "",
+    ):
+        super().__init__(app)
+        self.auth_mode = auth_mode
+        self.secret = secret
+        self.ttl_seconds = ttl_seconds
+        self.password = password
+        self.federation_key = federation_key
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        # 1. Localhost bypass — client.host is the socket-level IP and cannot
+        # be forged by the client (unlike the HTTP Host header).
+        client_host = request.client.host if request.client else ""
+        if client_host in _LOCALHOST_ADDRS:
+            return await call_next(request)
+
+        # 2. Exempt paths (login page, auth endpoints)
+        if request.url.path in _AUTH_EXEMPT_PATHS:
+            return await call_next(request)
+
+        # 3. Static assets — login page needs its CSS/JS/images before auth
+        path = request.url.path
+        if any(path.endswith(ext) for ext in _STATIC_EXTENSIONS):
+            return await call_next(request)
+
+        # 4. Valid session cookie
+        cookie = request.cookies.get("muxplex_session")
+        if cookie and verify_session_cookie(self.secret, cookie, self.ttl_seconds):
+            return await call_next(request)
+
+        # 4a. Bearer token (server-to-server federation)
+        auth_header = request.headers.get("authorization", "")
+        if self.federation_key and auth_header.lower().startswith("bearer "):
+            token = auth_header[7:]
+            if hmac.compare_digest(token, self.federation_key):
+                return await call_next(request)
+            _log.warning("federation: rejected Bearer from %s", client_host)
+
+        # 5. Authorization: Basic header
+        auth_header = request.headers.get("authorization", "")
+        if auth_header.lower().startswith("basic "):
+            try:
+                # Strip "Basic " prefix (6 chars) before base64-decoding
+                decoded = base64.b64decode(auth_header[6:]).decode()
+                username, _, pw = decoded.partition(":")
+                if self._check_credentials(username, pw):
+                    return await call_next(request)
+            except Exception:
+                pass
+            return JSONResponse({"detail": "Invalid credentials"}, status_code=401)
+
+        # 6. No auth — redirect browsers, 401 for API clients
+        accept = request.headers.get("accept", "")
+        if "application/json" in accept:
+            return JSONResponse({"detail": "Authentication required"}, status_code=401)
+        return RedirectResponse(url="/login", status_code=307)
+
+    def _check_credentials(self, username: str, password: str) -> bool:
+        """Validate credentials against the configured auth mode."""
+        if self.auth_mode == "pam":
+            return authenticate_pam(username, password)
+        return password == self.password

muxplex/bells.py

@@ -0,0 +1,177 @@
+"""
+Bell flag polling and unseen_count tracking for the tmux-web muxplex.
+
+Based on spike findings: reading the tmux window_bell_flag does NOT clear it.
+The flag persists until the window is made active inside tmux.
+
+In-memory state:
+    _bell_seen  — tracks whether the bell flag was '1' on the last poll,
+                  keyed by session_name. Used to detect 0→1 transitions.
+
+Public API:
+    poll_bell_flag(session_name)             → bool
+    process_bell_flags(session_names, state) → bool
+    should_clear_bell(session_name, state)   → bool
+    apply_bell_clear_rule(state)             → list[str]
+"""
+
+import time
+
+from muxplex.sessions import run_tmux
+from muxplex.state import empty_bell
+
+# ---------------------------------------------------------------------------
+# In-memory tracking: session_name → bool (was flag set on last poll?)
+# ---------------------------------------------------------------------------
+
+_bell_seen: dict[str, bool] = {}
+
+
+# ---------------------------------------------------------------------------
+# poll_bell_flag
+# ---------------------------------------------------------------------------
+
+
+async def poll_bell_flag(session_name: str) -> bool:
+    """Poll the tmux window_bell_flag for session_name.
+
+    Calls: tmux display-message -t <name> -p #{window_bell_flag}
+
+    Returns True if the output is '1', False otherwise (including on errors).
+    Note: reading does NOT clear the tmux bell flag.
+    """
+    try:
+        output = await run_tmux(
+            "display-message", "-t", session_name, "-p", "#{window_bell_flag}"
+        )
+        return output.strip() == "1"
+    except RuntimeError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# process_bell_flags
+# ---------------------------------------------------------------------------
+
+
+async def process_bell_flags(session_names: list[str], state: dict) -> bool:
+    """Poll bell flags for all sessions and update state accordingly.
+
+    NOTE: The tmux alert-bell hook (POST /api/sessions/{name}/bell) is the
+    primary bell detection mechanism. window_bell_flag is only set when NO
+    tmux client is watching the window — with an SSH/WezTerm session attached,
+    the flag is never set even though the bell fires. This function serves as
+    a fallback for sessions that fired before the coordinator registered the hook.
+
+    Detects 0→1 transitions using _bell_seen and increments unseen_count.
+    Persistent '1' flags (1→1) are not double-counted.
+    When flag clears (1→0), _bell_seen is reset so the next '1' counts as
+    a new, separate bell event.
+
+    Ensures the bell sub-dict exists for each session in state.
+
+    Args:
+        session_names: List of session names to poll.
+        state:         Mutable state dict (modified in-place).
+
+    Returns:
+        True if any bell state changed (new bell detected), False otherwise.
+    """
+    changed = False
+
+    for name in session_names:
+        # Ensure session entry and bell sub-dict exist
+        if name not in state["sessions"]:
+            state["sessions"][name] = {}
+        if "bell" not in state["sessions"][name]:
+            state["sessions"][name]["bell"] = empty_bell()
+
+        bell = state["sessions"][name]["bell"]
+        flag_set = await poll_bell_flag(name)
+        previously_seen = _bell_seen.get(name, False)
+
+        if flag_set and not previously_seen:
+            # 0→1 transition: new bell event
+            bell["unseen_count"] += 1
+            bell["last_fired_at"] = time.time()
+            _bell_seen[name] = True
+            changed = True
+        elif not flag_set and previously_seen:
+            # 1→0: flag cleared — reset tracking so next '1' is a new bell
+            # Do NOT decrement unseen_count
+            _bell_seen[name] = False
+
+    return changed
+
+
+# ---------------------------------------------------------------------------
+# Bell clear rule constants
+# ---------------------------------------------------------------------------
+
+_INTERACTION_WINDOW_SECONDS: float = 60.0
+
+
+# ---------------------------------------------------------------------------
+# should_clear_bell
+# ---------------------------------------------------------------------------
+
+
+def should_clear_bell(session_name: str, state: dict) -> bool:
+    """Return True if any connected device qualifies to globally acknowledge bells.
+
+    A session's bells should be cleared when ANY device satisfies ALL of:
+        - viewing_session == session_name
+        - view_mode == 'fullscreen'
+        - last_interaction_at > now - _INTERACTION_WINDOW_SECONDS
+
+    Args:
+        session_name: Name of the tmux session to check.
+        state:        Current application state dict.
+
+    Returns:
+        True if at least one device meets all conditions, False otherwise.
+    """
+    cutoff = time.time() - _INTERACTION_WINDOW_SECONDS
+    for device in state["devices"].values():
+        if (
+            device["viewing_session"] == session_name
+            and device["view_mode"] == "fullscreen"
+            and device["last_interaction_at"] > cutoff
+        ):
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# apply_bell_clear_rule
+# ---------------------------------------------------------------------------
+
+
+def apply_bell_clear_rule(state: dict) -> list[str]:
+    """Check every session with unseen_count > 0 against the active-device gate.
+
+    For each qualifying session (unseen_count > 0 AND should_clear_bell):
+        - Resets unseen_count to 0
+        - Sets seen_at to now
+        - Resets _bell_seen[name] = False
+
+    Args:
+        state: Mutable application state dict (modified in-place).
+
+    Returns:
+        List of session names whose bells were cleared.
+    """
+    cleared: list[str] = []
+    now = time.time()
+
+    for name, session in state["sessions"].items():
+        bell = session.get("bell")
+        if bell is None or bell.get("unseen_count", 0) == 0:
+            continue
+        if should_clear_bell(name, state):
+            bell["unseen_count"] = 0
+            bell["seen_at"] = now
+            _bell_seen[name] = False
+            cleared.append(name)
+
+    return cleared