Coverage for downtify/users.py: 99%

280 statements  

« 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. 

2 

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: 

6 

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. 

10 

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`). 

18 

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. 

22 

23Stored in ``downtify_auth.db`` next to devices and sessions. Passwords 

24are scrypt hashes (:func:`hash_password`). 

25""" 

26 

27from __future__ import annotations 

28 

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 

40 

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 

45 

46#: Shortest password accepted. 

47MIN_PASSWORD_LENGTH = 8 

48 

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 

54 

55ROLE_ADMIN = 'admin' 

56ROLE_USER = 'user' 

57ROLES = (ROLE_ADMIN, ROLE_USER) 

58 

59DEFAULT_USERNAME = 'admin' 

60DEFAULT_PASSWORD = 'downtify' 

61 

62#: Usernames: 3-32 letters, digits, dots, dashes or underscores. 

63_USERNAME_RE = re.compile(r'^[A-Za-z0-9._-]{3,32}$') 

64 

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} 

75 

76 

77class UserError(ValueError): 

78 """A request about users that can't be done; the message says why.""" 

79 

80 

81def _b64(data: bytes) -> str: 

82 return base64.urlsafe_b64encode(data).rstrip(b'=').decode() 

83 

84 

85def hash_password(password: str) -> str: 

86 """``scrypt$N$r$p$<salt>$<hash>`` for *password*.""" 

87 

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 ) 

101 

102 

103def verify_password(password: str, stored: str) -> bool: 

104 """Whether *password* matches a :func:`hash_password` value.""" 

105 

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) 

125 

126 

127def _now() -> str: 

128 return datetime.now(timezone.utc).isoformat() 

129 

130 

131def clean_username(value: Any) -> str: 

132 """*value* as a username, or :class:`UserError`.""" 

133 

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 

141 

142 

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 

150 

151 

152def clean_preferences(values: Any) -> dict[str, Any]: 

153 """The known preferences in *values*, each of its type.""" 

154 

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 

169 

170 

171def public_user(row: Any) -> dict[str, Any]: 

172 """A user as the API shows it - never the password hash.""" 

173 

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 } 

183 

184 

185class UserStore: 

186 """The users table (and the one-time accounts notice).""" 

187 

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() 

196 

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.""" 

200 

201 if fn not in self._listeners: 

202 self._listeners.append(fn) 

203 

204 def _changed(self) -> None: 

205 for fn in list(self._listeners): 

206 fn() 

207 

208 def _connect(self) -> AbstractContextManager[Connection]: 

209 return self.db.connect() 

210 

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.""" 

215 

216 if self._dummy is None: 

217 self._dummy = hash_password('not a real password') 

218 return self._dummy 

219 

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 """) 

251 

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 

258 

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 ) 

269 

270 # First run and upgrades 

271 

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. 

275 

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 """ 

281 

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 

321 

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).""" 

327 

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 } 

338 

339 def clear_notice(self) -> None: 

340 with self._connect() as conn: 

341 self._set_config(conn, 'accounts_notice', None) 

342 

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.""" 

346 

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 {} 

371 

372 # Signing in 

373 

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.""" 

379 

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) 

390 

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 ) 

398 

399 # Reading 

400 

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 

407 

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 

415 

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] 

422 

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``).""" 

426 

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 

433 

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. 

438 

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 """ 

443 

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) 

511 

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']) 

518 

519 # Changing 

520 

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 {} 

538 

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.""" 

548 

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 {} 

578 

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() 

590 

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) 

598 

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 

614 

615 # Preferences 

616 

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) 

629 

630 def set_preferences(self, user_id: int, values: Any) -> dict[str, Any]: 

631 """Merge *values* into the user's preferences; the result.""" 

632 

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