From 73b3b4cc025e17cdf5a3a94be561fe078f50e479 Mon Sep 17 00:00:00 2001 From: ospab Date: Fri, 29 May 2026 00:25:40 +0300 Subject: [PATCH] docs: add CONTRIBUTING guide in English and Russian, link in README --- CONTRIBUTING.md | 115 ++++++++++++++++++++++++++++++++++ CONTRIBUTING.ru.md | 115 ++++++++++++++++++++++++++++++++++ README.md | 2 +- README.ru.md | 2 +- ostp-gui/src-tauri/Cargo.lock | 4 +- 5 files changed, 234 insertions(+), 4 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.ru.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4644468 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,115 @@ +# Contributing to OSTP + +Thank you for your interest in contributing to **OSTP (Ospab Stealth Transport Protocol)**! We welcome contributions from developers, security researchers, testers, and documentation writers of all skill levels. + +By contributing to this project, you agree to abide by our code of conduct and license terms. + +--- + +## Table of Contents + +1. [Development Setup](#development-setup) +2. [Project Structure](#project-structure) +3. [Development Workflow](#development-workflow) +4. [Coding Guidelines](#coding-guidelines) +5. [Submitting Pull Requests](#submitting-pull-requests) +6. [Security Vulnerabilities](#security-vulnerabilities) + +--- + +## Development Setup + +To build and test OSTP locally, you will need: + +* **Rust Toolchain (1.75+)**: Install via [rustup](https://rustup.rs/). +* **Node.js (18+) & npm**: Required to build the frontend control panel (`ostp-control`) and compile Tauri GUI resources. +* **Git**: For version control. + +### Building the Project + +1. **Clone the repository**: + ```bash + git clone https://github.com/ospab/ostp.git + cd ostp + ``` + +2. **Build the control panel frontend**: + ```bash + cd ostp-control + npm install + npm run build + cd .. + ``` + +3. **Build the entire Cargo workspace**: + ```bash + cargo build + ``` + +4. **Run tests**: + ```bash + cargo test --workspace + ``` + +--- + +## Project Structure + +The repository is organized as a Cargo workspace containing the following crates: + +* [`ostp-core/`](file:///d:/ospab-projects/ostp/ostp-core): Core protocol logic, including packet formatting, serialization, selective ACK/NACK (ARQ) state machine, and the Noise protocol (`Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s`) handshake. +* [`ostp-client/`](file:///d:/ospab-projects/ostp/ostp-client): Client implementations, including SOCKS5/HTTP local proxies, `tun2socks` integration, native TUN interface routing, and split-tunneling bypass mechanisms. +* [`ostp-server/`](file:///d:/ospab-projects/ostp/ostp-server): Server logic, session dispatcher, anti-probing fallback server proxying, access key database, and the REST API for control panel communication. +* [`ostp-control/`](file:///d:/ospab-projects/ostp/ostp-control): A modern web dashboard for server administration (user management, real-time metrics, bandwidth limits). +* [`ostp-gui/`](file:///d:/ospab-projects/ostp/ostp-gui): Tauri-based desktop GUI application for Windows and Linux. +* [`ostp-flutter/`](file:///d:/ospab-projects/ostp/ostp-flutter): Mobile client code for Android platforms. + +--- + +## Development Workflow + +1. **Check for existing issues** or open a new one to discuss proposed changes before starting work. +2. **Fork the repository** and create a new branch from `master`: + ```bash + git checkout -b feat/your-feature-name + ``` +3. **Implement your changes**, ensuring you write appropriate unit or integration tests. +4. **Format your code**: + ```bash + cargo fmt --all + ``` +5. **Run linter checks**: + ```bash + cargo clippy --workspace --all-targets -- -D warnings + ``` +6. **Ensure all tests pass**: + ```bash + cargo test --workspace + ``` + +--- + +## Coding Guidelines + +* **Safety**: Avoid using `unsafe` blocks unless absolutely necessary for low-level system bindings (e.g., FFI configurations like `setsockopt`). When using `unsafe`, add safety doc comments explaining why it is safe. +* **Documentation**: Document public modules, structs, and functions. Maintain comment integrity across codebase changes. +* **Logging**: Use the `tracing` framework for structured logging. Avoid `println!` for production logs. +* **Aesthetics**: When editing GUI or Web components, adhere to premium, modern web design aesthetics (vibrant color palettes, glassmorphism, responsive grids). + +--- + +## Submitting Pull Requests + +1. Push your branch to your GitHub fork: + ```bash + git push origin feat/your-feature-name + ``` +2. Open a Pull Request (PR) targeting the `master` branch. +3. In your PR description, explain the rationale behind your changes, what was fixed/added, and how it was tested. +4. Verify that GitHub Actions CI runs successfully on your PR. + +--- + +## Security Vulnerabilities + +If you discover a security-related vulnerability, please do **not** open a public issue. Instead, report it privately by emailing the core maintainers at [gvoprgrg@gmail.com](mailto:gvoprgrg@gmail.com). We will coordinate a swift disclosure and fix. diff --git a/CONTRIBUTING.ru.md b/CONTRIBUTING.ru.md new file mode 100644 index 0000000..4b38904 --- /dev/null +++ b/CONTRIBUTING.ru.md @@ -0,0 +1,115 @@ +# Участие в разработке OSTP + +Спасибо за интерес к участию в разработке **OSTP (Ospab Stealth Transport Protocol)**! Мы рады любой помощи: от написания кода и тестирования до работы над документацией и проведения аудита безопасности. + +Присылая изменения в проект, вы соглашаетесь соблюдать правила нашего сообщества и условия лицензии. + +--- + +## Содержание + +1. [Подготовка окружения](#подготовка-окружения) +2. [Структура проекта](#структура-проекта) +3. [Процесс разработки](#процесс-разработки) +4. [Правила оформления кода](#правила-оформления-кода) +5. [Создание Pull Request](#создание-pull-request) +6. [Уязвимости безопасности](#уязвимости-безопасности) + +--- + +## Подготовка окружения + +Для локальной сборки и тестирования 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. **Соберите веб-интерфейс панели управления**: + ```bash + cd ostp-control + npm install + npm run build + cd .. + ``` + +3. **Соберите весь Cargo-workspace**: + ```bash + cargo build + ``` + +4. **Запустите тесты**: + ```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 прокси-серверы, интеграция с драйвером `wintun` / `tun2socks` и реализация раздельного туннелирования для прямого обхода трафика. +* [`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. + +--- + +## Процесс разработки + +1. **Проверьте существующие задачи** или откройте новую тему (Issue) для обсуждения предлагаемых изменений. +2. **Сделайте fork репозитория** и создайте новую ветку от `master`: + ```bash + git checkout -b feat/имя-вашей-фичи + ``` +3. **Внесите необходимые изменения** и добавьте соответствующие модульные или интеграционные тесты. +4. **Выровняйте форматирование кода**: + ```bash + cargo fmt --all + ``` +5. **Запустите статический анализатор**: + ```bash + cargo clippy --workspace --all-targets -- -D warnings + ``` +6. **Убедитесь, что все тесты проходят**: + ```bash + cargo test --workspace + ``` + +--- + +## Правила оформления кода + +* **Безопасность (Safety)**: Избегайте использования блоков `unsafe` везде, где это возможно. Допускается их использование только для низкоуровневых системных вызовов (например, FFI-настройки сокетов `setsockopt`). Любой блок `unsafe` должен сопровождаться комментарием `// SAFETY: ...`. +* **Документация**: Пишите документацию для публичных модулей, структур и методов. Сохраняйте целостность комментариев при рефакторинге. +* **Логирование**: Используйте фреймворк `tracing` для структурированного логирования. Не используйте `println!` в рабочем коде. +* **Дизайн**: При изменении веб-интерфейсов или GUI следуйте современным визуальным трендам (плавные анимации, сбалансированная цветовая гамма, адаптивная верстка). + +--- + +## Создание Pull Request + +1. Отправьте ветку в ваш fork-репозиторий: + ```bash + git push origin feat/имя-вашей-фичи + ``` +2. Создайте Pull Request (PR) в ветку `master` основного репозитория. +3. Подробно опишите внесенные изменения: какая проблема решается, как проводилось тестирование и на каких платформах проверялась сборка. +4. Убедитесь, что автоматическое тестирование (GitHub Actions CI) завершилось успешно. + +--- + +## Уязвимости безопасности + +Если вы обнаружили уязвимость, пожалуйста, **не** публикуйте её в открытых Issue. Вместо этого отправьте отчёт разработчикам на почту [gvoprgrg@gmail.com](mailto:gvoprgrg@gmail.com) для координации закрытого исправления. diff --git a/README.md b/README.md index a3078ae..54cff07 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # OSTP — Ospab Stealth Transport Protocol -[Русский язык](README.ru.md) · [Wiki](https://github.com/ospab/ostp/wiki) · [Releases](https://github.com/ospab/ostp/releases) +[Русский язык](README.ru.md) · [Wiki](https://github.com/ospab/ostp/wiki) · [Contributing](CONTRIBUTING.md) · [Releases](https://github.com/ospab/ostp/releases) ![GitHub Release](https://img.shields.io/github/v/release/ospab/ostp?style=flat-square&color=blue) ![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-orange.svg?style=flat-square) diff --git a/README.ru.md b/README.ru.md index faf42fd..713a3fb 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,6 +1,6 @@ # OSTP — Ospab Stealth Transport Protocol -[English](README.md) +[English](README.md) · [Contributing](CONTRIBUTING.ru.md) ![GitHub Release](https://img.shields.io/github/v/release/ospab/ostp?style=flat-square&color=blue) ![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-orange.svg?style=flat-square) diff --git a/ostp-gui/src-tauri/Cargo.lock b/ostp-gui/src-tauri/Cargo.lock index b6b5f21..520ed62 100644 --- a/ostp-gui/src-tauri/Cargo.lock +++ b/ostp-gui/src-tauri/Cargo.lock @@ -2632,7 +2632,7 @@ dependencies = [ [[package]] name = "ostp-client" -version = "0.2.66" +version = "0.2.67" dependencies = [ "anyhow", "base64 0.22.1", @@ -2662,7 +2662,7 @@ dependencies = [ [[package]] name = "ostp-core" -version = "0.2.66" +version = "0.2.67" dependencies = [ "anyhow", "bytes",