elmprodvpn/docs/phase-e/E5_SINGBOX_PROTOCOLS_MATRIX.md

# E5 SingBox Protocols Matrix (Desktop-first)

Дата: 2026-03-08  
Статус: active  
Владелец: Engineering  
Цель: зафиксировать поля подключения до реализации форм протоколов в GUI.

## 1) Источники (primary)
- Outbound overview: https://sing-box.sagernet.org/configuration/outbound/
- VLESS: https://sing-box.sagernet.org/configuration/outbound/vless/
- Trojan: https://sing-box.sagernet.org/configuration/outbound/trojan/
- Shadowsocks: https://sing-box.sagernet.org/configuration/outbound/shadowsocks/
- WireGuard: https://sing-box.sagernet.org/configuration/outbound/wireguard/
- Hysteria2: https://sing-box.sagernet.org/configuration/outbound/hysteria2/
- TUIC: https://sing-box.sagernet.org/configuration/outbound/tuic/
- Shared TLS: https://sing-box.sagernet.org/configuration/shared/tls/
- Shared V2Ray transport: https://sing-box.sagernet.org/configuration/shared/v2ray-transport/
- Shared Dial fields: https://sing-box.sagernet.org/configuration/shared/dial/
- Multiplex: https://sing-box.sagernet.org/configuration/shared/multiplex/
- UDP over TCP: https://sing-box.sagernet.org/configuration/shared/udp-over-tcp/

## 2) Фрейм реализации
- Target: `sing-box >= 1.12.x` (текущий runtime у нас `1.12.12`).
- UI-стратегия:
  - `MVP`: критичные поля подключения.
  - `Advanced`: дополнительные tuning-поля.
  - `Raw-only`: редкие/экзотические поля, остаются в raw JSON режиме.

---

## 3) Общие блоки (для большинства outbound)

### 3.1 Базовые outbound-поля

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.type` | enum/string | yes | MVP | фиксируется выбранным протоколом |
| `outbound.tag` | string | yes | MVP | стабильный id карточки |
| `outbound.detour` | string | no | Advanced | цепочка через другой outbound |

### 3.2 Shared Dial fields (ядро соединения)

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.server` | string | yes | MVP | hostname/IP сервера |
| `outbound.server_port` | int | yes | MVP | 1..65535 |
| `outbound.network` | enum | no | MVP | `tcp|udp` (по протоколу) |
| `outbound.connect_timeout` | duration | no | Advanced | таймаут dial |
| `outbound.tcp_fast_open` | bool | no | Advanced | TCP Fast Open |
| `outbound.tcp_multi_path` | bool | no | Advanced | MPTCP (если поддерживается) |
| `outbound.udp_fragment` | bool | no | Advanced | UDP fragmentation |
| `outbound.domain_resolver` | string/object | no | Advanced | используется с новым DNS-форматом |
| `outbound.bind_interface` | string | no | Advanced | привязка к интерфейсу |
| `outbound.routing_mark` | int | no | Advanced | fwmark для выхода |

### 3.3 Shared TLS/Reality блок (где применимо)

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.tls.enabled` | bool | depends | MVP | must be `true` для Reality |
| `outbound.tls.server_name` | string | depends | MVP | SNI |
| `outbound.tls.insecure` | bool | no | Advanced | skip verify |
| `outbound.tls.alpn` | []string | no | Advanced | ALPN list |
| `outbound.tls.utls.enabled` | bool | no | Advanced | uTLS toggle |
| `outbound.tls.utls.fingerprint` | enum/string | no | MVP | для Reality-сценариев обычно обязательно |
| `outbound.tls.reality.enabled` | bool | depends | MVP | Reality mode |
| `outbound.tls.reality.public_key` | string | depends | MVP | Reality PBK |
| `outbound.tls.reality.short_id` | string | no | MVP | Reality SID |

### 3.4 Shared V2Ray transport блок (где применимо)

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.transport.type` | enum/string | no | MVP | `ws|http|grpc|quic|httpupgrade|...` |
| `outbound.transport.path` | string | depends | MVP | чаще для `ws/http/httpupgrade` |
| `outbound.transport.host` | string/[]string | depends | Advanced | Host header/SNI-like values |
| `outbound.transport.service_name` | string | depends | MVP | обычно для `grpc` |
| `outbound.transport.headers` | object | no | Advanced | custom headers |

### 3.5 Shared Multiplex / UDP-over-TCP (где применимо)

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.multiplex` | object | no | Advanced | pooling/stream mux |
| `outbound.udp_over_tcp` | object | no | Advanced | туннелирование UDP через TCP |

---

## 4) Протокольные матрицы

## 4.1 VLESS outbound

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.type` | const `vless` | yes | MVP | |
| `outbound.server` | string | yes | MVP | |
| `outbound.server_port` | int | yes | MVP | |
| `outbound.uuid` | string | yes | MVP | UUID |
| `outbound.flow` | string | no | MVP | напр. `xtls-rprx-vision` |
| `outbound.packet_encoding` | enum/string | no | Advanced | с `1.11` default `none` |
| `outbound.network` | enum | no | MVP | |
| `outbound.tls` | object | depends | MVP | TLS/Reality для production-сценариев |
| `outbound.transport` | object | no | MVP | V2Ray transport block |

Guardrails:
- `VLESS-001`: если `tls.reality.enabled=true` -> `tls.enabled=true`.
- `VLESS-002`: если `flow=xtls-rprx-vision` -> transport должен быть совместим с сервером и TLS включён.

## 4.2 Trojan outbound

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.type` | const `trojan` | yes | MVP | |
| `outbound.server` | string | yes | MVP | |
| `outbound.server_port` | int | yes | MVP | |
| `outbound.password` | string | yes | MVP | secret |
| `outbound.network` | enum | no | MVP | |
| `outbound.tls` | object | yes (обычно) | MVP | TLS-блок |
| `outbound.transport` | object | no | MVP | V2Ray transport |

Guardrails:
- `TRJ-001`: пустой `password` блокирует apply.
- `TRJ-002`: без TLS для стандартного trojan-сервера помечать как risky.

## 4.3 Shadowsocks outbound

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.type` | const `shadowsocks` | yes | MVP | |
| `outbound.server` | string | yes | MVP | |
| `outbound.server_port` | int | yes | MVP | |
| `outbound.method` | enum/string | yes | MVP | cipher method |
| `outbound.password` | string | yes | MVP | secret |
| `outbound.plugin` | string | no | Advanced | SIP003 plugin |
| `outbound.plugin_opts` | string | no | Advanced | plugin options |
| `outbound.network` | enum | no | Advanced | |
| `outbound.udp_over_tcp` | object | no | Advanced | shared UDP-over-TCP fields |
| `outbound.multiplex` | object | no | Advanced | shared multiplex fields |

Guardrails:
- `SS-001`: `method` обязателен и валидируется против поддерживаемых cipher.
- `SS-002`: если `plugin` задан, но `plugin_opts` пуст и plugin его требует -> warning/block.

## 4.4 WireGuard outbound

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.type` | const `wireguard` | yes | MVP | |
| `outbound.server` | string | depends | MVP | при single-peer setup |
| `outbound.server_port` | int | depends | MVP | |
| `outbound.system_interface` | bool | no | Advanced | |
| `outbound.interface_name` | string | deprecated | Raw-only | deprecated с `1.11` |
| `outbound.local_address` | []string | yes | MVP | local tunnel address(es) |
| `outbound.private_key` | string | yes | MVP | secret |
| `outbound.peer_public_key` | string | depends | MVP | single-peer |
| `outbound.pre_shared_key` | string | no | Advanced | secret |
| `outbound.reserved` | []int | no | Advanced | |
| `outbound.workers` | int | no | Advanced | |
| `outbound.mtu` | int | no | Advanced | |
| `outbound.network` | enum | no | Advanced | |
| `outbound.peers` | []object | depends | Advanced | multi-peer schema |
| `outbound.peer_allowed_ips` | []string | no | Advanced | |
| `outbound.packet_encoding` | enum/string | no | Advanced | |

Guardrails:
- `WG-001`: `private_key` обязателен.
- `WG-002`: нужен или `peer_public_key` (single) или `peers[]` (multi).

## 4.5 Hysteria2 outbound

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.type` | const `hysteria2` | yes | MVP | |
| `outbound.server` | string | yes | MVP | |
| `outbound.server_port` | int | yes | MVP | |
| `outbound.up_mbps` | int | no | MVP | upload bandwidth hint |
| `outbound.down_mbps` | int | no | MVP | download bandwidth hint |
| `outbound.obfs` | string | no | Advanced | obfuscation method |
| `outbound.obfs_password` | string | depends | Advanced | secret |
| `outbound.password` | string | depends | MVP | auth password |
| `outbound.network` | enum | no | Advanced | |
| `outbound.tls` | object | yes (обычно) | MVP | TLS block |
| `outbound.brutal_debug` | bool | no | Raw-only | debug option |

Guardrails:
- `HY2-001`: если задан `obfs`, то `obfs_password` обязателен.
- `HY2-002`: пустой `password` при password-auth конфиге блокирует apply.

## 4.6 TUIC outbound

| JSON path | Type | Required | UI level | Notes |
|---|---|---|---|---|
| `outbound.type` | const `tuic` | yes | MVP | |
| `outbound.server` | string | yes | MVP | |
| `outbound.server_port` | int | yes | MVP | |
| `outbound.uuid` | string | yes | MVP | auth uuid |
| `outbound.password` | string | yes | MVP | secret |
| `outbound.congestion_control` | enum/string | no | Advanced | algo |
| `outbound.udp_relay_mode` | enum/string | no | Advanced | relay mode |
| `outbound.udp_over_stream` | bool | no | Advanced | |
| `outbound.zero_rtt_handshake` | bool | no | Raw-only | advanced/risky |
| `outbound.heartbeat` | duration/int | no | Raw-only | keepalive tuning |
| `outbound.network` | enum | no | Advanced | |
| `outbound.tls` | object | yes (обычно) | MVP | TLS block |

Guardrails:
- `TUIC-001`: `uuid` и `password` обязательны.
- `TUIC-002`: `zero_rtt_handshake=true` помечать warning (опция совместимости/риска).

---

## 5) Срез MVP полей для первой версии GUI
- `VLESS`: `server`, `server_port`, `uuid`, `flow`, `tls.server_name`, `tls.reality.public_key`, `tls.reality.short_id`, `tls.utls.fingerprint`.
- `Trojan`: `server`, `server_port`, `password`, `tls.server_name`.
- `Shadowsocks`: `server`, `server_port`, `method`, `password`.
- `WireGuard`: `server`, `server_port`, `local_address`, `private_key`, `peer_public_key`.
- `Hysteria2`: `server`, `server_port`, `password`, `up_mbps`, `down_mbps`.
- `TUIC`: `server`, `server_port`, `uuid`, `password`, `congestion_control`.

Все остальные поля:
- либо в секции `Advanced`,
- либо в `Raw JSON` (без потери функциональности).

## 6) DoD для этапа "матрица готова"
- Шаблон и матрица лежат в `docs/phase-e`.
- Для каждого протокола есть список MVP/Advanced/Raw-only полей.
- Для каждого протокола есть минимум 2 guardrail-правила валидации.
- Есть machine-readable манифест для последующей генерации форм.