# QuatrVPN Protocol Specification (Q4)

Version: 1.0.0

## Overview

Q4 (Quatr fourth-layer) — протокол туннелирования, оптимизированный для сетей с активным DPI
(включая ТСПУ Роскомнадзора). Не изобретает криптографию с нуля: комбинирует проверенные
примитивы (X25519, AES-GCM, ChaCha20-Poly1305) и транспорты sing-box в единый профиль
с согласованными параметрами маскировки.

## Design Goals

| Goal | Mechanism |
|------|-----------|
| Неотличимость от HTTPS | REALITY + uTLS Chrome fingerprint |
| Устойчивость к UDP-блокировкам | Hysteria2 + Salamander obfs |
| Нет фиксированной сигнатуры | Ротация short_id, decoy-доменов |
| Клиенты Android + macOS | sing-box (SFA / SFM) |
| Сервер Ubuntu | sing-box в Docker, Ansible |

## Layer Model

```
┌─────────────────────────────────────────────────────────┐
│ L4 Route — TUN interface, full tunnel 0.0.0.0/0         │
├─────────────────────────────────────────────────────────┤
│ L3 Session — UUID (VLESS) / password (HY2), short_id    │
├─────────────────────────────────────────────────────────┤
│ L2 Transport — TCP Vision | QUIC Hysteria2              │
├─────────────────────────────────────────────────────────┤
│ L1 Camouflage — REALITY handshake to decoy site         │
└─────────────────────────────────────────────────────────┘
```

## L1: Camouflage (REALITY)

Клиент инициирует TLS 1.3 ClientHello с SNI = decoy-домен (например `www.sberbank.ru`).
Сервер QuatrVPN отвечает сертификатом, неотличимым от настоящего (через REALITY handshake
к реальному `handshake.server`).

Параметры:
- `private_key` / `public_key` — X25519 keypair (генерирует `quatr-gen`)
- `short_id` — 0–16 hex символов, идентификатор сервера в REALITY
- `handshake.server` — реальный доступный сайт в РФ (банк, маркетплейс, CDN)

DPI видит: обычный TLS к популярному российскому ресурсу.

## L2: Transport

### Primary: VLESS + XTLS-Vision (TCP/443)

- Flow: `xtls-rprx-vision` — снижает утечку метаданных в TLS records
- Multiplex: один TCP-соединение, много потоков

### Fallback: Hysteria2 (UDP/443)

- QUIC transport, ALPN `h3`
- Obfuscation: Salamander (`obfs.type = salamander`)
- Masquerade: HTTP-ответ от decoy URL при зондировании

Клиент переключается на HY2, если TCP REALITY недоступен (блокировка TCP-only).

## L3: Session

| Transport | Credential | Format |
|-----------|------------|--------|
| VLESS REALITY | UUID v4 | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| VLESS REALITY | short_id | 8 hex chars |
| Hysteria2 | password | 32+ random chars |

Ротация: `quatr-gen --rotate` генерирует новые short_id и пароли без смены UUID.

## L4: Route

- Mode: TUN (full tunnel)
- `0.0.0.0/0`, `::/0` — весь трафик через VPN
- DNS: `8.8.8.8`, `1.1.1.1` через туннель (предотвращает DNS-leak)

## Client URI Formats

### VLESS REALITY

```
vless://{uuid}@{server}:443?encryption=none&flow=xtls-rprx-vision&security=reality&sni={decoy}&fp=chrome&pbk={public_key}&sid={short_id}&type=tcp#QuatrVPN
```

### Hysteria2

```
hysteria2://{password}@{server}:443?sni={decoy}&obfs=salamander&obfs-password={obfs_pass}#QuatrVPN-HY2
```

## Anti-Detection Checklist

1. Используйте decoy-домен из топ-1000 Рунета (не `google.com` — подозрительно из РФ).
2. Не публикуйте панель управления на том же IP.
3. Ротируйте `short_id` раз в 30–90 дней.
4. Не используйте стандартные порты VPN (1194, 51820, 8388).
5. Один IP — один протокол; не смешивайте OpenVPN на том же хосте.

## Threat Model

**Защищает от:**
- DPI по сигнатуре протокола (OpenVPN, WireGuard, SS)
- SNI-блокировки по имени VPN-домена
- Active probing простых прокси

**Не защищает от:**
- Блокировки всего IP-адреса сервера
- Корреляционного анализа трафика (timing/volume)
- Компрометации ключей на клиенте

## Reference Implementation

- Engine: [sing-box](https://github.com/SagerNet/sing-box) ≥ 1.12
- Config generator: `tools/quatr-gen`
- Server deploy: `deploy/ansible`