standkit 0.3.7__py3-none-any.whl

standkit_hub/logs_browser.py

@@ -0,0 +1,174 @@
+"""
+Просмотр лог-файлов стенда со стороны хаба: список файлов источника логов,
+выбор основного (самого свежего) файла, tail содержимого, открытие папки
+логов в файловом менеджере ОС хоста.
+
+ДВА ИСТОЧНИКА логов на стенд (``source``, см. ``resolve_logs_dir``):
+
+- ``"stand"`` — логи самого стенда (платформа BPMSoft), пишет их движок,
+  каталог ``<stand.stand_dir>/logs`` (папка ``logs`` в корне стенда). Это
+  ближе всего к тому, что видно в PS-окне/консоли самого стенда — дефолт
+  для панели "Текущее состояние".
+- ``"bpmkit"`` — логи BPMkit-ПРОЕКТА (scaffold, ``project_scaffold``): не
+  логи стенда и НЕ ``Stand.extra["logs_path"]`` (та запись указывает на тот
+  же каталог, что и ``"stand"``, — путать источники не нужно), а подпапка
+  ``logs`` внутри папки проекта ``Stand.extra["docs_folder"]``
+  (``<docs_folder>/logs``). Туда пишутся логи разработки поверх стенда;
+  если ``docs_folder`` в записи стенда не задан (провижининг без
+  project_scaffold), источник недоступен целиком.
+
+Важно отличать оба источника от ``standkit.lifecycle.log_path``/
+``standkit.logs`` (см. ``standkit_hub.server._api_stand_logs``) — тот лог
+существует только для стендов, ЗАПУЩЕННЫХ САМИМ standkit
+(``transport=local`` через ``lifecycle.start``), это третий, отдельный канал.
+
+STDLIB-ONLY: ``pathlib``, ``subprocess``, ``sys``, ``os`` (только ``os.startfile``
+на Windows).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from standkit.models import Stand
+
+# Допустимые значения ``source`` — единственный источник истины для валидации
+# как здесь, так и в standkit_hub.server (query-параметр ``source``).
+LOG_SOURCES = ("stand", "bpmkit")
+
+DEFAULT_LOG_SOURCE = "stand"
+
+
+def raw_logs_path(stand: Stand, source: str = DEFAULT_LOG_SOURCE) -> Optional[str]:
+    """
+    "Сырой" (не проверенный на существование) путь к каталогу логов для
+    выбранного источника — используется только для человекочитаемых сообщений
+    ("каталог не найден — <путь>"), когда ``resolve_logs_dir`` вернул ``None``.
+
+    Бросает ``ValueError`` на неизвестный ``source`` — та же дисциплина, что
+    и у ``resolve_logs_dir``.
+    """
+    if source == "stand":
+        return str(Path(stand.stand_dir) / "logs") if stand.stand_dir else None
+    if source == "bpmkit":
+        docs_folder = stand.extra.get("docs_folder")
+        return str(Path(docs_folder) / "logs") if docs_folder else None
+    raise ValueError(f"неизвестный источник логов: {source!r}")
+
+
+def resolve_logs_dir(stand: Stand, source: str = DEFAULT_LOG_SOURCE) -> Optional[Path]:
+    """
+    Резолвит каталог логов стенда для выбранного источника:
+
+    - ``source="stand"`` (по умолчанию) — ``<stand.stand_dir>/logs``;
+    - ``source="bpmkit"`` — ``<stand.extra["docs_folder"]>/logs`` (логи
+      BPMkit-проекта, папка ``logs`` внутри project-scaffold, НЕ
+      ``stand.extra["logs_path"]``).
+
+    Возвращает ``None``, если путь не задан (для "stand" — пуст сам
+    ``stand_dir``; для "bpmkit" — не задан ``docs_folder``), либо не
+    существует, либо указывает не на каталог —
+    вызывающая сторона (хаб) обязана отдать понятное сообщение "лог
+    недоступен", а не падать с исключением.
+
+    Бросает ``ValueError`` на неизвестный ``source`` — это ошибка вызывающего
+    кода (например, невалидированный query-параметр), а не штатная ситуация
+    "лога нет"; HTTP-слой (``standkit_hub.server``) обязан провалидировать
+    ``source`` ДО вызова и вернуть 400, не давая исключению дойти сюда.
+    """
+    raw = raw_logs_path(stand, source)
+    if not raw:
+        return None
+    p = Path(raw)
+    if not p.exists() or not p.is_dir():
+        return None
+    return p
+
+
+def list_log_files(logs_dir: Path) -> list[dict]:
+    """
+    Список лог-файлов каталога (без рекурсии в подкаталоги): имя, размер в
+    байтах, mtime (unix timestamp). Отсортирован по mtime по убыванию (самый
+    свежий — первым), чтобы фронтенду не нужно было сортировать самому.
+    """
+    entries: list[dict] = []
+    for child in logs_dir.iterdir():
+        if not child.is_file():
+            continue
+        try:
+            st = child.stat()
+        except OSError:
+            continue
+        entries.append({"name": child.name, "size": st.st_size, "mtime": st.st_mtime})
+    entries.sort(key=lambda e: e["mtime"], reverse=True)
+    return entries
+
+
+def pick_primary_log(logs_dir: Path) -> Optional[Path]:
+    """Выбирает "основной" лог каталога — самый свежий по mtime файл."""
+    files = list_log_files(logs_dir)
+    if not files:
+        return None
+    return logs_dir / files[0]["name"]
+
+
+def sanitize_log_filename(logs_dir: Path, name: str) -> Optional[Path]:
+    """
+    Резолвит имя файла лога СТРОГО внутри ``logs_dir`` (защита от path
+    traversal) — тот же принцип, что ``standkit_hub.security.sanitize_static_path``,
+    но для произвольного (не фиксированного) каталога логов конкретного стенда.
+
+    Возвращает ``None``, если путь небезопасен, не существует или указывает
+    не на файл.
+    """
+    if not name or name.startswith("/") or "\\" in name or ".." in Path(name).parts:
+        return None
+    logs_dir_resolved = logs_dir.resolve()
+    candidate = (logs_dir / name).resolve()
+    try:
+        candidate.relative_to(logs_dir_resolved)
+    except ValueError:
+        return None
+    if not candidate.is_file():
+        return None
+    return candidate
+
+
+@dataclass
+class OpenFolderResult:
+    """Результат попытки открыть папку логов в файловом менеджере ОС хоста."""
+
+    ok: bool
+    message: str
+
+
+def open_folder(path: Path) -> OpenFolderResult:
+    """
+    Открывает каталог в файловом менеджере ОС хоста: Windows — ``os.startfile``
+    (штатный способ ОС попросить проводник открыть путь — надёжнее выводит
+    открытое окно на передний план, чем спавн ``explorer`` через subprocess,
+    который часто просто сворачивает уже открытое окно той же папки в
+    таскбар вместо фокуса); macOS — ``open``, остальное — ``xdg-open`` (оба
+    через ``subprocess.Popen``, не блокируясь на ожидании закрытия окна).
+
+    Никогда не бросает исключение наружу — при отсутствии DISPLAY, нужной
+    утилиты в PATH и т.п. возвращает ``ok=False`` с текстом причины, чтобы
+    хаб мог показать это пользователю, а не упасть 500-й.
+    """
+    if not path.exists():
+        return OpenFolderResult(False, f"каталог не существует: {path}")
+    try:
+        if sys.platform == "win32":
+            os.startfile(str(path))  # type: ignore[attr-defined]
+        elif sys.platform == "darwin":
+            subprocess.Popen(["open", str(path)])
+        else:
+            subprocess.Popen(["xdg-open", str(path)])
+        return OpenFolderResult(True, f"открыто: {path}")
+    except OSError as exc:
+        return OpenFolderResult(False, f"не удалось открыть проводник: {exc}")

standkit_hub/redis_min.py

@@ -0,0 +1,326 @@
+"""
+Минимальный STDLIB-ONLY RESP-клиент для очистки БД Redis стенда (``SELECT`` +
+``FLUSHDB``) — используется кнопкой "Очистить Redis" в таблице стендов.
+
+Намеренно НЕ тянет ``redis``/``aioredis`` и т.п. — хаб (как и ядро/агент)
+разворачивается без ``pip install`` чего-либо стороннего. Протокол Redis
+(RESP) в объёме, нужном для двух команд, тривиален: массив bulk-строк на
+запрос, однострочный ``+OK``/``-ERR ...`` на ответ — велосипед оправдан
+отсутствием стороннего клиента в рантайме хаба.
+
+Намеренно НЕ разбирает произвольные RESP-ответы (bulk/array/integer) — только
+однострочные (``+``/``-``), этого достаточно для ``SELECT``/``FLUSHDB``.
+
+Также здесь живёт ``resolve_redis_from_stand_config`` — BEST-EFFORT резолвер
+параметров подключения к Redis ИЗ КОНФИГА САМОГО СТЕНДА (не реестра), на
+случай, когда ``extra["redis_db"]`` не задан в реестре BPMkit (частый
+случай — реестр вообще не хранит Redis-параметры). Используется как второй
+шаг резолва в ``standkit_hub.server._redis_connect_params``: реестр в
+приоритете, конфиг стенда — фолбэк.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+_DEFAULT_TIMEOUT_SEC = 5.0
+
+
+class RedisClearError(Exception):
+    """Ошибка обращения к Redis (недоступен, таймаут, протокольная ошибка)."""
+
+
+@dataclass
+class RedisClearResult:
+    """Результат попытки очистки БД Redis — никогда не бросает исключение наружу."""
+
+    ok: bool
+    message: str
+
+
+def _encode_command(*args: str) -> bytes:
+    """Кодирует команду в формате RESP (массив bulk-строк) — то, что понимает redis-server."""
+    parts = [f"*{len(args)}\r\n".encode("ascii")]
+    for arg in args:
+        raw = str(arg).encode("utf-8")
+        parts.append(f"${len(raw)}\r\n".encode("ascii"))
+        parts.append(raw)
+        parts.append(b"\r\n")
+    return b"".join(parts)
+
+
+def _read_line(sock) -> bytes:
+    """
+    Читает одну CRLF-терминированную строку ответа Redis (побайтово — простая,
+    не самая быстрая реализация, но ответы ``+OK``/``-ERR ...`` короткие,
+    производительность не критична для разовой административной операции).
+    """
+    buf = b""
+    while not buf.endswith(b"\r\n"):
+        chunk = sock.recv(1)
+        if not chunk:
+            raise RedisClearError("соединение с Redis закрыто неожиданно (до получения ответа)")
+        buf += chunk
+    return buf[:-2]
+
+
+def flush_db(host: str, port: int, db: int, *, timeout: float = _DEFAULT_TIMEOUT_SEC) -> RedisClearResult:
+    """
+    Подключается к ``host:port``, выполняет ``SELECT <db>`` затем ``FLUSHDB``.
+
+    Никогда не бросает исключение наружу (сетевые/протокольные ошибки
+    заворачиваются в ``RedisClearResult(ok=False, ...)``) — вызывающая сторона
+    (HTTP-слой хаба) должна показать понятный текст пользователю, а не 500-ю.
+    """
+    try:
+        sock = socket.create_connection((host, port), timeout=timeout)
+    except OSError as exc:
+        return RedisClearResult(False, f"не удалось подключиться к Redis {host}:{port}: {exc}")
+
+    try:
+        sock.settimeout(timeout)
+
+        sock.sendall(_encode_command("SELECT", str(db)))
+        reply = _read_line(sock)
+        if not reply.startswith(b"+"):
+            return RedisClearResult(
+                False, f"Redis отклонил SELECT {db}: {reply.decode('utf-8', errors='replace')}"
+            )
+
+        sock.sendall(_encode_command("FLUSHDB"))
+        reply = _read_line(sock)
+        if not reply.startswith(b"+"):
+            return RedisClearResult(
+                False, f"Redis отклонил FLUSHDB: {reply.decode('utf-8', errors='replace')}"
+            )
+
+        return RedisClearResult(True, f"Redis db={db} очищен ({host}:{port})")
+    except (OSError, RedisClearError) as exc:
+        return RedisClearResult(False, f"ошибка обращения к Redis {host}:{port}: {exc}")
+    finally:
+        try:
+            sock.close()
+        except OSError:
+            pass
+
+
+# --- best-effort резолвер Redis-параметров из конфига стенда (фолбэк реестра) ---
+#
+# Типичные для BPMSoft/.NET места: <stand_dir>\ConnectionStrings.config
+# (классический .NET connectionStrings-XML), <stand_dir>\appsettings.json
+# (JSON-конфиг ASP.NET Core), либо любой другой *.config/*.json в КОРНЕ
+# каталога стенда (без рекурсии в подпапки — не сканируем весь стенд).
+#
+# Best-effort: любая ошибка чтения/парсинга конкретного файла — файл просто
+# пропускается, никогда не бросаем исключение наружу. Формат Redis-строки у
+# BPMSoft заранее не задокументирован нам достоверно — резолвер ищет
+# правдоподобные пары ключ=значение (host/port/db/$db) в тексте рядом со
+# словом "redis", это эвристика, а не парсер конкретного формата.
+
+_REDIS_CONFIG_FILENAMES = ("ConnectionStrings.config", "appsettings.json")
+_REDIS_CONFIG_EXTENSIONS = (".config", ".json")
+# Не читаем большие файлы целиком без нужды — конфиги стенда обычно ↓ 200KB,
+# 2MB — щедрый потолок на случай нетипичного файла.
+_MAX_CONFIG_FILE_BYTES = 2 * 1024 * 1024
+
+_REDIS_KV_RE = re.compile(r"(?i)(\$db|\bdb\b|\bhost\b|\bport\b)\s*=\s*([^;,\s\"']+)")
+
+
+def _parse_redis_connection_string(text: str) -> Optional[dict]:
+    """
+    Ищет пары ``host=``/``port=``/``db=``/``$db=`` в произвольном тексте
+    (типично — значение атрибута ``connectionString`` или кусок JSON-строки).
+
+    ``db`` обязателен — без него результат бесполезен для очистки (нельзя
+    угадывать номер БД), при отсутствии возвращает ``None``. ``host``/``port``
+    — опциональны, дефолты ``127.0.0.1``/``6379`` (та же дисциплина, что и у
+    резолвера из реестра, см. ``standkit_hub.server._redis_from_registry``).
+    """
+    if not text:
+        return None
+    found: dict[str, Any] = {}
+    for m in _REDIS_KV_RE.finditer(text):
+        key = m.group(1).lower().lstrip("$")
+        val = m.group(2).strip().rstrip(";,")
+        if key == "db" and "db" not in found:
+            try:
+                found["db"] = int(val)
+            except ValueError:
+                continue
+        elif key == "host" and "host" not in found:
+            found["host"] = val
+        elif key == "port" and "port" not in found:
+            try:
+                found["port"] = int(val)
+            except ValueError:
+                continue
+    if "db" not in found:
+        return None
+    return {"host": found.get("host", "127.0.0.1"), "port": found.get("port", 6379), "db": found["db"]}
+
+
+def _extract_connection_string_from_config_xml(text: str) -> Optional[str]:
+    """
+    Ищет ``<add name="..." connectionString="..."/>`` записи, чьё имя/тег
+    содержит "redis" (регистронезависимо) — стандартный вид ``<connectionStrings>``
+    секции .NET-конфига (``ConnectionStrings.config``/``Web.config``/``App.config``).
+    """
+    for m in re.finditer(r"<add\b[^>]*/?>", text, re.IGNORECASE):
+        tag = m.group(0)
+        if "redis" not in tag.lower():
+            continue
+        cs_m = re.search(r'connectionString\s*=\s*"([^"]*)"', tag, re.IGNORECASE)
+        if cs_m and cs_m.group(1):
+            return cs_m.group(1)
+    return None
+
+
+def _windowed_redis_search(text: str) -> Optional[dict]:
+    """Запасной вариант для произвольного текста: окно ~350 символов вокруг первого упоминания "redis"."""
+    lower = text.lower()
+    idx = lower.find("redis")
+    if idx == -1:
+        return None
+    window = text[max(0, idx - 50): idx + 300]
+    return _parse_redis_connection_string(window)
+
+
+def _extract_host_port_db_from_json_dict(d: dict) -> Optional[dict]:
+    """
+    Достаёт host/port/db из JSON-объекта, ПОХОЖЕГО на настройки redis
+    (напр. ``{"Host": "127.0.0.1", "Port": 6379, "Db": 2}``), либо, если это
+    обёртка над строкой подключения (``{"ConnectionString": "host=..;db=.."}``),
+    делегирует в ``_parse_redis_connection_string``.
+    """
+    lower = {k.lower(): v for k, v in d.items() if isinstance(k, str)}
+    db_val = None
+    for key in ("db", "database", "number", "redisdb", "redis_db"):
+        if key in lower:
+            try:
+                db_val = int(lower[key])
+                break
+            except (TypeError, ValueError):
+                continue
+    if db_val is None:
+        for key in ("connectionstring", "connection_string", "value", "url"):
+            if key in lower and isinstance(lower[key], str):
+                parsed = _parse_redis_connection_string(lower[key])
+                if parsed:
+                    return parsed
+        return None
+    host = lower.get("host") or lower.get("hostname") or "127.0.0.1"
+    port_raw = lower.get("port")
+    try:
+        port = int(port_raw) if port_raw is not None else 6379
+    except (TypeError, ValueError):
+        port = 6379
+    return {"host": str(host), "port": port, "db": db_val}
+
+
+def _find_redis_in_json(data: Any) -> Optional[dict]:
+    """
+    Рекурсивно ищет "redis"-ключ (регистронезависимо) в разобранном JSON
+    (dict/list произвольной вложенности — ``appsettings.json`` обычно
+    группирует секции, поэтому Redis может лежать не в корне) и пытается
+    извлечь host/port/db из значения (строка-подключение ИЛИ объект).
+    """
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(key, str) and "redis" in key.lower():
+                if isinstance(value, str):
+                    parsed = _parse_redis_connection_string(value)
+                    if parsed:
+                        return parsed
+                elif isinstance(value, dict):
+                    parsed = _extract_host_port_db_from_json_dict(value)
+                    if parsed:
+                        return parsed
+        for value in data.values():
+            result = _find_redis_in_json(value)
+            if result:
+                return result
+    elif isinstance(data, list):
+        for item in data:
+            result = _find_redis_in_json(item)
+            if result:
+                return result
+    return None
+
+
+def _try_extract_redis_from_file(path: Path) -> Optional[dict]:
+    """Best-effort извлечение Redis-параметров из ОДНОГО файла. Никогда не бросает исключение."""
+    try:
+        if path.stat().st_size > _MAX_CONFIG_FILE_BYTES:
+            return None
+        text = path.read_text(encoding="utf-8-sig", errors="ignore")
+    except OSError:
+        return None
+
+    if path.suffix.lower() == ".json":
+        try:
+            data = json.loads(text)
+        except (json.JSONDecodeError, ValueError, RecursionError):
+            return None
+        return _find_redis_in_json(data)
+
+    # .config и прочее текстовое — сначала штатный вид <add .../>, иначе
+    # запасной поиск "redis" по окну текста.
+    cs = _extract_connection_string_from_config_xml(text)
+    if cs:
+        parsed = _parse_redis_connection_string(cs)
+        if parsed:
+            return parsed
+    return _windowed_redis_search(text)
+
+
+def resolve_redis_from_stand_config(stand_dir: Optional[str]) -> Optional[dict]:
+    """
+    Best-effort резолвер параметров подключения к Redis ИЗ КОНФИГА СТЕНДА —
+    фолбэк, когда реестр BPMkit не содержит ``extra["redis_db"]`` (частый
+    случай, см. docstring модуля). Возвращает ``{"host": str, "port": int,
+    "db": int}`` либо ``None``, если ничего похожего на redis-подключение с
+    номером БД не нашлось (или ``stand_dir`` пуст/не существует).
+
+    Порядок поиска в ``stand_dir`` (без рекурсии в подпапки):
+      1. ``ConnectionStrings.config``, ``appsettings.json`` (типичные для
+         BPMSoft/.NET имена) — в этом порядке;
+      2. остальные ``*.config``/``*.json`` файлы в корне каталога стенда.
+
+    Никогда не бросает исключение — отсутствующий/битый/нечитаемый файл
+    просто пропускается (следующий кандидат).
+    """
+    if not stand_dir:
+        return None
+    root = Path(stand_dir)
+    if not root.is_dir():
+        return None
+
+    candidates: list[Path] = []
+    for name in _REDIS_CONFIG_FILENAMES:
+        p = root / name
+        if p.is_file():
+            candidates.append(p)
+
+    try:
+        entries = sorted(root.iterdir())
+    except OSError:
+        entries = []
+    for p in entries:
+        try:
+            if not p.is_file() or p in candidates:
+                continue
+        except OSError:
+            continue
+        if p.suffix.lower() in _REDIS_CONFIG_EXTENSIONS:
+            candidates.append(p)
+
+    for path in candidates:
+        result = _try_extract_redis_from_file(path)
+        if result:
+            return result
+    return None

standkit_hub/security.py

@@ -0,0 +1,146 @@
+"""
+Security-примитивы веб-хаба standkit_hub: сессионный токен, извлечение
+предъявленного токена (cookie/заголовок), anti-CSRF/cross-origin проверка
+мутаций, санитайзинг путей статики.
+
+По образцу ``standkit_agent/security.py`` (fail-closed bind-проверка,
+``hmac.compare_digest`` вместо ``==``), но адаптировано под браузерный клиент:
+сессия — HttpOnly-cookie, а мутации (POST/DELETE) дополнительно требуют
+дублирующий заголовок ``X-Standkit-Token`` (double-submit паттерн: сторонний
+сайт может заставить браузер отправить cookie, но не может ни прочитать её,
+ни подделать наш кастомный заголовок для cross-origin запроса) плюс сверку
+``Origin``/``Referer`` с адресом самого хаба.
+
+Хаб — та же RCE-поверхность, что и headless-агент (управляет процессами
+через ``standkit.lifecycle``/``standkit_hub.agent_control``), поэтому
+fail-closed bind-проверка (``validate_bind_security``/``InsecureBindError``/
+``is_loopback_host``) переиспользуется напрямую из ``standkit_agent.security``
+— дублировать эту логику здесь было бы источником рассинхронизации.
+
+STDLIB-ONLY: ``hmac``, ``re``, ``secrets``, ``urllib.parse``.
+"""
+
+from __future__ import annotations
+
+import hmac
+import re
+import secrets as _secrets_mod
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+# Реэкспорт — единственный источник fail-closed bind-логики (не дублируем).
+from standkit_agent.security import (  # noqa: F401
+    InsecureBindError,
+    is_loopback_host,
+    validate_bind_security,
+)
+
+SESSION_COOKIE_NAME = "standkit_session"
+TOKEN_HEADER_NAME = "X-Standkit-Token"
+TOKEN_QUERY_PARAM = "t"
+
+DEFAULT_MAX_BODY_BYTES = 256 * 1024  # 256 КБ — лимит тела JSON-запроса хаба
+DEFAULT_MAX_LOGS_N = 10_000
+
+_COOKIE_ATTR_RE = re.compile(r"^" + re.escape(SESSION_COOKIE_NAME) + r"=([^;]*)")
+
+# То же множество символов, что допускает реестр/агент — не дублируем правило
+# отдельным regex'ом с шансом разъехаться, просто переиспользуем то же имя.
+_STAND_NAME_RE = re.compile(r"^[A-Za-z0-9_.-]{1,128}$")
+_SECRET_REF_RE = re.compile(r"^[A-Za-z0-9_.:-]{1,256}$")
+
+
+def generate_session_token() -> str:
+    """Криптостойкий сессионный токен хаба (генерируется один раз при старте процесса)."""
+    return _secrets_mod.token_urlsafe(32)
+
+
+def extract_cookie_token(cookie_header: str) -> Optional[str]:
+    """Достаёт значение cookie ``standkit_session`` из заголовка ``Cookie`` (без внешних зависимостей)."""
+    if not cookie_header:
+        return None
+    for part in cookie_header.split(";"):
+        part = part.strip()
+        m = _COOKIE_ATTR_RE.match(part)
+        if m:
+            return m.group(1)
+    return None
+
+
+def tokens_match(presented: Optional[str], expected: str) -> bool:
+    """Сравнение токенов ТОЛЬКО через ``hmac.compare_digest`` (защита от timing-атак)."""
+    if not presented:
+        return False
+    return hmac.compare_digest(presented, expected)
+
+
+def is_local_origin(value: Optional[str], *, expected_port: int) -> bool:
+    """
+    True, если ``Origin``/``Referer`` указывает на loopback-хост И порт,
+    совпадающий с портом самого хаба.
+
+    Anti-CSRF проверка на мутациях (в дополнение к double-submit токену) —
+    сторонний сайт не может ни подделать заголовок ``Origin`` браузера, ни
+    прочитать наш HttpOnly-cookie, чтобы продублировать его в заголовок.
+    """
+    if not value:
+        return False
+    try:
+        parsed = urlparse(value)
+    except ValueError:
+        return False
+    if not is_loopback_host(parsed.hostname or ""):
+        return False
+    return parsed.port == expected_port
+
+
+def sanitize_static_path(web_dir: Path, rel_path: str) -> Optional[Path]:
+    """
+    Резолвит путь внутри ``web_dir`` для статики, отклоняя traversal
+    (``..``, абсолютные пути в компонентах). Возвращает ``None``, если путь
+    небезопасен, не существует или указывает не на файл.
+    """
+    if not rel_path or rel_path.startswith("/") or ".." in Path(rel_path).parts:
+        return None
+    web_dir_resolved = web_dir.resolve()
+    candidate = (web_dir / rel_path).resolve()
+    try:
+        candidate.relative_to(web_dir_resolved)
+    except ValueError:
+        return None
+    if not candidate.is_file():
+        return None
+    return candidate
+
+
+def validate_stand_name(name: str) -> bool:
+    """Валидация имени стенда из URL — тот же whitelist, что и у агента."""
+    return bool(name) and bool(_STAND_NAME_RE.match(name))
+
+
+def validate_secret_ref(ref: str) -> bool:
+    """Валидация ссылки на секрет из URL (буквы/цифры/``_.:-``, кап длины)."""
+    return bool(ref) and bool(_SECRET_REF_RE.match(ref))
+
+
+def clamp_logs_n(raw: str, *, max_n: int = DEFAULT_MAX_LOGS_N) -> int:
+    """Парсит и капит параметр ``n`` запроса логов. Бросает ``ValueError`` на некорректный ввод."""
+    n = int(raw)
+    if n < 0:
+        raise ValueError("n не может быть отрицательным")
+    return min(n, max_n)
+
+
+def validate_content_length(header_value: Optional[str], *, max_bytes: int = DEFAULT_MAX_BODY_BYTES) -> int:
+    """Разбирает ``Content-Length`` и проверяет лимит тела запроса ДО его фактического чтения из сокета."""
+    raw = header_value if header_value not in (None, "") else "0"
+    try:
+        n = int(raw)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"некорректный Content-Length: {raw!r}") from exc
+    if n < 0:
+        raise ValueError("Content-Length не может быть отрицательным")
+    if n > max_bytes:
+        raise ValueError(f"тело запроса превышает лимит {max_bytes} байт")
+    return n