7.0 KiB

Raw Blame History

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.

Development Setup
Project Structure
Branch Strategy
Development Workflow
Commit Message Conventions
Coding Guidelines
Submitting Pull Requests
Security Vulnerabilities

Development Setup

To build and test OSTP locally, you will need:

Rust Toolchain (1.75+): Install via rustup.
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

Clone the repository:

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

Build the entire Cargo workspace:
```
cargo build
```
ostp-control (the web panel) is only needed if you're working on it specifically — the server build embeds a dummy dist/ via rust-embed otherwise, so this step is not required for day-to-day core/client/server work. If you are touching the panel:
```
cd ostp-control && npm install && npm run build && cd ..
```
Run tests:
```
cargo test --workspace
```

Project Structure

The repository is organized as a Cargo workspace containing the following crates:

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/: Client implementations, including SOCKS5/HTTP local proxies, the native OSTP TUN interface routing, and split-tunneling bypass mechanisms.
ostp-server/: Server logic, session dispatcher, anti-probing fallback server proxying, access key database, and the REST API for control panel communication.
ostp-control/: A modern web dashboard for server administration (user management, real-time metrics, bandwidth limits).
ostp-gui/: Tauri-based desktop GUI application for Windows and Linux.
ostp-flutter/: Mobile client code for Android platforms.

Branch Strategy

The repository runs three long-lived branches, in increasing order of stability:

Branch	Role
`nightly`	Active development. All feature work and fixes land here first.
`pre-release`	Periodically fast-forwarded from `nightly` once it's had some soak time. Ships as the `{version}-beta` release channel.
`master`	Fast-forwarded from `pre-release` when it's proven stable. Real, tagged releases (`vX.Y.Z`) are cut from here.

pre-release and master are never committed to directly — they only ever move forward by fast-forwarding from the branch below them. This means promotion is always a plain git merge with zero conflicts by construction: don't git merge/rebase feature work directly onto pre-release or master.

Contributor PRs target nightly, not master.

Development Workflow

Check for existing issues or open a new one to discuss proposed changes before starting work.

Fork the repository and create a new branch from nightly:

git checkout nightly
git checkout -b feat/your-feature-name

Implement your changes, ensuring you write appropriate unit or integration tests.
Format your code:
```
cargo fmt --all
```

Run linter checks:

cargo clippy --workspace --all-targets -- -D warnings

Ensure all tests pass:
```
cargo test --workspace
```

Commit Message Conventions

<type>(<scope>): <short, imperative summary>

<optional body — explain WHY, not what; the diff already shows what changed>

Type — one of: feat (new capability), fix (bug fix), docs, refactor (no behavior change), perf, test, chore (deps/tooling/version bumps), ci, security.
Scope (optional) — the crate or area touched: client, server, core, gui, flutter, ci, docs, etc. e.g. fix(client): ....
Summary — imperative mood ("add", not "added"/"adds"), no trailing period, ideally under ~70 characters.
Body — only when the why isn't obvious from the diff: a prior bug this fixes, a constraint that shaped the approach, a tradeoff you made. Don't restate what the diff already shows. Wrap at ~72 columns.

fix(server): drop junk frames by per-key marker instead of a global one

A fixed 4-byte marker on every junk packet is itself a DPI signature any
observer can filter on across every OSTP deployment. Derive the marker
from the access key (HKDF, same scheme as obfuscation_key/psk) so it's
per-user and indistinguishable from the packet's own random payload.

Multiple unrelated changes belong in separate commits, not one bundled commit — it keeps git bisect and review useful. Squash-merge is fine for a PR with a few "fix typo" / "address review" commits, but don't squash logically distinct changes together.

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

Push your branch to your GitHub fork:
```
git push origin feat/your-feature-name
```
Open a Pull Request (PR) targeting the nightly branch (see Branch Strategy — master only receives fast-forwards from pre-release, never direct PRs).
In your PR description, explain the rationale behind your changes, what was fixed/added, and how it was tested.
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. We will coordinate a swift disclosure and fix.

7.0 KiB Raw Blame History