# Интеграция AuraVPN с sing-box (план)

Цель: дать клиенту на телефоне, работающему под **sing-box**, возможность подключиться к серверу
Aura по протоколу **AuraVPN** (это собственное туннелирование Aura, не сторонний протокол). Это
короткая заметка о том, *как* это сделать; сам wire-протокол, который должна повторять реализация,
полностью описан в [`protocol.md`](protocol.md).

sing-box написан на Go, и в нём нет универсального плагина «загрузить произвольный внешний wire-
протокол», поэтому интеграция означает дать sing-box Go-реализацию (или мост) протокола Aura. Три
реалистичных пути, от самого дешёвого:

## Option A — Process bridge (быстрее всего, для десктопа/сервера)

Запустить существующий Rust-клиент `aura` как локальный процесс и выставить локальный
прокси/TUN, а затем направить sing-box на него:

- `aura client` уже создаёт TUN и направляет туда трафик через туннель Aura; sing-box может
  заворачивать выбранный трафик в этот интерфейс, **или**
- добавить в `aura-cli` локальный **SOCKS5 inbound** (небольшое дополнение) и настроить в
  sing-box `socks` outbound на `127.0.0.1:<port>`.

Плюсы: переиспользует прошедшую аудит Rust-сердцевину дословно; нет переписывания криптографии.
Минусы: два процесса; плохо ложится на мобильные платформы (мобильные приложения sing-box
встраивают ядро и не умеют легко запускать вспомогательные процессы).

## Option B — Нативный Go-outbound/inbound (целевой путь для телефонов)

Реализовать протокол AuraVPN на Go нативно и зарегистрировать его как sing-box **outbound**
(клиент) и **inbound** (сервер), чтобы встроенное в телефон ядро sing-box само говорило на
AuraVPN. Это чистый, производительный и mobile-friendly путь. Криптография чисто ложится на
существующие Go-библиотеки:

| Компонент Aura                  | Rust-крейт          | Эквивалент в Go                                         |
|--------------------------------|---------------------|---------------------------------------------------------|
| X25519 ECDH                    | `x25519-dalek`      | `crypto/ecdh` (stdlib)                                  |
| ML-KEM-768 (FIPS 203)          | `ml-kem`            | `crypto/mlkem` (Go 1.24+) или `cloudflare/circl`        |
| ChaCha20-Poly1305              | `chacha20poly1305`  | `golang.org/x/crypto/chacha20poly1305`                  |
| HKDF-SHA256                    | `hkdf`              | `golang.org/x/crypto/hkdf`                              |
| HMAC-SHA256 (Finished)         | `hmac`              | `crypto/hmac` + `crypto/sha256`                         |
| ECDSA P-256 signatures (cert)  | `ring`              | `crypto/ecdsa` + `crypto/x509`                          |
| X.509 verify + CRL             | `rustls-webpki`     | `crypto/x509`                                           |

Что Go-код должен повторить **в точности** (см. `protocol.md`):

- 5-байтный заголовок кадра: `msg_type(1) || len(u24 BE) || version=0x01`.
- Порядок рукопожатия `CH → SH → ServerAuth → ClientAuth → Finished(c→s) → Finished(s→c)`;
  транскрипт = `SHA-256(ClientHello_frame || ServerHello_frame)`; подпись ECDSA-P256/SHA-256 по
  транскрипту; Finished — HMAC-SHA256.
- Гибридный общий секрет = `x25519_ss || mlkem_ss`; salt HKDF = `client_nonce || server_nonce`,
  info = `b"aura-v1-session"`.
- Запись данных (datagram/UDP) = `seq(8 BE) || ChaCha20Poly1305(frame, aad = seq)`, nonce =
  `LE(seq) || 0x00000000`; окно anti-replay — 64. (Stream/TCP-запись дополнительно включает
  5-байтный заголовок в AAD.)
- Выбор транспорта: UDP (тип-байт `0x01` HS / `0x02` DATA) как основной; TCP/443 и QUIC как
  fallback.

Чтобы снизить риск порта в Go, экспортируйте со стороны Rust **known-answer test vectors**
(захваченный транскрипт рукопожатия + производные ключи + запечатанная запись данных) и
утверждайте, что Go-реализация воспроизводит их побайтово. KAT для ML-KEM уже лежит в
`aura-crypto/tests/kat_kyber.rs`.

## Option C — Rust core через cgo (`cdylib`)

Скомпилировать Rust-сердцевину Aura в C-ABI shared library и вызывать её из тонкого Go-shim'а
sing-box через cgo. Переиспользует прошедшую аудит крипто/рукопожатие без Go-переписывания, но
cgo плюс упаковка под каждую платформу (Android/iOS) — занудно и усложняет чисто-Go-сборку
sing-box.

## Рекомендация

- **Сейчас:** Option A (process bridge) для валидации на десктопе/сервере — минимум работы,
  настоящий протокол.
- **Для телефона:** Option B (нативный Go-outbound), написанный по `protocol.md` + по
  экспортированным из Rust тест-векторам. Это единственный вариант, который хорошо ложится на
  встроенное мобильное ядро sing-box.
- Держите `protocol.md` единственным источником истины и версионируйте wire-протокол (заголовок
  уже несёт `version = 0x01`), чтобы Rust- и Go-реализации шли в ногу.

> Статус: это проектная заметка. Go-кода и sing-box-модуля пока **нет** — это отдельный
> deliverable, поставленный в план после стабилизации Rust-транспорта.