Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

22.6 KB
Raw Blame
"""
Session management for encrypted database connections.
Handles session creation, validation, and cleanup.
"""

import datetime
import secrets
import threading
from dataclasses import dataclass
from datetime import UTC
from typing import Dict, Optional, Set, TypedDict

from loguru import logger

from ...database.authorization_epoch import read_user_authorization_epoch
from ...database.rekey_lock import (
    RekeyEpochUnreadableError,
    RekeyOperationalError,
)
from ...security import get_security_default
from ...utilities.formatting import short_id


class _SessionData(TypedDict):
    username: str
    created_at: datetime.datetime
    last_access: datetime.datetime
    remember_me: bool
    rekey_epoch: str


class StaleLoginProofError(Exception):
    """The login proved its password against a no-longer-current epoch.

    Raised by ``create_session`` when the durable epoch the login's
    ``open_user_database`` proved differs from the committed epoch at
    session creation: a rekey (password change, possibly in another
    worker) committed in between, so the password this login presented
    no longer opens the database and must not mint a session.
    """

    def __init__(self, username: str) -> None:
        self.username = username
        super().__init__("login proof is stale: the password changed")


# Key under the ASGI ``scope["state"]`` (``request.state``) where
# ``DatabaseMiddleware`` (``_enforce_session_revocation``) records the
# ``(session_id, username)`` it validated for THIS request, so
# ``require_auth`` does not re-project the durable epoch a second time.
# ``scope["state"]`` is per request (Starlette/uvicorn copy it for each
# request) and is written only by server code after a successful
# validation; nothing client-controlled reaches it.
VALIDATED_SESSION_STATE_KEY = "ldr_validated_session"

# Set in ``scope["state"]`` by ``DatabaseMiddleware`` when it let a
# ``POST /auth/logout`` through WITHOUT validating the session, because the
# durable epoch could not be read. Only the logout route reads it.
UNVALIDATED_LOGOUT_STATE_KEY = "ldr_unvalidated_logout"

# The ``detail`` of the 503 that refuses a request whose session could not
# be validated (``SessionValidationUnavailableError``), from either
# ``DatabaseMiddleware`` or ``require_auth``.
SESSION_VALIDATION_UNAVAILABLE_DETAIL = (
    "Service temporarily unavailable, please retry"
)


class SessionValidationUnavailableError(Exception):
    """The session's durable epoch could not be read for THIS check.

    Raised by ``validate_session_identity`` / ``validate_session`` when
    the epoch file read itself failed (``RekeyEpochUnreadableError``:
    EMFILE, ENFILE, EAGAIN, EIO, ...). Nothing is known about the
    epoch, so the request must be refused (fail closed), but the session
    record is KEPT: only durable state that was actually read and does
    not vouch for the session ends it. Callers answer 503 (HTTP) or
    reject the socket action, and must NOT clear the cookie -- that would
    log out every active user on a transient fd-exhaustion spike.

    Deliberately not a ``RekeyOperationalError`` and not a falsy return:
    a caller that forgets to handle it gets an error response, never an
    authenticated one.
    """

    def __init__(self, username: str, error_number: int | None) -> None:
        self.username = username
        self.errno = error_number
        super().__init__(
            "session epoch temporarily unreadable "
            f"(errno={'unknown' if error_number is None else error_number})"
        )


@dataclass(frozen=True, slots=True)
class ValidatedSession:
    """An identity proven against the durable rekey epoch it was bound to."""

    session_id: str
    username: str
    rekey_epoch: str


class SessionManager:
    """Manages user sessions and database connection lifecycle.

    Note: session state is in-memory and per-process (no Redis or other
    shared store). In multi-worker deployments (e.g. gunicorn with more
    than one worker) each worker holds its own ``sessions`` dict, and a
    worker restart drops all sessions it held. ``validate_session`` only
    ever sees sessions created by *this* process — including for callers
    like the socket connect-time session gate, which now relies on this
    lookup — but every record is validated against the shared durable
    rekey epoch, so a password change in ANY worker fences the stale
    local identities of every other worker too. ``has_active_sessions_for``
    re-projects the epoch too (a stale or unverifiable record does not
    count as active). The idle sweeps (``cleanup_expired_sessions``,
    ``get_active_usernames``) are time-based only and do NOT re-project
    the epoch: a stale-epoch record is removed by its next validation or
    when it idles out, and until then ``get_active_usernames`` can keep
    its user counted as active by the idle-connection sweep. See
    ``security/account_lockout.py`` and ``web/routers/rag.py`` for the
    same multi-worker caveat elsewhere in the codebase.
    """

    def __init__(self):
        self.sessions: Dict[str, dict] = {}
        # WARNING: never call logger.* while holding _lock. The synchronous
        # frontend_progress_sink can re-enter emit_to_subscribers ->
        # touch_session -> _lock on the same thread and self-deadlock (this is
        # a plain Lock, not an RLock).
        self._lock = threading.Lock()
        # Load session timeouts from security settings
        session_hours = get_security_default(
            "security.session_timeout_hours", 2
        )
        remember_days = get_security_default(
            "security.session_remember_me_days", 30
        )
        self.session_timeout = datetime.timedelta(hours=session_hours)
        self.remember_me_timeout = datetime.timedelta(days=remember_days)

    def create_session(
        self,
        username: str,
        remember_me: bool = False,
        *,
        proven_epoch: str | None = None,
    ) -> str:
        """Create a new session for a user.

        Args:
            username: The username to create a session for.
            remember_me: If True, use extended session timeout.
            proven_epoch: The durable epoch the caller's credential check
                proved (``LoginProof.epoch`` from the login's
                ``open_user_database``). When given, the session is created
                only if it is still the committed epoch.

        Returns:
            The session ID as a URL-safe string.

        Raises:
            StaleLoginProofError: ``proven_epoch`` is no longer committed
                (a rekey committed after the password was proved).
            RekeyOperationalError: the durable epoch cannot be projected
                (the login route answers 503).
        """
        # Bind the committed durable epoch. With a proof, it must equal the
        # epoch the password was verified against: an old-password login
        # straddling a rekey committed in another worker would otherwise be
        # bound to the NEW epoch and survive the password change.
        rekey_epoch = read_user_authorization_epoch(username)
        if proven_epoch is not None and proven_epoch != rekey_epoch:
            raise StaleLoginProofError(username)
        session_id = secrets.token_urlsafe(32)
        now = datetime.datetime.now(UTC)

        with self._lock:
            self.sessions[session_id] = {
                "username": username,
                "created_at": now,
                "last_access": now,
                "remember_me": remember_me,
                "rekey_epoch": rekey_epoch,
            }

        logger.debug(f"Created session {session_id[:8]}... for user {username}")
        return session_id

    def validate_session_identity(
        self, session_id: str
    ) -> Optional[ValidatedSession]:
        """Validate one epoch-bound session and refresh its idle timestamp.

        The durable epoch is projected OUTSIDE ``_lock`` (it reads a file),
        then the record is re-checked under the lock so a concurrent
        destroy/recreate cannot be validated against a stale snapshot.

        Failure discipline (fail closed):

        * epoch mismatch — the database was rekeyed (password changed)
          somewhere; this session's credential can no longer open it, so
          the record is REMOVED;
        * the epoch files could not be READ at all
          (``RekeyEpochUnreadableError``: EMFILE, ENFILE, EAGAIN, EIO,
          ...) — nothing is known about the epoch, so this check
          fails closed by raising ``SessionValidationUnavailableError``,
          but the record is KEPT. Every caller that sees a ``None``
          clears the cookie, so deleting (or returning ``None``) here
          would log out every active user on a transient fd spike;
        * any other ``RekeyOperationalError`` — the files were read and
          the durable state (malformed token, a pending rekey in flight
          or awaiting recovery, pending without committed) cannot vouch
          for the identity; the record is REMOVED. A pending state is
          kept on this side on purpose: after a crashed rekey it stays
          until the next open recovers it (which always advances the
          epoch), and a kept record would answer 503 until it idled out
          instead of sending the user back to the login that recovers.

        Whenever the record is REMOVED (idle expiry, epoch mismatch, or
        unvouchable durable state), the live sockets that handshook on
        this session id are disconnected too, best-effort and after
        ``_lock`` is released (``_disconnect_expired_sockets``; it never
        raises). The removed record is invisible to every later sweep, so
        this is the only point that can still revoke them.

        Raises:
            SessionValidationUnavailableError: the epoch was unreadable.
        """
        expired_username: Optional[str] = None
        with self._lock:
            session_data = self.sessions.get(session_id)
            if session_data is None:
                return None
            timeout = (
                self.remember_me_timeout
                if session_data["remember_me"]
                else self.session_timeout
            )
            username = session_data["username"]
            rekey_epoch = session_data["rekey_epoch"]

        try:
            current_epoch = read_user_authorization_epoch(username)
        except RekeyEpochUnreadableError as error:
            # Transient I/O: refuse THIS check, keep the record.
            # Identity is a separate field; exception text contains only errno.
            # bearer:disable python_lang_exception
            raise SessionValidationUnavailableError(
                username, error.errno
            ) from None
        except RekeyOperationalError:
            with self._lock:
                removed = self.sessions.get(session_id) is session_data
                if removed:
                    del self.sessions[session_id]
            if removed:
                self._disconnect_expired_sockets([session_id])
            return None

        now = datetime.datetime.now(UTC)
        with self._lock:
            if self.sessions.get(session_id) is not session_data:
                return None
            if now - session_data["last_access"] > timeout:
                # Session expired — remove inline (already under lock).
                # Defer the log call until after the lock is released: see
                # the warning in __init__ about not logging while holding
                # _lock.
                expired_username = username
                del self.sessions[session_id]
            elif current_epoch != rekey_epoch:
                # The database was rekeyed after this session was issued:
                # its credential is dead and so is the identity it
                # vouches for. Remove the record (other sessions of the
                # same user bound to the new epoch stay).
                del self.sessions[session_id]
            else:
                # Update last access
                session_data["last_access"] = now
                return ValidatedSession(session_id, username, rekey_epoch)

        # The record was removed above (expired or bound to a superseded
        # epoch). Sever the sockets that handshook on it too, after the
        # lock is released and best-effort: once the record is gone no
        # sweep can find this session again, and a socket is authorised
        # once at handshake, so a left-over sid would keep receiving the
        # user's events (``settings_changed`` carries plaintext secrets).
        self._disconnect_expired_sockets([session_id])
        if expired_username is not None:
            logger.debug(
                f"Session {session_id[:8]}... expired for {expired_username}"
            )
        return None

    def validate_session(self, session_id: str) -> Optional[str]:
        """Validate a session and return username if valid.

        Updates last access time.

        Raises:
            SessionValidationUnavailableError: the epoch was unreadable;
                refuse the request but keep the session (see
                ``validate_session_identity``).
        """
        identity = self.validate_session_identity(session_id)
        return None if identity is None else identity.username

    def touch_session(self, session_id: str) -> None:
        """Refresh a session's ``last_access`` without enforcing the timeout.

        Called on socket activity: a user actively watching a long research
        run makes no HTTP requests, so the request-path idle-timeout refresh
        (in ``validate_session``) never fires and the session would silently
        expire mid-run. Unlike ``validate_session`` this never deletes an
        expired session — it only bumps ``last_access`` for one still present.
        """
        if not session_id:
            return
        with self._lock:
            session_data = self.sessions.get(session_id)
            if session_data is not None:
                session_data["last_access"] = datetime.datetime.now(UTC)

    def session_owner(self, session_id: str) -> Optional[str]:
        """The username the server-side record for ``session_id`` names.

        ``None`` when there is no record. NOT a validation, exactly like
        ``session_belongs_to``: no epoch read, no expiry check, no
        ``last_access`` refresh, so it must never gate access to anything.
        Its only caller is ``_revoke_server_session``, which scopes a
        teardown with it: an epoch-read fault must not stop the teardown
        of a cookie that is being cleared anyway.
        """
        if not session_id:
            return None
        with self._lock:
            session_data = self.sessions.get(session_id)
            return None if session_data is None else session_data["username"]

    def session_belongs_to(self, session_id: str, username: str) -> bool:
        """Whether a server-side record still binds ``session_id`` to
        ``username``.

        NOT a validation: no epoch read, no expiry check, no
        ``last_access`` refresh, so it must never gate access to anything.
        Its only caller is logout during an epoch-read fault, where it
        scopes what logout may destroy: a cookie whose record is already
        gone tears down nothing of that user's beyond its own cookie.
        """
        if not session_id:
            return False
        with self._lock:
            session_data = self.sessions.get(session_id)
            return (
                session_data is not None
                and session_data["username"] == username
            )

    def destroy_session(self, session_id: str):
        """Destroy a session and clean up."""
        username = None
        with self._lock:
            if session_id in self.sessions:
                username = self.sessions[session_id]["username"]
                del self.sessions[session_id]

        # Logged after releasing the lock: see the warning in __init__
        # about not logging while holding _lock.
        if username is not None:
            logger.debug(
                f"Destroyed session {short_id(session_id)} for user {username}"
            )

    def destroy_all_user_sessions(self, username: str) -> int:
        """Destroy all sessions for a given user. Returns count destroyed."""
        with self._lock:
            to_delete = [
                sid
                for sid, data in self.sessions.items()
                if data["username"] == username
            ]
            for sid in to_delete:
                del self.sessions[sid]
        if to_delete:
            logger.debug(
                f"Destroyed {len(to_delete)} session(s) for user {username}"
            )
        return len(to_delete)

    def cleanup_expired_sessions(self):
        """Remove all expired sessions and disconnect their live sockets."""
        now = datetime.datetime.now(UTC)
        expired = []

        with self._lock:
            for session_id, data in self.sessions.items():
                timeout = (
                    self.remember_me_timeout
                    if data["remember_me"]
                    else self.session_timeout
                )
                if now - data["last_access"] > timeout:
                    expired.append(session_id)

            for session_id in expired:
                del self.sessions[session_id]

        if expired:
            logger.info(f"Cleaned up {len(expired)} expired sessions")
            # Tear down any sockets still attached to these now-dead sessions.
            # A socket is authorised once at handshake and then frozen, so
            # without this an expired session's tab keeps receiving the user's
            # events. Done AFTER releasing the lock (disconnect reaches into
            # the socket server) and best-effort — socket teardown must never
            # break session cleanup.
            self._disconnect_expired_sockets(expired)

    @staticmethod
    def _disconnect_expired_sockets(session_ids: list[str]) -> None:
        """Best-effort disconnect of the sockets for removed session ids.

        Called by ``cleanup_expired_sessions`` and by
        ``validate_session_identity`` whenever it removes a record (idle
        expiry, superseded epoch, unvouchable durable state). Never raises.

        Lazy-imports the socket layer to avoid an import cycle and to
        tolerate its absence in non-web contexts (CLI, tests). Each session is
        torn down independently so one failure can't strand the rest.

        Retargeted from the deleted Flask ``SocketIOService`` onto the ASGI
        layer. The old import raised ``ModuleNotFoundError`` into the bare
        ``except Exception`` below, so this path silently disconnected
        nothing: an idle-expired session's sockets stayed live and kept
        receiving that user's events -- including ``settings_changed``. It
        was masked whenever the idle-DB-close
        sweep happened to tear the user down anyway, but not when they had
        another live session or an in-flight research run.
        """
        try:
            from ..services.socketio_asgi import disconnect_session
        except Exception:
            logger.opt(exception=True).warning(
                "Failed to resolve socket layer for expired-session teardown"
            )
            return
        for session_id in session_ids:
            try:
                disconnect_session(session_id)
            except Exception:
                logger.opt(exception=True).warning(
                    "Failed to disconnect sockets for an expired session"
                )

    def get_active_sessions_count(self) -> int:
        """Get count of active sessions."""
        self.cleanup_expired_sessions()
        with self._lock:
            return len(self.sessions)

    def get_user_sessions(self, username: str) -> list:
        """Get all active sessions for a user."""
        user_sessions = []
        with self._lock:
            for session_id, data in self.sessions.items():
                if data["username"] == username:
                    user_sessions.append(
                        {
                            "session_id": session_id[:8] + "...",
                            "created_at": data["created_at"],
                            "last_access": data["last_access"],
                            "remember_me": data["remember_me"],
                        }
                    )
        return user_sessions

    def get_active_usernames(self) -> Set[str]:
        """Return set of usernames with at least one non-expired session."""
        now = datetime.datetime.now(UTC)
        with self._lock:
            return {
                data["username"]
                for data in self.sessions.values()
                if now - data["last_access"]
                <= (
                    self.remember_me_timeout
                    if data["remember_me"]
                    else self.session_timeout
                )
            }

    def has_active_sessions_for(self, username: str) -> bool:
        """Check if a user has any non-expired, epoch-current session.

        Uses the same epoch check as ``validate_session_identity``: a
        record bound to an epoch that is no longer committed (the password
        was changed, possibly in another worker) is NOT active, even
        before its next validation removes it. When the epoch cannot be
        read, raise ``SessionValidationUnavailableError`` without changing
        any records. Cleanup callers must defer shared teardown when the
        answer is unknown. Readable durable state that cannot vouch for an
        identity still counts as inactive.
        Read-only: records are neither refreshed nor removed here.
        """
        now = datetime.datetime.now(UTC)
        with self._lock:
            bound_epochs = {
                data["rekey_epoch"]
                for data in self.sessions.values()
                if data["username"] == username
                and now - data["last_access"]
                <= (
                    self.remember_me_timeout
                    if data["remember_me"]
                    else self.session_timeout
                )
            }
        if not bound_epochs:
            return False
        # The epoch is a file read: outside _lock, like validation.
        try:
            current_epoch = read_user_authorization_epoch(username)
        except RekeyEpochUnreadableError as error:
            # Identity is a separate field; exception text contains only errno.
            # bearer:disable python_lang_exception
            raise SessionValidationUnavailableError(
                username, error.errno
            ) from None
        except RekeyOperationalError:
            return False
        return current_epoch in bound_epochs


# Module-level singleton
session_manager = SessionManager()