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.

24.8 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

"""Persisted policy and launch policy for Settings > LAN access. The listener itself lives in ``lan_access``; this decides whether the current launch may own one, whether the user is allowed to turn it on, and remembers the answer across restarts."""

from __future__ import annotations

import ipaddress
import os
import socket

import threading
from typing import Any, Optional

from loggers import get_logger

logger = get_logger(__name__)

LAN_ACCESS_AUTO_START_KEY = "lan_access_auto_start"
DEFAULT_LAN_ACCESS_AUTO_START = False

LAN_ACCESS_PORT_KEY = "lan_access_port"
DEFAULT_LAN_ACCESS_PORT = 8888
LAST_LAN_ACCESS_PORT = 8908

LAN_ACCESS_ADDRESSES_KEY = "lan_access_addresses"
_MAX_LAN_ACCESS_ADDRESSES = 64
_UNREADABLE = object()


_management_lock = threading.RLock()

_PRIVATE_LAN_NETWORKS = (
    ipaddress.ip_network("10.0.0.0/8"),
    ipaddress.ip_network("172.16.0.0/12"),
    ipaddress.ip_network("192.168.0.0/16"),
    ipaddress.ip_network("169.254.0.0/16"),
    ipaddress.ip_network("fc00::/7"),
    ipaddress.ip_network("fe80::/10"),
)


def _normalized_ip(address: str):
    """Parse one literal address, normalizing IPv4-mapped IPv6."""
    if not isinstance(address, str):
        return None
    value = address.strip().strip("[]")
    if "%" in value:
        value = value.split("%", 1)[0]
    try:
        parsed = ipaddress.ip_address(value)
    except ValueError:
        return None
    if isinstance(parsed, ipaddress.IPv6Address) and parsed.ipv4_mapped is not None:
        return parsed.ipv4_mapped
    return parsed


def _resolve_host_addresses(host: str, port: int) -> tuple:
    """Resolve a literal or hostname to normalized transport addresses."""
    literal = _normalized_ip(host)
    if literal is not None:
        return (literal,)
    if not isinstance(host, str) or not isinstance(port, int) or port < 0:
        return ()
    try:
        infos = socket.getaddrinfo(host, port, type = socket.SOCK_STREAM)
    except OSError:
        return ()
    addresses = []
    for _family, _kind, _protocol, _name, sockaddr in infos:
        if not sockaddr:
            continue
        parsed = _normalized_ip(sockaddr[0])
        if parsed is not None and parsed not in addresses:
            addresses.append(parsed)
    return tuple(addresses)


def _private_non_loopback(address) -> bool:
    return not address.is_loopback and any(address in network for network in _PRIVATE_LAN_NETWORKS)


def _all_addresses_are(host: str, port: int, predicate) -> bool:
    addresses = _resolve_host_addresses(host, port)
    return bool(addresses) and all(predicate(address) for address in addresses)


def request_is_loopback(request) -> bool:
    """Whether both authoritative transport endpoints are loopback."""
    scope = getattr(request, "scope", {})
    server = scope.get("server")
    client = scope.get("client")
    if not isinstance(server, (tuple, list)) or len(server) < 2:
        return False
    if not isinstance(client, (tuple, list)) or len(client) < 1:
        return False
    server_host, server_port = server[0], server[1]
    client_host = client[0]
    if not isinstance(server_host, str) or not isinstance(server_port, int):
        return False
    if not isinstance(client_host, str):
        return False
    return _all_addresses_are(server_host, server_port, lambda address: address.is_loopback) and (
        _all_addresses_are(client_host, server_port, lambda address: address.is_loopback)
    )


def _addresses_match(host: str, port: int, candidates) -> bool:
    request_addresses = set(_resolve_host_addresses(host, port))
    if not request_addresses:
        return False
    configured = set()
    for candidate in candidates or ():
        if isinstance(candidate, str):
            configured.update(_resolve_host_addresses(candidate, port))
    return bool(request_addresses & configured)


def request_on_lan_access(request) -> bool:
    """Classify a request from ASGI socket state, never client-controlled headers. Both the accepting endpoint and peer must be private and non-loopback, and the accepting endpoint must also match either the exact live settings listener or the launch-managed bind and port published at startup."""
    from lan_access import lan_listener_status

    scope = getattr(request, "scope", {})
    server = scope.get("server")
    client = scope.get("client")
    if not isinstance(server, (tuple, list)) or len(server) < 2:
        return False
    if not isinstance(client, (tuple, list)) or len(client) < 1:
        return False
    server_host, server_port = server[0], server[1]
    client_host = client[0]
    if not isinstance(server_host, str) or not isinstance(server_port, int):
        return False
    if not isinstance(client_host, str):
        return False
    if not _all_addresses_are(server_host, server_port, _private_non_loopback):
        return False
    if not _all_addresses_are(client_host, server_port, _private_non_loopback):
        return False

    try:
        listener = lan_listener_status()
    except Exception:
        return False
    if not isinstance(listener, dict):
        return False
    if (
        listener.get("running") is True
        and listener.get("port") == server_port
        and _addresses_match(server_host, server_port, listener.get("addresses"))
    ):
        return True

    try:
        app_state = request.app.state
    except Exception:
        return False
    if bool(getattr(app_state, "lan_access_is_colab", False)):
        return False
    if bool(getattr(app_state, "lan_access_secure_launch", False)):
        return False
    if not bool(getattr(app_state, "lan_access_launch_managed", False)):
        return False
    if getattr(app_state, "lan_access_port", None) != server_port:
        return False
    if bool(getattr(app_state, "lan_access_wildcard_bind", False)):
        return True
    return _addresses_match(
        server_host,
        server_port,
        getattr(app_state, "lan_access_launch_addresses", ()),
    )


def _coerce_bool(value: Any) -> Optional[bool]:
    return value if isinstance(value, bool) else None


def get_lan_access_auto_start() -> bool:
    """Read the preference, failing closed on missing, invalid, or unreadable data."""
    try:
        from storage.studio_db import get_app_setting
        stored = get_app_setting(LAN_ACCESS_AUTO_START_KEY, None)
    except Exception:
        return False
    parsed = _coerce_bool(stored)
    return parsed if parsed is not None else DEFAULT_LAN_ACCESS_AUTO_START


def set_lan_access_auto_start(enabled: bool) -> bool:
    if not isinstance(enabled, bool):
        raise ValueError("LAN access auto-start must be true or false.")
    from storage.studio_db import upsert_app_settings

    upsert_app_settings({LAN_ACCESS_AUTO_START_KEY: enabled})
    return enabled


def _valid_port(value: Any) -> bool:
    return isinstance(value, int) and not isinstance(value, bool) and 1 <= value <= 65535


def _read_lan_access_port(*, strict: bool) -> Optional[int]:
    try:
        from storage.studio_db import get_app_setting
        stored = get_app_setting(LAN_ACCESS_PORT_KEY, None)
    except Exception as exc:
        if strict:
            raise RuntimeError("lan_access_port_unavailable") from exc
        return None
    if stored is None or _valid_port(stored):
        return stored
    if strict:
        raise RuntimeError("lan_access_port_invalid")
    return None


def get_lan_access_port() -> Optional[int]:
    """The valid saved port, or ``None`` for Automatic/status fallback."""
    return _read_lan_access_port(strict = False)


def set_lan_access_port(port: Optional[int]) -> Optional[int]:
    if port is not None and not _valid_port(port):
        raise ValueError("LAN access port must be between 1 and 65535.")
    from storage.studio_db import upsert_app_settings

    upsert_app_settings({LAN_ACCESS_PORT_KEY: port})
    return port


def lan_access_port_candidates() -> tuple[int, ...]:
    custom = _read_lan_access_port(strict = True)
    if custom is not None:
        return (custom,)
    return tuple(range(DEFAULT_LAN_ACCESS_PORT, LAST_LAN_ACCESS_PORT + 1))


def normalize_lan_access_addresses(addresses: Any) -> Optional[tuple[str, ...]]:
    """``None`` is Automatic; else a de-duplicated tuple of bindable IPv4 literals, detected right now or not."""
    if addresses is None:
        return None
    if not isinstance(addresses, (list, tuple)):
        raise ValueError("LAN access addresses must be a list of IPv4 addresses.")
    # counted before de-duplicating, so a padded list cannot make validation quadratic
    if len(addresses) > _MAX_LAN_ACCESS_ADDRESSES:
        raise ValueError(f"At most {_MAX_LAN_ACCESS_ADDRESSES} LAN access addresses can be chosen.")
    normalized: list[str] = []
    for value in addresses:
        if not isinstance(value, str):
            raise ValueError("LAN access addresses must be a list of IPv4 addresses.")
        try:
            parsed = ipaddress.IPv4Address(value.strip())
        except ValueError:
            raise ValueError(f"{value!r} is not an IPv4 address.") from None
        if (
            parsed.is_loopback
            or parsed.is_link_local
            or parsed.is_multicast
            or parsed.is_unspecified
            or parsed.is_reserved
        ):
            raise ValueError(f"{value!r} cannot be reached from another device.")
        if str(parsed) not in normalized:
            normalized.append(str(parsed))
    if not normalized:
        raise ValueError("Choose at least one LAN access address, or Automatic.")
    return tuple(normalized)


def _read_lan_access_addresses(*, strict: bool) -> Optional[tuple[str, ...]]:
    """Strict reads (a start) fail closed: Automatic here would bind the addresses the user excluded."""
    try:
        from storage.studio_db import get_app_setting, get_app_settings
        stored = get_app_setting(LAN_ACCESS_ADDRESSES_KEY, _UNREADABLE)
        # the fallback also answers an undecodable row; only a missing row is Automatic
        if stored is _UNREADABLE and LAN_ACCESS_ADDRESSES_KEY not in get_app_settings(
            [LAN_ACCESS_ADDRESSES_KEY]
        ):
            stored = None
    except Exception as exc:
        if strict:
            raise RuntimeError("lan_access_addresses_unavailable") from exc
        return None
    if stored is _UNREADABLE:
        if strict:
            raise RuntimeError("lan_access_addresses_invalid")
        return None
    try:
        return normalize_lan_access_addresses(stored)
    except ValueError:
        if strict:
            raise RuntimeError("lan_access_addresses_invalid") from None
        return None


def get_lan_access_addresses() -> Optional[tuple[str, ...]]:
    return _read_lan_access_addresses(strict = False)


def set_lan_access_addresses(addresses: Any) -> Optional[tuple[str, ...]]:
    normalized = normalize_lan_access_addresses(addresses)
    from storage.studio_db import upsert_app_settings

    upsert_app_settings(
        {LAN_ACCESS_ADDRESSES_KEY: list(normalized) if normalized is not None else None}
    )
    return normalized


def save_lan_access_addresses(app, addresses: Any) -> dict:
    normalized = normalize_lan_access_addresses(addresses)
    with _management_lock:
        status = lan_access_status(app)
        if bool(getattr(app.state, "lan_access_is_colab", False)):
            raise RuntimeError("colab")
        if status["state"] == "online":
            raise RuntimeError("lan_access_running")
        set_lan_access_addresses(normalized)
        from lan_access import clear_lan_listener_error

        clear_lan_listener_error()
        return lan_access_status(app)


def _available_lan_addresses() -> list[dict]:
    """Detected addresses, then virtual switch ones flagged ``host_only``; a detection failure offers nothing
    rather than failing status."""
    try:
        from lan_access import detect_host_only_addresses, detect_lan_addresses, is_public_address

        detected = detect_lan_addresses()
        host_only = [address for address in detect_host_only_addresses() if address not in detected]
        return [
            {
                "address": address,
                "public": is_public_address(address),
                "host_only": address in host_only,
            }
            for address in (*detected, *host_only)
        ]
    except Exception:
        return []


def _public_lan_addresses(addresses) -> list[str]:
    from lan_access import is_public_address
    return [address for address in addresses if is_public_address(address)]


def save_lan_access_port(app, port: Optional[int]) -> dict:
    with _management_lock:
        status = lan_access_status(app)
        if bool(getattr(app.state, "lan_access_is_colab", False)):
            raise RuntimeError("colab")
        if status["state"] == "online":
            raise RuntimeError("lan_access_running")
        set_lan_access_port(port)
        from lan_access import clear_lan_listener_error

        clear_lan_listener_error()
        return lan_access_status(app)


def _admin_password_ready() -> bool:
    try:
        from auth.storage import DEFAULT_ADMIN_USERNAME, requires_password_change
        return not requires_password_change(DEFAULT_ADMIN_USERNAME)
    except Exception:
        return False


def configure_lan_access(
    app_state, *, port: int, bind_host: str, secure: bool, is_colab: bool, frontend_served: bool
) -> None:
    """Publish immutable launch policy used by every settings request."""
    from utils.host_policy import wildcard_ip_versions

    app_state.lan_access_port = port
    app_state.lan_access_wildcard_ip_versions = wildcard_ip_versions(bind_host)
    app_state.lan_access_wildcard_bind = bool(app_state.lan_access_wildcard_ip_versions)
    app_state.lan_access_bind_host = bind_host
    app_state.lan_access_launch_addresses = tuple(
        str(address) for address in _resolve_host_addresses(bind_host, port)
    )
    resolved_loopback = bool(app_state.lan_access_launch_addresses) and all(
        _normalized_ip(address).is_loopback for address in app_state.lan_access_launch_addresses
    )
    # An unresolved hostname is launch-managed but never trusted for keyless LAN admission: request_on_lan_access requires its resolved address set.
    app_state.lan_access_launch_managed = (
        app_state.lan_access_wildcard_bind or not resolved_loopback
    )
    # --secure forces the loopback bind precisely so the raw port is never exposed
    app_state.lan_access_secure_launch = bool(secure)
    app_state.lan_access_is_colab = bool(is_colab)
    app_state.lan_access_frontend_served = bool(frontend_served)
    app_state.lan_access_ready = False


_CONTAINER_NETWORKS = (ipaddress.ip_network("172.16.0.0/12"), ipaddress.ip_network("10.88.0.0/16"))


def _container_network_address(address: str) -> bool:
    try:
        ip = ipaddress.ip_address(address)
    except ValueError:
        return False
    return any(ip in network for network in _CONTAINER_NETWORKS if ip.version == network.version)


def _veth_addresses(sysfs: str = "/sys/class/net") -> set[str]:
    """Addresses on a link whose peer (iflink) is outside this namespace: a bridged container's veth. A NIC or VLAN
    links to an index visible here, so host networking keeps a 172.16/12 LAN (kernel ABI sysfs-class-net)."""

    def read(name: str, attr: str) -> str:
        with open(f"{sysfs}/{name}/{attr}", encoding = "utf-8") as handle:
            return handle.read().strip()

    try:
        import psutil
        interfaces = psutil.net_if_addrs()
        indexes = {read(name, "ifindex") for name in os.listdir(sysfs)}
    except Exception:
        return set()
    addresses = set()
    for name, entries in interfaces.items():
        try:
            if read(name, "iflink") in indexes:
                continue
        except OSError:
            continue
        addresses.update(entry.address.split("%", 1)[0] for entry in entries)
    return addresses


def _launch_urls(app_state) -> list[str]:
    """Where a launch-managed bind answers on this network. A wildcard launch cannot rely only on ``server_url``: run.py gives that direct base one LAN-reachable address, while Settings must show every currently reachable address in each family the launch serves."""
    if getattr(app_state, "lan_access_wildcard_bind", False):
        from lan_access import detect_lan_addresses
        from utils.paths.file_manager import _in_container

        addresses = []
        for ip_version in getattr(app_state, "lan_access_wildcard_ip_versions", ()) or (4,):
            for address in detect_lan_addresses(ip_version):
                if address not in addresses:
                    addresses.append(address)
        if _in_container():
            # A bridged container's own IP reaches nothing outside it; host networking's addresses stay.
            bridged = _veth_addresses()
            addresses = [
                a for a in addresses if not (a in bridged and _container_network_address(a))
            ]
        return _listener_urls(
            addresses,
            getattr(app_state, "lan_access_port", None),
            _url_scheme(app_state),
        )
    url = getattr(app_state, "server_url", None)
    if url is None and _url_scheme(app_state) == "https":
        # run.py publishes no server_url for TLS; the bound host is still where LAN peers reach it
        return _listener_urls(
            (getattr(app_state, "lan_access_bind_host", ""),),
            getattr(app_state, "lan_access_port", None),
            "https",
        )
    return [url] if url else []


def _url_scheme(app_state) -> str:
    return "https" if getattr(app_state, "studio_tls", None) is not None else "http"


def _listener_urls(
    addresses,
    port: Optional[int],
    scheme: str = "http",
) -> list[str]:
    if not port:
        return []
    urls = []
    for address in addresses:
        url_host = f"[{address}]" if ":" in address else address
        urls.append(f"{scheme}://{url_host}:{port}")
    return urls


def _public_urls(urls: list[str], resolved_addresses: tuple[str, ...] = ()) -> list[str]:
    """The subset reachable from the internet rather than only this network."""
    from urllib.parse import urlparse

    resolved = []
    for address in resolved_addresses:
        parsed = _normalized_ip(address)
        if parsed is not None:
            resolved.append(parsed)
    if any(address.is_global for address in resolved):
        return list(urls)
    public = []
    for url in urls:
        parsed = urlparse(url)
        port = parsed.port or 80
        addresses = _resolve_host_addresses(parsed.hostname or "", port)
        if addresses and any(address.is_global for address in addresses):
            public.append(url)
    return public


def _has_keyless_lan_url(urls: list[str]) -> bool:
    """Shares admission's check, so a hostname bind or an IPv4-mapped literal is never advertised."""
    import ipaddress
    from urllib.parse import urlparse

    from utils.keyless_api_access import (
        KEYLESS_SCOPE_INFERENCE,
        keyless_authority_address_allowed,
    )

    for url in urls:
        parsed = urlparse(url)
        if not parsed.hostname:
            continue
        try:
            # urlparse already strips the IPv6 brackets and lowercases; parse the remaining literal without normalising it.
            address = ipaddress.ip_address(parsed.hostname)
        except ValueError:
            continue
        if not keyless_authority_address_allowed(address, KEYLESS_SCOPE_INFERENCE):
            continue
        if _all_addresses_are(parsed.hostname, parsed.port or 80, _private_non_loopback):
            return True
    return False


def lan_access_status(app) -> dict:
    """Everything Settings > LAN access renders, resolved for the current launch."""
    from lan_access import lan_listener_status

    app_state = app.state
    listener = lan_listener_status()
    ready = bool(getattr(app_state, "lan_access_ready", False))
    is_colab = bool(getattr(app_state, "lan_access_is_colab", False))
    launch_managed = bool(getattr(app_state, "lan_access_launch_managed", False))
    frontend_served = bool(getattr(app_state, "lan_access_frontend_served", False))

    block_reason = None
    if not ready:
        block_reason = "server_starting"
    elif is_colab:
        block_reason = "colab"
    elif launch_managed:
        block_reason = "launch_managed"
    elif bool(getattr(app_state, "lan_access_secure_launch", False)):
        block_reason = "secure_launch"
    elif not _admin_password_ready():
        block_reason = "admin_password_change_required"

    running = bool(listener["running"])
    configured_port = get_lan_access_port()
    configured_addresses = get_lan_access_addresses()
    if launch_managed:
        state, urls, managed_by = "online", _launch_urls(app_state), "launch"
        active_port = getattr(app_state, "lan_access_port", None)
    elif running:
        state, urls, managed_by = (
            "online",
            _listener_urls(listener["addresses"], listener["port"], _url_scheme(app_state)),
            "settings",
        )
        active_port = listener["port"]
    else:
        state = "error" if listener["error"] else "off"
        urls, managed_by, active_port = [], None, None

    controllable = block_reason is None
    try:
        from utils.keyless_api_access import get_keyless_api_access_settings

        keyless_scope, keyless_tools = get_keyless_api_access_settings()
        from auth.policy import installation_has_managed_accounts

        # Effective, not saved: one managed account turns keyless admission off install-wide.
        if installation_has_managed_accounts():
            keyless_scope, keyless_tools = "off", False
    except Exception:
        keyless_scope, keyless_tools = "off", False
    return {
        "state": state,
        "urls": urls,
        "public_urls": _public_urls(
            urls,
            getattr(app_state, "lan_access_launch_addresses", ()) if launch_managed else (),
        ),
        "error": listener["error"],
        "auto_start": get_lan_access_auto_start(),
        "configured_port": configured_port,
        "configured_addresses": list(configured_addresses)
        if configured_addresses is not None
        else None,
        "available_addresses": [] if launch_managed else _available_lan_addresses(),
        # a saved address that is down still needs its public warning
        "configured_public_addresses": _public_lan_addresses(configured_addresses or ()),
        "active_port": active_port,
        "managed_by": managed_by,
        "can_start": controllable and not running,
        "can_stop": controllable and running,
        "block_reason": block_reason,
        "bind_host": getattr(app_state, "lan_access_bind_host", None),
        "wildcard_bind": bool(getattr(app_state, "lan_access_wildcard_bind", False)),
        "serves_web_ui": frontend_served,
        "keyless_lan_eligible": _has_keyless_lan_url(urls),
        "keyless_scope": keyless_scope,
        "keyless_tools": keyless_tools,
    }


def _server_loop(app_state):
    """The loop the primary server serves on, or a refusal if it is not serving."""
    loop = getattr(app_state, "lan_access_loop", None)
    if loop is None or loop.is_closed() or not loop.is_running():
        raise RuntimeError("server_not_running")
    return loop


def start_lan_access(app) -> dict:
    """Bring the LAN listener up for this launch. Repeated requests are idempotent."""
    from lan_access import start_lan_listener
    with _management_lock:
        status = lan_access_status(app)
        if status["state"] == "online":
            return status
        if not status["can_start"]:
            raise RuntimeError(status["block_reason"] or "operation_in_progress")

        ports = lan_access_port_candidates()
        selected = _read_lan_access_addresses(strict = True)
        addresses = start_lan_listener(
            app,
            _server_loop(app.state),
            ports[0],
            ports[1:],
            selected,
        )
        logger.info("LAN access started on %s", ", ".join(addresses))
        return lan_access_status(app)


def stop_lan_access(app) -> dict:
    """Take the LAN listener down without changing the auto-start preference."""
    from lan_access import clear_lan_listener_error, stop_lan_listener

    status = lan_access_status(app)
    if status["managed_by"] == "launch":
        raise RuntimeError("launch_managed")
    # a stop that could not confirm the port is closed leaves the host reachable, and lan_access keeps the trust flag with the listener state it describes.
    if stop_lan_listener():
        clear_lan_listener_error()
    return lan_access_status(app)


def maybe_auto_start_lan_access(app) -> bool:
    """Start the listener at boot when the persisted preference allows it."""
    if not get_lan_access_auto_start():
        return False
    try:
        start_lan_access(app)
    except Exception as exc:
        # an optional preference must never take the whole server down with it
        logger.info("LAN access auto-start skipped: %s", exc)
        return False
    return True