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
+106
View File
@@ -0,0 +1,106 @@
package transport
import (
"testing"
)
func TestKnockForMinuteDeterministicAndMinuteSensitive(t *testing.T) {
var k [32]byte
for i := range k {
k[i] = byte(i)
}
a := KnockForMinute(k, 1_000_000)
b := KnockForMinute(k, 1_000_000)
if a != b {
t.Fatalf("same inputs gave different output: %x vs %x", a, b)
}
c := KnockForMinute(k, 1_000_001)
if a == c {
t.Fatalf("different minute gave same output: %x", c)
}
var k2 [32]byte
copy(k2[:], k[:])
k2[0] ^= 1
d := KnockForMinute(k2, 1_000_000)
if a == d {
t.Fatalf("different key gave same output: %x", d)
}
}
func TestReorderBufferDeliversInSequenceOrder(t *testing.T) {
a := newHSAdapter(nil, DefaultOptions())
// Direct manipulation of the adapter's reorder buffer mimicking the Rust unit test
// `reorder_buffer_delivers_in_sequence_order`.
a.acceptIncoming(2, []byte("ccc"))
a.acceptIncoming(1, []byte("bbb"))
if len(a.ready) != 0 {
t.Fatalf("contiguous run unexpectedly emitted: %x", a.ready)
}
a.acceptIncoming(0, []byte("aaa"))
if string(a.ready) != "aaabbbccc" {
t.Fatalf("delivery order wrong: %s", a.ready)
}
if a.nextDeliverSeq != 3 {
t.Fatalf("contig counter wrong: %d", a.nextDeliverSeq)
}
}
func TestDuplicateDatagramsAreDropped(t *testing.T) {
a := newHSAdapter(nil, DefaultOptions())
a.acceptIncoming(0, []byte("x"))
a.acceptIncoming(0, []byte("x"))
if string(a.ready) != "x" {
t.Fatalf("duplicate retransmit double-counted: %s", a.ready)
}
a.acceptIncoming(2, []byte("z"))
a.acceptIncoming(2, []byte("z"))
a.acceptIncoming(1, []byte("y"))
if string(a.ready) != "xyz" {
t.Fatalf("delivery wrong with duplicates: %s", a.ready)
}
}
func TestAckUptoReportsHighestContiguousOrSentinel(t *testing.T) {
a := newHSAdapter(nil, DefaultOptions())
if a.ackUpto() != ackNone {
t.Fatalf("initial ack not sentinel: 0x%04X", a.ackUpto())
}
a.acceptIncoming(0, []byte("a"))
if a.ackUpto() != 0 {
t.Fatalf("after seq 0: %d", a.ackUpto())
}
a.acceptIncoming(2, []byte("c"))
if a.ackUpto() != 0 {
t.Fatalf("gap should not advance ack: %d", a.ackUpto())
}
a.acceptIncoming(1, []byte("b"))
if a.ackUpto() != 2 {
t.Fatalf("filling gap should advance: %d", a.ackUpto())
}
}
func TestPruneAckedIsCumulativeAndRespectsSentinel(t *testing.T) {
a := newHSAdapter(nil, DefaultOptions())
a.unacked[0] = []byte{0}
a.unacked[1] = []byte{1}
a.unacked[2] = []byte{2}
a.pruneAcked(ackNone)
if len(a.unacked) != 3 {
t.Fatalf("sentinel should prune nothing, got %d", len(a.unacked))
}
a.pruneAcked(1)
if _, ok := a.unacked[0]; ok {
t.Fatal("seq 0 should be pruned")
}
if _, ok := a.unacked[1]; ok {
t.Fatal("seq 1 should be pruned")
}
if _, ok := a.unacked[2]; !ok {
t.Fatal("seq 2 should remain")
}
a.pruneAcked(2)
if len(a.unacked) != 0 {
t.Fatalf("should be empty: %d", len(a.unacked))
}
}