feat: Stage 2 — authentication and setup flow

Backend (tasks 2.1–2.6, 2.10):
- settings_repo: get/set/delete/get_all CRUD for the key-value settings table
- session_repo: create/get/delete/delete_expired for session rows
- setup_service: bcrypt password hashing, one-time-only enforcement,
  run_setup() / is_setup_complete() / get_password_hash()
- auth_service: login() with bcrypt verify + token creation,
  validate_session() with expiry check, logout()
- setup router: GET /api/setup (status), POST /api/setup (201 / 409)
- auth router: POST /api/auth/login (token + HttpOnly cookie),
               POST /api/auth/logout (clears cookie, idempotent)
- SetupRedirectMiddleware: 307 → /api/setup for all API paths until setup done
- require_auth dependency: cookie or Bearer token → Session or 401
- conftest.py: manually bootstraps app.state.db for router tests
  (ASGITransport does not trigger ASGI lifespan)
- 85 tests pass; ruff 0 errors; mypy --strict 0 errors

Frontend (tasks 2.7–2.9):
- types/auth.ts, types/setup.ts, api/auth.ts, api/setup.ts
- AuthProvider: sessionStorage-backed context (isAuthenticated, login, logout)
- RequireAuth: guard component → /login?next=<path> when unauthenticated
- SetupPage: Fluent UI form, client-side validation, inline errors
- LoginPage: single password input, ?next= redirect after success
- DashboardPage: placeholder (full impl Stage 5)
- App.tsx: full route tree (/setup, /login, /, *)

backend/app/services/auth_service.py

@@ -0,0 +1,113 @@
+"""Authentication service.
+
+Handles password verification, session creation, session validation, and
+session expiry.  Sessions are stored in the SQLite database so they
+survive server restarts.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import TYPE_CHECKING
+
+import bcrypt
+import structlog
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+    from app.models.auth import Session
+
+from app.repositories import session_repo
+from app.services import setup_service
+from app.utils.time_utils import add_minutes, utc_now
+
+log: structlog.stdlib.BoundLogger = structlog.get_logger()
+
+
+def _check_password(plain: str, hashed: str) -> bool:
+    """Return ``True`` if *plain* matches the bcrypt *hashed* password.
+
+    Args:
+        plain: The plain-text password to verify.
+        hashed: The stored bcrypt hash string.
+
+    Returns:
+        ``True`` on a successful match, ``False`` otherwise.
+    """
+    return bool(bcrypt.checkpw(plain.encode(), hashed.encode()))
+
+
+async def login(
+    db: aiosqlite.Connection,
+    password: str,
+    session_duration_minutes: int,
+) -> Session:
+    """Verify *password* and create a new session on success.
+
+    Args:
+        db: Active aiosqlite connection.
+        password: Plain-text password supplied by the user.
+        session_duration_minutes: How long the new session is valid for.
+
+    Returns:
+        A :class:`~app.models.auth.Session` domain model for the new session.
+
+    Raises:
+        ValueError: If the password is incorrect or no password hash is stored.
+    """
+    stored_hash = await setup_service.get_password_hash(db)
+    if stored_hash is None:
+        log.warning("bangui_login_no_hash")
+        raise ValueError("No password is configured — run setup first.")
+
+    if not _check_password(password, stored_hash):
+        log.warning("bangui_login_wrong_password")
+        raise ValueError("Incorrect password.")
+
+    token = secrets.token_hex(32)
+    now = utc_now()
+    created_iso = now.isoformat()
+    expires_iso = add_minutes(now, session_duration_minutes).isoformat()
+
+    session = await session_repo.create_session(
+        db, token=token, created_at=created_iso, expires_at=expires_iso
+    )
+    log.info("bangui_login_success", token_prefix=token[:8])
+    return session
+
+
+async def validate_session(db: aiosqlite.Connection, token: str) -> Session:
+    """Return the session for *token* if it is valid and not expired.
+
+    Args:
+        db: Active aiosqlite connection.
+        token: The opaque session token from the client.
+
+    Returns:
+        The :class:`~app.models.auth.Session` if it is valid.
+
+    Raises:
+        ValueError: If the token is not found or has expired.
+    """
+    session = await session_repo.get_session(db, token)
+    if session is None:
+        raise ValueError("Session not found.")
+
+    now_iso = utc_now().isoformat()
+    if session.expires_at <= now_iso:
+        await session_repo.delete_session(db, token)
+        raise ValueError("Session has expired.")
+
+    return session
+
+
+async def logout(db: aiosqlite.Connection, token: str) -> None:
+    """Invalidate the session identified by *token*.
+
+    Args:
+        db: Active aiosqlite connection.
+        token: The session token to revoke.
+    """
+    await session_repo.delete_session(db, token)
+    log.info("bangui_logout", token_prefix=token[:8])

backend/app/services/setup_service.py

@@ -0,0 +1,101 @@
+"""Setup service.
+
+Implements the one-time first-run configuration wizard.  Responsible for
+hashing the master password, persisting all initial settings, and
+enforcing the rule that setup can only run once.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import bcrypt
+import structlog
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+from app.repositories import settings_repo
+
+log: structlog.stdlib.BoundLogger = structlog.get_logger()
+
+# Keys used in the settings table.
+_KEY_PASSWORD_HASH = "master_password_hash"
+_KEY_SETUP_DONE = "setup_completed"
+_KEY_DATABASE_PATH = "database_path"
+_KEY_FAIL2BAN_SOCKET = "fail2ban_socket"
+_KEY_TIMEZONE = "timezone"
+_KEY_SESSION_DURATION = "session_duration_minutes"
+
+
+async def is_setup_complete(db: aiosqlite.Connection) -> bool:
+    """Return ``True`` if initial setup has already been performed.
+
+    Args:
+        db: Active aiosqlite connection.
+
+    Returns:
+        ``True`` when the ``setup_completed`` key exists in settings.
+    """
+    value = await settings_repo.get_setting(db, _KEY_SETUP_DONE)
+    return value == "1"
+
+
+async def run_setup(
+    db: aiosqlite.Connection,
+    *,
+    master_password: str,
+    database_path: str,
+    fail2ban_socket: str,
+    timezone: str,
+    session_duration_minutes: int,
+) -> None:
+    """Persist the initial configuration and mark setup as complete.
+
+    Hashes *master_password* with bcrypt before storing.  Raises
+    :class:`RuntimeError` if setup has already been completed.
+
+    Args:
+        db: Active aiosqlite connection.
+        master_password: Plain-text master password chosen by the user.
+        database_path: Filesystem path to the BanGUI SQLite database.
+        fail2ban_socket: Unix socket path for the fail2ban daemon.
+        timezone: IANA timezone identifier (e.g. ``"UTC"``).
+        session_duration_minutes: Session validity period in minutes.
+
+    Raises:
+        RuntimeError: If setup has already been completed.
+    """
+    if await is_setup_complete(db):
+        raise RuntimeError("Setup has already been completed.")
+
+    log.info("bangui_setup_started")
+
+    # Hash the master password — bcrypt automatically generates a salt.
+    password_bytes = master_password.encode()
+    hashed = bcrypt.hashpw(password_bytes, bcrypt.gensalt()).decode()
+
+    await settings_repo.set_setting(db, _KEY_PASSWORD_HASH, hashed)
+    await settings_repo.set_setting(db, _KEY_DATABASE_PATH, database_path)
+    await settings_repo.set_setting(db, _KEY_FAIL2BAN_SOCKET, fail2ban_socket)
+    await settings_repo.set_setting(db, _KEY_TIMEZONE, timezone)
+    await settings_repo.set_setting(
+        db, _KEY_SESSION_DURATION, str(session_duration_minutes)
+    )
+    # Mark setup as complete — must be last so a partial failure leaves
+    # setup_completed unset and does not lock out the user.
+    await settings_repo.set_setting(db, _KEY_SETUP_DONE, "1")
+
+    log.info("bangui_setup_completed")
+
+
+async def get_password_hash(db: aiosqlite.Connection) -> str | None:
+    """Return the stored bcrypt password hash, or ``None`` if not set.
+
+    Args:
+        db: Active aiosqlite connection.
+
+    Returns:
+        The bcrypt hash string, or ``None``.
+    """
+    return await settings_repo.get_setting(db, _KEY_PASSWORD_HASH)