tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/web/auth.py

@@ -0,0 +1,373 @@
+"""Access control for the rest api: password hashes, users file, sessions and login throttling."""
+
+import base64
+import hashlib
+import hmac
+import logging
+import os
+import secrets
+import stat
+import threading
+import time
+from collections.abc import Callable
+from typing import Any, TypeGuard
+
+import yaml
+
+__all__ = [
+    "MAX_USERNAME_LENGTH",
+    "MIN_PASSWORD_LENGTH",
+    "ROLES",
+    "LoginThrottle",
+    "Session",
+    "Sessions",
+    "UsersFile",
+    "has_role",
+    "hash_password",
+    "valid_username",
+    "verify_password",
+]
+
+ROLES = ("user", "admin")  # admin may do everything a user may do
+MIN_PASSWORD_LENGTH = 8
+MAX_USERNAME_LENGTH = 64
+
+
+def valid_username(name: object) -> TypeGuard[str]:
+    """A name for a user of the page - the same rule on the page and for ``tinyjukebox-users``: not empty, no blanks
+    around it, no ``:``, at most :data:`MAX_USERNAME_LENGTH` characters."""
+    return (
+        isinstance(name, str)
+        and bool(name)
+        and name == name.strip()
+        and ":" not in name
+        and len(name) <= MAX_USERNAME_LENGTH
+        and name.isprintable()
+    )
+
+
+# scrypt parameters - n=2**14 needs 16 MB and ~50 ms on a Raspberry Pi 3
+_SCRYPT_N = 2**14
+_SCRYPT_R = 8
+_SCRYPT_P = 1
+
+Clock = Callable[[], float]
+
+
+def _b64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def hash_password(password: str) -> str:
+    """'scrypt$n$r$p$salt$hash' (salt and hash base64 encoded)."""
+    salt = secrets.token_bytes(16)
+    digest = hashlib.scrypt(password.encode("utf-8"), salt=salt, n=_SCRYPT_N, r=_SCRYPT_R, p=_SCRYPT_P, dklen=32)
+    return f"scrypt${_SCRYPT_N}${_SCRYPT_R}${_SCRYPT_P}${_b64(salt)}${_b64(digest)}"
+
+
+def verify_password(password: str, password_hash: object) -> bool:
+    """Constant time comparison; malformed hashes never match."""
+    try:
+        algorithm, n, r, p, salt, digest = str(password_hash).split("$")
+        if algorithm != "scrypt":
+            return False
+        expected = base64.b64decode(digest)
+        candidate = hashlib.scrypt(
+            password.encode("utf-8"),
+            salt=base64.b64decode(salt),
+            n=int(n),
+            r=int(r),
+            p=int(p),
+            dklen=len(expected),
+            maxmem=128 * 1024 * 1024,
+        )
+    except (ValueError, TypeError):
+        return False
+    return hmac.compare_digest(candidate, expected)
+
+
+# compared against if the user is unknown - login takes as long as for a known user (no user enumeration)
+_DUMMY_HASH = hash_password(secrets.token_hex(16))
+
+# one password check at a time: each one needs 16 MB, and parallel logins (one thread per connection) would multiply
+# that - and pass the login throttle before the first failure has been counted
+_VERIFY_LOCK = threading.Lock()
+
+
+def has_role(role: str, required_role: str) -> bool:
+    return ROLES.index(role) >= ROLES.index(required_role)
+
+
+class UsersFile:
+    """Users are stored in a yaml file (managed with ``tinyjukebox-users``)::
+
+        users:
+            mama:
+                password-hash: scrypt$16384$8$1$...
+                role: admin
+
+    The file is reloaded if it has been changed - adding or removing users needs no restart. The web page changes
+    it with :meth:`change`. A session ends when its user has a new password, wherever it was set
+    (:meth:`session_role`).
+    """
+
+    def __init__(self, filename: str, logger: logging.Logger) -> None:
+        self.filename = filename
+        self._logger = logger
+        self._lock = threading.Lock()
+        self._mtime: int | None = None
+        self._users: dict[str, dict[str, Any]] = {}
+        self._reload()
+
+    @staticmethod
+    def read(filename: str) -> dict[str, dict[str, Any]]:
+        """:raises ValueError: if the file is not a valid users file."""
+        try:
+            with open(filename, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+        except FileNotFoundError:
+            return {}
+        users = data.get("users") or {} if isinstance(data, dict) else None
+        if not isinstance(users, dict):
+            raise ValueError(f"'users' in '{filename}' must be a mapping.")
+        for name, user in users.items():
+            if not isinstance(user, dict) or "password-hash" not in user or user.get("role") not in ROLES:
+                raise ValueError(f"user '{name}' in '{filename}' needs a password-hash and a role ({'/'.join(ROLES)}).")
+        return users
+
+    @staticmethod
+    def write(filename: str, users: dict[str, dict[str, Any]]) -> None:
+        """Write the users file (mode 600, atomically)."""
+        os.makedirs(os.path.dirname(os.path.abspath(filename)), exist_ok=True)
+        temp = filename + ".tmp"
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            yaml.safe_dump({"users": users}, f, default_flow_style=False, allow_unicode=True)
+        os.replace(temp, filename)
+
+    def _reload(self) -> None:
+        try:
+            st = os.stat(self.filename)
+        except FileNotFoundError:
+            if self._mtime is not None or not self._users:
+                self._logger.warning(
+                    "users file '%s' not found - nobody can log in. "
+                    "create users with 'tinyjukebox-users -f %s add NAME'.",
+                    self.filename,
+                    self.filename,
+                )
+            self._users = {}
+            self._mtime = None
+            return
+        if st.st_mtime_ns == self._mtime:
+            return
+        if st.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+            self._logger.warning("users file '%s' is readable by other users - use 'chmod 600'.", self.filename)
+        try:
+            self._users = self.read(self.filename)
+        except (ValueError, yaml.YAMLError) as e:
+            self._logger.error("cannot read users file: %s - keeping the previous users.", e)
+        self._mtime = st.st_mtime_ns
+
+    def roles(self) -> dict[str, str]:
+        """The role of every user."""
+        with self._lock:
+            self._reload()
+            return {name: str(user["role"]) for name, user in self._users.items()}
+
+    def change(self, change: Callable[[dict[str, dict[str, Any]]], None]) -> None:
+        """Apply ``change`` to the users of the file and write it back. Whatever ``change`` raises leaves the file
+        as it is.
+
+        :raises ValueError: if the file is not a valid users file."""
+        with self._lock:
+            users = self.read(self.filename)
+            change(users)
+            self.write(self.filename, users)
+            # not via _reload: on a coarse file system the new file may have the mtime of the old one
+            self._users = users
+            self._mtime = os.stat(self.filename).st_mtime_ns
+
+    def authenticate(self, username: str, password: str) -> str | None:
+        """The role of the user - None for unknown users or wrong passwords."""
+        with self._lock:
+            self._reload()
+            user = self._users.get(username)
+        with _VERIFY_LOCK:
+            if user is None:
+                verify_password(password, _DUMMY_HASH)
+                return None
+            return str(user["role"]) if verify_password(password, user["password-hash"]) else None
+
+    def get_role(self, username: str) -> str | None:
+        """Current role of the user - None if the user has been removed in the meantime."""
+        with self._lock:
+            self._reload()
+            user = self._users.get(username)
+        return None if user is None else str(user["role"])
+
+    def credential(self, username: str) -> str | None:
+        """What a session remembers of the password of its user: it changes with every new password, set on the page
+        or with ``tinyjukebox-users``. None for an unknown user."""
+        with self._lock:
+            self._reload()
+            user = self._users.get(username)
+        return None if user is None else _credential(str(user["password-hash"]))
+
+    def session_role(self, session: "Session") -> str | None:
+        """The current role of the user of the session - None if the user has been removed or has a new password
+        since the session began: then the session has ended."""
+        with self._lock:
+            self._reload()
+            user = self._users.get(session.username)
+        if user is None or _credential(str(user["password-hash"])) != session.credential:
+            return None
+        return str(user["role"])
+
+
+def _credential(password_hash: str) -> str:
+    """A fingerprint of a password hash - a session keeps this, not the hash."""
+    return hashlib.sha256(password_hash.encode("utf-8")).hexdigest()
+
+
+class Session:
+    def __init__(self, username: str, role: str, expires: float, active: float, credential: str = "") -> None:
+        self.username = username
+        self.role = role
+        self.expires = expires
+        self.active = active  # when the user did something last
+        self.credential = credential  # of the password the session began with (UsersFile.credential)
+
+
+class Sessions:
+    """Random session tokens; only their sha256 hash is kept. Sessions expire after ``timeout`` seconds without
+    use, and after ``idle_timeout`` seconds in which the user did nothing (0: never) - an open page asks all the time,
+    so only what it reports as done by the user counts for that."""
+
+    def __init__(self, timeout: float, clock: Clock = time.monotonic, idle_timeout: float = 0) -> None:
+        self._timeout = timeout
+        self.idle_timeout = idle_timeout
+        self._clock = clock
+        self._sessions: dict[str, Session] = {}
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def _key(token: str) -> str:
+        return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+    def create(self, username: str, role: str, credential: str = "") -> str:
+        token = secrets.token_urlsafe(32)
+        with self._lock:
+            self._purge()
+            now = self._clock()
+            self._sessions[self._key(token)] = Session(username, role, now + self._timeout, now, credential)
+        return token
+
+    def get(self, token: str | None, idle: float | None = 0) -> Session | None:
+        """The session of the token (its expiry is extended) - None for unknown or expired tokens.
+
+        ``idle``: the user did something last this many seconds ago - 0 for a request that is an action itself, None
+        for one that says nothing about the user (the page asking by itself)."""
+        if not token:
+            return None
+        key = self._key(token)
+        with self._lock:
+            session = self._sessions.get(key)
+            if session is None:
+                return None
+            now = self._clock()
+            if idle is not None:
+                session.active = max(session.active, now - max(idle, 0))
+            if session.expires < now or (self.idle_timeout > 0 and now - session.active > self.idle_timeout):
+                del self._sessions[key]
+                return None
+            session.expires = now + self._timeout
+            return session
+
+    def remove(self, token: str) -> None:
+        with self._lock:
+            self._sessions.pop(self._key(token), None)
+
+    def remove_user(self, username: str, keep: str | None = None, credential: str | None = None) -> None:
+        """Ends all sessions of the user - except the one of the token ``keep``, which gets ``credential`` if given:
+        the user who has just set a new password stays logged in."""
+        keep_key = self._key(keep) if keep else None
+        with self._lock:
+            for key in [k for k, s in self._sessions.items() if s.username == username and k != keep_key]:
+                del self._sessions[key]
+            kept = self._sessions.get(keep_key) if keep_key else None
+            if kept is not None and kept.username == username and credential is not None:
+                kept.credential = credential
+
+    def _purge(self) -> None:
+        """Forget the sessions that have expired. Whether a session in which the user did nothing for too long ends is
+        decided when it is used (:meth:`get`): a page that is opened again counts as doing something - not whether
+        somebody else logged in meanwhile."""
+        now = self._clock()
+        for key in [k for k, s in self._sessions.items() if s.expires < now]:
+            del self._sessions[key]
+
+
+class LoginThrottle:
+    """After ``max_failures`` failed logins from one address, every further failed attempt blocks the address for
+    ``lockout`` seconds. Failures are forgotten ``reset_after`` seconds after the last failure or with a successful
+    login.
+
+    At most ``max_addresses`` addresses are tracked. If there are more, addresses that are not blocked are forgotten
+    first (oldest failure first) - flooding the table from many addresses must not unblock an attacked address.
+    """
+
+    def __init__(
+        self,
+        max_failures: int = 5,
+        lockout: float = 30,
+        reset_after: float = 900,
+        clock: Clock = time.monotonic,
+        max_addresses: int = 10000,
+    ) -> None:
+        self._max_failures = max_failures
+        self._lockout = lockout
+        self._reset_after = reset_after
+        self._clock = clock
+        self._max_addresses = max_addresses
+        self._failures: dict[str, list[float]] = {}  # address -> [count, time of last failure, blocked until]
+        self._lock = threading.Lock()
+
+    def _entry(self, address: str) -> list[float] | None:
+        entry = self._failures.get(address)
+        if entry is not None and self._clock() - entry[1] > self._reset_after:
+            del self._failures[address]
+            entry = None
+        return entry
+
+    def retry_after(self, address: str) -> int:
+        """Seconds until the next login attempt is allowed (0: allowed now)."""
+        with self._lock:
+            entry = self._entry(address)
+            if entry is None:
+                return 0
+            return max(0, int(entry[2] - self._clock() + 0.999))
+
+    def failed(self, address: str) -> None:
+        with self._lock:
+            now = self._clock()
+            entry = self._entry(address)
+            if entry is None:
+                entry = self._failures[address] = [0, now, 0]
+            entry[0] += 1
+            entry[1] = now
+            if entry[0] >= self._max_failures:
+                entry[2] = now + self._lockout
+            if len(self._failures) > self._max_addresses:
+                self._shrink(now)
+
+    def _shrink(self, now: float) -> None:
+        excess = len(self._failures) - self._max_addresses
+        # not blocked before blocked, then oldest failure first
+        order = sorted(self._failures.items(), key=lambda item: (item[1][2] > now, item[1][1]))
+        for address, _ in order[:excess]:
+            del self._failures[address]
+
+    def succeeded(self, address: str) -> None:
+        with self._lock:
+            self._failures.pop(address, None)

tinyjukebox/web/certificates.py

@@ -0,0 +1,111 @@
+"""Self signed certificate for the rest api - created with the openssl command line tool on first start."""
+
+import hashlib
+import logging
+import os
+import socket
+import ssl
+import subprocess
+from collections.abc import Iterable
+
+__all__ = ["create_self_signed_certificate", "create_ssl_context", "ensure_certificate", "fingerprint"]
+
+
+def _is_ip(name: str) -> bool:
+    for family in (socket.AF_INET, socket.AF_INET6):
+        try:
+            socket.inet_pton(family, name)
+        except OSError:
+            continue
+        return True
+    return False
+
+
+def _subject_alt_names(hostnames: Iterable[str] | None) -> str:
+    names = ["localhost", socket.gethostname(), socket.gethostname() + ".local", *(hostnames or [])]
+    entries: list[str] = []
+    for name in [*names, "127.0.0.1"]:
+        entry = f"{'IP' if _is_ip(name) else 'DNS'}:{name}"
+        if entry not in entries:
+            entries.append(entry)
+    return ",".join(entries)
+
+
+def _create_private_file(filename: str) -> None:
+    """Empty file with mode 600 - openssl writes the key into it, so the key is never readable by others.
+
+    (The previous version changed the umask of the whole process, which affected files created by other threads.)
+    """
+    if os.path.exists(filename):
+        os.chmod(filename, 0o600)
+    else:
+        os.close(os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600))
+
+
+def create_self_signed_certificate(
+    certificate_file: str, key_file: str, hostnames: Iterable[str] | None = None, days: int = 3650
+) -> None:
+    """Create an ec (prime256v1) key and a self signed certificate for this host (valid for ``days`` days).
+
+    :raises RuntimeError: if openssl is missing or fails.
+    """
+    for filename in (certificate_file, key_file):
+        os.makedirs(os.path.dirname(os.path.abspath(filename)), mode=0o700, exist_ok=True)
+    _create_private_file(key_file)
+    try:
+        result = subprocess.run(
+            [
+                "openssl",
+                "req",
+                "-x509",
+                "-newkey",
+                "ec",
+                "-pkeyopt",
+                "ec_paramgen_curve:prime256v1",
+                "-nodes",
+                "-sha256",
+                "-days",
+                str(days),
+                "-subj",
+                f"/CN={socket.gethostname()}/O=Tiny Jukebox",
+                "-addext",
+                f"subjectAltName={_subject_alt_names(hostnames)}",
+                "-keyout",
+                key_file,
+                "-out",
+                certificate_file,
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        raise RuntimeError("openssl not found - install openssl or provide certificate and private key.") from None
+    if result.returncode != 0:
+        raise RuntimeError(f"creating the certificate failed: {result.stderr.strip()}")
+    os.chmod(key_file, 0o600)
+
+
+def fingerprint(certificate_file: str) -> str:
+    """SHA-256 fingerprint as shown by browsers (AA:BB:...)."""
+    with open(certificate_file, encoding="ascii") as f:
+        der = ssl.PEM_cert_to_DER_cert(f.read())
+    digest = hashlib.sha256(der).hexdigest().upper()
+    return ":".join(digest[i : i + 2] for i in range(0, len(digest), 2))
+
+
+def ensure_certificate(
+    certificate_file: str, key_file: str, logger: logging.Logger, hostnames: Iterable[str] | None = None
+) -> str:
+    """Create certificate and key if one of them is missing. Returns the fingerprint of the certificate."""
+    if not (os.path.exists(certificate_file) and os.path.exists(key_file)):
+        logger.info("creating self signed certificate '%s'.", certificate_file)
+        create_self_signed_certificate(certificate_file, key_file, hostnames)
+    return fingerprint(certificate_file)
+
+
+def create_ssl_context(certificate_file: str, key_file: str) -> ssl.SSLContext:
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    context.minimum_version = ssl.TLSVersion.TLSv1_2
+    context.load_cert_chain(certificate_file, key_file)
+    return context

tinyjukebox/web/logbuffer.py

@@ -0,0 +1,62 @@
+"""Keeps the latest log records in memory - shown on the web page."""
+
+import collections
+import itertools
+import logging
+import threading
+from typing import Any
+
+__all__ = ["LEVELS", "LogBuffer"]
+
+LEVELS = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+class LogBuffer(logging.Handler):
+    """Log handler with the newest ``capacity`` records; every record gets an increasing id."""
+
+    def __init__(self, capacity: int = 5000) -> None:
+        super().__init__(logging.DEBUG)
+        self._records: collections.deque[dict[str, Any]] = collections.deque(maxlen=capacity)
+        self._counter = itertools.count(1)
+        self._lock_records = threading.Lock()
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            message = record.getMessage()
+            if record.exc_info:
+                message += "\n" + logging.Formatter().formatException(record.exc_info)
+        except Exception:  # a broken log call must not break the logging
+            message = str(record.msg)
+        with self._lock_records:
+            self._records.append(
+                {
+                    "id": next(self._counter),
+                    "time": record.created,
+                    "level": record.levelname,
+                    "logger": record.name,
+                    "thread": record.threadName,
+                    "message": message,
+                }
+            )
+
+    @property
+    def last_id(self) -> int:
+        """Id of the newest record (0: none yet)."""
+        with self._lock_records:
+            return self._records[-1]["id"] if self._records else 0
+
+    def get(self, after: int = 0, level: str = "DEBUG", text: str | None = None, limit: int = 500) -> dict[str, Any]:
+        """Records with id > after, at least ``level``, containing ``text`` (case insensitive) - the newest
+        ``limit``."""
+        minimum = LEVELS.index(level) if level in LEVELS else 0
+        needle = text.lower() if text else None
+        with self._lock_records:
+            records = list(self._records)
+        result = [
+            r
+            for r in records
+            if r["id"] > after
+            and (r["level"] not in LEVELS or LEVELS.index(r["level"]) >= minimum)
+            and (needle is None or needle in r["message"].lower() or needle in r["logger"].lower())
+        ]
+        return {"entries": result[-limit:], "last_id": records[-1]["id"] if records else after}