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>

singbox-aura/aura/session/replay.go

@@ -0,0 +1,70 @@
+// Package session provides the post-handshake AEAD-protected Frame exchange and the sliding
+// replay window — direct port of crates/aura-proto/src/session.rs.
+package session
+
+import "fmt"
+
+// ReplayWindow is the width (in records) of the anti-replay sliding window.
+const ReplayWindow uint64 = 64
+
+// ErrReplay is returned when a record's sequence number is a duplicate or too old.
+type ErrReplay struct{ Seq uint64 }
+
+func (e *ErrReplay) Error() string { return fmt.Sprintf("aura/session: replay seq=%d", e.Seq) }
+
+// Replay tracks the highest accepted sequence number and a 64-bit bitmap of the positions
+// below it that have already been accepted. A datagram is accepted iff its seq is strictly
+// newer than everything seen, or falls inside the window and was not previously seen.
+type Replay struct {
+	highest uint64
+	bitmap  uint64
+	seeded  bool
+}
+
+// NewReplay primes a window so the first expected record is `start` (the AEAD counter at the
+// end of the handshake). Anything strictly below `start` is treated as already-consumed.
+//
+// This mirrors ReplayWindow::new in the Rust impl: highest = start - 1 (saturating),
+// seeded = start > 0.
+func NewReplay(start uint64) *Replay {
+	r := &Replay{seeded: start > 0}
+	if start > 0 {
+		r.highest = start - 1
+	}
+	return r
+}
+
+// CheckAndSet records a seen seq. Returns nil if it is fresh; *ErrReplay otherwise.
+func (r *Replay) CheckAndSet(seq uint64) error {
+	if !r.seeded {
+		// First-ever record (only reachable when started at 0): accept and seed.
+		r.seeded = true
+		r.highest = seq
+		r.bitmap = 0
+		return nil
+	}
+	if seq > r.highest {
+		shift := seq - r.highest
+		if shift >= 64 {
+			r.bitmap = 0
+		} else {
+			r.bitmap = (r.bitmap << shift) | (1 << (shift - 1))
+		}
+		r.highest = seq
+		return nil
+	}
+	// seq <= highest: must be inside the window and previously unseen.
+	offset := r.highest - seq
+	if offset >= ReplayWindow {
+		return &ErrReplay{Seq: seq}
+	}
+	if offset == 0 {
+		return &ErrReplay{Seq: seq}
+	}
+	mask := uint64(1) << (offset - 1)
+	if r.bitmap&mask != 0 {
+		return &ErrReplay{Seq: seq}
+	}
+	r.bitmap |= mask
+	return nil
+}

singbox-aura/aura/session/session.go

@@ -0,0 +1,88 @@
+package session
+
+import (
+	"encoding/binary"
+	"errors"
+	"fmt"
+
+	"github.com/aura/singbox-aura/aura/crypto"
+	"github.com/aura/singbox-aura/aura/frame"
+)
+
+// SeqLen is the size of the per-record sequence-number prefix.
+const SeqLen = 8
+
+// PostHandshakeCounter is the AEAD counter at which the first application Data record starts,
+// because each direction sealed exactly two encrypted handshake messages before it.
+const PostHandshakeCounter uint64 = 2
+
+// DatagramSender holds the outbound explicit-nonce AEAD plus the next sequence number to
+// stamp. Produced by Session.IntoDatagramParts() after the handshake completes.
+type DatagramSender struct {
+	key *crypto.AeadKey
+	seq uint64
+}
+
+// NewDatagramSender wraps a 32-byte key starting at the given counter.
+func NewDatagramSender(rawKey []byte, startCounter uint64) (*DatagramSender, error) {
+	k, err := crypto.NewAeadKey(rawKey)
+	if err != nil {
+		return nil, err
+	}
+	return &DatagramSender{key: k, seq: startCounter}, nil
+}
+
+// Seal encodes f, seals it under the next sequence number, and returns the on-wire datagram
+// payload: seq(8 BE) || ciphertext.
+func (s *DatagramSender) Seal(f *frame.Frame) []byte {
+	seq := s.seq
+	enc := frame.EncodeFrame(f)
+	var seqBE [SeqLen]byte
+	binary.BigEndian.PutUint64(seqBE[:], seq)
+	ct := s.key.Seal(seq, enc, seqBE[:])
+	out := make([]byte, 0, SeqLen+len(ct))
+	out = append(out, seqBE[:]...)
+	out = append(out, ct...)
+	s.seq++
+	return out
+}
+
+// NextSeq is the sequence number the next Seal will use (test/diagnostic helper).
+func (s *DatagramSender) NextSeq() uint64 { return s.seq }
+
+// DatagramReceiver authenticates, replay-checks, and decodes incoming datagram payloads.
+type DatagramReceiver struct {
+	key    *crypto.AeadKey
+	replay *Replay
+}
+
+// NewDatagramReceiver wraps a 32-byte key plus a replay window primed at startCounter.
+func NewDatagramReceiver(rawKey []byte, startCounter uint64) (*DatagramReceiver, error) {
+	k, err := crypto.NewAeadKey(rawKey)
+	if err != nil {
+		return nil, err
+	}
+	return &DatagramReceiver{key: k, replay: NewReplay(startCounter)}, nil
+}
+
+// Open parses one datagram payload, runs the replay check first (so a duplicate cannot advance
+// the AEAD state), then verifies and decodes the inner Frame.
+func (r *DatagramReceiver) Open(datagram []byte) (*frame.Frame, error) {
+	if len(datagram) < SeqLen {
+		return nil, fmt.Errorf("aura/session: datagram shorter than seq prefix")
+	}
+	seqBE := datagram[:SeqLen]
+	seq := binary.BigEndian.Uint64(seqBE)
+	ct := datagram[SeqLen:]
+	if err := r.replay.CheckAndSet(seq); err != nil {
+		return nil, err
+	}
+	pt, err := r.key.Open(seq, ct, seqBE)
+	if err != nil {
+		return nil, err
+	}
+	return frame.DecodeFrame(pt)
+}
+
+// ErrUnexpectedMsg is returned by the stream half when the wire carries a non-Data record.
+var ErrUnexpectedMsg = errors.New("aura/session: unexpected message type")

singbox-aura/aura/session/session_test.go

@@ -0,0 +1,123 @@
+package session
+
+import (
+	"bytes"
+	"errors"
+	"testing"
+
+	"github.com/aura/singbox-aura/aura/frame"
+)
+
+func TestReplayWindowBasicMonotonic(t *testing.T) {
+	w := NewReplay(2)
+	for _, s := range []uint64{2, 3, 4} {
+		if err := w.CheckAndSet(s); err != nil {
+			t.Fatalf("seq %d: unexpected %v", s, err)
+		}
+	}
+	for _, s := range []uint64{2, 3, 4} {
+		var e *ErrReplay
+		if err := w.CheckAndSet(s); !errors.As(err, &e) {
+			t.Fatalf("seq %d: want replay, got %v", s, err)
+		}
+	}
+}
+
+func TestReplayWindowOutOfOrderWithinWindow(t *testing.T) {
+	w := NewReplay(0)
+	if err := w.CheckAndSet(0); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.CheckAndSet(10); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.CheckAndSet(5); err != nil {
+		t.Fatalf("5 inside window: %v", err)
+	}
+	if err := w.CheckAndSet(5); err == nil {
+		t.Fatal("replay of 5 must be rejected")
+	}
+	if err := w.CheckAndSet(10); err == nil {
+		t.Fatal("replay of 10 must be rejected")
+	}
+	if err := w.CheckAndSet(11); err != nil {
+		t.Fatalf("new high 11: %v", err)
+	}
+}
+
+func TestReplayWindowRejectsTooOld(t *testing.T) {
+	w := NewReplay(0)
+	if err := w.CheckAndSet(0); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.CheckAndSet(200); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.CheckAndSet(1); err == nil {
+		t.Fatal("far below window must be rejected")
+	}
+	if err := w.CheckAndSet(200 - ReplayWindow); err == nil {
+		t.Fatal("at the floor of the window must be rejected")
+	}
+	if err := w.CheckAndSet(200 - ReplayWindow + 1); err != nil {
+		t.Fatalf("just inside window: %v", err)
+	}
+}
+
+func TestDatagramRoundtripReorderAndReplay(t *testing.T) {
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = 11
+	}
+	tx, err := NewDatagramSender(key, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rx, err := NewDatagramReceiver(key, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	d0 := tx.Seal(&frame.Frame{Kind: frame.FrameData, StreamID: 0, Payload: []byte("pkt-a")})
+	d1 := tx.Seal(&frame.Frame{Kind: frame.FrameData, StreamID: 0, Payload: []byte("pkt-b")})
+
+	// Out-of-order delivery within the window.
+	gotB, err := rx.Open(d1)
+	if err != nil {
+		t.Fatalf("open d1: %v", err)
+	}
+	if gotB.Kind != frame.FrameData || string(gotB.Payload) != "pkt-b" {
+		t.Fatalf("d1: %+v", gotB)
+	}
+	gotA, err := rx.Open(d0)
+	if err != nil {
+		t.Fatalf("open d0: %v", err)
+	}
+	if string(gotA.Payload) != "pkt-a" {
+		t.Fatalf("d0: %+v", gotA)
+	}
+
+	if _, err := rx.Open(d1); err == nil {
+		t.Fatal("replay of d1 must be rejected")
+	}
+
+	bad := tx.Seal(&frame.Frame{Kind: frame.FramePing, Seq: 7})
+	bad[len(bad)-1] ^= 1
+	if _, err := rx.Open(bad); err == nil {
+		t.Fatal("tampered ciphertext must fail")
+	}
+}
+
+func TestSenderNextSeqAdvances(t *testing.T) {
+	tx, err := NewDatagramSender(bytes.Repeat([]byte{1}, 32), 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if tx.NextSeq() != 2 {
+		t.Fatalf("initial next seq %d", tx.NextSeq())
+	}
+	_ = tx.Seal(&frame.Frame{Kind: frame.FramePing, Seq: 1})
+	if tx.NextSeq() != 3 {
+		t.Fatalf("after seal: %d", tx.NextSeq())
+	}
+}