Coverage for downtify/users.py: 99%
280 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""User accounts: who signs in to Downtify, and what they may do.
3Every web page and API call is made by a user, signed in with a username
4and password (or through a phone paired to their account - see
5:mod:`downtify.auth`). There are two roles:
7* **admin** - everything: every setting, every user, the activity log.
8* **user** - listen, search, download, like; in Settings only General,
9 Apps and About, and only their own account, preferences and devices.
11A new install starts with one admin, ``admin`` / ``downtify``
12(:data:`DEFAULT_USERNAME`, :data:`DEFAULT_PASSWORD`), flagged as still
13using the default password so the web app keeps suggesting a change. An
14install upgraded from a version without accounts gets the same account -
15or, when it had set the single sign-in password of the version before,
16that password (so it keeps working) - and a one-time notice on the
17sign-in page saying accounts exist now (:meth:`UserStore.notice`).
19The last admin can't be deleted or made a normal user: somebody has to
20be able to manage the server. ``python main.py auth-reset`` puts
21``admin`` / ``downtify`` back (as an admin) for a forgotten password.
23Stored in ``downtify_auth.db`` next to devices and sessions. Passwords
24are scrypt hashes (:func:`hash_password`).
25"""
27from __future__ import annotations
29import base64
30import hashlib
31import hmac
32import json
33import re
34import secrets
35import threading
36from contextlib import AbstractContextManager
37from datetime import datetime, timezone
38from pathlib import Path
39from typing import Any, Callable, Optional
41from .db.config import Dialect
42from .db.core import Connection, Database, as_database
43from .db.dialect import column_names, insert_returning_id
44from .db.errors import IntegrityError
46#: Shortest password accepted.
47MIN_PASSWORD_LENGTH = 8
49# scrypt: N=2**15, r=8, p=1 (~32 MiB, ~50-100 ms) - the OWASP minimum.
50_SCRYPT_N = 2**15
51_SCRYPT_R = 8
52_SCRYPT_P = 1
53_SCRYPT_MAXMEM = 64 * 1024 * 1024
55ROLE_ADMIN = 'admin'
56ROLE_USER = 'user'
57ROLES = (ROLE_ADMIN, ROLE_USER)
59DEFAULT_USERNAME = 'admin'
60DEFAULT_PASSWORD = 'downtify'
62#: Usernames: 3-32 letters, digits, dots, dashes or underscores.
63_USERNAME_RE = re.compile(r'^[A-Za-z0-9._-]{3,32}$')
65#: The preferences a user keeps for themselves (Settings > General), with
66#: their type. Anything else sent is ignored.
67PREFERENCES: dict[str, type] = {
68 'theme': str,
69 'locale': str,
70 'show_lyrics': bool,
71 'normalize_volume': bool,
72 'search_albums': bool,
73 'show_public_playlists': bool,
74}
77class UserError(ValueError):
78 """A request about users that can't be done; the message says why."""
81def _b64(data: bytes) -> str:
82 return base64.urlsafe_b64encode(data).rstrip(b'=').decode()
85def hash_password(password: str) -> str:
86 """``scrypt$N$r$p$<salt>$<hash>`` for *password*."""
88 salt = secrets.token_bytes(16)
89 digest = hashlib.scrypt(
90 password.encode(),
91 salt=salt,
92 n=_SCRYPT_N,
93 r=_SCRYPT_R,
94 p=_SCRYPT_P,
95 maxmem=_SCRYPT_MAXMEM,
96 )
97 return (
98 f'scrypt${_SCRYPT_N}${_SCRYPT_R}${_SCRYPT_P}$'
99 f'{_b64(salt)}${_b64(digest)}'
100 )
103def verify_password(password: str, stored: str) -> bool:
104 """Whether *password* matches a :func:`hash_password` value."""
106 try:
107 scheme, n, r, p, salt_b64, hash_b64 = stored.split('$')
108 if scheme != 'scrypt':
109 return False
110 salt = base64.urlsafe_b64decode(salt_b64 + '=' * (-len(salt_b64) % 4))
111 expected = base64.urlsafe_b64decode(
112 hash_b64 + '=' * (-len(hash_b64) % 4)
113 )
114 digest = hashlib.scrypt(
115 password.encode(),
116 salt=salt,
117 n=int(n),
118 r=int(r),
119 p=int(p),
120 maxmem=_SCRYPT_MAXMEM,
121 )
122 except (ValueError, TypeError):
123 return False
124 return hmac.compare_digest(digest, expected)
127def _now() -> str:
128 return datetime.now(timezone.utc).isoformat()
131def clean_username(value: Any) -> str:
132 """*value* as a username, or :class:`UserError`."""
134 name = str(value or '').strip()
135 if not _USERNAME_RE.fullmatch(name):
136 raise UserError(
137 'Usernames are 3 to 32 letters, digits, dots, dashes or '
138 'underscores'
139 )
140 return name
143def check_password_rules(password: Any) -> str:
144 text = str(password or '')
145 if len(text) < MIN_PASSWORD_LENGTH:
146 raise UserError(f'Use at least {MIN_PASSWORD_LENGTH} characters')
147 if len(text) > 256:
148 raise UserError('That password is too long')
149 return text
152def clean_preferences(values: Any) -> dict[str, Any]:
153 """The known preferences in *values*, each of its type."""
155 if not isinstance(values, dict):
156 return {}
157 clean: dict[str, Any] = {}
158 for key, kind in PREFERENCES.items():
159 if key not in values:
160 continue
161 value = values[key]
162 if kind is bool:
163 clean[key] = bool(value)
164 elif value is None:
165 clean[key] = ''
166 else:
167 clean[key] = str(value)[:32]
168 return clean
171def public_user(row: Any) -> dict[str, Any]:
172 """A user as the API shows it - never the password hash."""
174 return {
175 'id': int(row['id']),
176 'username': row['username'],
177 'role': row['role'],
178 'default_password': bool(row['default_password']),
179 'created_at': row['created_at'],
180 'last_login_at': row['last_login_at'],
181 'last_login_ip': row['last_login_ip'] or '',
182 }
185class UserStore:
186 """The users table (and the one-time accounts notice)."""
188 def __init__(self, db_path: str | Path | Database) -> None:
189 self.db = as_database(db_path, 'auth')
190 self._path = None if self.db.path is None else str(self.db.path)
191 self._lock = threading.Lock()
192 self._listeners: list[Callable[[], None]] = []
193 self._dummy: Optional[str] = None
194 if self.db.dialect is Dialect.SQLITE:
195 self._init_db()
197 def add_change_listener(self, fn: Callable[[], None]) -> None:
198 """Call *fn* after an account's name, role or password changes,
199 or it is deleted - e.g. to drop cached sign-ins."""
201 if fn not in self._listeners:
202 self._listeners.append(fn)
204 def _changed(self) -> None:
205 for fn in list(self._listeners):
206 fn()
208 def _connect(self) -> AbstractContextManager[Connection]:
209 return self.db.connect()
211 @property
212 def _dummy_hash(self) -> str:
213 """A hash to check against when there's no user, so an unknown
214 username takes as long as a wrong password."""
216 if self._dummy is None:
217 self._dummy = hash_password('not a real password')
218 return self._dummy
220 def _init_db(self) -> None:
221 # SQLite only: on PostgreSQL the migration made this schema.
222 with self._connect() as conn:
223 conn.execute("""
224 CREATE TABLE IF NOT EXISTS users (
225 id INTEGER PRIMARY KEY AUTOINCREMENT,
226 username TEXT NOT NULL UNIQUE COLLATE NOCASE,
227 password_hash TEXT NOT NULL,
228 role TEXT NOT NULL DEFAULT 'user',
229 default_password INTEGER NOT NULL DEFAULT 0,
230 prefs_json TEXT NOT NULL DEFAULT '{}',
231 created_at TEXT NOT NULL,
232 last_login_at TEXT,
233 last_login_ip TEXT NOT NULL DEFAULT ''
234 )
235 """)
236 conn.execute("""
237 CREATE TABLE IF NOT EXISTS auth_config (
238 key TEXT PRIMARY KEY,
239 value TEXT NOT NULL
240 )
241 """)
242 conn.execute("""
243 CREATE TABLE IF NOT EXISTS auth_oidc_identities (
244 issuer TEXT NOT NULL,
245 subject TEXT NOT NULL,
246 user_id INTEGER NOT NULL,
247 PRIMARY KEY (issuer, subject),
248 UNIQUE (user_id)
249 )
250 """)
252 @staticmethod
253 def _config(conn: Connection, key: str) -> Optional[str]:
254 row = conn.execute(
255 'SELECT value FROM auth_config WHERE key = ?', (key,)
256 ).fetchone()
257 return row['value'] if row else None
259 @staticmethod
260 def _set_config(conn: Connection, key: str, value: Optional[str]) -> None:
261 if value is None:
262 conn.execute('DELETE FROM auth_config WHERE key = ?', (key,))
263 else:
264 conn.execute(
265 """INSERT INTO auth_config (key, value) VALUES (?, ?)
266 ON CONFLICT(key) DO UPDATE SET value = excluded.value""",
267 (key, value),
268 )
270 # First run and upgrades
272 def ensure_default_admin(self, *, existing_install: bool) -> bool:
273 """Create the first admin when there are no users yet. Returns
274 whether one was created.
276 An *existing_install* (upgraded from a version without accounts)
277 also gets the accounts notice. The single sign-in password of the
278 version before, if one was set, becomes the admin's password, and
279 the paired devices of that version are given to the admin.
280 """
282 with self._lock, self._connect() as conn:
283 if conn.execute('SELECT 1 FROM users LIMIT 1').fetchone():
284 return False
285 legacy = self._config(conn, 'password_hash')
286 inserted = conn.execute(
287 'INSERT INTO users (username, password_hash, role, '
288 'default_password, created_at) VALUES (?, ?, ?, ?, ?) '
289 'ON CONFLICT DO NOTHING',
290 (
291 DEFAULT_USERNAME,
292 legacy or hash_password(DEFAULT_PASSWORD),
293 ROLE_ADMIN,
294 0 if legacy else 1,
295 _now(),
296 ),
297 ).rowcount
298 if not inserted:
299 # Another process created the first admin meanwhile.
300 return False
301 admin_id = conn.execute(
302 'SELECT id FROM users WHERE lower(username) = lower(?)',
303 (DEFAULT_USERNAME,),
304 ).fetchone()['id']
305 # Devices paired before accounts existed belong to the admin.
306 columns = set(column_names(conn, 'auth_devices'))
307 if 'user_id' in columns:
308 conn.execute(
309 'UPDATE auth_devices SET user_id = ? WHERE user_id = 0',
310 (admin_id,),
311 )
312 if existing_install:
313 self._set_config(
314 conn,
315 'accounts_notice',
316 'kept_password' if legacy else 'default_password',
317 )
318 self._set_config(conn, 'password_hash', None)
319 self._set_config(conn, 'require_sign_in', None)
320 return True
322 def notice(self) -> Optional[dict[str, Any]]:
323 """The one-time notice for an upgraded install, shown on the
324 sign-in page until an admin has signed in with a password of
325 their own: ``{username, password}`` - the password only when it
326 is still the default (``None`` when the old one was kept)."""
328 with self._connect() as conn:
329 kind = self._config(conn, 'accounts_notice')
330 if not kind:
331 return None
332 return {
333 'username': DEFAULT_USERNAME,
334 'password': DEFAULT_PASSWORD
335 if kind == 'default_password'
336 else None,
337 }
339 def clear_notice(self) -> None:
340 with self._connect() as conn:
341 self._set_config(conn, 'accounts_notice', None)
343 def reset_admin(self) -> dict[str, Any]:
344 """Recovery (``python main.py auth-reset``): an admin ``admin``
345 with the default password, whether or not it existed."""
347 with self._lock, self._connect() as conn:
348 row = conn.execute(
349 'SELECT id FROM users WHERE lower(username) = lower(?)',
350 (DEFAULT_USERNAME,),
351 ).fetchone()
352 if row is None:
353 conn.execute(
354 'INSERT INTO users (username, password_hash, role, '
355 'default_password, created_at) VALUES (?, ?, ?, 1, ?)',
356 (
357 DEFAULT_USERNAME,
358 hash_password(DEFAULT_PASSWORD),
359 ROLE_ADMIN,
360 _now(),
361 ),
362 )
363 else:
364 conn.execute(
365 'UPDATE users SET password_hash = ?, role = ?, '
366 'default_password = 1 WHERE id = ?',
367 (hash_password(DEFAULT_PASSWORD), ROLE_ADMIN, row['id']),
368 )
369 self._changed()
370 return self.by_username(DEFAULT_USERNAME) or {}
372 # Signing in
374 def authenticate(
375 self, username: str, password: str
376 ) -> Optional[dict[str, Any]]:
377 """The user, when *username* and *password* match; else ``None``.
378 Takes as long either way."""
380 with self._connect() as conn:
381 row = conn.execute(
382 'SELECT * FROM users WHERE lower(username) = lower(?)',
383 (str(username or '').strip(),),
384 ).fetchone()
385 stored = row['password_hash'] if row else self._dummy_hash
386 ok = verify_password(str(password or ''), stored)
387 if row is None or not ok:
388 return None
389 return public_user(row)
391 def record_login(self, user_id: int, ip: str) -> None:
392 with self._connect() as conn:
393 conn.execute(
394 'UPDATE users SET last_login_at = ?, last_login_ip = ? '
395 'WHERE id = ?',
396 (_now(), ip[:64], user_id),
397 )
399 # Reading
401 def get(self, user_id: int) -> Optional[dict[str, Any]]:
402 with self._connect() as conn:
403 row = conn.execute(
404 'SELECT * FROM users WHERE id = ?', (user_id,)
405 ).fetchone()
406 return public_user(row) if row else None
408 def by_username(self, username: str) -> Optional[dict[str, Any]]:
409 with self._connect() as conn:
410 row = conn.execute(
411 'SELECT * FROM users WHERE lower(username) = lower(?)',
412 (username,),
413 ).fetchone()
414 return public_user(row) if row else None
416 def list(self) -> list[dict[str, Any]]:
417 with self._connect() as conn:
418 rows = conn.execute(
419 'SELECT * FROM users ORDER BY lower(username)'
420 ).fetchall()
421 return [public_user(r) for r in rows]
423 def first_admin(self) -> Optional[dict[str, Any]]:
424 """The oldest admin - who everyone is when sign-in is turned off
425 (``DOWNTIFY_DISABLE_AUTH``)."""
427 with self._connect() as conn:
428 row = conn.execute(
429 'SELECT * FROM users WHERE role = ? ORDER BY id LIMIT 1',
430 (ROLE_ADMIN,),
431 ).fetchone()
432 return public_user(row) if row else None
434 def _get_or_create_oidc_user(
435 self, issuer: str, subject: str, username: str, role: str
436 ) -> dict[str, Any]:
437 """Find an external identity or provision its first local account.
439 The issuer and subject are the identity key; usernames are only a
440 display name and are never used to link an existing local account.
441 The role follows the configured OIDC group mapping on each login.
442 """
444 if not issuer or not subject:
445 raise UserError('OIDC issuer and subject are required')
446 if role not in ROLES:
447 raise UserError('Unknown role')
448 name = clean_username(username)
449 changed = False
450 with self._lock, self._connect() as conn:
451 row = conn.execute(
452 'SELECT users.* FROM auth_oidc_identities '
453 'JOIN users ON users.id = auth_oidc_identities.user_id '
454 'WHERE issuer = ? AND subject = ?',
455 (issuer, subject),
456 ).fetchone()
457 if row:
458 if row['role'] != role:
459 if (
460 row['role'] == ROLE_ADMIN
461 and role != ROLE_ADMIN
462 and conn.execute(
463 'SELECT COUNT(*) AS n FROM users WHERE role = ?',
464 (ROLE_ADMIN,),
465 ).fetchone()['n']
466 <= 1
467 ):
468 raise UserError('The last admin must stay an admin')
469 conn.execute(
470 'UPDATE users SET role = ? WHERE id = ?',
471 (role, row['id']),
472 )
473 changed = True
474 user_id = row['id']
475 else:
476 suffix = hashlib.sha256(
477 f'{issuer}\0{subject}'.encode()
478 ).hexdigest()[:8]
479 candidate = name
480 index = 0
481 while conn.execute(
482 'SELECT 1 FROM users WHERE lower(username) = lower(?)',
483 (candidate,),
484 ).fetchone():
485 extra = suffix if index == 0 else f'{suffix}{index}'
486 candidate = f'{name[: 32 - len(extra) - 1]}_{extra}'
487 index += 1
488 user_id = insert_returning_id(
489 conn,
490 'INSERT INTO users (username, password_hash, role, '
491 'created_at) VALUES (?, ?, ?, ?)',
492 (
493 candidate,
494 hash_password(secrets.token_urlsafe(48)),
495 role,
496 _now(),
497 ),
498 )
499 conn.execute(
500 'INSERT INTO auth_oidc_identities '
501 '(issuer, subject, user_id) VALUES (?, ?, ?)',
502 (issuer, subject, user_id),
503 )
504 changed = True
505 row = conn.execute(
506 'SELECT * FROM users WHERE id = ?', (user_id,)
507 ).fetchone()
508 if changed:
509 self._changed()
510 return public_user(row)
512 def admin_count(self) -> int:
513 with self._connect() as conn:
514 row = conn.execute(
515 'SELECT COUNT(*) AS n FROM users WHERE role = ?', (ROLE_ADMIN,)
516 ).fetchone()
517 return int(row['n'])
519 # Changing
521 def create(
522 self, username: Any, password: Any, role: str = ROLE_USER
523 ) -> dict[str, Any]:
524 name = clean_username(username)
525 secret = check_password_rules(password)
526 if role not in ROLES:
527 raise UserError('Unknown role')
528 try:
529 with self._connect() as conn:
530 conn.execute(
531 'INSERT INTO users (username, password_hash, role, '
532 'created_at) VALUES (?, ?, ?, ?)',
533 (name, hash_password(secret), role, _now()),
534 )
535 except IntegrityError as exc:
536 raise UserError('That username is taken') from exc
537 return self.by_username(name) or {}
539 def update(
540 self,
541 user_id: int,
542 *,
543 username: Any = None,
544 role: Optional[str] = None,
545 ) -> dict[str, Any]:
546 """Rename a user and/or change their role. Refuses to leave the
547 server without an admin."""
549 with self._lock:
550 current = self.get(user_id)
551 if current is None:
552 raise UserError('User not found')
553 updates: dict[str, Any] = {}
554 if username is not None:
555 updates['username'] = clean_username(username)
556 if role is not None:
557 if role not in ROLES:
558 raise UserError('Unknown role')
559 if (
560 current['role'] == ROLE_ADMIN
561 and role != ROLE_ADMIN
562 and self.admin_count() <= 1
563 ):
564 raise UserError('The last admin must stay an admin')
565 updates['role'] = role
566 if updates:
567 assignments = ', '.join(f'{key} = ?' for key in updates)
568 try:
569 with self._connect() as conn:
570 conn.execute(
571 f'UPDATE users SET {assignments} WHERE id = ?',
572 (*updates.values(), user_id),
573 )
574 except IntegrityError as exc:
575 raise UserError('That username is taken') from exc
576 self._changed()
577 return self.get(user_id) or {}
579 def set_password(self, user_id: int, password: Any) -> None:
580 secret = check_password_rules(password)
581 with self._connect() as conn:
582 cur = conn.execute(
583 'UPDATE users SET password_hash = ?, default_password = 0 '
584 'WHERE id = ?',
585 (hash_password(secret), user_id),
586 )
587 if cur.rowcount == 0:
588 raise UserError('User not found')
589 self._changed()
591 def check_password(self, user_id: int, password: str) -> bool:
592 with self._connect() as conn:
593 row = conn.execute(
594 'SELECT password_hash FROM users WHERE id = ?', (user_id,)
595 ).fetchone()
596 stored = row['password_hash'] if row else self._dummy_hash
597 return bool(row) and verify_password(str(password or ''), stored)
599 def delete(self, user_id: int) -> dict[str, Any]:
600 with self._lock:
601 current = self.get(user_id)
602 if current is None:
603 raise UserError('User not found')
604 if current['role'] == ROLE_ADMIN and self.admin_count() <= 1:
605 raise UserError('The last admin cannot be deleted')
606 with self._connect() as conn:
607 conn.execute(
608 'DELETE FROM auth_oidc_identities WHERE user_id = ?',
609 (user_id,),
610 )
611 conn.execute('DELETE FROM users WHERE id = ?', (user_id,))
612 self._changed()
613 return current
615 # Preferences
617 def preferences(self, user_id: int) -> dict[str, Any]:
618 with self._connect() as conn:
619 row = conn.execute(
620 'SELECT prefs_json FROM users WHERE id = ?', (user_id,)
621 ).fetchone()
622 if row is None:
623 return {}
624 try:
625 data = json.loads(row['prefs_json'])
626 except ValueError:
627 return {}
628 return clean_preferences(data)
630 def set_preferences(self, user_id: int, values: Any) -> dict[str, Any]:
631 """Merge *values* into the user's preferences; the result."""
633 merged = {**self.preferences(user_id), **clean_preferences(values)}
634 with self._connect() as conn:
635 conn.execute(
636 'UPDATE users SET prefs_json = ? WHERE id = ?',
637 (json.dumps(merged), user_id),
638 )
639 return merged