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.

10.9 KB
Raw Blame
"""
Authentication database initialization and management.
This manages the central ldr_auth.db which only stores usernames.
"""

import errno
import os
import threading
from contextlib import contextmanager
from pathlib import Path
from typing import Optional

from loguru import logger
from sqlalchemy import create_engine, event
from sqlalchemy.engine import Engine
from sqlalchemy.orm import sessionmaker, Session
from sqlalchemy.pool import QueuePool
from sqlalchemy.schema import CreateIndex, CreateTable

from ..config.paths import get_data_directory
from .models.auth import User
from .pool_config import POOL_PRE_PING, POOL_RECYCLE_SECONDS


# Global cached engine for auth database to prevent file descriptor leaks
_auth_engine: Optional[Engine] = None
_auth_engine_path: Optional[Path] = (
    None  # Track the path the engine was created for
)
_auth_engine_lock = threading.Lock()


def get_auth_db_path() -> Path:
    """Get the path to the authentication database."""
    return get_data_directory() / "ldr_auth.db"


def _best_effort_chmod(path: Path, mode: int) -> None:
    """Tighten permissions on the auth DB file to ``mode``, never raising.

    Mirrors ``encrypted_db._best_effort_chmod``: permission hardening
    must NOT be able to break auth database creation. On filesystems
    where chmod raises even for the owner (some Docker bind mounts and
    network/FUSE volumes), the file stays at its umask default and the
    downgrade is surfaced at warning level — ``ldr_auth.db`` holds
    usernames and login metadata, so a silent group/world-readable
    state deserves visibility.
    """
    try:
        os.chmod(str(path), mode)
    except OSError as exc:
        # Copy out before logging: the check-sensitive-logging pre-commit
        # hook flags any reference to the ``except`` variable itself inside
        # a non-debug logger call (including its attributes, since e.g.
        # e.strerror carries the same detail as str(e)) as a potential
        # secret leak. errno/strerror are plain OS error codes/text, not
        # sensitive, but the hook can't tell that apart -- so, like
        # encrypted_db._db_path_is_symlinked's ``target = f"...{exc
        # .strerror}>"``, the detail is copied into ordinary local
        # variables first and only those are interpolated below.
        chmod_errno = exc.errno
        chmod_strerror = exc.strerror
        logger.warning(
            f"Could not set permissions {oct(mode)} on auth database "
            f"{path}; left at filesystem default "
            f"(errno={chmod_errno}, {chmod_strerror})"
        )


def _create_private_file(path: Path) -> None:
    """Create ``path`` as an empty, owner-only regular file, never via a link.

    Mirrors ``encrypted_db._create_private_file``: ``O_CREAT | O_EXCL``
    fails when anything exists at ``path`` — including a symlink, dangling
    or not — and ``O_NOFOLLOW`` is added where the platform has it, so a
    planted symlink is refused rather than followed. This closes the
    creation-race window where SQLite would otherwise create the file at
    umask-default permissions (typically 0644) before the post-DDL chmod
    ever runs. Callers tolerate ``FileExistsError`` — the file may already
    exist from a previous run, in which case SQLite simply opens it and the
    existing-file chmod paths (here and in ``_get_auth_engine``) tighten it.
    """
    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
    try:
        fd = os.open(str(path), flags, 0o600)
    except OSError as exc:
        # A platform may report the symlink through O_NOFOLLOW (ELOOP)
        # before O_EXCL gets to say EEXIST; both mean "something is
        # already at this path", so callers see one exception type.
        if exc.errno == errno.ELOOP:
            raise FileExistsError(
                errno.EEXIST, "Path is a symlink", str(path)
            ) from exc
        raise
    os.close(fd)


def _get_auth_engine() -> Engine:
    """
    Get or create a cached engine for the auth database.

    This prevents file descriptor leaks by reusing a single engine
    instead of creating a new one for every session.

    The engine is invalidated if the data directory path changes
    (e.g., during testing when LDR_DATA_DIR is set to a temp directory).
    """
    global _auth_engine, _auth_engine_path

    auth_db_path = get_auth_db_path()

    # Check if we have a cached engine for the current path
    if _auth_engine is not None and _auth_engine_path == auth_db_path:
        return _auth_engine

    with _auth_engine_lock:
        # Double-check after acquiring lock
        if _auth_engine is not None and _auth_engine_path == auth_db_path:
            return _auth_engine

        # If path changed, dispose old engine first
        if _auth_engine is not None and _auth_engine_path != auth_db_path:
            try:
                _auth_engine.dispose()
                logger.debug(
                    "Disposed auth engine due to data directory change"
                )
            except Exception:
                logger.warning("Error disposing old auth engine")
            _auth_engine = None
            _auth_engine_path = None

        # Ensure database exists
        if not auth_db_path.exists():
            init_auth_database()

        # SECURITY: tighten permissions whenever the engine is (re)created
        # for this path. init_auth_database() already does this for a
        # fresh database, but this call also covers an existing file from
        # an older install that predates owner-only creation (still 0644)
        # — upgrading and restarting is then enough to tighten it, with no
        # migration step. Best-effort and idempotent; this block runs at
        # most once per process per path since the cached-engine check
        # above short-circuits every later call for the same path.
        _best_effort_chmod(auth_db_path, 0o600)

        # Moderate pool — auth DB is unencrypted SQLite used by every
        # authenticated request via before_request middleware.
        # See ADR-0004 for pool sizing rationale.
        _auth_engine = create_engine(
            f"sqlite:///{auth_db_path}",
            poolclass=QueuePool,
            pool_size=10,
            max_overflow=20,
            pool_pre_ping=POOL_PRE_PING,
            pool_recycle=POOL_RECYCLE_SECONDS,
            echo=False,
        )

        def _apply_auth_pragmas(dbapi_connection, connection_record):
            dbapi_connection.execute("PRAGMA busy_timeout = 10000")
            dbapi_connection.execute("PRAGMA temp_store = MEMORY")

        event.listen(_auth_engine, "connect", _apply_auth_pragmas)

        _auth_engine_path = auth_db_path
        logger.debug("Created cached auth database engine")

        return _auth_engine


def init_auth_database():
    """Initialize the authentication database if it doesn't exist.

    Uses SQL-level IF NOT EXISTS (via CreateTable/CreateIndex) so that
    concurrent calls are handled atomically by the database engine,
    eliminating the TOCTOU race in SQLAlchemy's checkfirst inspect.
    """
    auth_db_path = get_auth_db_path()

    # Ensure the data directory exists.
    # Lazy import: this runs during early app bootstrap, so avoid a
    # top-level security -> ... -> database import cycle.
    from ..security.directory_creation import create_directory

    create_directory(
        auth_db_path.parent,
        context="auth database directory",
    )

    logger.debug(f"Ensuring auth database at {auth_db_path}")

    # SECURITY: materialize the file ourselves, owner-only and no-follow,
    # before handing the path to SQLite. Without this, SQLite's own lazy
    # create below lands the file at umask-default permissions (typically
    # 0644) for the window between that create and the post-DDL chmod
    # further down — a same-host reader with an fd opened in that window
    # keeps read access even after the chmod. This call is idempotent and
    # is what init_auth_database's callers rely on for repeated/concurrent
    # invocations (see the "IF NOT EXISTS" DDL below), so a FileExistsError
    # from an already-present file is expected and tolerated — but only
    # when it is a regular file. init_auth_database() only runs when
    # _get_auth_engine() sees auth_db_path.exists() is False, which is
    # also true for a dangling symlink, so a dangling symlink at this
    # path is caught right here and refused. An existing database file —
    # including one reached through a symlink to an existing target —
    # never reaches this function at all: _get_auth_engine() opens it as
    # before via create_engine() and tightens it with its own chmod,
    # following the link the same way SQLite's open always has.
    try:
        _create_private_file(auth_db_path)
    except FileExistsError:
        if auth_db_path.is_symlink():
            raise ValueError(
                f"Auth database path {auth_db_path} is a symlink; "
                "refusing to create or open the database there"
            )

    # Create the database with a temporary engine
    engine = create_engine(f"sqlite:///{auth_db_path}")

    # Use SQL-level IF NOT EXISTS — idempotent and atomic, safe for
    # concurrent calls without Python-level locking.
    with engine.begin() as conn:
        conn.execute(CreateTable(User.__table__, if_not_exists=True))
        for index in User.__table__.indexes:
            conn.execute(CreateIndex(index, if_not_exists=True))

    # Dispose the temporary engine
    engine.dispose()

    # SECURITY: SQLite creates the file with umask-default permissions
    # (typically 0644), while every other DB artifact is owner-only.
    # Tighten to owner read/write — best-effort so a chmod-hostile
    # filesystem cannot break auth database creation.
    _best_effort_chmod(auth_db_path, 0o600)

    logger.debug("Auth database initialized successfully")


def get_auth_db_session() -> Session:
    """
    Get a session for the auth database.

    IMPORTANT: The caller MUST close the session when done to return
    the connection to the pool. Use auth_db_session() context manager
    for automatic cleanup.
    """
    engine = _get_auth_engine()
    SessionFactory = sessionmaker(bind=engine)
    return SessionFactory()


@contextmanager
def auth_db_session():
    """
    Context manager for auth database sessions.

    Usage:
        with auth_db_session() as session:
            user = session.query(User).filter_by(username=username).first()

    The session is automatically closed when the context exits.
    """
    session = get_auth_db_session()
    try:
        yield session
    finally:
        from ..utilities.resource_utils import safe_close

        safe_close(session, "auth DB session")


def dispose_auth_engine():
    """
    Dispose the auth engine (for shutdown/cleanup).
    """
    global _auth_engine, _auth_engine_path

    with _auth_engine_lock:
        if _auth_engine is not None:
            _auth_engine.dispose()
            _auth_engine = None
            _auth_engine_path = None
            logger.debug("Disposed auth database engine")