standkit 0.3.7__py3-none-any.whl

standkit/secrets.py

@@ -0,0 +1,144 @@
+"""
+Secret-first доступ к секретам стенда (пароли БД, токены агентов и т.п.).
+
+Контракт разрешения секрета (по духу совпадает с secretstore из BPMkit, но без
+зависимости от него — ядро standkit самодостаточно):
+
+  1. Переменная окружения ``STANDKIT_SECRET__<REF_UPPER>`` (двойное подчёркивание
+     как разделитель, символы, недопустимые в имени переменной окружения,
+     заменяются на "_");
+  2. системный keyring (опциональная зависимость — импортируется в try/except,
+     ядро НЕ требует пакет ``keyring`` для работы);
+  3. явный фолбэк, переданный вызывающей стороной (например, открытое поле
+     ``db_password`` из записи реестра — сознательно менее приоритетно, чем
+     секрет);
+  4. если ничего не найдено — SecretError.
+
+Секрет никогда не логируется и не попадает в текстовое представление ошибки
+целиком (в сообщении об ошибке фигурирует только ref, не значение).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Optional
+
+try:
+    import keyring  # type: ignore
+
+    _HAS_KEYRING = True
+except ImportError:  # keyring — опциональная зависимость
+    keyring = None  # type: ignore
+    _HAS_KEYRING = False
+
+_KEYRING_SERVICE = "standkit"
+_ENV_PREFIX = "STANDKIT_SECRET__"
+
+
+class SecretError(Exception):
+    """Секрет не найден ни в одном из источников."""
+
+
+def _env_var_name(ref: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9]", "_", ref).upper()
+    return f"{_ENV_PREFIX}{safe}"
+
+
+def has_secret(ref: str) -> bool:
+    """Быстрая проверка наличия секрета (без исключений) — env либо keyring."""
+    if os.environ.get(_env_var_name(ref)):
+        return True
+    if _HAS_KEYRING:
+        try:
+            return keyring.get_password(_KEYRING_SERVICE, ref) is not None
+        except Exception:
+            # Бэкенд keyring недоступен на этой машине (нет DBus/Credential
+            # Manager и т.п.) — не считаем это фатальной ошибкой на этапе has_secret.
+            return False
+    return False
+
+
+def set_secret(ref: str, value: str) -> None:
+    """
+    Сохраняет значение секрета под ссылкой ``ref`` в системном keyring.
+
+    Симметрично ``get_secret``/``has_secret`` — тот же backend (keyring,
+    сервис ``standkit``). Требует опциональную зависимость ``keyring``
+    (extra ``standkit[secrets]``/``standkit[gui]``); при её отсутствии или
+    сбое backend'а бросает понятную ``SecretError`` (без падения импорта
+    модуля — см. try/except вокруг ``import keyring`` выше).
+
+    Значение секрета никогда не логируется и не попадает в текст ошибки.
+    """
+    if not _HAS_KEYRING:
+        raise SecretError(
+            f"Невозможно задать секрет '{ref}': пакет keyring не установлен. "
+            "Установите опциональную зависимость: pip install standkit[secrets]"
+        )
+    try:
+        keyring.set_password(_KEYRING_SERVICE, ref, value)
+    except Exception as exc:
+        # Значение секрета намеренно не попадает в текст исключения — только ref.
+        raise SecretError(f"Не удалось сохранить секрет '{ref}' в keyring: {exc}") from exc
+
+
+def delete_secret(ref: str) -> None:
+    """
+    Удаляет секрет по ссылке ``ref`` из системного keyring.
+
+    Идемпотентно по духу с остальным контрактом: отсутствие backend'а —
+    SecretError; отсутствие самого секрета в keyring backend обычно тоже
+    трактует как ошибку (PasswordDeleteError) — она также оборачивается в
+    SecretError, вызывающая сторона может считать "секрета и так не было"
+    нормальным исходом при необходимости (проверить через has_secret до
+    удаления).
+    """
+    if not _HAS_KEYRING:
+        raise SecretError(
+            f"Невозможно удалить секрет '{ref}': пакет keyring не установлен. "
+            "Установите опциональную зависимость: pip install standkit[secrets]"
+        )
+    try:
+        keyring.delete_password(_KEYRING_SERVICE, ref)
+    except Exception as exc:
+        raise SecretError(f"Не удалось удалить секрет '{ref}' из keyring: {exc}") from exc
+
+
+def get_secret(ref: str, *, fallback: Optional[str] = None) -> str:
+    """
+    Возвращает значение секрета по ссылке ``ref`` согласно Secret-first контракту.
+
+    ``fallback`` — необязательное значение "последней надежды" (например,
+    открытое поле реестра) — используется только если ни env, ни keyring не
+    дали ответа. Если и фолбэка нет — SecretError.
+    """
+    env_val = os.environ.get(_env_var_name(ref))
+    if env_val:
+        return env_val
+
+    if _HAS_KEYRING:
+        try:
+            val = keyring.get_password(_KEYRING_SERVICE, ref)
+        except Exception:
+            val = None
+        if val:
+            return val
+
+    if fallback:
+        return fallback
+
+    raise SecretError(
+        f"Секрет '{ref}' не найден ни в переменной окружения {_env_var_name(ref)}, "
+        f"ни в keyring, ни в переданном fallback"
+    )
+
+
+# --- TODO(следующая итерация) ---
+# - CLI-обёртка (set/get/status/rotate/delete/list) по аналогии с
+#   BPMkit/server/secretstore.py, но для сервиса "standkit" (set_secret/
+#   delete_secret уже есть как программное API — CLI поверх них тривиален);
+# - файловый фолбэк secrets.enc с мастер-ключом из переменной окружения — для
+#   машин без доступного системного keyring (headless Linux без dbus/libsecret);
+# - явный `status()` с диагностикой источника (env/keyring/fallback/not found)
+#   для онбординга новой машины без раскрытия самого значения.

standkit-0.3.7.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: standkit
+Version: 0.3.7
+Summary: Свободное ядро (MIT) для управления жизненным циклом локальных и удалённых стендов BPMSoft: headless start/stop/restart, health-пробы, логи, реестр стендов. Часть экосистемы BPMkit.
+Author: standkit contributors
+License: MIT
+Project-URL: Homepage, https://github.com/thinkquattro/BPMkitStand
+Project-URL: Экосистема BPMkit, https://github.com/thinkquattro/BPMkit-dev
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: secrets
+Requires-Dist: keyring>=24; extra == "secrets"
+Provides-Extra: desktop
+Requires-Dist: pywebview>=5; extra == "desktop"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/thinkquattro/BPMkitStand/main/standkit_hub/web/bpmkit-logo.svg" alt="BPMkit" width="300"/>
+
+# BPMkitStand
+
+**Свободный диспетчер стендов BPMSoft.**
+Локальный веб-дашборд для запуска, остановки и мониторинга ваших стендов — в один клик, без консоли.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-f9763d.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![Platform](https://img.shields.io/badge/OS-Windows%20%7C%20Linux-lightgrey.svg)]()
+
+[Сайт](https://bpmkit.pro) · [Telegram](https://t.me/quattrolife) · [Companion-версия](https://bpmkit.pro)
+
+</div>
+
+---
+
+## Что это
+
+**BPMkitStand** — бесплатный инструмент экосистемы [BPMkit](https://bpmkit.pro) для управления
+локальными и удалёнными стендами BPMSoft. Открывает лёгкий локальный веб-дашборд в браузере:
+видно состояние каждого стенда, его можно запустить/остановить/перезапустить, посмотреть логи
+текущей сессии и очистить Redis — всё без ручных команд в PowerShell.
+
+Ядро (`standkit`) написано на чистой стандартной библиотеке Python — без тяжёлых зависимостей,
+работает на Windows и Linux.
+
+## Возможности
+
+- **Дашборд стендов** — список из общего реестра BPMkit (`projects.json`), состояние в реальном времени.
+- **Жизненный цикл** — старт / стоп / рестарт стенда с честной обратной связью (спиннер до готовности, без ложных «не поднялся» на прогреве).
+- **Логи** — просмотр логов текущей сессии стенда, открытие папки логов стенда и папки BPMkit-проекта.
+- **Redis** — очистка кэша стенда (номер БД берётся из конфигурации стенда).
+- **Тёмная и светлая тема** с переключателем.
+- **Безопасность по умолчанию** — дашборд слушает только `127.0.0.1`, сессионный токен, защита мутаций (CSRF + проверка Origin).
+- **Удалённые стенды** *(в развитии)* — через лёгкие кроссплатформенные headless-агенты с TLS/mTLS.
+
+## Скриншоты
+
+| Дашборд (светлая тема) | Дашборд (тёмная тема) |
+|---|---|
+| ![Дашборд, светлая тема](https://raw.githubusercontent.com/thinkquattro/BPMkitStand/main/docs/img/dashboard-light.png) | ![Дашборд, тёмная тема](https://raw.githubusercontent.com/thinkquattro/BPMkitStand/main/docs/img/dashboard-dark.png) |
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/thinkquattro/BPMkitStand/main/docs/img/about.png" alt="Модальное окно «О программе»" width="360"/>
+</div>
+
+## Как это работает
+
+BPMkitStand состоит из **ядра и двух оболочек**:
+
+- **`standkit`** — ядро (MIT) на чистой стандартной библиотеке Python: движок жизненного цикла
+  над реестром `projects.json` (старт/стоп/рестарт процесса стенда), health-пробы (процесс / HTTP
+  / порт БД / порт Redis), tail лога, Secret-first доступ к секретам. Без веб-слоя и сетевых
+  зависимостей — можно использовать и как библиотеку/CLI.
+- **`standkit_hub`** — локальный веб-дашборд (то, что видно на скриншотах). Сам себя отдаёт по
+  HTTP через `stdlib http.server` (vanilla JS/CSS, без CDN и сборки) и открывается в системном
+  браузере; опционально — в нативном окне (`standkit[desktop]`, `--desktop`). Устанавливается
+  только на машину оператора.
+- **`standkit_agent`** — лёгкий headless-демон на хосте удалённого стенда (см. ниже).
+
+Дашборд — **федеративный клиент**: он собирает в один список и локальные стенды (управляет ими
+напрямую через ядро), и удалённые (ходит к их агентам по HTTP). В таблице колонка «Транспорт»
+показывает, как дашборд дотягивается до стенда: `local` или `agent`.
+
+Реестр стендов — **единый с MCP BPMkit**: один `projects.json` (стенды под ключом `projects`),
+путь резолвится через `BPMSOFT_PROJECTS_FILE` → `%APPDATA%\BPMkit\projects.json`
+(`~/.config/BPMkit/...` на Linux) → `./projects.json`. Секреты (пароли БД, токены агентов) в
+реестре не хранятся — только ссылки на них (Secret-first).
+
+Запуск стенда честный: дашборд поднимает `dotnet <stand_dll>` и держит спиннер до реального
+ответа web-хоста по HTTP, а не рапортует «запущено» по факту создания процесса.
+
+## Удалённые стенды
+
+Стенды на других хостах (виртуалки, серверы, контуры заказчика) управляются через **федерацию
+лёгких кроссплатформенных агентов** (`standkit_agent`, Windows/Linux, только stdlib). На хосте
+стенда поднимается агент, дашборд оператора ходит к нему по HTTPS с Bearer-токеном; стенд
+объявляется удалённым одним полем `transport: "agent"` в реестре. Агент — RCE-поверхность по
+дизайну, поэтому защищён secure-defaults: loopback по умолчанию, fail-closed на non-loopback без
+TLS, TLS 1.2+/mTLS, скоупы control/readonly, lockout по IP, аудит.
+
+**Полное описание, установка агента, TLS/mTLS, служба и траблшутинг — в
+[docs/REMOTE_STANDS.md](docs/REMOTE_STANDS.md).**
+
+## Установка
+
+Нужен Python 3.10+.
+
+```bash
+pip install "git+https://github.com/thinkquattro/BPMkitStand.git"
+```
+
+Запуск дашборда:
+
+```bash
+standkit-hub
+```
+
+Откроется браузер с локальным дашбордом. Реестр стендов берётся из
+`%APPDATA%\BPMkit\projects.json` (или из переменной окружения `BPMSOFT_PROJECTS_FILE`).
+
+## Реестр стендов
+
+BPMkitStand использует тот же реестр, что и MCP BPMkit — единый `projects.json`.
+Образец формата — [`projects.sample.json`](projects.sample.json).
+
+## Безопасность
+
+Дашборд и агент проектировались с расчётом на прод-контур. Модель угроз, харденинг и чек-лист —
+в [SECURITY.md](SECURITY.md). Кратко: fail-closed bind на loopback, TLS 1.2+/mTLS для агента,
+скоупы токена, per-IP lockout, аудит без утечки секретов.
+
+## BPMkitStand и Companion
+
+Бесплатная версия — полноценный диспетчер стендов. **Companion-версия** дополнительно даёт
+автообновление MCP BPMkit и контроль лицензии; поставляется в составе установщика MCP-клиента.
+Подробнее — на [bpmkit.pro](https://bpmkit.pro).
+
+## Лицензия
+
+[MIT](LICENSE) © Владимир Терновский
+
+---
+
+<div align="center">
+<sub>Часть экосистемы <a href="https://bpmkit.pro">BPMkit</a> — AI-ассистента для разработки на BPMSoft.</sub>
+</div>

standkit-0.3.7.dist-info/RECORD

@@ -0,0 +1,38 @@
+standkit/__init__.py,sha256=zmlBZ6BtkoH1mvInZBnAWFWXiNhRXlbY0xWAIThVELM,515
+standkit/health.py,sha256=rjfluQrks6WdN764oZxmFze_pF4X9jZ9QN6zBD57Qj8,7351
+standkit/lifecycle.py,sha256=notNgz3W_aele4Jt2cDQNSQO_LhS3f2NTadsI6WxxT0,9525
+standkit/logs.py,sha256=eGTjlZtX_6HId_E9-IJfeS7Eoy_Kkg0NnINnfm0McfQ,12458
+standkit/models.py,sha256=sUOwkVKWyERvQVG6qjIWrkVfdH-XBEXoQAtVP7EXkKk,8895
+standkit/platform.py,sha256=ER-0YJ1Q0ydpHTQAuE2Brh-hX3tfVNYwQEtC1F1MMU4,7598
+standkit/registry.py,sha256=97goPJQv0DR3pQqyngeIEDXVR257IoHItpgvEOxrRcE,11043
+standkit/secrets.py,sha256=80nEVTEli7Qb4N1WLu6ErfJCLFcwoCfFRyNfu31vd3E,7267
+standkit-0.3.7.dist-info/licenses/LICENSE,sha256=rszyODf-5JGU50GROQX7tP2ULMpvxVveFnvI5kuK1XE,1078
+standkit_agent/__init__.py,sha256=yWsYdZ1i-3BKYmnhnW2Yxs2STd1006yxwE3e267kN3s,569
+standkit_agent/__main__.py,sha256=Xdc_PXsWFmTJKWzlD0FgwFPTxMa-Pv2b2tY7ozNN4TY,8922
+standkit_agent/audit.py,sha256=Xa7FmarL537AOrd8N6GmvYjtoAP7tgpO8wiFOlKrr8k,3716
+standkit_agent/security.py,sha256=QqcDT9_BrX2B-QwNu2jgxRBmN3mRicxl0gCClAR4I64,14545
+standkit_agent/server.py,sha256=KjttdAZ8dLxjLC921DnV_ty-KItoa-xugZWE12eHzJY,18478
+standkit_hub/__init__.py,sha256=4aE2g17dRVRnlBzY2CImMakVr5hmnIqxuOexdXoBaK8,830
+standkit_hub/__main__.py,sha256=zH1IFVTNiwAlDW_uDmVbE2G1mCei4fGt3az6iG2XkFs,5475
+standkit_hub/agent_control.py,sha256=3l-iQROAAlBmUioID0WruqNBlN2JPZhs5m-JFYI6kt0,9193
+standkit_hub/client.py,sha256=zXKMc_PA0oidfLY76cYB5dpJx0ZW-4ifPqFJVxb_moE,7860
+standkit_hub/config.py,sha256=RrPzHlCZuxjV6RbPxj3pgWGR79zMtwZNvPW9DEWecwQ,7016
+standkit_hub/logs_browser.py,sha256=VMUtJ15sUnMPG5B5_O857HIHuUpyakgFnGIuU_1nnpM,9078
+standkit_hub/redis_min.py,sha256=l537Y7oOoRp7KJdGtjOBCggKNq5Lgd4-o0ekMUOzPEc,15152
+standkit_hub/security.py,sha256=NnRxXFobFsbI5GnpFGPzzVDSOVooNkwphBmy8y6SPlQ,6934
+standkit_hub/server.py,sha256=hYuo_r2GNuwP6cXFQCWJ2OuJ7ovtk2PkEAvriNTvgtY,42706
+standkit_hub/shortcut.py,sha256=FlBcgDC4pm0Hv6ixfI_NIHG9RcIT6Rus1jPhHXy37mM,10649
+standkit_hub/assets/bpmkit-icon.ico,sha256=3d6Ymsk29tGp2k3ODf2jpbW1BXGsjcG3rLBqLSLRsc4,19265
+standkit_hub/assets/icon.png,sha256=0qGNU9UoRSyEuGJG-xeZh19zfr8DiV_XsEjYgN5vjqU,16386
+standkit_hub/web/app.js,sha256=PwwJDh-gvaFUVNPyW4JJQCvgD9h2gQ3UXRJzi3clrzc,34842
+standkit_hub/web/bpmkit-logo-dark.svg,sha256=0DRtZU3jdro5PvndG14w02hqVxxu8invnBKccueqZ4w,530
+standkit_hub/web/bpmkit-logo.svg,sha256=ukeUGKk6jEtJVyeKfMh1Ti_qBU76TdNB16GzVpYtMO8,491
+standkit_hub/web/favicon.png,sha256=0qGNU9UoRSyEuGJG-xeZh19zfr8DiV_XsEjYgN5vjqU,16386
+standkit_hub/web/favicon.svg,sha256=hq4Y_4MPPd6vvAgHWZrk3-MRwMcy3zdGYjrBYh5p2dE,314
+standkit_hub/web/index.html,sha256=ERtm6fpuPGLYUcbSs70BDhX57QX9N-3pOffldBt4U14,14866
+standkit_hub/web/style.css,sha256=ux48bEaryiX6ytuSwua9vCtgLVkwYlRkglH7hy8EyNE,17247
+standkit-0.3.7.dist-info/METADATA,sha256=TkK7LsQ8tBvE2uR0GAowdXxpNXZz1O5GVMbNJ_u66Zk,9840
+standkit-0.3.7.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+standkit-0.3.7.dist-info/entry_points.txt,sha256=8ROYOwvYAzY-od3CEidY_e-RcZfI7_6pTA-kUxpvgDs,148
+standkit-0.3.7.dist-info/top_level.txt,sha256=nuG5K9GO1qU22M369LXDcB6u10IiuiNo5rWzPrQD9AU,37
+standkit-0.3.7.dist-info/RECORD,,

standkit-0.3.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

standkit-0.3.7.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+standkit-agent = standkit_agent.__main__:main
+standkit-gui = standkit_hub.__main__:main
+standkit-hub = standkit_hub.__main__:main

standkit-0.3.7.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 standkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

standkit-0.3.7.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+standkit
+standkit_agent
+standkit_hub

standkit_agent/__init__.py

@@ -0,0 +1,9 @@
+"""
+standkit_agent — лёгкий headless-демон на хосте стенда: ядро standkit +
+крошечный HTTP/RPC сервер (stdlib-only: http.server, subprocess, socket,
+urllib). Кроссплатформенный (Windows/Linux). Без Qt и без сторонних
+зависимостей — специально, чтобы агент можно было развернуть на "голом"
+хосте стенда без сборки колёс под конкретную ОС/архитектуру.
+"""
+
+__all__: list[str] = []

standkit_agent/__main__.py

@@ -0,0 +1,192 @@
+"""
+Точка входа агента: ``python -m standkit_agent`` (или консольный скрипт
+``standkit-agent`` после установки пакета).
+
+БЕЗОПАСНОСТЬ (см. также standkit_agent/security.py, README.md → раздел
+"Безопасность"): агент управляет жизненным циклом процессов на хосте стенда
+(start/stop/restart) — это RCE-поверхность по дизайну. Secure-defaults:
+    - ``--host`` по умолчанию ``127.0.0.1`` (НЕ 0.0.0.0);
+    - non-loopback host без TLS ОТКАЗЫВАЕТСЯ стартовать (fail-closed),
+      если явно не передан ``--insecure`` (только dev/тест, НЕ прод);
+    - Bearer-токен сравнивается через hmac.compare_digest (защита от
+      timing-атак);
+    - lockout по source-IP после серии неудачных аутентификаций;
+    - append-only JSON-lines аудит-лог всех запросов (без токенов).
+
+Примеры:
+    # dev, loopback, без TLS (secure default при отсутствии удалённого доступа)
+    python -m standkit_agent --registry ./projects.json \\
+        --token-ref standkit:my-stand:agent-token
+
+    # прод, удалённый доступ, TLS + mTLS
+    python -m standkit_agent --host 0.0.0.0 --port 8765 \\
+        --registry /opt/standkit/projects.json \\
+        --token-ref standkit:my-stand:agent-token \\
+        --readonly-token-ref standkit:my-stand:agent-readonly-token \\
+        --tls-cert /etc/standkit/agent.crt --tls-key /etc/standkit/agent.key \\
+        --tls-client-ca /etc/standkit/clients-ca.crt
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from standkit.registry import Registry, default_registry_path
+from standkit.secrets import SecretError, get_secret
+from standkit_agent.security import (
+    Authenticator,
+    InsecureBindError,
+    LockoutTracker,
+    DEFAULT_LOCKOUT_MAX_FAILURES,
+    DEFAULT_LOCKOUT_WINDOW_SECONDS,
+    validate_bind_security,
+)
+from standkit_agent.server import run_server
+
+
+def _resolve_token(token_ref: str, *, label: str) -> str:
+    try:
+        return get_secret(token_ref)
+    except SecretError as exc:
+        print(f"[standkit-agent] ОШИБКА: не удалось получить секрет {label} ({token_ref!r}): {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="standkit-agent",
+        description=(
+            "Headless-агент standkit для хоста стенда. RCE-поверхность по дизайну "
+            "(start/stop/restart процессов) — secure-defaults: loopback-only без TLS, "
+            "fail-closed на non-loopback без TLS. См. README.md → раздел «Безопасность»."
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="адрес, на котором слушать (по умолчанию 127.0.0.1 — loopback-only, secure default)",
+    )
+    parser.add_argument("--port", type=int, default=8765, help="порт (по умолчанию 8765)")
+    parser.add_argument(
+        "--registry",
+        default=None,
+        help=(
+            "путь к реестру стендов, которыми управляет этот агент (по умолчанию — "
+            "тот же реестр, что резолвит BPMkit MCP: env BPMSOFT_PROJECTS_FILE, "
+            "иначе %%APPDATA%%\\BPMkit\\projects.json / ~/.config/BPMkit/projects.json, "
+            "иначе ./projects.json; см. standkit.registry.default_registry_path)"
+        ),
+    )
+    parser.add_argument(
+        "--token-ref",
+        required=True,
+        help="ссылка на секрет control-токена (start/stop/restart + read), Secret-first (см. standkit.secrets)",
+    )
+    parser.add_argument(
+        "--readonly-token-ref",
+        default=None,
+        help="ссылка на секрет readonly-токена (только GET /stands, /status, /logs) — опционально",
+    )
+    parser.add_argument("--run-dir", default=None, help="каталог pid-файлов (по умолчанию ~/.standkit/run)")
+    parser.add_argument("--log-dir", default=None, help="каталог лог-файлов (по умолчанию ~/.standkit/logs)")
+    parser.add_argument(
+        "--audit-log",
+        default=None,
+        help="путь к JSON-lines аудит-логу (по умолчанию ~/.standkit/audit.log)",
+    )
+    parser.add_argument(
+        "--tls-cert",
+        default=None,
+        help="путь к серверному TLS-сертификату (PEM). Требуется вместе с --tls-key для включения TLS",
+    )
+    parser.add_argument(
+        "--tls-key",
+        default=None,
+        help="путь к приватному ключу серверного TLS-сертификата (PEM)",
+    )
+    parser.add_argument(
+        "--tls-client-ca",
+        default=None,
+        help="путь к CA (PEM) для проверки клиентских сертификатов — включает mTLS "
+        "(CERT_REQUIRED); без этого флага TLS работает без проверки клиента",
+    )
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="ОСОЗНАННЫЙ обход fail-closed проверки: разрешить открытый HTTP на "
+        "non-loopback адресе без TLS. ТОЛЬКО для dev/тестовых сценариев за "
+        "изолированным периметром — НЕ для прода/недоверенной сети. Выводит "
+        "громкое предупреждение в stderr",
+    )
+    parser.add_argument(
+        "--lockout-max-failures",
+        type=int,
+        default=DEFAULT_LOCKOUT_MAX_FAILURES,
+        help=f"порог неудачных аутентификаций с одного IP до блокировки (по умолчанию {DEFAULT_LOCKOUT_MAX_FAILURES})",
+    )
+    parser.add_argument(
+        "--lockout-window",
+        type=float,
+        default=DEFAULT_LOCKOUT_WINDOW_SECONDS,
+        help=f"окно (сек) для подсчёта неудачных аутентификаций (по умолчанию {DEFAULT_LOCKOUT_WINDOW_SECONDS:.0f})",
+    )
+    args = parser.parse_args(argv)
+
+    registry_path = Path(args.registry) if args.registry else default_registry_path()
+    registry = Registry.load(registry_path)
+
+    control_token = _resolve_token(args.token_ref, label="control-токена агента")
+    readonly_token = (
+        _resolve_token(args.readonly_token_ref, label="readonly-токена агента")
+        if args.readonly_token_ref
+        else None
+    )
+    authenticator = Authenticator(control_token, readonly_token)
+    lockout = LockoutTracker(max_failures=args.lockout_max_failures, window_seconds=args.lockout_window)
+
+    run_dir = Path(args.run_dir) if args.run_dir else None
+    log_dir = Path(args.log_dir) if args.log_dir else None
+    audit_log_path = Path(args.audit_log) if args.audit_log else None
+
+    tls_enabled = bool(args.tls_cert and args.tls_key)
+
+    # Fail-closed bind-проверка ДО любого вывода "слушаю ..." — если конфигурация
+    # небезопасна, агент не должен даже создавать впечатление, что он стартовал.
+    try:
+        validate_bind_security(args.host, tls_enabled=tls_enabled, insecure=args.insecure)
+    except InsecureBindError as exc:
+        print(f"[standkit-agent] {exc}", file=sys.stderr)
+        return 1
+
+    print(
+        f"[standkit-agent] слушаю {args.host}:{args.port} "
+        f"(tls={'on' if tls_enabled else 'off'}"
+        f"{'+mtls' if tls_enabled and args.tls_client_ca else ''}), "
+        f"реестр={registry_path}, стендов={len(registry)}, readonly-токен={'да' if readonly_token else 'нет'}"
+    )
+
+    try:
+        run_server(
+            registry,
+            authenticator,
+            host=args.host,
+            port=args.port,
+            run_dir=run_dir,
+            log_dir=log_dir,
+            tls_cert=args.tls_cert,
+            tls_key=args.tls_key,
+            tls_client_ca=args.tls_client_ca,
+            insecure=args.insecure,
+            lockout=lockout,
+            audit_log_path=audit_log_path,
+        )
+    except InsecureBindError as exc:
+        print(f"[standkit-agent] {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())