12 KiB

Raw Blame History

Участие в разработке OSTP

Спасибо за интерес к участию в разработке OSTP (Ospab Stealth Transport Protocol)! Мы рады любой помощи: от написания кода и тестирования до работы над документацией и проведения аудита безопасности.

Присылая изменения в проект, вы соглашаетесь соблюдать правила нашего сообщества и условия лицензии.

Подготовка окружения

Для локальной сборки и тестирования OSTP вам понадобятся:

Rust Toolchain (1.75+): Рекомендуется установить через rustup.
Node.js (18+) и npm: Необходимы для сборки веб-панели управления (ostp-control) и сборки интерфейса Tauri.
Git: Для контроля версий.

Сборка проекта

Клонируйте репозиторий:

git clone https://github.com/ospab/ostp.git
cd ostp

Соберите весь Cargo-workspace:
```
cargo build
```
ostp-control (веб-панель) нужна только если вы работаете конкретно над ней — в остальных случаях сервер собирается с пустым dist/ через rust-embed, и этот шаг не нужен для повседневной работы над core/client/server. Если вы всё же трогаете панель:
```
cd ostp-control && npm install && npm run build && cd ..
```
Запустите тесты:
```
cargo test --workspace
```

Структура проекта

Репозиторий представляет собой единый Cargo-workspace со следующими компонентами:

ostp-core/: Базовая логика протокола: форматирование пакетов, сериализация, конечный автомат выборочного подтверждения (ARQ/ACK/NACK) и рукопожатие Noise (Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s).
ostp-client/: Клиентская часть: локальные SOCKS5/HTTP прокси-серверы, нативный OSTP TUN-интерфейс (через драйвер wintun) и реализация раздельного туннелирования для прямого обхода трафика.
ostp-server/: Серверная часть: диспетчеризация сессий, маскировка под классические веб-серверы при активном сканировании, база данных ключей доступа и REST API панели управления.
ostp-control/: Панель администратора (пользователи, статистика трафика в реальном времени, лимиты скорости и объема данных).
ostp-gui/: Настольное приложение-клиент для Windows и Linux на платформе Tauri.
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.

Процесс разработки

Проверьте существующие задачи или откройте новую тему (Issue) для обсуждения предлагаемых изменений.
Сделайте fork репозитория и создайте новую ветку от nightly:
```
git checkout nightly
git checkout -b feat/имя-вашей-фичи
```
Внесите необходимые изменения и добавьте соответствующие модульные или интеграционные тесты.
Выровняйте форматирование кода:
```
cargo fmt --all
```
Запустите статический анализатор:
```
cargo clippy --workspace --all-targets -- -D warnings
```
Убедитесь, что все тесты проходят:
```
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

Отправьте ветку в ваш fork-репозиторий:
```
git push origin feat/имя-вашей-фичи
```
Создайте Pull Request (PR) в ветку nightly основного репозитория (см. Стратегия веток — master получает только fast-forward от pre-release, PR туда не принимаются напрямую).
Подробно опишите внесенные изменения: какая проблема решается, как проводилось тестирование и на каких платформах проверялась сборка.
Убедитесь, что автоматическое тестирование (GitHub Actions CI) завершилось успешно.

Уязвимости безопасности

Если вы обнаружили уязвимость, пожалуйста, не публикуйте её в открытых Issue. Вместо этого отправьте отчёт разработчикам на почту gvoprgrg@gmail.com для координации закрытого исправления.

12 KiB Raw Blame History Unescape Escape