# Участие в разработке OSTP Спасибо за интерес к участию в разработке **OSTP (Ospab Stealth Transport Protocol)**! Мы рады любой помощи: от написания кода и тестирования до работы над документацией и проведения аудита безопасности. Присылая изменения в проект, вы соглашаетесь соблюдать правила нашего сообщества и условия лицензии. --- ## Содержание 1. [Подготовка окружения](#подготовка-окружения) 2. [Структура проекта](#структура-проекта) 3. [Стратегия веток](#стратегия-веток) 4. [Процесс разработки](#процесс-разработки) 5. [Оформление коммитов](#оформление-коммитов) 6. [Правила оформления кода](#правила-оформления-кода) 7. [Создание Pull Request](#создание-pull-request) 8. [Уязвимости безопасности](#уязвимости-безопасности) --- ## Подготовка окружения Для локальной сборки и тестирования OSTP вам понадобятся: * **Rust Toolchain (1.75+)**: Рекомендуется установить через [rustup](https://rustup.rs/). * **Node.js (18+) и npm**: Необходимы для сборки веб-панели управления (`ostp-control`) и сборки интерфейса Tauri. * **Git**: Для контроля версий. ### Сборка проекта 1. **Клонируйте репозиторий**: ```bash git clone https://github.com/ospab/ostp.git cd ostp ``` 2. **Соберите весь Cargo-workspace**: ```bash cargo build ``` `ostp-control` (веб-панель) нужна только если вы работаете конкретно над ней — в остальных случаях сервер собирается с пустым `dist/` через `rust-embed`, и этот шаг не нужен для повседневной работы над core/client/server. Если вы всё же трогаете панель: ```bash cd ostp-control && npm install && npm run build && cd .. ``` 3. **Запустите тесты**: ```bash cargo test --workspace ``` --- ## Структура проекта Репозиторий представляет собой единый Cargo-workspace со следующими компонентами: * [`ostp-core/`](file:///d:/ospab-projects/ostp/ostp-core): Базовая логика протокола: форматирование пакетов, сериализация, конечный автомат выборочного подтверждения (ARQ/ACK/NACK) и рукопожатие Noise (`Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s`). * [`ostp-client/`](file:///d:/ospab-projects/ostp/ostp-client): Клиентская часть: локальные SOCKS5/HTTP прокси-серверы, нативный OSTP TUN-интерфейс (через драйвер `wintun`) и реализация раздельного туннелирования для прямого обхода трафика. * [`ostp-server/`](file:///d:/ospab-projects/ostp/ostp-server): Серверная часть: диспетчеризация сессий, маскировка под классические веб-серверы при активном сканировании, база данных ключей доступа и REST API панели управления. * [`ostp-control/`](file:///d:/ospab-projects/ostp/ostp-control): Панель администратора (пользователи, статистика трафика в реальном времени, лимиты скорости и объема данных). * [`ostp-gui/`](file:///d:/ospab-projects/ostp/ostp-gui): Настольное приложение-клиент для Windows и Linux на платформе Tauri. * [`ostp-flutter/`](file:///d:/ospab-projects/ostp/ostp-flutter): Мобильный клиент для платформы Android. --- ## Стратегия веток В репозитории три долгоживущие ветки, по возрастанию стабильности: | Ветка | Роль | |---|---| | `nightly` | Активная разработка. Вся новая работа и фиксы попадают сюда первыми. | | `pre-release` | Периодически перематывается вперёд (fast-forward) от `nightly`, когда та немного «отлежалась». Собирается в канал релиза `{версия}-beta`. | | `master` | Перематывается вперёд от `pre-release`, когда та доказала стабильность. Настоящие тегированные релизы (`vX.Y.Z`) режутся отсюда. | В `pre-release` и `master` **никогда** не коммитят напрямую — они только перематываются вперёд от ветки уровнем ниже. Это значит, что промоушен — всегда обычный `git merge` без единого конфликта по построению: не мержите/не ребейзьте свою фичу прямо в `pre-release` или `master`. **PR от контрибьюторов нацелены на `nightly`**, не на `master`. --- ## Процесс разработки 1. **Проверьте существующие задачи** или откройте новую тему (Issue) для обсуждения предлагаемых изменений. 2. **Сделайте fork репозитория** и создайте новую ветку от `nightly`: ```bash git checkout nightly git checkout -b feat/имя-вашей-фичи ``` 3. **Внесите необходимые изменения** и добавьте соответствующие модульные или интеграционные тесты. 4. **Выровняйте форматирование кода**: ```bash cargo fmt --all ``` 5. **Запустите статический анализатор**: ```bash cargo clippy --workspace --all-targets -- -D warnings ``` 6. **Убедитесь, что все тесты проходят**: ```bash cargo test --workspace ``` --- ## Оформление коммитов ``` <тип>(<область>): <краткое описание в повелительном наклонении> <опционально: тело — объясняет ПОЧЕМУ, а не что; диф и так показывает что изменилось> ``` - **Тип** — один из: `feat` (новая функциональность), `fix` (исправление бага), `docs`, `refactor` (без изменения поведения), `perf`, `test`, `chore` (зависимости/тулинг/версии), `ci`, `security`. - **Область** (опционально) — крейт или часть проекта: `client`, `server`, `core`, `gui`, `flutter`, `ci`, `docs` и т.д., например `fix(client): ...`. - **Краткое описание** — повелительное наклонение ("добавь", а не "добавил"/"добавляет"), без точки в конце, желательно до ~70 символов. - **Тело** — только когда причина не очевидна из дифа: какой баг это чинит, какое ограничение определило подход, на какой trade-off вы пошли. Не пересказывайте то, что и так видно в дифе. Перенос строк на ~72 символах. ``` fix(server): отбрасывать junk-фреймы по маркеру для каждого ключа, а не глобальному Фиксированный 4-байтовый маркер на каждом junk-пакете сам по себе — сигнатура DPI, по которой можно фильтровать любого наблюдателя во всех деплойментах OSTP сразу. Выводим маркер из access_key (HKDF, та же схема что у obfuscation_key/psk), чтобы он был индивидуальным для ключа и неотличимым от случайной полезной нагрузки пакета. ``` Несколько несвязанных изменений — это несколько отдельных коммитов, а не один сборный. Это сохраняет пользу от `git bisect` и код-ревью. Squash-merge подходит для PR с парой коммитов вроде "fix typo" / "address review", но не сквошьте вместе логически разные изменения. --- ## Правила оформления кода * **Безопасность (Safety)**: Избегайте использования блоков `unsafe` везде, где это возможно. Допускается их использование только для низкоуровневых системных вызовов (например, FFI-настройки сокетов `setsockopt`). Любой блок `unsafe` должен сопровождаться комментарием `// SAFETY: ...`. * **Документация**: Пишите документацию для публичных модулей, структур и методов. Сохраняйте целостность комментариев при рефакторинге. * **Логирование**: Используйте фреймворк `tracing` для структурированного логирования. Не используйте `println!` в рабочем коде. * **Дизайн**: При изменении веб-интерфейсов или GUI следуйте современным визуальным трендам (плавные анимации, сбалансированная цветовая гамма, адаптивная верстка). --- ## Создание Pull Request 1. Отправьте ветку в ваш fork-репозиторий: ```bash git push origin feat/имя-вашей-фичи ``` 2. Создайте Pull Request (PR) в ветку `nightly` основного репозитория (см. [Стратегия веток](#стратегия-веток) — `master` получает только fast-forward от `pre-release`, PR туда не принимаются напрямую). 3. Подробно опишите внесенные изменения: какая проблема решается, как проводилось тестирование и на каких платформах проверялась сборка. 4. Убедитесь, что автоматическое тестирование (GitHub Actions CI) завершилось успешно. --- ## Уязвимости безопасности Если вы обнаружили уязвимость, пожалуйста, **не** публикуйте её в открытых Issue. Вместо этого отправьте отчёт разработчикам на почту [gvoprgrg@gmail.com](mailto:gvoprgrg@gmail.com) для координации закрытого исправления.