ospab
/
ostp
mirror of https://github.com/ospab/ostp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: add CONTRIBUTING guide in English and Russian, link in README

This commit is contained in:
ospab 2026-05-29 00:25:40 +03:00
parent 1141958759
commit 73b3b4cc02
5 changed files with 234 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
CONTRIBUTING.md Normal file
View File

@ -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.

115
CONTRIBUTING.ru.md Normal file
View File

@ -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) для координации закрытого исправления.

2
README.md
View File

@ -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)

2
README.ru.md
View File

@ -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)

4
ostp-gui/src-tauri/Cargo.lock generated
View File

@ -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",