~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
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()