feat(singbox-aura,tools): Go port of Aura UDP client + KAT bridge to Rust

Lays the foundation for sing-box mobile clients (Option B from
docs/sing-box.md): an independent Go module that speaks the AuraVPN wire
protocol byte-for-byte. Proof of equivalence is in KAT tests cross-loaded
from a Rust-side deterministic vector exporter.

- tools/export-kat (new Rust bin in workspace): captures a handshake +
  derived keys + a sealed datagram record + a knock token using seeded
  RNGs (rand::rngs::StdRng + ml-kem's *_deterministic public API), emits
  JSON. Reproducible byte-for-byte.
- singbox-aura/ (new Go module, ~3000 LOC, 22 files):
  - aura/frame: 5-byte protocol header + Frame{Data,Ping,Pong,Close,
    Control} + magic envelope (0xAA,0xAA,0xC0,0x01) — encode/decode
    matching aura-proto::frame.
  - aura/crypto: hybrid X25519 + ML-KEM-768 (stdlib crypto/ecdh +
    crypto/mlkem on Go 1.24+; falls back to circl on older Go via a
    documented swap), HKDF-SHA256 derive_session_keys, ChaCha20-Poly1305
    with the **LE(u64 counter) || [0;4]** nonce scheme that matches
    aura-crypto::AeadKey/AeadSession.
  - aura/handshake: client_handshake state machine reproducing protocol.md
    §6.2 exactly (CH→SH→ServerAuth→ClientAuth→Finished×2; transcript hash;
    ECDSA-P256 transcript signature; HMAC-SHA256 Finished).
  - aura/session: DatagramSender/Receiver + 64-wide sliding replay window.
  - aura/transport: reliable HS-adapter (DTLS-flight retransmit) + UDP
    datagram data path + 16-byte HMAC port-knock with ±1-minute window.
  - aura/outbound: sing-box-shaped shim (interface signatures only — sing-
    box upstream registration is one more step, documented in README).
  - cmd/aura-client: standalone Go binary; reads client.toml via
    pelletier/go-toml/v2 and connects to a real aura server. Validates
    end-to-end interop with the Rust side.
- KAT: 6 comparisons against Rust vectors — session_keys (HKDF), hybrid
  KEM ek/encaps roundtrip, c2s + s2c Finished HMAC, sealed datagram
  record at seq=2 (incl. 16-byte Poly1305 tag), knock token. All byte-
  for-byte.

Go: 29 tests across 5 packages, all green. Only deps: golang.org/x/crypto
and pelletier/go-toml/v2. Rust: 293 tests still green; tools/export-kat
added to workspace members.

v1 limits documented in singbox-aura/README.md: UDP-only (no TCP/QUIC
fallback yet), no cell padding / cover traffic, no relay/exit role, no
multi-hop, sing-box upstream-registration sketch (vendor sagernet/sing-box +
init() RegisterOutbound) for follow-up.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
xah30
2026-05-27 21:14:23 +03:00
parent 5ea643a9e5
commit a070da0be9
26 changed files with 3425 additions and 0 deletions
+68
View File
@@ -0,0 +1,68 @@
package frame
import (
"encoding/binary"
"fmt"
)
// ControlEnvelopeMagic is the 4-byte prefix marking a v2 control message multiplexed through the
// PacketConnection's send_packet path. An IPv4 packet's first byte is 0x4X and an IPv6 packet's
// first byte is 0x6X, so this magic (starting with 0xAA) never collides with a real IP packet.
var ControlEnvelopeMagic = [4]byte{0xAA, 0xAA, 0xC0, 0x01}
// ControlKind is the on-wire byte selector inside a control envelope.
type ControlKind byte
// Known control kinds (must match crates/aura-proto/src/frame.rs ControlKind).
const (
ControlCrlPush ControlKind = 0x01
ControlCrlAck ControlKind = 0x02
ControlExtendBridge ControlKind = 0x03
ControlCircuitReady ControlKind = 0x04
ControlCircuitFailed ControlKind = 0x05
)
// EncodeControlEnvelope wraps (kind, payload) as
//
// MAGIC(4) || kind(u8) || u32_be(payload_len) || payload
//
// suitable for shipping through PacketConnection.SendPacket.
func EncodeControlEnvelope(kind ControlKind, payload []byte) []byte {
out := make([]byte, 0, len(ControlEnvelopeMagic)+1+4+len(payload))
out = append(out, ControlEnvelopeMagic[:]...)
out = append(out, byte(kind))
var lb [4]byte
binary.BigEndian.PutUint32(lb[:], uint32(len(payload)))
out = append(out, lb[:]...)
out = append(out, payload...)
return out
}
// DecodeControlEnvelope returns (kind, payload, true, nil) if buf starts with the magic and
// parses cleanly. If buf does NOT start with the magic (i.e. it is a normal IP packet) the third
// return is false and the error is nil. A malformed envelope (truncated) returns an error.
func DecodeControlEnvelope(buf []byte) (ControlKind, []byte, bool, error) {
if len(buf) < len(ControlEnvelopeMagic) {
return 0, nil, false, nil
}
for i, b := range ControlEnvelopeMagic {
if buf[i] != b {
return 0, nil, false, nil
}
}
rest := buf[len(ControlEnvelopeMagic):]
if len(rest) < 1 {
return 0, nil, true, fmt.Errorf("%w: control envelope: missing kind", ErrMalformedFrame)
}
kind := ControlKind(rest[0])
if len(rest) < 5 {
return 0, nil, true, fmt.Errorf("%w: control envelope: missing payload length", ErrMalformedFrame)
}
plen := int(binary.BigEndian.Uint32(rest[1:5]))
if len(rest) < 5+plen {
return 0, nil, true, fmt.Errorf("%w: control envelope: truncated payload", ErrMalformedFrame)
}
payload := make([]byte, plen)
copy(payload, rest[5:5+plen])
return kind, payload, true, nil
}