keepup-admin 0.1.0__py3-none-any.whl

keepup/auth/seed_accounts.py

@@ -0,0 +1,322 @@
+"""The accounts an application creates for itself on the first start.
+
+There are two. `admin` is a person's first way in: without it nobody can sign
+into a fresh database and there would be nothing to bring the panel up with.
+`system` is not a person but a signature: background jobs record their work
+under somebody's name and need a row in `users`.
+
+Both used to be created with a password typed into the source: `admin123` for
+the first and `system_internal_use_only_123` for the second, while two other
+places that created the same `system` also typed `system_password`. A password
+in a repository is not a password: it is known to everyone who has seen the
+code, it is the same on every deployment, and it does not change because the
+deployment became reachable from outside. `admin123` is on top of that in the
+breach lists, and the browser warns about it at every sign-in -- truthfully.
+
+Three decisions follow.
+
+**The administrator's password is set by whoever deploys, not by the code.** It
+is read from `ADMIN_INITIAL_PASSWORD`; without that variable it is generated at
+random and printed once into the start-up log -- that is exactly where it can
+be read, and it differs on every deployment. A default fit for everyone does
+not exist here.
+
+**`system` has no password at all.** Nobody signs in as it, so it is given a
+random value known to no one, ourselves included, and a status that sign-in
+rejects. The account stays a signature and stops being a way in.
+
+**One place creates the accounts.** Three implementations of the same thing had
+already drifted apart in password, role and even in what to write into
+`status`; when one of them is fixed, the others go on creating the hole.
+
+Existing databases are not healed by this on their own: `system` is already
+there, and the creating code does not look at it. So a known password on an
+existing row is retired at start-up -- see `retire_known_system_password`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+from typing import Iterable, Mapping, Optional, Sequence, Tuple
+
+import bcrypt
+
+logger = logging.getLogger(__name__)
+
+#: The first administrator's password, when whoever deploys wants to set it.
+ADMIN_PASSWORD_ENV = "ADMIN_INITIAL_PASSWORD"
+
+ADMIN_USERNAME = "admin"
+SYSTEM_USERNAME = "system"
+
+#: The status sign-in refuses: it admits `active` only
+#: (`keepup/auth/routes.py`). The same trick is already used for the platform's
+#: own account in token settlement.
+SYSTEM_STATUS = "system"
+
+#: The passwords earlier builds handed `system` -- all three, because there
+#: were three places creating it. An existing row holding any of them stops
+#: being a way in at the next start.
+RETIRED_SYSTEM_PASSWORDS: Tuple[str, ...] = (
+    "system_internal_use_only_123",
+    "system_password",
+)
+
+#: The same for the administrator. Its password is not overwritten silently --
+#: somebody may be working with the deployment right now -- but it is named at
+#: every start.
+RETIRED_ADMIN_PASSWORDS: Tuple[str, ...] = ("admin123",)
+
+#: Length of a generated password, in bytes of randomness before encoding.
+GENERATED_PASSWORD_BYTES = 18
+
+
+# --- decisions that can be checked without a database ----------------------
+
+
+def generated_password(nbytes: int = GENERATED_PASSWORD_BYTES) -> str:
+    """A random password fit both for typing by hand and for pasting.
+
+    Args:
+        nbytes: bytes of randomness before encoding.
+
+    Returns:
+        The password.
+    """
+    return secrets.token_urlsafe(nbytes)
+
+
+def initial_admin_password(environ: Optional[Mapping[str, str]] = None) -> Tuple[str, bool]:
+    """The first administrator's password, and whether it was generated.
+
+    An empty variable is not a password that was set, it is a variable that was
+    forgotten: an empty password cannot be signed in with, and accepting it
+    silently would mean creating an account nobody can use.
+
+    Args:
+        environ: the environment to read; the process environment when omitted.
+
+    Returns:
+        A pair (password, generated), where generated says it has to be
+        announced because nobody else knows it.
+    """
+    if environ is None:
+        environ = os.environ
+    given = (environ.get(ADMIN_PASSWORD_ENV) or "").strip()
+    if given:
+        return given, False
+    return generated_password(), True
+
+
+def unusable_password() -> str:
+    """A password nobody knows: it does not leave this function.
+
+    Returns:
+        The value to store as a hash for an account that must not be a way in.
+    """
+    return secrets.token_urlsafe(32)
+
+
+def hash_password(password: str) -> str:
+    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def matches_any(password_hash: Optional[str], candidates: Iterable[str]) -> bool:
+    """Whether the hash matches one of the known retired passwords.
+
+    A hash that cannot be read (empty, from another scheme, a marker left by an
+    external provider) is not a match but a case that is not ours: the answer
+    is a silent no, because the only action here is retiring a known password,
+    and retiring somebody else's scheme is not ours to do.
+
+    Args:
+        password_hash: the stored hash, whatever it holds.
+        candidates: the retired passwords to check against.
+
+    Returns:
+        True when one of them matches.
+    """
+    if not password_hash:
+        return False
+    for candidate in candidates:
+        try:
+            if bcrypt.checkpw(candidate.encode("utf-8"), password_hash.encode("utf-8")):
+                return True
+        except (ValueError, TypeError):
+            return False
+    return False
+
+
+def announce_generated_admin_password(password: str, log=logger) -> None:
+    """The only place a generated password is shown to a person.
+
+    Args:
+        password: the generated password.
+        log: the logger to announce through.
+    """
+    log.warning(
+        "Created the administrator account '%s' with a generated password: %s\n"
+        "It is stored nowhere else and will not be shown again. Sign in and "
+        "change it, or set %s before the first start.",
+        ADMIN_USERNAME, password, ADMIN_PASSWORD_ENV,
+    )
+
+
+def warn_about_retired_admin_password(log=logger) -> None:
+    """Say out loud what would otherwise be learned from the browser.
+
+    Args:
+        log: the logger to warn through.
+    """
+    log.warning(
+        "Account '%s' still carries a password from earlier builds. It is the "
+        "same on every deployment, known to everyone who has seen the source, "
+        "and is in the breach lists. Change it in the panel: the Users section "
+        "-> Change password.",
+        ADMIN_USERNAME,
+    )
+
+
+# --- what is written to the database ---------------------------------------
+
+
+def _sql(query: str, is_postgres: bool) -> str:
+    """Queries are written with `?`; PostgreSQL gets `%s`, as elsewhere in the schema.
+
+    Args:
+        query: the query as written.
+        is_postgres: whether the connection is PostgreSQL.
+
+    Returns:
+        The query in the dialect of that connection.
+    """
+    return query.replace("?", "%s") if is_postgres else query
+
+
+def _scalar(row) -> int:
+    """The row's first column, however the cursor returns the row.
+
+    Args:
+        row: a row, as a mapping or a sequence, or nothing.
+
+    Returns:
+        The value, or 0 when there is no row.
+    """
+    if not row:
+        return 0
+    if hasattr(row, "get") and callable(getattr(row, "get")):
+        return row.get("count", 0) or 0
+    return row[0] if len(row) > 0 else 0
+
+
+def _exists(cursor, username: str, is_postgres: bool) -> bool:
+    cursor.execute(_sql("SELECT COUNT(*) as count FROM users WHERE username = ?", is_postgres),
+                   (username,))
+    return _scalar(cursor.fetchone()) > 0
+
+
+def _insert(cursor, *, username: str, password_hash: str, status: str, role: str,
+            auth_source: str, is_postgres: bool) -> None:
+    cursor.execute(
+        _sql("INSERT INTO users (username, password_hash, status, role, auth_source) "
+             "VALUES (?, ?, ?, ?, ?)", is_postgres),
+        (username, password_hash, status, role, auth_source),
+    )
+
+
+def ensure_admin(cursor, *, role: str, auth_source: str, is_postgres: bool,
+                 environ: Optional[Mapping[str, str]] = None) -> None:
+    """Create the administrator when absent; otherwise check its password.
+
+    An existing password is left alone: somebody may be working with the
+    deployment right now, and changing it from a background procedure would cut
+    a person off from their own panel.
+
+    Args:
+        cursor: an open cursor on the users table.
+        role: the role to give a newly created account.
+        auth_source: what to record as the account's origin.
+        is_postgres: whether the connection is PostgreSQL.
+        environ: the environment to read the password from.
+    """
+    if not _exists(cursor, ADMIN_USERNAME, is_postgres):
+        password, generated = initial_admin_password(environ)
+        _insert(cursor, username=ADMIN_USERNAME, password_hash=hash_password(password),
+                status="active", role=role, auth_source=auth_source,
+                is_postgres=is_postgres)
+        if generated:
+            announce_generated_admin_password(password)
+        else:
+            logger.info("Created the administrator account '%s' with the given password",
+                        ADMIN_USERNAME)
+        return
+
+    cursor.execute(_sql("SELECT password_hash FROM users WHERE username = ?", is_postgres),
+                   (ADMIN_USERNAME,))
+    row = cursor.fetchone()
+    stored = row.get("password_hash") if hasattr(row, "get") else (row[0] if row else None)
+    if matches_any(stored, RETIRED_ADMIN_PASSWORDS):
+        warn_about_retired_admin_password()
+
+
+def ensure_system_user(cursor, *, role: str, auth_source: str, is_postgres: bool) -> None:
+    """Create the signature background jobs sign with -- with no usable password.
+
+    Args:
+        cursor: an open cursor on the users table.
+        role: the role to give the account.
+        auth_source: what to record as the account's origin.
+        is_postgres: whether the connection is PostgreSQL.
+    """
+    if _exists(cursor, SYSTEM_USERNAME, is_postgres):
+        retire_known_system_password(cursor, is_postgres=is_postgres)
+        return
+
+    _insert(cursor, username=SYSTEM_USERNAME,
+            password_hash=hash_password(unusable_password()),
+            status=SYSTEM_STATUS, role=role, auth_source=auth_source,
+            is_postgres=is_postgres)
+    logger.info("Created the service account '%s'; it cannot be signed in as",
+                SYSTEM_USERNAME)
+
+
+def retire_known_system_password(cursor, *, is_postgres: bool,
+                                 candidates: Sequence[str] = RETIRED_SYSTEM_PASSWORDS) -> bool:
+    """Retire the `system` password in a database left by earlier builds.
+
+    Idempotent: the second time round the password matches none of the known
+    ones and no statement runs.
+
+    Args:
+        cursor: an open cursor on the users table.
+        is_postgres: whether the connection is PostgreSQL.
+        candidates: the retired passwords to look for.
+
+    Returns:
+        Whether anything had to be changed.
+    """
+    cursor.execute(_sql("SELECT password_hash, status FROM users WHERE username = ?", is_postgres),
+                   (SYSTEM_USERNAME,))
+    row = cursor.fetchone()
+    if not row:
+        return False
+    if hasattr(row, "get") and callable(getattr(row, "get")):
+        stored, status = row.get("password_hash"), row.get("status")
+    else:
+        stored, status = row[0], row[1]
+
+    if not matches_any(stored, candidates) and status == SYSTEM_STATUS:
+        return False
+
+    cursor.execute(
+        _sql("UPDATE users SET password_hash = ?, status = ? WHERE username = ?", is_postgres),
+        (hash_password(unusable_password()), SYSTEM_STATUS, SYSTEM_USERNAME),
+    )
+    logger.warning(
+        "Service account '%s' carried a password from earlier builds; it has "
+        "been retired and the account can no longer be signed in as",
+        SYSTEM_USERNAME,
+    )
+    return True

keepup/auth/session_lifetime.py

@@ -0,0 +1,104 @@
+"""How much life a session has left, and when to warn about it.
+
+The access token is a JWT: it carries its own expiry and the server keeps no
+session state, so "when does this session end" is answerable only from the
+token itself. These are the numbers around that -- no request, no database, no
+token decoding -- which is what makes the rule checkable on its own.
+
+Why it matters beyond a person's convenience: the host agent logs in the same
+way and authorises its reconnect with the same token. An expired one leaves it
+unable to obtain a websocket key at all, so the host drops out of the system
+while the machine is running.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Optional
+
+#: How long before the end a holder is told to renew. An hour is far longer
+#: than any pause in the agent's work -- it reconnects in seconds and reports
+#: telemetry in minutes -- so a warning always arrives while there is still a
+#: valid token to exchange.
+WARNING_WINDOW = timedelta(hours=1)
+
+#: How long a session may keep renewing itself, counted from the login that
+#: started it. Renewal is authorised by the token being renewed and nothing
+#: else, so without a ceiling one login lasts forever and changing a password
+#: takes nothing away from whoever already holds a token.
+#:
+#: The default is long on purpose: the host agent holds its session across a
+#: rental, and asking its owner to type a password mid-rent drops the host out
+#: of the system with a machine still running on it. A month bounds the session
+#: without making that the normal case.
+RENEWAL_WINDOW_ENV = "SESSION_RENEWAL_WINDOW_HOURS"
+DEFAULT_RENEWAL_WINDOW = timedelta(days=30)
+
+
+def renewal_window(environ=None) -> timedelta:
+    """How long a session may go on being renewed."""
+    import os
+
+    environ = environ if environ is not None else os.environ
+    raw = environ.get(RENEWAL_WINDOW_ENV)
+    if raw is None:
+        return DEFAULT_RENEWAL_WINDOW
+    try:
+        hours = int(raw)
+    except (TypeError, ValueError):
+        return DEFAULT_RENEWAL_WINDOW
+    return timedelta(hours=hours) if hours > 0 else DEFAULT_RENEWAL_WINDOW
+
+
+def is_renewable(
+        session_started_at: Optional[datetime],
+        now: Optional[datetime] = None,
+        environ=None,
+) -> bool:
+    """Whether a session that began then may still be renewed.
+
+    A session with no recorded beginning is renewable: tokens issued before this
+    rule existed carry no such mark, and refusing them would log everybody out
+    twice over -- once for the key change, once for this.
+    """
+    if session_started_at is None:
+        return True
+    now = now or datetime.utcnow()
+    return now - session_started_at <= renewal_window(environ)
+
+
+def seconds_left(expires_at: Optional[datetime], now: Optional[datetime] = None) -> int:
+    """Seconds of life the session has left, never negative.
+
+    A session with no known expiry counts as ended: not knowing when a token
+    dies is not a reason to treat it as immortal.
+    """
+    if expires_at is None:
+        return 0
+    now = now or datetime.utcnow()
+    remaining = (expires_at - now).total_seconds()
+    return max(0, int(remaining))
+
+
+def is_expired(expires_at: Optional[datetime], now: Optional[datetime] = None) -> bool:
+    """Whether the session is over."""
+    return seconds_left(expires_at, now) <= 0
+
+
+def should_warn(expires_at: Optional[datetime], now: Optional[datetime] = None) -> bool:
+    """Whether the holder should be told to renew now.
+
+    An already expired session is not warned about: there is nothing left to
+    exchange, and the holder will find out from the next refusal.
+    """
+    left = seconds_left(expires_at, now)
+    return 0 < left <= WARNING_WINDOW.total_seconds()
+
+
+def can_refresh(expires_at: Optional[datetime], now: Optional[datetime] = None) -> bool:
+    """Whether this session may still be exchanged for a new one.
+
+    Only a living token buys a new one. Renewing an expired token would make
+    the expiry mean nothing: one token issued once would live forever.
+    """
+    return not is_expired(expires_at, now)

keepup/auth/signing_key.py

@@ -0,0 +1,138 @@
+"""The key that signs access tokens, and the single place that resolves it.
+
+The key used to live as a module constant next to the provider base class, and
+half the code signed with that constant while the other half read the value out
+of ``auth_config``. Nothing kept the two in step, and the constant shipped in the
+repository: anyone who read it could mint a token for any account, including an
+administrator's. The agent's sources are meant to be opened to host owners, so a
+secret that lives in the source is a secret that is already published.
+
+Resolution order is the environment first, ``config/auth.yaml`` second. The
+environment is what a deployment actually controls; the YAML file is committed
+with real-looking values and is an environment, not a template, so it is the
+fallback rather than the source.
+
+A key that is absent, too short, or left at one of the placeholder values from
+the setup examples is refused rather than used. The refusal is what the caller
+turns into a failed start: a deployment brought up with a placeholder must not
+come up at all, because the alternative is discovering it the day someone signs
+their own administrator token.
+"""
+
+import os
+from typing import Mapping, Optional
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "SigningKeyUnavailable",
+    "resolve_signing_key",
+]
+
+#: Where a deployment puts the key. Named in the refusal, so it stays a constant.
+SIGNING_KEY_ENV = "SECRET_KEY"
+
+#: Shortest key accepted. HS256 keys shorter than the digest they feed buy
+#: nothing over a guessable passphrase, and 32 characters is what the token
+#: generators in this repository already produce.
+MINIMUM_KEY_LENGTH = 32
+
+#: Values that appear in the setup examples of this repository and in the
+#: documentation. A deployment that still carries one of them has not been
+#: configured, whatever its length.
+PLACEHOLDER_KEYS = frozenset({
+    "your-secret-key-here-change-in-production",
+    "your-jwt-secret-key-change-in-production",
+    "your-secret-key-change-in-production",
+    "your-very-secure-secret-key-change-this",
+    "change-me",
+    "changeme",
+    "secret",
+})
+
+
+class SigningKeyUnavailable(RuntimeError):
+    """No usable signing key: the message says which variable to set."""
+
+
+def _configured_key(config: Optional[object]) -> Optional[str]:
+    """Read the key out of the auth configuration, if it carries one."""
+    if config is None:
+        return None
+    value = getattr(config, "jwt_secret", None)
+    return value if isinstance(value, str) else None
+
+
+def signing_key_problem(
+        environ: Optional[Mapping[str, str]] = None,
+        config: Optional[object] = None,
+) -> Optional[str]:
+    """Return why the signing key is unusable, or None when it is fine.
+
+    Reports rather than raises, so the start-up check can name the problem and
+    the resolver can raise on the same verdict.
+    """
+    if environ is None:
+        environ = os.environ
+    if config is None:
+        config = _auth_config()
+
+    candidate = environ.get(SIGNING_KEY_ENV) or _configured_key(config) or ""
+    candidate = candidate.strip()
+
+    if not candidate:
+        return (
+            f"Token signing secret is not set: set the environment variable "
+            f"{SIGNING_KEY_ENV} to a value at least {MINIMUM_KEY_LENGTH} characters long."
+        )
+
+    if candidate in PLACEHOLDER_KEYS:
+        return (
+            f"Token signing secret is left at the example configuration value: "
+            f"set the environment variable {SIGNING_KEY_ENV} to your own value "
+            f"at least {MINIMUM_KEY_LENGTH} characters long."
+        )
+
+    if len(candidate) < MINIMUM_KEY_LENGTH:
+        return (
+            f"Token signing secret is shorter than {MINIMUM_KEY_LENGTH} characters: "
+            f"set the environment variable {SIGNING_KEY_ENV} to a longer value."
+        )
+
+    return None
+
+
+def resolve_signing_key(
+        environ: Optional[Mapping[str, str]] = None,
+        config: Optional[object] = None,
+) -> str:
+    """Return the key that signs and verifies access tokens.
+
+    Not cached: reading an environment variable costs nothing next to the
+    signature that follows it, and a cache would make the key of a running
+    process depend on which test imported it first.
+    """
+    if environ is None:
+        environ = os.environ
+    if config is None:
+        config = _auth_config()
+
+    problem = signing_key_problem(environ, config)
+    if problem:
+        raise SigningKeyUnavailable(problem)
+
+    return (environ.get(SIGNING_KEY_ENV) or _configured_key(config) or "").strip()
+
+
+def _auth_config() -> Optional[object]:
+    """The loaded auth configuration, or None when it cannot be imported.
+
+    Imported lazily: this module is imported by the provider base class, which
+    the configuration module does not depend on, and a module-level import would
+    close that loop.
+    """
+    try:
+        from keepup.auth.config import auth_config
+    except Exception:  # pragma: no cover - configuration is optional here
+        return None
+    return auth_config

keepup/auth/websocket.py

@@ -0,0 +1,86 @@
+"""Who is on the other end of a WebSocket.
+
+A handshake carries no Authorization header a browser would let a page set, so
+a socket is signed in by one of two things, in this order:
+
+* a real token in the address (`?token=`) -- what programmatic clients send;
+* the panel session cookie -- what the panel sends. A handshake is not bound by
+  CORS, so the cookie counts only when the page that opened the socket is
+  served from this same server; otherwise any site the user visits could open
+  a socket as them.
+
+Whatever the reason for refusing, the socket is closed with 1008 (policy
+violation) and a short reason; the reasons are the ones the panel and the logs
+already know from the first socket that did this by hand.
+
+A plugin gets this without calling anything: a WebSocket route declared with
+`require_auth: True` is signed in by the framework before its handler runs
+(keepup/plugins/registry.py).
+"""
+
+from typing import Any, Dict, Optional
+
+from fastapi import HTTPException
+
+from keepup.auth import dependencies, panel_session
+
+#: What an application may import from this module. Everything else is
+#: internal and may change without notice -- see doc/keepup.md.
+__all__ = [
+    "WebSocketRefused",
+    "authenticate_websocket",
+]
+
+#: WebSocket close code for "policy violation": the connection is refused on
+#: grounds of who is asking, not because something broke.
+WS_CLOSE_POLICY_VIOLATION = 1008
+
+REASON_CROSS_ORIGIN = "Cross-origin session"
+REASON_MISSING_TOKEN = "Missing token"
+REASON_INVALID_TOKEN = "Invalid token"
+
+
+class WebSocketRefused(Exception):
+    """The socket is not signed in; `code` and `reason` are what it is closed with."""
+
+    def __init__(self, reason: str, code: int = WS_CLOSE_POLICY_VIOLATION):
+        super().__init__(reason)
+        self.code = code
+        self.reason = reason
+
+
+def _token_of(websocket) -> str:
+    token = panel_session.real_bearer(websocket.query_params.get("token"))
+    if token:
+        return token
+    if not panel_session.same_origin(websocket.headers):
+        raise WebSocketRefused(REASON_CROSS_ORIGIN)
+    token = panel_session.websocket_token(None, websocket.cookies)
+    if not token:
+        raise WebSocketRefused(REASON_MISSING_TOKEN)
+    return token
+
+
+async def websocket_user(websocket) -> Dict[str, Any]:
+    """The signed-in user of this socket, or `WebSocketRefused`.
+
+    The user is resolved through `dependencies.get_current_user` looked up at
+    call time, so whatever replaces it (a test, another provider) is honoured.
+    """
+    token = _token_of(websocket)
+    try:
+        user = await dependencies.get_current_user(token=token)
+    except HTTPException:
+        raise WebSocketRefused(REASON_INVALID_TOKEN)
+    if not (user or {}).get("id"):
+        raise WebSocketRefused(REASON_INVALID_TOKEN)
+    return user
+
+
+async def authenticate_websocket(websocket) -> Optional[Dict[str, Any]]:
+    """The user of this socket, or None after closing it with the reason."""
+    try:
+        return await websocket_user(websocket)
+    except WebSocketRefused as refused:
+        await websocket.close(code=refused.code, reason=refused.reason)
+        return None