keepup-auth 0.4.0__py3-none-any.whl

keepup_auth/dependencies.py

@@ -0,0 +1,556 @@
+"""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
+
+import bcrypt
+from fastapi import HTTPException, Depends, Request
+import jwt
+from jwt import PyJWTError as JWTError
+from starlette import status
+
+from keepup_auth.usernames import is_valid_username
+from keepup_auth import panel_session
+from keepup_auth.dto.token import TokenData
+from keepup_auth.external_accounts import AccountUnavailable
+from keepup_auth.factory import AuthProviderFactory
+from keepup_auth.identity import access
+from keepup_auth.identity import runtime as identity_runtime
+from keepup_auth.identity.contract import IdentityRejected, ProviderUnavailable
+from keepup_auth.providers.base import AuthProvider, ALGORITHM, oauth2_scheme
+from keepup_auth.signing_key import resolve_signing_key
+from keepup_auth import user_roles
+from keepup.roles import ROLE_ADMIN, ROLE_CLIENT
+from keepup.db import 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.
+
+    Synchronous, for plugins and background jobs that cannot await. It used to
+    wrap the provider's coroutine -- and, called from a running loop, ran it on a
+    loop of its own in a thread that the caller waited for, holding the loop.
+    The provider answers synchronously itself now.
+    """
+    return user_roles.attach_roles(auth_provider.lookup_user(username))
+
+
+def get_user_by_id(user_id: int):
+    """Return a user by id, with the roles it holds.
+
+    The set travels with the account wherever the framework hands one out: code
+    that asks whether this person holds a role must not have to know which of
+    the two reads it came from.
+    """
+    # TODO: auth_provider needs a lookup by id as well; without it this only
+    # works against the local database.
+    return user_roles.attach_roles(
+        DatabaseManagerV2.execute_one("SELECT * FROM users WHERE id = :id", {"id": user_id}))
+
+
+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, with the roles each of them holds."""
+    users = DatabaseManagerV2.execute(
+        "SELECT id, username, status, role, created_at FROM users ORDER BY created_at DESC"
+    ) or []
+    held = {}
+    for row in DatabaseManagerV2.execute(
+            "SELECT user_id, role_name FROM user_roles") or []:
+        held.setdefault(row["user_id"], []).append(row["role_name"])
+    # One read for the whole list rather than one per user: this is the panel's
+    # first screen, and a query per row is what makes it slow on a real stand.
+    # An account whose set has never been filled in reads as its mirror says,
+    # which is known from the row already read.
+    return [dict(user, roles=(sorted(held.get(user["id"], []))
+                              or user_roles.held_by(user) or [ROLE_CLIENT]))
+            for user in users]
+
+
+def save_user_to_db(username: str, password: str):
+    """Create a user, for any configured auth provider."""
+    if not is_valid_username(username):
+        raise HTTPException(status_code=400, detail="Username may contain letters, digits "
+                                                    "and . _ @ + -, at most 64 characters")
+    password_hash = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
+
+    query = """
+    INSERT INTO users (username, password_hash, status, role) 
+    VALUES (:username, :password_hash, :status, :role)
+    """
+
+    try:
+        row = DatabaseManagerV2.execute_commit_returning(
+            query,
+            {"username": username, "password_hash": password_hash, "status": "blocked",
+             "role": ROLE_CLIENT})
+        user_id = row["id"] if row else None
+        if user_id is not None:
+            # The set is the truth about who this is, so a new account gets its
+            # row now rather than relying on the read's fallback until the next
+            # start (keepup/auth/user_roles.py).
+            user_roles.set_roles(user_id, [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)
+
+    # The account is created once, above. This used to hand the provider the
+    # same account again -- with the name and password as one-element tuples --
+    # and the provider's create_user calls back into this function: a second
+    # insert that failed on every creation and was logged and swallowed
+    # (keepup-79).
+
+    # 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."""
+    changes = {"status": status, "role": role, "email": email, "phone": phone,
+               "full_name": full_name}
+    changes = {column: value for column, value in changes.items() if value is not None}
+    if not changes:
+        return
+
+    # The column names come from the fixed set above, never from the caller.
+    assignments = ", ".join(f"{column} = :{column}" for column in changes)
+    DatabaseManagerV2.execute_commit(
+        f"UPDATE users SET {assignments}, updated_at = CURRENT_TIMESTAMP WHERE id = :id",
+        {**changes, "id": user_id})
+
+    # A caller setting the single role means "this person is a client now", so
+    # the whole set becomes that role. Leaving ADMIN in it would quietly keep a
+    # right the administrator had just taken away (keepup-51). Unchecked, because
+    # this column never checked: turning a call that worked into a refusal is not
+    # what a deprecated field should do on its way out.
+    if role is not None:
+        user_roles.set_roles(user_id, [role], checked=False)
+
+
+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:
+        # Every renewal is held to the window, not only /api/auth/refresh: the
+        # exchange of a token for the cookie carried a session on without the
+        # check, so a stolen token could be renewed for ever (keepup-64).
+        from keepup_auth import session_lifetime
+        if not session_lifetime.is_renewable(session_started_at):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="This session has run its course. Sign in again.",
+            )
+        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_owner(sid: str) -> Optional[int]:
+    """The account the live session ``sid`` belongs to, or None."""
+    try:
+        return panel_session.session_owner(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 None
+
+
+def _session_and_user(payload: dict, username: str):
+    """Whether the token's session is live and, only if it is, whose account it is.
+
+    A token is good only while its session is live and belongs to the account
+    the token names: otherwise it was not issued by this server, or names an
+    account recreated under the same name (keepup-64). A token without a
+    session is refused: tokens from before sessions were recorded were accepted
+    until they expired, and that transition is over (keepup-81).
+
+    The role set is read here too, in the same hop out of the event loop: one
+    more statement on the thread that read the account, not a second thread and
+    a second loop (keepup-43). It is not cached -- see keepup/auth/user_roles.py.
+    """
+    sid = payload.get(panel_session.SESSION_CLAIM)
+    if not sid:
+        return False, None
+    # One connection and one commit for the three reads, not one each: this
+    # runs on every request, and it was half of what a replica spent (keepup-85).
+    try:
+        with DatabaseManagerV2.shared_session():
+            owner = _session_owner(sid)
+            if owner is None:
+                return False, None
+            user = auth_provider.lookup_user(username)
+            if user is not None and int(user["id"]) != owner:
+                return False, None
+            return True, user_roles.attach_roles(user)
+    except Exception as error:
+        # A failed read leaves the shared session unable to commit; either way
+        # the answer is the one a failed check always gave -- refuse.
+        logger.error(f"Could not check the session of {username}: {error}")
+        return False, None
+
+
+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
+        # Every token this server issues has an expiry, a subject and a session;
+        # one without them was not issued here, or was issued before sessions
+        # were recorded -- long enough ago to have expired (keepup-64, keepup-81).
+        payload = jwt.decode(token, resolve_signing_key(), algorithms=[ALGORITHM],
+                             options={"require": ["exp", "sub", panel_session.SESSION_CLAIM]})
+        username: str = payload.get("sub")
+        if username is None:
+            if ignore_empty_user:
+                return None
+            raise credentials_exception
+        token_data = TokenData(username=username)
+    except _OUR_TOKEN_REFUSED:
+        # The signature is ours and the rest is not right: expired, not yet
+        # valid, or missing what every token of ours carries. It is refused
+        # here and never shown to the provider, which has no business seeing
+        # this framework's tokens.
+        if ignore_empty_user:
+            return None
+        raise credentials_exception
+    except JWTError:
+        # Not a token of this framework at all: another signature, another
+        # algorithm, not a JWT. The configured provider may know it.
+        return await _foreign_user(token, credentials_exception, ignore_empty_user)
+
+    # Both reads are blocking queries, so they leave the loop together: one hop
+    # to a worker thread per request, and the account is read once -- it used
+    # to be read twice, each time on a new event loop in a thread the request
+    # waited for while holding the loop (keepup-43).
+    live, user = await asyncio.to_thread(_session_and_user, payload, token_data.username)
+    if not live or user is None:
+        raise credentials_exception
+
+    if 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.
+    user = dict(user)
+    user["token_expires_at"] = _token_expiry(payload)
+    user["session_started_at"] = _session_start(payload)
+    user["session_id"] = payload.get(panel_session.SESSION_CLAIM)
+
+    return user
+
+
+#: Refusals that mean the token is ours: the signature matched and something
+#: else did not. Everything else PyJWT raises means somebody else signed it.
+_OUR_TOKEN_REFUSED = (jwt.ExpiredSignatureError, jwt.ImmatureSignatureError,
+                      jwt.MissingRequiredClaimError)
+
+
+async def _foreign_user(token: str, credentials_exception: HTTPException,
+                        ignore_empty_user: bool = False):
+    """The user of a token some other system issued, through the configured provider.
+
+    Only when the deployment switched the provider's token mode on; otherwise a
+    token that is not ours is simply not a token. Every refusal answers the same
+    as a bad token of ours. An unavailable provider is a 503: a client told its
+    token is bad throws it away, and it must not do that because somebody else's
+    server is down.
+    """
+    runtime = identity_runtime.current()
+    if runtime is None or not runtime.config.accept_tokens:
+        if ignore_empty_user:
+            return None
+        raise credentials_exception
+    try:
+        identity = await runtime.identity_for_token(token)
+        account = await runtime.user_for_identity(identity)
+    except IdentityRejected as refusal:
+        logger.info("Token refused by identity provider %s: %s", runtime.config.name, refusal)
+        if ignore_empty_user:
+            return None
+        raise credentials_exception
+    except (ProviderUnavailable, AccountUnavailable) as error:
+        if isinstance(error, AccountUnavailable):
+            logger.error("Account for identity provider %s unavailable: %s",
+                         runtime.config.name, error)
+        if ignore_empty_user:
+            return None
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                            detail=access.UNAVAILABLE)
+
+    if account.get("status") != "active":
+        # Vouched for there is not the same as allowed in here.
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is blocked",
+        )
+    return runtime.signed_in(account, identity)
+
+
+def refuse_foreign_session(current_user: dict) -> None:
+    """Refuse to turn a token of another system into a session of this one.
+
+    Both renewal and the move into the panel cookie issue a session here. For a
+    caller who came with the provider's token that would be a session the
+    other system cannot revoke, outliving the token it was traded for.
+    """
+    source = (current_user or {}).get("authenticated_by")
+    if source:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"This token was issued by {source}; renew it there.",
+        )
+
+
+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)):
+    # The right is ADMIN being among the roles, not one role being equal to it:
+    # somebody who is both an administrator and a client holds two (keepup-51).
+    if not user_roles.has_role(current_user, 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(panel_session.session_token_in(request.cookies))
+
+
+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