keepup-admin 0.1.0__py3-none-any.whl

keepup/auth/__init__.py

@@ -0,0 +1,7 @@
+"""Authentication: providers, dependencies, the panel session and its routes.
+
+The provider is chosen by ``config/auth.yaml`` through
+:mod:`keepup.auth.factory`. What the application adds -- documents a person
+must accept, the rule a password is held to, where a sign-in is written down --
+arrives through settings, not from here.
+"""

keepup/auth/config.py

@@ -0,0 +1,128 @@
+"""Where the accounts of this deployment live.
+
+One source: the application's own ``users`` table. Signing in through an
+external identity provider is not a second source and not a second provider --
+the account is still here, the provider only proves who is knocking. That path
+is configured by the application through ``KeepupSettings.oidc`` and lives in
+:mod:`keepup.auth.oidc`.
+
+Until task 170 there was a second provider, an Apache Directory one, which
+wrote into the directory as much as it read from it. It was never enabled on
+any deployment and has been removed; ``provider: "ldap"`` now stops the start
+rather than falling back to local, because a deployment expecting a directory
+and silently getting local sign-in is an open door where nobody looked for one.
+"""
+
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+from keepup.roles import ROLE_CLIENT
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "AuthConfig",
+    "AuthProviderType",
+    # Assigned inside a try at module level: the configuration is read on
+    # import, and an application takes the object rather than building one.
+    "auth_config",
+]
+
+#: Kept as an enum although it has one member: the configuration file says a
+#: name, and a name has to be validated against something.
+class AuthProviderType(str, Enum):
+    """Where a deployment keeps its accounts."""
+
+    LOCAL = "local"
+
+
+#: Removed providers, named so that a deployment still asking for one is told
+#: what happened instead of quietly getting something else.
+RETIRED_PROVIDERS = {
+    "ldap": "the Apache Directory provider was removed in task 170; put an "
+            "OpenID Connect provider in front of your directory (Keycloak, for "
+            "example) and configure the application with it",
+}
+
+
+class RetiredProvider(RuntimeError):
+    """Raised at start-up for a provider that no longer exists."""
+
+
+class AuthConfig(BaseModel):
+    """The authentication settings of this deployment."""
+
+    model_config = ConfigDict(validate_default=True)
+
+    provider: AuthProviderType = Field(AuthProviderType.LOCAL,
+                                       description="Where the accounts live")
+    enabled: bool = Field(True, description="Whether authentication is enabled")
+    default_role: str = Field(ROLE_CLIENT, description="Default role")
+
+    #: No default. The placeholder that used to stand here is one of the
+    #: values keepup.auth.signing_key refuses outright, so it never worked as
+    #: a default -- it only put a key-shaped string into the package.
+    jwt_secret: str = Field("", description="JWT signing key; supplied by the deployment")
+    jwt_algorithm: str = Field("HS256", description="JWT algorithm")
+    jwt_expire_minutes: int = Field(1440, description="Token lifetime, in minutes")
+
+    @classmethod
+    def from_yaml(cls, config_path: Path = Path("config/auth.yaml")) -> "AuthConfig":
+        """Load the configuration from a YAML file."""
+        if not config_path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {config_path}")
+
+        with open(config_path, 'r', encoding='utf-8') as f:
+            config_data = yaml.safe_load(f) or {}
+
+        return cls.from_mapping(config_data)
+
+    @classmethod
+    def from_mapping(cls, config_data: Dict[str, Any]) -> "AuthConfig":
+        """Build the configuration from already parsed data."""
+        section = config_data.get("auth", config_data)
+        provider_str = str(section.get("provider", "local")).lower()
+
+        if provider_str in RETIRED_PROVIDERS:
+            raise RetiredProvider(
+                f"config/auth.yaml asks for the '{provider_str}' provider: "
+                f"{RETIRED_PROVIDERS[provider_str]}")
+
+        try:
+            provider = AuthProviderType(provider_str)
+        except ValueError:
+            print(f"Unknown provider '{provider_str}', falling back to 'local'")
+            provider = AuthProviderType.LOCAL
+
+        jwt_config = config_data.get("jwt", {}) or {}
+
+        return cls(
+            provider=provider,
+            enabled=section.get("enabled", True),
+            default_role=section.get("default_role", ROLE_CLIENT),
+            jwt_secret=jwt_config.get("secret", ""),
+            jwt_algorithm=jwt_config.get("algorithm", "HS256"),
+            jwt_expire_minutes=jwt_config.get("expire_minutes", 1440),
+        )
+
+
+try:
+    config_path = Path(os.environ.get("AUTH_CONFIG_PATH", "config/auth.yaml"))
+    auth_config = AuthConfig.from_yaml(config_path)
+    print(f"Authentication configuration loaded from {config_path}")
+    print(f"Provider in use: {auth_config.provider}")
+except RetiredProvider:
+    # Never swallowed: the whole point is that this deployment must not come up
+    # signing people in some other way than it asked for.
+    raise
+except FileNotFoundError as e:
+    print(f"Warning: {e}. Falling back to the default configuration.")
+    auth_config = AuthConfig()
+except Exception as e:
+    print(f"Could not load the configuration: {e}. Falling back to the default one.")
+    auth_config = AuthConfig()

keepup/auth/dependencies.py

@@ -0,0 +1,485 @@
+"""Who is making this request, as FastAPI dependencies.
+
+`get_current_user` and `get_current_admin` are what a route says instead of
+checking a token itself; every plugin route generated by the registry gets the
+result handed to it. Issuing and reading tokens lives here too, at module level
+rather than inside the route, so that a sign-in can be exercised without HTTP.
+
+The password rule and where a sign-in is written down are not decided here: the
+application supplies both through KeepupSettings, because a rule the framework
+invented would be a different rule from the one its invitations enforce.
+"""
+
+import asyncio
+import logging
+from datetime import timedelta, datetime
+from typing import Optional, List, Dict
+
+import bcrypt
+from fastapi import HTTPException, Depends, Request
+from jose import jwt, JWTError
+from starlette import status
+
+from keepup.auth import panel_session
+from keepup.auth.dto.token import TokenData
+from keepup.auth.factory import AuthProviderFactory
+from keepup.auth.providers.base import AuthProvider, ALGORITHM, oauth2_scheme
+from keepup.auth.signing_key import resolve_signing_key
+from keepup.roles import ROLE_ADMIN, ROLE_CLIENT
+from keepup.auth.config import auth_config, AuthProviderType
+from keepup.db import DatabaseManager, db_config, DatabaseManagerV2
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "create_user",
+    "get_all_users",
+    "get_current_admin",
+    "get_current_user",
+    "get_optional_user",
+    "get_panel_user",
+    "get_user_by_id",
+    "get_user_by_username",
+    "issue_session_token",
+]
+
+logger = logging.getLogger(__name__)
+
+from keepup.auth import seed_accounts
+
+auth_provider: AuthProvider = AuthProviderFactory.get_provider()
+
+
+async def get_user_by_username_async(username: str):
+    """Return a user by name, including the extra fields."""
+    return await auth_provider.get_user_info(username)
+
+
+def get_user_by_username(username: str):
+    """Return a user by name, including the extra fields."""
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+    if loop.is_running():
+        import asyncio as async_module
+        import threading
+
+        result = None
+        event = threading.Event()
+
+        def run_in_thread():
+            nonlocal result
+            new_loop = async_module.new_event_loop()
+            try:
+                async_module.set_event_loop(new_loop)
+                result = new_loop.run_until_complete(
+                    auth_provider.get_user_info(username)
+                )
+            except Exception as e:
+                logger.error(f"Error in thread: {e}")
+            finally:
+                # Closed on every path, including the failing one: a loop holds
+                # an epoll descriptor and a self-pipe, and this runs once per
+                # authenticated call. Left open, a long-lived process reaches its
+                # descriptor limit and then cannot open anything at all -- which
+                # surfaces as "database connection failed", not as a leak.
+                try:
+                    new_loop.close()
+                except Exception as e:
+                    logger.warning(f"Could not close the worker event loop: {e}")
+                async_module.set_event_loop(None)
+                event.set()
+
+        thread = threading.Thread(target=run_in_thread)
+        thread.start()
+        thread.join(timeout=10)
+
+        if event.is_set() and result is not None:
+            return result
+        else:
+            logger.warning(f"Async call failed, falling back to DB for user {username}")
+            return None
+
+    user_info = loop.run_until_complete(
+        auth_provider.get_user_info(username)
+    )
+
+    return user_info
+
+
+def get_user_by_id(user_id: int):
+    """Return a user by id, for any configured auth provider."""
+    # TODO: auth_provider needs a lookup by id as well; without it this only
+    # works against the local database.
+    result = DatabaseManager.execute_query(
+        "SELECT * FROM users WHERE id = ?",
+        (user_id,),
+        fetch_one=True
+    )
+    return result
+
+
+def get_system_user_id():
+    """Return the id of the system user that background work is signed with.
+
+    The account itself is created once, at start-up, by
+    `keepup.auth.seed_accounts` -- without a password anyone could sign in with.
+    Creating it here as well is what let three spellings of it drift apart; a
+    missing account now means the schema has not been initialised, and inventing
+    one with a password of our own would only hide that.
+    """
+    try:
+        system_user = get_user_by_username(seed_accounts.SYSTEM_USERNAME)
+        if system_user:
+            return system_user['id']
+        logger.error(
+            "The service account '%s' is not in the database: the schema was "
+            "not initialised. Background work will go unsigned.",
+            seed_accounts.SYSTEM_USERNAME)
+        return None
+    except Exception as e:
+        logger.error(f"Error getting system user: {e}")
+        return None
+
+
+def get_all_users():
+    """Return every user, for any configured auth provider."""
+    return DatabaseManager.execute_query(
+        "SELECT id, username, status, role, created_at FROM users ORDER BY created_at DESC"
+    )
+
+
+def save_user_to_db(username: str, password: str):
+    """Create a user, for any configured auth provider."""
+    password_hash = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
+
+    query = """
+    INSERT INTO users (username, password_hash, status, role) 
+    VALUES (?, ?, ?, ?)
+    """
+
+    if db_config.is_postgres():
+        query += " RETURNING id"
+
+    try:
+        user_id = DatabaseManager.execute_commit(
+            query,
+            (username, password_hash, "blocked", ROLE_CLIENT)
+        )
+        return user_id
+
+    except Exception as e:
+        if "unique constraint" in str(e).lower() or "duplicate" in str(e).lower():
+            raise HTTPException(status_code=400, detail="Username already exists")
+        raise e
+
+
+async def create_user(
+        username: str,
+        password: str,
+        email: str = None,
+        phone: str = None,
+        full_name: str = None,
+        agree_terms: bool = False
+):
+    user_id = auth_provider.create_user_in_db(username, password, email, phone, full_name, agree_terms)
+
+    user_data = {"user_id": user_id, "username": (username,), "password": (password,), "email": email, "phone": phone,
+                 "full_name": full_name, "agree_terms": agree_terms}
+
+    await auth_provider.create_user(user_data)
+
+    # The id is returned to the caller: it was computed and then thrown away,
+    # while callers assigned the result to a variable and got None. The nearest
+    # consequence was that creating test users considered itself unsuccessful
+    # every time and never got as far as their wallets.
+    return user_id
+
+
+def update_user(user_id: int, status: Optional[str] = None, role: Optional[str] = None,
+                email: Optional[str] = None, phone: Optional[str] = None, full_name: Optional[str] = None):
+    """Update a user, including the extra fields."""
+    conn = DatabaseManager.get_connection()
+    cursor = conn.cursor()
+
+    update_fields = []
+    params = []
+
+    if status is not None:
+        update_fields.append("status = ?")
+        params.append(status)
+
+    if role is not None:
+        update_fields.append("role = ?")
+        params.append(role)
+
+    if email is not None:
+        update_fields.append("email = ?")
+        params.append(email)
+
+    if phone is not None:
+        update_fields.append("phone = ?")
+        params.append(phone)
+
+    if full_name is not None:
+        update_fields.append("full_name = ?")
+        params.append(full_name)
+
+    if not update_fields:
+        return
+
+    update_fields.append("updated_at = CURRENT_TIMESTAMP")
+    params.append(user_id)
+
+    query = f"UPDATE users SET {', '.join(update_fields)} WHERE id = ?"
+
+    if db_config.is_postgres():
+        query = query.replace('?', '%s')
+
+    cursor.execute(query, params)
+    conn.commit()
+    cursor.close()
+    conn.close()
+
+
+async def authenticate(username: str, password: str):
+    return await auth_provider.authenticate(username=username, password=password)
+
+
+def verify_password(plain_password: str, hashed_password: str):
+    return bcrypt.checkpw(plain_password.encode('utf-8'), hashed_password.encode('utf-8'))
+
+
+#: When the session this token belongs to began. Carried by the token rather
+#: than kept on the server, which keeps no session state; renewal reads it to
+#: know whether the session has gone on long enough.
+SESSION_START_CLAIM = "sst"
+
+
+def create_access_token(
+        data: dict,
+        expires_delta: Optional[timedelta] = None,
+        session_started_at: Optional[datetime] = None,
+):
+    to_encode = data.copy()
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=15)
+    to_encode.update({"exp": expire})
+
+    # A renewal carries the beginning of the session forward unchanged. Stamping
+    # "now" on every renewal is what made a session endless: each exchange would
+    # reset the clock that is supposed to be running out.
+    started = session_started_at or datetime.utcnow()
+    to_encode.setdefault(SESSION_START_CLAIM, int(started.timestamp()))
+
+    encoded_jwt = jwt.encode(to_encode, resolve_signing_key(), algorithm=ALGORITHM)
+    return encoded_jwt
+
+
+def issue_session_token(user_id: int, username: str, sid: Optional[str] = None,
+                        session_started_at: Optional[datetime] = None) -> dict:
+    """A token bound to a session record: a new session, or `sid` carried on.
+
+    Every token the server hands a person or an agent goes through here, so every
+    one of them can be revoked.
+    """
+    from keepup.auth.providers.base import ACCESS_TOKEN_EXPIRE_MINUTES
+    lifetime = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+    if sid is None:
+        sid = panel_session.open_session(user_id, lifetime)
+    else:
+        panel_session.extend(sid, lifetime)
+    token = create_access_token({"sub": username, panel_session.SESSION_CLAIM: sid},
+                                expires_delta=lifetime, session_started_at=session_started_at)
+    return {"access_token": token, "session_id": sid,
+            "expires_in": int(lifetime.total_seconds())}
+
+
+def _session_start(payload: dict) -> Optional[datetime]:
+    """Read the session's beginning out of a decoded token, or None."""
+    started = payload.get(SESSION_START_CLAIM)
+    if started is None:
+        return None
+    try:
+        return datetime.utcfromtimestamp(int(started))
+    except (TypeError, ValueError, OSError):
+        return None
+
+
+async def request_token(request: Request, bearer: Optional[str] = Depends(oauth2_scheme)) -> Optional[str]:
+    """The request's token: a real bearer header, else the panel session cookie."""
+    return panel_session.token_from_request(request, bearer)
+
+
+def _session_is_live(payload: dict) -> bool:
+    """A token that names a session is good only while that session is.
+
+    A token without one was issued before sessions were recorded and is accepted
+    until it expires -- at most a day after the deployment.
+    """
+    sid = payload.get(panel_session.SESSION_CLAIM)
+    if sid is None:
+        return True
+    try:
+        return panel_session.is_active(sid)
+    except Exception as error:
+        # Failing open here would make revocation depend on the database being
+        # up; failing closed only costs a retry.
+        logger.error(f"Could not check session {str(sid)[:8]}...: {error}")
+        return False
+
+
+async def get_current_user(token: str = Depends(request_token)):
+    """Return the current user of this token.
+
+    The signature carries nothing but the token, and that is a rule rather than
+    a detail: a scalar parameter with a default on a dependency is a *query*
+    parameter to FastAPI. One used to stand here -- `ignore_empty_user` -- and
+    it was published on every route of the framework and of every plugin, as a
+    switch a caller could set to turn the check off. Code that wants None
+    instead of a refusal calls get_optional_user() below, which is not a
+    dependency and takes the token as an argument.
+
+    One branch since task 170: the accounts live in this application's table.
+    Somebody who signed in through an external provider is here too -- that
+    path ends by issuing this same session, so by the time a request arrives
+    there is nothing left to tell apart.
+    """
+    return await _get_local_user(token)
+
+
+def _token_expiry(payload: dict) -> Optional[datetime]:
+    """Read the expiry out of a decoded token payload, or None."""
+    expires_at = payload.get("exp")
+    if expires_at is None:
+        return None
+    try:
+        return datetime.utcfromtimestamp(int(expires_at))
+    except (TypeError, ValueError, OSError):
+        return None
+
+
+async def _get_local_user(token: Optional[str], ignore_empty_user: bool = False):
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        if token is None:
+            if ignore_empty_user:
+                return None
+            raise credentials_exception
+        payload = jwt.decode(token, resolve_signing_key(), algorithms=[ALGORITHM])
+        username: str = payload.get("sub")
+        if username is None:
+            if ignore_empty_user:
+                return None
+            raise credentials_exception
+        token_data = TokenData(username=username)
+    except JWTError:
+        if ignore_empty_user:
+            return None
+        raise credentials_exception
+
+    if not _session_is_live(payload):
+        raise credentials_exception
+
+    user = get_user_by_username(token_data.username)
+    if user is None:
+        raise credentials_exception
+
+    fresh_user = get_user_by_username(token_data.username)
+    if fresh_user["status"] != "active":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is blocked",
+        )
+
+    # When this session ends. The server keeps no session state, so the moment
+    # the token is decoded is the only place that knows -- and a handler that
+    # needs to warn about the end (or record it alongside a websocket key)
+    # cannot decode the token itself: it never sees it.
+    fresh_user = dict(fresh_user)
+    fresh_user["token_expires_at"] = _token_expiry(payload)
+    fresh_user["session_started_at"] = _session_start(payload)
+    fresh_user["session_id"] = payload.get(panel_session.SESSION_CLAIM)
+
+    return fresh_user
+
+
+async def get_optional_user(token: Optional[str]):
+    """The user of this token, or None when there is none.
+
+    For callers outside the request cycle -- a route that serves both a signed-in
+    user and a guest, a socket that authenticates itself. Deliberately not a
+    dependency: see get_current_user() for what happens when a switch like this
+    ends up in a dependency's signature.
+
+    Args:
+        token: the bearer or panel token, or None.
+
+    Returns:
+        The user, or None when the token is absent, unreadable or names nobody.
+    """
+    return await _get_local_user(token, ignore_empty_user=True)
+
+
+async def get_current_admin(current_user: dict = Depends(get_current_user)):
+    if current_user["role"] != ROLE_ADMIN:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access required",
+        )
+    return current_user
+
+
+# --- The panel session's user -------------------------------------------------
+
+#: Set by the application through configure_panel_gate(): given a user, it
+#: returns the documents that user has yet to accept. The framework has no
+#: documents of its own, so without it the gate is simply open.
+pending_documents = None
+
+
+def configure_panel_gate(pending=None):
+    """Supply the application's "documents this user must accept" rule.
+
+    Setting it to None opens the gate: an application with no documents is not
+    the same as an application that keeps the previous one's.
+    """
+    global pending_documents
+    pending_documents = pending
+
+
+def _authenticated_by_cookie(request: Request) -> bool:
+    return panel_session.real_bearer(_bearer_of(request)) is None \
+        and bool(request.cookies.get(panel_session.SESSION_COOKIE))
+
+
+def _bearer_of(request: Request) -> Optional[str]:
+    scheme, _, value = (request.headers.get("authorization") or "").partition(" ")
+    return value if scheme.lower() == "bearer" else None
+
+
+async def get_panel_user(request: Request, current_user: dict = Depends(get_current_user)):
+    """The user of a plugin route, refused while a required document is not accepted.
+
+    Only for the panel's cookie session. An agent or a script sends Bearer, and a
+    new version of a document must not stop an agent in the middle of a rental;
+    what a developer needs a script for -- an API key -- is created in the panel.
+    """
+    if _authenticated_by_cookie(request) and pending_documents is not None:
+        missing = pending_documents(current_user)
+        if missing:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail={
+                "code": "agreements_required",
+                "message": "Accept " + ", ".join(d.title for d in missing) + " to continue",
+                "pending": [d.id for d in missing],
+            })
+    return current_user

keepup/auth/dto/token.py

@@ -0,0 +1,31 @@
+"""What a sign-in hands back, and what a token carries.
+
+Two shapes rather than dictionaries: the reply is part of the API and the claim
+set is read on every request, and both used to be assembled by hand in several
+places that disagreed about the field names.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "Token",
+    "TokenData",
+]
+
+
+class Token(BaseModel):
+    """What a successful sign-in hands back."""
+
+    access_token: str
+    token_type: str
+    success: bool = True
+
+
+class TokenData(BaseModel):
+    """The claims read back out of a token."""
+
+    username: Optional[str] = None

keepup/auth/factory.py

@@ -0,0 +1,28 @@
+"""Which provider answers "is this the right password".
+
+Since task 170 there is one answer -- accounts live in this application's own
+table -- but the choice stays a lookup rather than a call of LocalAuthProvider:
+`config/auth.yaml` names a provider, and a name that no longer exists has to
+stop the start with a message instead of silently becoming the local one.
+"""
+
+from keepup.auth.providers.base import AuthProvider
+from keepup.auth.config import auth_config, AuthProviderType
+from keepup.auth.providers.local import LocalAuthProvider
+
+
+class AuthProviderFactory:
+    """Factory creating authentication providers."""
+
+    #: One entry since task 170: accounts live in this application's table.
+    #: Signing in through an external provider is a separate path, not another
+    #: entry here -- that path never receives a password to check.
+    _providers = {
+        AuthProviderType.LOCAL: LocalAuthProvider,
+    }
+
+    @classmethod
+    def get_provider(cls) -> AuthProvider:
+        """Return the currently configured authentication provider."""
+        provider_class = cls._providers.get(auth_config.provider, LocalAuthProvider)
+        return provider_class()