Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

33.9 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Authentication API routes."""

from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
from fastapi.security import HTTPAuthorizationCredentials

import base64
import hashlib
import importlib.util
import ipaddress
import os
import shlex
import sqlite3
import sys
import threading
import time
from collections import deque
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Optional

from models.auth import (
    ApiKeyListResponse,
    ApiKeyResponse,
    AuthLoginRequest,
    AuthStatusResponse,
    ChangePasswordRequest,
    CreateApiKeyRequest,
    CreateApiKeyResponse,
    DesktopInitialPasswordRequest,
    DesktopLoginRequest,
    RefreshTokenRequest,
)
from models.users import Token
from auth import storage, hashing, policy
from loggers import get_logger
from storage import sqlite_gate
from utils.account_context import OWNER_ACCOUNT_ID
from auth.authentication import (
    authenticated_via_desktop_jwt,
    authenticated_without_credential,
    create_access_token,
    create_refresh_token,
    get_current_credential,
    get_current_subject,
    get_current_subject_allow_password_change,
    is_keyless,
    new_refresh_token_value,
    refresh_access_token,
    security,
)

router = APIRouter()
logger = get_logger(__name__)


def _account_id_of(username: str) -> "str | None":
    """Immutable account id for ``username``, or None. Names are reusable, so state must not key
    on the name: a recreated account would inherit its predecessor's data."""
    if username == storage.DEFAULT_ADMIN_USERNAME:
        return OWNER_ACCOUNT_ID
    account = storage.get_account(username)
    return account.account_id if account is not None else None


def _require_a_credential_of_its_own(what: str):
    """Refuse keyless-API-only callers: keys and sign-outs they cause outlive the keyless setting."""

    def dependency(no_credential: bool = Depends(authenticated_without_credential)) -> None:
        if no_credential:
            raise HTTPException(
                status_code = status.HTTP_403_FORBIDDEN,
                detail = f"{what} can only be done from the Unsloth UI or with an existing API key.",
            )

    return dependency


# Byte-identical to _WINDOWS_CLI_ENTRYPOINT in unsloth_cli/commands/studio.py and to
# the bootstrap unsloth_cli/__main__.py documents for user-site installs.
_CLI_BOOTSTRAP = (
    "import sys, os; sys.path[:1] = [x for x in sys.path[:1] if getattr(sys.flags, 'safe_path', False) or x not in ('', os.getcwd())]; "
    "sys.argv[0] = 'unsloth'; from unsloth_cli import app; sys.exit(app())"
)


def _cli_is_inside(prefix: str) -> bool:
    """Whether unsloth_cli sits under prefix, so python -I still finds it; located by spec not
    import, since this runs in a request handler."""
    try:
        spec = importlib.util.find_spec("unsloth_cli")
        origin = getattr(spec, "origin", None)
        if not origin:
            # A namespace package, or nothing found.
            return False
        return Path(origin).resolve().is_relative_to(Path(prefix).resolve())
    except (ImportError, OSError, ValueError, AttributeError):
        return False


def _reset_password_command_on_path() -> str:
    """PATH form only: an unauthenticated 401 body is readable by any origin, so no host paths here."""
    if os.name == "nt":
        return "unsloth.cmd studio reset-password"
    return "unsloth studio reset-password"


def _reset_password_command() -> str:
    """Shell command for the password hint. Windows names unsloth.cmd, never unsloth.exe, which AppControl may deny; -I only inside prefix."""
    try:
        bin_dir = os.path.dirname(os.path.abspath(sys.executable))
        if os.name == "nt":
            python = os.path.abspath(sys.executable)
            if " " not in python:
                if _cli_is_inside(sys.prefix):
                    return f"{python} -I -m unsloth_cli studio reset-password"
                return f'{python} -X utf8 -c "{_CLI_BOOTSTRAP}" studio reset-password'
            # A spaced interpreter path cannot be written unquoted: fall through to the PATH form.
        else:
            exe = os.path.join(bin_dir, "unsloth")
            if os.path.isfile(exe):
                return f"{shlex.quote(exe)} studio reset-password"
    except Exception:
        pass
    return _reset_password_command_on_path()


# Per-(ip, user) bucket stops one user's typos blocking others; per-IP stops username spray.
# Single-process only; multi-worker deployments need a shared store.
_LOGIN_BUCKETS: dict[tuple[str, str], deque] = {}
_LOGIN_IP_BUCKETS: dict[str, deque] = {}
_LOGIN_BUCKETS_LOCK = threading.Lock()
_LOGIN_WINDOW_SECONDS = 60.0
_LOGIN_MAX_FAILS = 5
_LOGIN_IP_MAX_FAILS = 30
# On overflow, reclaim expired buckets, then use sharded overflow rather than evict a hot bucket.
_LOGIN_MAX_BUCKETS = 4096
# Last full stale-sweep time; rate-limits the O(n) sweep under a burst of new IPs.
_LAST_IP_PRUNE = 0.0
# Overflow shards for per-IP failures with no bucket; when full, a new IP evicts the lowest count.
_LOGIN_IP_OVERFLOW_SHARDS = 256
_LOGIN_IP_OVERFLOW_MAX = 64
_LOGIN_IP_OVERFLOW: list[dict] = [dict() for _ in range(_LOGIN_IP_OVERFLOW_SHARDS)]


def _overflow_shard(ip: str) -> dict:
    return _LOGIN_IP_OVERFLOW[hash(ip) % _LOGIN_IP_OVERFLOW_SHARDS]


def _overflow_record(ip: str, now: float) -> int:
    """Record an overflow failure for ``ip`` and return its windowed count."""
    shard = _overflow_shard(ip)
    entry = shard.get(ip)
    if entry is not None:
        if now - entry[1] > _LOGIN_WINDOW_SECONDS:
            entry[0], entry[1] = 1, now
        else:
            # Cap at the threshold so a saturated source cannot build a huge deque under the lock.
            entry[0] = min(entry[0] + 1, _LOGIN_IP_MAX_FAILS)
        return entry[0]
    if len(shard) >= _LOGIN_IP_OVERFLOW_MAX:
        # Make room by dropping the lowest-count entry.
        del shard[min(shard, key = lambda k: shard[k][0])]
    shard[ip] = [1, now]
    return 1


def _overflow_blocked(ip: str, now: float) -> int:
    """Seconds this IP is throttled by its own overflow count, or 0."""
    shard = _overflow_shard(ip)
    entry = shard.get(ip)
    if entry is None:
        return 0
    if now - entry[1] > _LOGIN_WINDOW_SECONDS:
        del shard[ip]
        return 0
    if entry[0] >= _LOGIN_IP_MAX_FAILS:
        return max(1, int(_LOGIN_WINDOW_SECONDS - (now - entry[1])))
    return 0


def _overflow_take(ip: str, now: float) -> tuple[int, float]:
    """Pop an IP overflow entry to migrate its count into a fresh bucket; (0, now) if none or expired."""
    entry = _overflow_shard(ip).pop(ip, None)
    if entry is None or now - entry[1] > _LOGIN_WINDOW_SECONDS:
        return 0, now
    # Clamp the carried count so migration allocates at most _LOGIN_IP_MAX_FAILS deque entries.
    return min(entry[0], _LOGIN_IP_MAX_FAILS), entry[1]


# Leading NUL is not a real username; folds unknown users into one slot so attacker names cannot blow up the bucket dict.
_UNKNOWN_LOGIN_USER = "\x00unknown-user"
# Own slot: sharing /login's would let anyone lock out every account via the tunnel.
_DESKTOP_LOGIN_USER = "\x00desktop-login"


def _trust_forwarded_for() -> bool:
    """Honour X-Forwarded-For only when UNSLOTH_STUDIO_TRUST_FORWARDED is set. Off by default so a
    direct caller can't spoof the header."""
    return os.environ.get("UNSLOTH_STUDIO_TRUST_FORWARDED", "").lower() in (
        "1",
        "true",
        "yes",
    )


def _normalize_forwarded_addr(value: str) -> str:
    """Parse an XFF / Forwarded `for=` value into a bare IP (port-stripped)."""
    value = (value or "").strip().strip('"')
    if not value or value.lower() == "unknown":
        return ""
    if value.startswith("["):
        # Bracketed IPv6, optionally with port.
        end = value.find("]")
        if end <= 0:
            return ""
        host = value[1:end]
    elif value.count(":") == 1:
        # IPv4:port. Bare IPv6 has multiple colons → else branch.
        head, _, tail = value.rpartition(":")
        host = head if tail.isdigit() and head else value
    else:
        host = value
    try:
        return str(ipaddress.ip_address(host))
    except ValueError:
        return ""


def _forwarded_for_from_element(element: str) -> str:
    """Pick the `for=` token out of a single ``Forwarded`` element."""
    for tok in element.split(";"):
        key, sep, val = tok.strip().partition("=")
        if sep and key.lower() == "for":
            return _normalize_forwarded_addr(val)
    return ""


def _client_ip(request: Request | None) -> str:
    if request is None:
        return "_unknown"
    if _trust_forwarded_for():
        # Rightmost entry only: the trusted proxy appends the client it saw, and everything left of
        # it is the caller's own text, so keying on it would let each guess pick a fresh bucket.
        from utils.client_ip import header_fields

        xff = header_fields(request.headers, "x-forwarded-for")
        if xff:
            normalized = _normalize_forwarded_addr(xff.rsplit(",", 1)[-1])
            if normalized:
                return normalized
        fwd = header_fields(request.headers, "forwarded")
        if fwd:
            normalized = _forwarded_for_from_element(fwd.rsplit(",", 1)[-1])
            if normalized:
                return normalized
    return (request.client.host if request.client else None) or "_unknown"


_MAX_BUCKET_USERNAME_CHARS = 256


def _bucket_key(request: Request | None, username: str) -> tuple[str, str]:
    name = (username or "").casefold()
    # Bound the memory each bucket key holds; real usernames are far shorter and keep their own key.
    if len(name) > _MAX_BUCKET_USERNAME_CHARS:
        name = "\x00long:" + hashlib.sha256(name.encode("utf-8", "surrogatepass")).hexdigest()
    return (_client_ip(request), name)


def _unknown_user_key(request: Request | None) -> tuple[str, str]:
    return (_client_ip(request), _UNKNOWN_LOGIN_USER)


def _desktop_login_key(request: Request | None) -> tuple[str, str]:
    # Separate from /login: tunnel and shell share loopback, so guesses would 429 the shell.
    return (_client_ip(request) + _DESKTOP_LOGIN_USER, _DESKTOP_LOGIN_USER)


def _prune_bucket(bucket: deque, now: float) -> None:
    while bucket and now - bucket[0] > _LOGIN_WINDOW_SECONDS:
        bucket.popleft()


def _prune_stale_buckets(now: float) -> None:
    """Drop empty / expired account buckets to bound memory under spray."""
    stale: list[tuple[str, str]] = []
    for key, bucket in _LOGIN_BUCKETS.items():
        _prune_bucket(bucket, now)
        if not bucket:
            stale.append(key)
    for key in stale:
        _LOGIN_BUCKETS.pop(key, None)


def _prune_stale_ip_buckets(now: float) -> None:
    """Prune empty or expired per-IP buckets to bound memory under spray; only successful logins
    otherwise reclaim them, so failure-only spray grows the dict without bound."""
    stale: list[str] = []
    for bucket_ip, bucket in _LOGIN_IP_BUCKETS.items():
        _prune_bucket(bucket, now)
        if not bucket:
            stale.append(bucket_ip)
    for bucket_ip in stale:
        _LOGIN_IP_BUCKETS.pop(bucket_ip, None)


def _record_login_failure(key: tuple[str, str]) -> int:
    global _LAST_IP_PRUNE
    now = time.monotonic()
    ip, _username = key
    with _LOGIN_BUCKETS_LOCK:
        # At the cap, a new IP reclaims expired buckets (rate-limited) so a spray cannot reset hot ones.
        ip_bucket = _LOGIN_IP_BUCKETS.get(ip)
        if ip_bucket is None and len(_LOGIN_IP_BUCKETS) >= _LOGIN_MAX_BUCKETS:
            if now - _LAST_IP_PRUNE >= 1.0:
                _prune_stale_ip_buckets(now)
                _LAST_IP_PRUNE = now
        if ip_bucket is None and len(_LOGIN_IP_BUCKETS) >= _LOGIN_MAX_BUCKETS:
            # Every bucket is hot: count in the overflow shard, never evict a live bucket, since that would reset its IP counter.
            ip_fails = _overflow_record(ip, now)
        else:
            if ip_bucket is None:
                ip_bucket = _LOGIN_IP_BUCKETS[ip] = deque()
                # Carry overflow failures so the transition can't double the per-IP limit.
                carried, start = _overflow_take(ip, now)
                ip_bucket.extend([start] * carried)
            _prune_bucket(ip_bucket, now)
            ip_bucket.append(now)
            ip_fails = len(ip_bucket)

        if key not in _LOGIN_BUCKETS and len(_LOGIN_BUCKETS) >= _LOGIN_MAX_BUCKETS:
            _prune_stale_buckets(now)
        if key in _LOGIN_BUCKETS or len(_LOGIN_BUCKETS) < _LOGIN_MAX_BUCKETS:
            account_bucket = _LOGIN_BUCKETS.setdefault(key, deque())
            _prune_bucket(account_bucket, now)
            account_bucket.append(now)
            return len(account_bucket)
        # Both dicts at cap (sustained spray): fall back to the per-IP count.
        return ip_fails


def _blocked_for(bucket: deque | None, now: float, max_fails: int) -> int:
    if not bucket:
        return 0
    _prune_bucket(bucket, now)
    if len(bucket) >= max_fails:
        return max(1, int(_LOGIN_WINDOW_SECONDS - (now - bucket[0])))
    return 0


def _login_blocked(key: tuple[str, str]) -> int:
    """Return seconds until the next attempt is allowed, or 0."""
    now = time.monotonic()
    ip, _username = key
    with _LOGIN_BUCKETS_LOCK:
        # Honor the IP's overflow shard regardless of current dict capacity
        ip_blocked = max(
            _blocked_for(_LOGIN_IP_BUCKETS.get(ip), now, _LOGIN_IP_MAX_FAILS),
            _overflow_blocked(ip, now),
        )
        return max(_blocked_for(_LOGIN_BUCKETS.get(key), now, _LOGIN_MAX_FAILS), ip_blocked)


def _clear_login_bucket(key: tuple[str, str]) -> None:
    ip, _username = key
    with _LOGIN_BUCKETS_LOCK:
        _LOGIN_BUCKETS.pop(key, None)
        _LOGIN_IP_BUCKETS.pop(ip, None)
        # Successful login clears only this IP's throttle and overflow entry, not a shard-mate's.
        _overflow_shard(ip).pop(ip, None)


# Sync def: SQLite on first call, so FastAPI runs it in the threadpool.
@router.get("/identity")
def identity(nonce: str, request: Request) -> dict:
    """Challenge-response proof this is the real local Unsloth: caller sends a nonce,
    gets HMAC(install identity secret, nonce, connection address + port).
    Unauthenticated and side-effect free; a process that can't read the same-user
    secret can't forge a proof, and binding to the address/port the connection
    landed on stops a squatter relaying a proof from the real Unsloth elsewhere."""
    try:
        raw = base64.urlsafe_b64decode(nonce)
    except Exception:
        raise HTTPException(
            status_code = status.HTTP_400_BAD_REQUEST, detail = "nonce must be base64url"
        )
    if not 16 <= len(raw) <= 128:
        raise HTTPException(
            status_code = status.HTTP_400_BAD_REQUEST, detail = "nonce must decode to 16-128 bytes"
        )
    # scope server is getsockname, never the client-controlled Host header.
    server = request.scope.get("server") or ("", 0)
    host = server[0] or ""
    port = server[1] if server[1] is not None else 0
    return {"proof": storage.compute_identity_proof(raw, host, port)}


# FastAPI offloads sync reads; mutations stay on-loop to preserve atomic sequences.
@router.get("/status", response_model = AuthStatusResponse)
def auth_status() -> AuthStatusResponse:
    """Auth initialization state; ``default_username`` is exposed for first-boot UI prefill only."""
    from auth.bootstrap_timeout import bootstrap_deadline_remaining_seconds

    requires_change = (
        storage.requires_password_change(storage.DEFAULT_ADMIN_USERNAME)
        if storage.is_initialized()
        else True
    )
    # Only while the default password stands: that is what the deadline fires on.
    from auth.policy import installation_has_managed_accounts, login_mode

    return AuthStatusResponse(
        initialized = storage.is_initialized(),
        default_username = storage.DEFAULT_ADMIN_USERNAME,
        login_mode = login_mode(),
        # Public pre-login hint for older clients; signed-in clients use the account role.
        full_access = not installation_has_managed_accounts(),
        requires_password_change = requires_change,
        bootstrap_deadline_seconds = (
            bootstrap_deadline_remaining_seconds() if requires_change else None
        ),
    )


def _login_failure_detail() -> str:
    """PATH form only: the body is unauthenticated, so it must not reveal the account or install layout."""
    command = _reset_password_command_on_path()
    where = "in the environment Unsloth is installed in"
    if policy.installation_is_multi_user():
        return (
            "Incorrect username, password or setup code. Ask the installation owner to reset "
            f"the account, by running this on the Unsloth Studio host {where}: {command} "
            "--username <name>"
        )
    return f"Incorrect password. To reset it, run this in your terminal, {where}: {command}"


@router.post("/login", response_model = Token)
async def login(payload: AuthLoginRequest, request: Request) -> Token:
    """Login with username/password. Per-account + per-IP rate-limited."""
    username = payload.username
    if policy.installation_is_multi_user():
        # Before the bucket key, so the owner's sign-in name and "unsloth" share one budget.
        username = storage.resolve_login_username(username.casefold())
    key = _bucket_key(request, username)
    unknown_key = _unknown_user_key(request)
    blocked_for = max(_login_blocked(key), _login_blocked(unknown_key))
    if blocked_for > 0:
        raise HTTPException(
            status_code = status.HTTP_429_TOO_MANY_REQUESTS,
            # IP not interpolated into the body: behind a proxy/NAT it is misleading or an info leak.
            detail = (f"Too many failed login attempts. " f"Try again in {blocked_for} seconds."),
            headers = {"Retry-After": str(blocked_for)},
        )

    record = storage.get_user_and_secret(username)
    if record is None:
        # Per-name buckets as for real accounts: a shared unknown bucket is an existence oracle.
        hashing.equalize_login_work(payload.password)
        _record_login_failure(key)
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = _login_failure_detail(),
        )

    if username == storage.DEFAULT_ADMIN_USERNAME:
        salt, pwd_hash, jwt_secret, must_change_password = record
        verified = hashing.verify_password(payload.password, salt, pwd_hash)
    else:
        record = storage.authenticate_account_login(username, payload.password)
        verified = record is not None
        if record is not None:
            salt, pwd_hash, jwt_secret, must_change_password = record
    if not verified:
        _record_login_failure(key)
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = _login_failure_detail(),
        )

    _clear_login_bucket(key)
    _clear_login_bucket(unknown_key)
    # Issue against the credential version just verified.
    access_token = create_access_token(subject = username, secret = jwt_secret)
    refresh_token = create_refresh_token(subject = username, secret = jwt_secret)
    return Token(
        access_token = access_token,
        refresh_token = refresh_token,
        token_type = "bearer",
        must_change_password = must_change_password,
        account_id = _account_id_of(username),
    )


@router.post("/logout", status_code = status.HTTP_204_NO_CONTENT)
async def logout(
    request: Request,
    current_subject: str = Depends(get_current_subject_allow_password_change),
    _own_credential: None = Depends(_require_a_credential_of_its_own("Signing out")),
) -> Response:
    """Revoke refresh tokens for the subject; the access token is stateless and expires on its own."""
    try:
        storage.revoke_user_refresh_tokens(current_subject, account_id = _key_account_scope())
    except Exception:
        pass
    if current_subject == storage.DEFAULT_ADMIN_USERNAME:
        try:
            request.app.state.bootstrap_password = None
        except AttributeError:
            pass
    return Response(status_code = status.HTTP_204_NO_CONTENT)


# Sync def: PBKDF2 + SQLite would block the event loop.
@router.post("/desktop-login", response_model = Token)
def desktop_login(payload: DesktopLoginRequest, request: Request) -> Token | Response:
    """Exchange a local desktop secret for desktop-marked owner tokens.

    Multi-user installations return ``login_required`` instead of tokens.
    Failed attempts are rate-limited per IP independently of /login.
    """
    # Shell ownership probes need 401 for malformed secrets even when throttled.
    if not storage.desktop_secret_is_well_formed(payload.secret):
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = "Desktop authentication failed",
        )

    key = _desktop_login_key(request)
    blocked_for = _login_blocked(key)
    if blocked_for > 0:
        raise HTTPException(
            status_code = status.HTTP_429_TOO_MANY_REQUESTS,
            detail = (f"Too many failed login attempts. " f"Try again in {blocked_for} seconds."),
            headers = {"Retry-After": str(blocked_for)},
        )

    verified = storage.validate_desktop_secret_with_credential(payload.secret)
    if verified is None:
        _record_login_failure(key)
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = "Desktop authentication failed",
        )
    username, jwt_secret = verified
    # Safe to clear the aggregate: the suffixed key belongs to this route alone, so clearing cannot hand out a fresh guessing budget.
    _clear_login_bucket(key)
    # Shell-owned backends never use the seeded password; terminal-started ones keep the web autofill.
    if getattr(request.app.state, "desktop_owned", False):
        request.app.state.bootstrap_password = None

    from auth.policy import installation_is_multi_user

    if installation_is_multi_user():
        # The secret proves the shell owns the backend, not which account is using it.
        return Response(
            content = '{"login_required":true,"login_mode":"multi"}',
            media_type = "application/json",
        )

    return Token(
        access_token = create_access_token(subject = username, desktop = True, secret = jwt_secret),
        refresh_token = create_refresh_token(subject = username, desktop = True, secret = jwt_secret),
        token_type = "bearer",
        must_change_password = False,
        account_id = _account_id_of(username),
    )


# Sync def: rotation is one transaction, so a busy auth.db wait must not freeze the event loop.
@router.post("/refresh", response_model = Token)
def refresh(payload: RefreshTokenRequest) -> Token:
    """Exchange a refresh token for a new access+refresh pair (single-use)."""
    new_refresh_token, new_expires_at = new_refresh_token_value()
    try:
        rotated = storage.rotate_refresh_token(
            payload.refresh_token, new_refresh_token, new_expires_at
        )
    except sqlite3.OperationalError as exc:
        if not sqlite_gate.is_busy_error(exc):
            raise
        logger.warning("Token refresh deferred: auth.db is busy (%s)", exc)
        raise HTTPException(
            status_code = status.HTTP_503_SERVICE_UNAVAILABLE,
            detail = "Unsloth Studio is busy. Try again in a moment.",
            headers = {"Retry-After": "2"},
        )
    if rotated is None:
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = "Invalid or expired refresh token",
        )
    return Token(
        access_token = create_access_token(
            subject = rotated.username, desktop = rotated.is_desktop, secret = rotated.jwt_secret
        ),
        refresh_token = new_refresh_token,
        token_type = "bearer",
        must_change_password = rotated.must_change_password,
        account_id = rotated.account_id,
    )


@router.post("/desktop-initial-password", response_model = Token)
async def set_desktop_initial_password(
    payload: DesktopInitialPasswordRequest,
    request: Request,
    current_subject: str = Depends(get_current_subject_allow_password_change),
    is_desktop: bool = Depends(authenticated_via_desktop_jwt),
) -> Token:
    """Set the first real password from the desktop app, which never sees the seeded one.

    Desktop auth is passwordless, so the desktop user cannot complete the normal
    flow: it needs the generated bootstrap password that only the terminal ever
    printed. Remote browser logins do need a real password, so an
    already-authenticated desktop session may set it while the seeded credential
    is still in place. Once set, change-password owns every later change.
    """
    if not is_desktop or current_subject != storage.DEFAULT_ADMIN_USERNAME:
        raise HTTPException(
            status_code = status.HTTP_403_FORBIDDEN,
            detail = "This action requires the Unsloth desktop app.",
        )

    record = storage.get_user_and_secret(current_subject)
    if record is None:
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = "User session is invalid",
        )

    _salt, pwd_hash, _jwt_secret, must_change_password = record
    if not must_change_password:
        raise HTTPException(
            status_code = status.HTTP_409_CONFLICT,
            detail = "A password is already set. Change it instead.",
        )
    if any(ch.isspace() for ch in payload.new_password):
        raise HTTPException(
            status_code = status.HTTP_400_BAD_REQUEST,
            detail = "New password cannot contain spaces",
        )

    # Conditional on the credential just read, so a concurrent change is not overwritten.
    new_secret = storage.update_password(
        current_subject,
        payload.new_password,
        revoke_refresh_tokens = True,
        expect_password_hash = pwd_hash,
        preserve_desktop_secret = True,
    )
    if new_secret is None:
        raise HTTPException(
            status_code = status.HTTP_409_CONFLICT,
            detail = "The password changed while this request was in flight. Try again.",
        )
    try:
        request.app.state.bootstrap_password = None
    except AttributeError:
        pass
    access_token = create_access_token(subject = current_subject, desktop = True, secret = new_secret)
    refresh_token = create_refresh_token(subject = current_subject, desktop = True, secret = new_secret)
    return Token(
        access_token = access_token,
        refresh_token = refresh_token,
        token_type = "bearer",
        must_change_password = False,
        account_id = _account_id_of(current_subject),
    )


@router.post("/change-password", response_model = Token)
async def change_password(
    payload: ChangePasswordRequest,
    request: Request,
    current_subject: str = Depends(get_current_subject_allow_password_change),
    is_desktop: bool = Depends(authenticated_via_desktop_jwt),
    _own_credential: None = Depends(_require_a_credential_of_its_own("Changing passwords")),
) -> Token:
    """Allow the authenticated user to replace the default password."""
    record = storage.get_user_and_secret(current_subject)
    if record is None:
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = "User session is invalid",
        )

    salt, pwd_hash, _jwt_secret, _must_change_password = record
    if not hashing.verify_password(payload.current_password, salt, pwd_hash):
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = "Current password is incorrect",
        )
    if any(ch.isspace() for ch in payload.new_password):
        raise HTTPException(
            status_code = status.HTTP_400_BAD_REQUEST,
            detail = "New password cannot contain spaces",
        )
    if payload.current_password == payload.new_password:
        raise HTTPException(
            status_code = status.HTTP_400_BAD_REQUEST,
            detail = "New password must be different from the current password",
        )

    # Single transaction so pre-change refresh tokens cannot survive the password commit;
    # conditional on the hash just verified so a concurrent reset-password is not overwritten.
    if current_subject == storage.DEFAULT_ADMIN_USERNAME:
        new_secret = storage.update_password(
            current_subject,
            payload.new_password,
            revoke_refresh_tokens = True,
            expect_password_hash = pwd_hash,
            preserve_desktop_secret = is_desktop,
        )
    else:
        new_secret = storage.update_account_password(
            current_subject,
            payload.new_password,
            expect_password_hash = pwd_hash,
            expect_secret = _jwt_secret,
        )
    if new_secret is None:
        raise HTTPException(
            status_code = status.HTTP_409_CONFLICT,
            detail = "The password changed while this request was in flight. Sign in again.",
        )
    if current_subject == storage.DEFAULT_ADMIN_USERNAME:
        try:
            request.app.state.bootstrap_password = None
        except AttributeError:
            pass
    access_token = create_access_token(
        subject = current_subject, desktop = is_desktop, secret = new_secret
    )
    refresh_token = create_refresh_token(
        subject = current_subject, desktop = is_desktop, secret = new_secret
    )
    return Token(
        access_token = access_token,
        refresh_token = refresh_token,
        token_type = "bearer",
        must_change_password = False,
        account_id = _account_id_of(current_subject),
    )


def _row_to_api_key_response(row: dict) -> ApiKeyResponse:
    return ApiKeyResponse(
        id = row["id"],
        name = row["name"],
        key_prefix = row["key_prefix"],
        created_at = row["created_at"],
        last_used_at = row.get("last_used_at"),
        expires_at = row.get("expires_at"),
        is_active = bool(row["is_active"]),
        purpose = row.get("purpose"),
    )


def _key_account_scope() -> "str | None":
    from utils.account_context import current_account, is_owner_context
    if is_owner_context():
        return None
    return current_account().account_id


@router.post("/api-keys", response_model = CreateApiKeyResponse)
async def create_api_key(
    payload: CreateApiKeyRequest,
    credential: tuple = Depends(get_current_credential),
    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
    _own_credential: None = Depends(_require_a_credential_of_its_own("Managing API keys")),
    is_desktop: bool = Depends(authenticated_via_desktop_jwt),
) -> CreateApiKeyResponse:
    """Create a new API key. The raw key is returned once and cannot be retrieved later."""
    current_subject, generation = credential
    if payload.name == storage.UNSLOTH_START_API_KEY_NAME and not is_desktop:
        raise HTTPException(
            status_code = status.HTTP_403_FORBIDDEN,
            detail = "This key name is reserved for `unsloth start`.",
        )
    expires_at = None
    if payload.expires_in_days is not None:
        expires_at = (
            datetime.now(timezone.utc) + timedelta(days = payload.expires_in_days)
        ).isoformat()
    # A key minted by an expiring key never outlives it, so leaks stay short-lived.
    parent_expires_at = _api_key_caller_expiry(credentials)
    if parent_expires_at is not None and (
        expires_at is None
        or datetime.fromisoformat(expires_at) > datetime.fromisoformat(parent_expires_at)
    ):
        expires_at = parent_expires_at

    try:
        raw_key, row = storage.create_api_key(
            username = current_subject,
            name = payload.name,
            expires_at = expires_at,
            expect_gen = generation,
            account_id = _key_account_scope(),
            purpose = storage.UNSLOTH_START_API_KEY_PURPOSE
            if payload.name == storage.UNSLOTH_START_API_KEY_NAME
            else None,
        )
    except storage.CredentialRotated:
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED,
            detail = "Invalid or expired token",
        )
    return CreateApiKeyResponse(
        key = raw_key,
        api_key = _row_to_api_key_response(row),
    )


def _api_key_caller_expiry(credentials: Optional[HTTPAuthorizationCredentials]) -> Optional[str]:
    """Expiry of the sk-unsloth key on this request; None for UI, keyless or non-expiring."""
    if credentials is None or is_keyless(credentials):
        return None
    raw = credentials.credentials or ""
    if not raw.startswith(storage.API_KEY_PREFIX):
        return None
    validated = storage.validate_api_key_account(raw, touch = False)
    if validated is None:
        # Expired or revoked since it authenticated: no cap to apply, so refuse rather than mint uncapped.
        raise HTTPException(
            status_code = status.HTTP_401_UNAUTHORIZED, detail = "Invalid or expired token"
        )
    return validated[0].get("expires_at")


@router.get("/api-keys", response_model = ApiKeyListResponse)
def list_api_keys(
    current_subject: str = Depends(get_current_subject),
    _own_credential: None = Depends(_require_a_credential_of_its_own("Managing API keys")),
) -> ApiKeyListResponse:
    """List all API keys for the authenticated user (raw keys are never exposed)."""
    rows = storage.list_api_keys(current_subject, account_id = _key_account_scope())
    return ApiKeyListResponse(
        api_keys = [_row_to_api_key_response(r) for r in rows],
    )


@router.delete("/api-keys/{key_id}")
async def revoke_api_key(
    key_id: int,
    current_subject: str = Depends(get_current_subject),
    _own_credential: None = Depends(_require_a_credential_of_its_own("Managing API keys")),
) -> dict:
    """Revoke (soft-delete) an API key."""
    if not storage.revoke_api_key(current_subject, key_id, account_id = _key_account_scope()):
        raise HTTPException(
            status_code = status.HTTP_404_NOT_FOUND,
            detail = "API key not found",
        )
    return {"detail": "API key revoked"}