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/crypto/aead.go

@@ -0,0 +1,102 @@
+package crypto
+
+import (
+	"crypto/cipher"
+	"encoding/binary"
+	"fmt"
+
+	"golang.org/x/crypto/chacha20poly1305"
+)
+
+// NonceLen is the AEAD nonce length (96 bits for ChaCha20-Poly1305).
+const NonceLen = 12
+
+// NonceFor reproduces the AeadSession::nonce_for layout exactly:
+//
+//	nonce[0..8]  = LE(u64) counter
+//	nonce[8..12] = 0
+//
+// Both stream- and datagram-mode AEADs share this nonce derivation; the only difference is
+// whether the counter is advanced lock-step (stream) or carried on the wire (datagram).
+func NonceFor(counter uint64) [NonceLen]byte {
+	var n [NonceLen]byte
+	binary.LittleEndian.PutUint64(n[0:8], counter)
+	return n
+}
+
+// AeadKey wraps a 32-byte ChaCha20-Poly1305 key for explicit-nonce datagram use. The caller owns
+// nonce uniqueness — Aura's datagram codec carries the counter on the wire as `seq`.
+type AeadKey struct {
+	aead cipher.AEAD
+}
+
+// NewAeadKey builds an AeadKey from a 32-byte key. Returns an error if the key is the wrong
+// size; ChaCha20-Poly1305 always wants 32.
+func NewAeadKey(key []byte) (*AeadKey, error) {
+	if len(key) != SessionKeyLen {
+		return nil, fmt.Errorf("aead key must be %d bytes, got %d", SessionKeyLen, len(key))
+	}
+	a, err := chacha20poly1305.New(key)
+	if err != nil {
+		return nil, fmt.Errorf("chacha20poly1305.New: %w", err)
+	}
+	return &AeadKey{aead: a}, nil
+}
+
+// Seal encrypts plaintext under the nonce derived from counter, returning ciphertext||tag.
+func (k *AeadKey) Seal(counter uint64, plaintext, aad []byte) []byte {
+	nonce := NonceFor(counter)
+	return k.aead.Seal(nil, nonce[:], plaintext, aad)
+}
+
+// Open authenticates and decrypts ciphertext (which must include the 16-byte Poly1305 tag).
+// Returns the plaintext, or an error on authentication failure.
+func (k *AeadKey) Open(counter uint64, ciphertext, aad []byte) ([]byte, error) {
+	nonce := NonceFor(counter)
+	out, err := k.aead.Open(nil, nonce[:], ciphertext, aad)
+	if err != nil {
+		return nil, fmt.Errorf("aead open: %w", err)
+	}
+	return out, nil
+}
+
+// AeadSession is the stream-mode counterpart: it holds the key plus a monotonically increasing
+// 64-bit counter that advances on every Seal and Open. Used by the handshake's encrypted
+// messages (ServerAuth, ClientAuth, Finished) so the two sides stay in lockstep without putting
+// the counter on the wire.
+type AeadSession struct {
+	key     *AeadKey
+	counter uint64
+}
+
+// NewAeadSession starts a session at counter 0.
+func NewAeadSession(rawKey []byte) (*AeadSession, error) {
+	k, err := NewAeadKey(rawKey)
+	if err != nil {
+		return nil, err
+	}
+	return &AeadSession{key: k, counter: 0}, nil
+}
+
+// Counter is the current counter (the nonce that the next Seal/Open will use). Test-only and
+// used by Session.IntoDatagramParts to hand off the explicit-nonce key.
+func (s *AeadSession) Counter() uint64 { return s.counter }
+
+// Seal seals plaintext at the current counter then advances it.
+func (s *AeadSession) Seal(plaintext, aad []byte) []byte {
+	ct := s.key.Seal(s.counter, plaintext, aad)
+	s.counter++
+	return ct
+}
+
+// Open verifies+decrypts ciphertext at the current counter then advances it (symmetric to Seal
+// so a failed decrypt keeps the two ends aligned).
+func (s *AeadSession) Open(ciphertext, aad []byte) ([]byte, error) {
+	pt, err := s.key.Open(s.counter, ciphertext, aad)
+	s.counter++
+	return pt, err
+}
+
+// IntoKey returns the underlying AeadKey so datagram-mode codecs can continue at the same
+// counter without re-deriving anything (matches Rust's into_parts).
+func (s *AeadSession) IntoKey() *AeadKey { return s.key }

singbox-aura/aura/crypto/crypto_test.go

@@ -0,0 +1,279 @@
+package crypto
+
+import (
+	"bytes"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+// vectorsJSON mirrors the JSON written by tools/export-kat (in Rust). Every field is hex.
+type vectorsJSON struct {
+	CAFingerprint       string `json:"ca_fingerprint"`
+	ClientX25519Priv    string `json:"client_x25519_priv"`
+	ClientX25519Pub     string `json:"client_x25519_pub"`
+	ClientKyberPriv     string `json:"client_kyber_priv"`
+	ClientKyberPub      string `json:"client_kyber_pub"`
+	ServerX25519EphPriv string `json:"server_x25519_eph_priv"`
+	ServerX25519EphPub  string `json:"server_x25519_eph_pub"`
+	ServerKyberCt       string `json:"server_kyber_ct"`
+	ClientNonce         string `json:"client_nonce"`
+	ServerNonce         string `json:"server_nonce"`
+	X25519SS            string `json:"x25519_ss"`
+	KyberSS             string `json:"kyber_ss"`
+	SessionKeys         struct {
+		C2S string `json:"c2s"`
+		S2C string `json:"s2c"`
+	} `json:"session_keys"`
+	TranscriptHash     string `json:"transcript_hash"`
+	ClientFinishedHmac string `json:"client_finished_hmac"`
+	ServerFinishedHmac string `json:"server_finished_hmac"`
+	DatagramTest       struct {
+		Seq          uint64 `json:"seq"`
+		Frame        string `json:"frame"`
+		Key          string `json:"key"`
+		SealedRecord string `json:"sealed_record"`
+	} `json:"datagram_test"`
+	KnockTest struct {
+		CAFingerprint string `json:"ca_fingerprint"`
+		UnixMinute    uint64 `json:"unix_minute"`
+		Knock         string `json:"knock"`
+	} `json:"knock_test"`
+}
+
+// loadVectors finds the vectors file at <module>/kat/vectors.json. The file is created by
+//
+//	cargo run -p export-kat
+//
+// from the workspace root.
+func loadVectors(t *testing.T) *vectorsJSON {
+	t.Helper()
+	// crypto_test.go is at singbox-aura/aura/crypto/. The KAT lives at singbox-aura/kat/.
+	_, thisFile, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("runtime.Caller failed")
+	}
+	path := filepath.Join(filepath.Dir(thisFile), "..", "..", "kat", "vectors.json")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Skipf("KAT vectors.json not present at %s — run `cargo run -p export-kat` first: %v", path, err)
+		return nil
+	}
+	var v vectorsJSON
+	if err := json.Unmarshal(data, &v); err != nil {
+		t.Fatalf("parse vectors.json: %v", err)
+	}
+	return &v
+}
+
+func mustHex(t *testing.T, s string) []byte {
+	t.Helper()
+	b, err := hex.DecodeString(s)
+	if err != nil {
+		t.Fatalf("hex decode %q: %v", s, err)
+	}
+	return b
+}
+
+func mustHex32(t *testing.T, s string) [32]byte {
+	b := mustHex(t, s)
+	if len(b) != 32 {
+		t.Fatalf("want 32 bytes, got %d", len(b))
+	}
+	var out [32]byte
+	copy(out[:], b)
+	return out
+}
+
+// TestKAT_SessionKeys: HKDF-derive from the shared secrets in the vector reproduces the
+// session_keys.{c2s,s2c} byte-for-byte.
+func TestKAT_SessionKeys(t *testing.T) {
+	v := loadVectors(t)
+	if v == nil {
+		return
+	}
+	xss := mustHex32(t, v.X25519SS)
+	kss := mustHex32(t, v.KyberSS)
+	cn := mustHex32(t, v.ClientNonce)
+	sn := mustHex32(t, v.ServerNonce)
+	wantC2S := mustHex(t, v.SessionKeys.C2S)
+	wantS2C := mustHex(t, v.SessionKeys.S2C)
+
+	shared := &HybridSharedSecret{X25519SS: xss, MLKEMSS: kss}
+	keys := DeriveSessionKeys(shared, cn, sn)
+	if !bytes.Equal(keys.ClientToServer[:], wantC2S) {
+		t.Fatalf("c2s mismatch:\n got %x\nwant %x", keys.ClientToServer, wantC2S)
+	}
+	if !bytes.Equal(keys.ServerToClient[:], wantS2C) {
+		t.Fatalf("s2c mismatch:\n got %x\nwant %x", keys.ServerToClient, wantS2C)
+	}
+}
+
+// TestKAT_HybridDecapsulateRoundtrip: load the client's deterministic hybrid key from the
+// vector, then run Decapsulate against the server's ciphertext. The derived shared secrets must
+// match x25519_ss / kyber_ss in the vector.
+func TestKAT_HybridDecapsulateRoundtrip(t *testing.T) {
+	v := loadVectors(t)
+	if v == nil {
+		return
+	}
+	xPriv := mustHex32(t, v.ClientX25519Priv)
+	// We don't ship the ml-kem seed in the JSON directly (the export tool uses a fixed seed and
+	// stores only the expanded private key for diagnostics). Instead, reconstruct from the seed
+	// the export tool documents — match the literal bytes in tools/export-kat/src/main.rs.
+	var seed [64]byte
+	copy(seed[:32], []byte("AURA-MLKEM-DSEED-CLIENT--FIXED32"))
+	copy(seed[32:], []byte("AURA-MLKEM-ZSEED-CLIENT--FIXED32"))
+	priv, pub, err := NewHybridPrivateFromBytes(xPriv, seed)
+	if err != nil {
+		t.Fatalf("rebuild hybrid: %v", err)
+	}
+	// Sanity: the recomputed encapsulation key must match what the Rust side emitted.
+	if !bytes.Equal(pub.MLKEM, mustHex(t, v.ClientKyberPub)) {
+		t.Fatalf("ml-kem ek mismatch: Go and Rust derive different bytes from the same seed")
+	}
+	if !bytes.Equal(pub.X25519[:], mustHex(t, v.ClientX25519Pub)) {
+		t.Fatalf("x25519 pub mismatch")
+	}
+	// Decapsulate.
+	ct := &HybridCiphertext{MLKEMCT: mustHex(t, v.ServerKyberCt)}
+	copy(ct.X25519Eph[:], mustHex(t, v.ServerX25519EphPub))
+	ss, err := priv.Decapsulate(ct)
+	if err != nil {
+		t.Fatalf("decapsulate: %v", err)
+	}
+	if !bytes.Equal(ss.X25519SS[:], mustHex(t, v.X25519SS)) {
+		t.Fatalf("x25519_ss mismatch:\n got %x\nwant %s", ss.X25519SS, v.X25519SS)
+	}
+	if !bytes.Equal(ss.MLKEMSS[:], mustHex(t, v.KyberSS)) {
+		t.Fatalf("kyber_ss mismatch:\n got %x\nwant %s", ss.MLKEMSS, v.KyberSS)
+	}
+}
+
+// TestKAT_ClientFinishedHMAC: HMAC-SHA256(c2s, transcript_hash) reproduces the Rust value.
+func TestKAT_ClientFinishedHMAC(t *testing.T) {
+	v := loadVectors(t)
+	if v == nil {
+		return
+	}
+	key := mustHex(t, v.SessionKeys.C2S)
+	transcript := mustHex(t, v.TranscriptHash)
+	mac := hmac.New(sha256.New, key)
+	mac.Write(transcript)
+	got := mac.Sum(nil)
+	want := mustHex(t, v.ClientFinishedHmac)
+	if !bytes.Equal(got, want) {
+		t.Fatalf("client finished mismatch:\n got %x\nwant %x", got, want)
+	}
+}
+
+// TestKAT_ServerFinishedHMAC: HMAC-SHA256(s2c, transcript_hash) reproduces the Rust value.
+func TestKAT_ServerFinishedHMAC(t *testing.T) {
+	v := loadVectors(t)
+	if v == nil {
+		return
+	}
+	key := mustHex(t, v.SessionKeys.S2C)
+	transcript := mustHex(t, v.TranscriptHash)
+	mac := hmac.New(sha256.New, key)
+	mac.Write(transcript)
+	got := mac.Sum(nil)
+	want := mustHex(t, v.ServerFinishedHmac)
+	if !bytes.Equal(got, want) {
+		t.Fatalf("server finished mismatch:\n got %x\nwant %x", got, want)
+	}
+}
+
+// TestKAT_SealedDatagramRecord: ChaCha20-Poly1305.Seal under the c2s key at seq 2 with
+// aad=seq_be reproduces the exact sealed_record bytes (seq_be || ciphertext).
+func TestKAT_SealedDatagramRecord(t *testing.T) {
+	v := loadVectors(t)
+	if v == nil {
+		return
+	}
+	key, err := NewAeadKey(mustHex(t, v.DatagramTest.Key))
+	if err != nil {
+		t.Fatal(err)
+	}
+	frameBytes := mustHex(t, v.DatagramTest.Frame)
+	seq := v.DatagramTest.Seq
+	var seqBE [8]byte
+	binary.BigEndian.PutUint64(seqBE[:], seq)
+	ct := key.Seal(seq, frameBytes, seqBE[:])
+	got := append(append([]byte{}, seqBE[:]...), ct...)
+	want := mustHex(t, v.DatagramTest.SealedRecord)
+	if !bytes.Equal(got, want) {
+		t.Fatalf("sealed datagram mismatch:\n got %x\nwant %x", got, want)
+	}
+	// Round-trip: opening at the same seq must return the original frame bytes.
+	pt, err := key.Open(seq, ct, seqBE[:])
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if !bytes.Equal(pt, frameBytes) {
+		t.Fatal("open returned different plaintext")
+	}
+}
+
+// TestKAT_KnockToken: HMAC-SHA256(ca_fp, u64_be(minute))[:16] matches the Rust knock value.
+func TestKAT_KnockToken(t *testing.T) {
+	v := loadVectors(t)
+	if v == nil {
+		return
+	}
+	key := mustHex(t, v.KnockTest.CAFingerprint)
+	var mb [8]byte
+	binary.BigEndian.PutUint64(mb[:], v.KnockTest.UnixMinute)
+	mac := hmac.New(sha256.New, key)
+	mac.Write(mb[:])
+	tag := mac.Sum(nil)
+	if len(tag) < 16 {
+		t.Fatalf("hmac too short: %d", len(tag))
+	}
+	got := tag[:16]
+	want := mustHex(t, v.KnockTest.Knock)
+	if !bytes.Equal(got, want) {
+		t.Fatalf("knock mismatch:\n got %x\nwant %x", got, want)
+	}
+}
+
+// TestNonceLayout: explicit sanity that NonceFor matches the documented LE(u64) || 0x00000000.
+func TestNonceLayout(t *testing.T) {
+	if got := NonceFor(0); got != ([NonceLen]byte{}) {
+		t.Fatalf("counter 0: want zero, got %x", got)
+	}
+	n := NonceFor(0x0807060504030201)
+	if !bytes.Equal(n[:8], []byte{1, 2, 3, 4, 5, 6, 7, 8}) {
+		t.Fatalf("LE layout wrong: %x", n[:8])
+	}
+	if !bytes.Equal(n[8:], []byte{0, 0, 0, 0}) {
+		t.Fatalf("upper 4 bytes not zero: %x", n[8:])
+	}
+}
+
+// TestAeadSessionCounterMonotonic: Seal/Open lock-step advances the counter by exactly 1.
+func TestAeadSessionCounterMonotonic(t *testing.T) {
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i)
+	}
+	s, err := NewAeadSession(key)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.Counter() != 0 {
+		t.Fatalf("initial counter %d", s.Counter())
+	}
+	for want := uint64(1); want <= 5; want++ {
+		_ = s.Seal([]byte("x"), nil)
+		if s.Counter() != want {
+			t.Fatalf("after %d seals: counter %d", want, s.Counter())
+		}
+	}
+}

singbox-aura/aura/crypto/kdf.go

@@ -0,0 +1,46 @@
+package crypto
+
+import (
+	"crypto/sha256"
+	"hash"
+
+	"golang.org/x/crypto/hkdf"
+)
+
+// HKDFInfo is the domain-separation string bound into the HKDF expansion.
+// MUST match HKDF_INFO in crates/aura-crypto/src/kdf.rs.
+var HKDFInfo = []byte("aura-v1-session")
+
+// SessionKeyLen is the size of one directional AEAD key.
+const SessionKeyLen = 32
+
+// SessionKeys is the pair of directional 256-bit keys produced by the HKDF expansion.
+type SessionKeys struct {
+	ClientToServer [SessionKeyLen]byte
+	ServerToClient [SessionKeyLen]byte
+}
+
+// DeriveSessionKeys runs HKDF-SHA256 with
+//
+//	salt = client_nonce || server_nonce (64 bytes)
+//	IKM  = x25519_ss || mlkem_ss        (64 bytes)
+//	info = "aura-v1-session", OKM 64 bytes -> (c2s, s2c)
+//
+// matching the production helper in crates/aura-crypto/src/kdf.rs byte-for-byte.
+func DeriveSessionKeys(shared *HybridSharedSecret, clientNonce, serverNonce [32]byte) *SessionKeys {
+	salt := make([]byte, 64)
+	copy(salt[:32], clientNonce[:])
+	copy(salt[32:], serverNonce[:])
+
+	ikm := shared.Concat()
+	hk := hkdf.New(func() hash.Hash { return sha256.New() }, ikm, salt, HKDFInfo)
+	okm := make([]byte, 64)
+	if _, err := hk.Read(okm); err != nil {
+		// HKDF-Read for 64 bytes from SHA-256 is infallible; treat any error as a bug.
+		panic(err)
+	}
+	var keys SessionKeys
+	copy(keys.ClientToServer[:], okm[:32])
+	copy(keys.ServerToClient[:], okm[32:])
+	return &keys
+}

singbox-aura/aura/crypto/kem.go

@@ -0,0 +1,174 @@
+// Package crypto implements the Aura primitives the Go client side needs: hybrid X25519 +
+// ML-KEM-768 KEM, HKDF-SHA256 session-key derivation, ChaCha20-Poly1305 AEAD using the same
+// LE(u64)||[0;4] nonce scheme the Rust side uses, and the HMAC-SHA256 port-knock token.
+//
+// All exported sizes match the on-wire constants in crates/aura-crypto and aura-proto:
+//
+//	X25519 public / shared secret    32 bytes
+//	ML-KEM-768 encapsulation key    1184 bytes
+//	ML-KEM-768 ciphertext           1088 bytes
+//	ML-KEM-768 shared secret          32 bytes
+//
+// We use crypto/mlkem (Go 1.24+ stdlib) for the post-quantum half. The Rust side uses the
+// `ml_kem` 0.3 crate; both are FIPS 203 ML-KEM-768. The shared secrets agree byte-for-byte —
+// asserted in crypto_test.go against the KAT vector emitted by `tools/export-kat`.
+package crypto
+
+import (
+	"crypto/ecdh"
+	"crypto/mlkem"
+	"crypto/rand"
+	"errors"
+	"fmt"
+)
+
+// Sizes of the hybrid KEM building blocks, all in bytes.
+const (
+	X25519Len   = 32
+	MLKEMEKLen  = 1184
+	MLKEMCTLen  = 1088
+	MLKEMSSLen  = 32
+	HybridSSLen = X25519Len + MLKEMSSLen
+)
+
+// HybridPublicKey is the client's public half: a 32-byte X25519 public key plus a 1184-byte
+// ML-KEM-768 encapsulation key.
+type HybridPublicKey struct {
+	X25519 [X25519Len]byte
+	MLKEM  []byte // 1184 bytes
+}
+
+// HybridPrivateKey is the client's secret half. We hold the high-level keys so encapsulate /
+// decapsulate are simple method calls.
+type HybridPrivateKey struct {
+	x25519Priv *ecdh.PrivateKey
+	mlkemDk    *mlkem.DecapsulationKey768
+}
+
+// HybridCiphertext is the server's response: its ephemeral X25519 public key plus the ML-KEM
+// ciphertext.
+type HybridCiphertext struct {
+	X25519Eph [X25519Len]byte
+	MLKEMCT   []byte // 1088 bytes
+}
+
+// HybridSharedSecret is the 64-byte concatenation x25519_ss || kyber_ss.
+type HybridSharedSecret struct {
+	X25519SS [X25519Len]byte
+	MLKEMSS  [MLKEMSSLen]byte
+}
+
+// Concat returns x25519_ss || mlkem_ss in one slice (the IKM HKDF consumes).
+func (h *HybridSharedSecret) Concat() []byte {
+	out := make([]byte, HybridSSLen)
+	copy(out[:X25519Len], h.X25519SS[:])
+	copy(out[X25519Len:], h.MLKEMSS[:])
+	return out
+}
+
+// GenerateHybridKeypair produces a fresh client hybrid keypair using the OS RNG. Used by the
+// standalone CLI; tests that need determinism instead call NewHybridPrivateFromSeeds or
+// reconstruct from explicit bytes.
+func GenerateHybridKeypair() (*HybridPrivateKey, *HybridPublicKey, error) {
+	x, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return nil, nil, fmt.Errorf("x25519 keygen: %w", err)
+	}
+	dk, err := mlkem.GenerateKey768()
+	if err != nil {
+		return nil, nil, fmt.Errorf("ml-kem keygen: %w", err)
+	}
+	return buildHybrid(x, dk)
+}
+
+// NewHybridPrivateFromBytes reconstructs a hybrid private key from raw 32-byte X25519 seed and
+// the 64-byte ML-KEM seed (d || z). Mirrors the deterministic constructor the export-kat tool
+// uses so the Go side can drive a handshake against the same KAT vector.
+func NewHybridPrivateFromBytes(x25519Priv [X25519Len]byte, mlkemSeed [64]byte) (*HybridPrivateKey, *HybridPublicKey, error) {
+	// x25519: NewPrivateKey requires a 32-byte scalar. Go enforces clamping inside the curve.
+	x, err := ecdh.X25519().NewPrivateKey(x25519Priv[:])
+	if err != nil {
+		return nil, nil, fmt.Errorf("x25519 from bytes: %w", err)
+	}
+	dk, err := mlkem.NewDecapsulationKey768(mlkemSeed[:])
+	if err != nil {
+		return nil, nil, fmt.Errorf("ml-kem from seed: %w", err)
+	}
+	return buildHybrid(x, dk)
+}
+
+func buildHybrid(x *ecdh.PrivateKey, dk *mlkem.DecapsulationKey768) (*HybridPrivateKey, *HybridPublicKey, error) {
+	priv := &HybridPrivateKey{x25519Priv: x, mlkemDk: dk}
+	pub := &HybridPublicKey{MLKEM: dk.EncapsulationKey().Bytes()}
+	if len(pub.MLKEM) != MLKEMEKLen {
+		return nil, nil, fmt.Errorf("ml-kem ek wrong length: %d", len(pub.MLKEM))
+	}
+	xPub := x.PublicKey().Bytes()
+	if len(xPub) != X25519Len {
+		return nil, nil, fmt.Errorf("x25519 pub wrong length: %d", len(xPub))
+	}
+	copy(pub.X25519[:], xPub)
+	return priv, pub, nil
+}
+
+// Decapsulate runs the client-side decapsulation: ECDH against the server's ephemeral X25519
+// plus ML-KEM-768 decapsulation under the stored secret key.
+func (h *HybridPrivateKey) Decapsulate(ct *HybridCiphertext) (*HybridSharedSecret, error) {
+	if len(ct.MLKEMCT) != MLKEMCTLen {
+		return nil, fmt.Errorf("ml-kem ct wrong length: %d", len(ct.MLKEMCT))
+	}
+	peerPub, err := ecdh.X25519().NewPublicKey(ct.X25519Eph[:])
+	if err != nil {
+		return nil, fmt.Errorf("x25519 peer pub: %w", err)
+	}
+	xss, err := h.x25519Priv.ECDH(peerPub)
+	if err != nil {
+		return nil, fmt.Errorf("x25519 ecdh: %w", err)
+	}
+	if len(xss) != X25519Len {
+		return nil, fmt.Errorf("x25519 ss wrong length: %d", len(xss))
+	}
+	kss, err := h.mlkemDk.Decapsulate(ct.MLKEMCT)
+	if err != nil {
+		return nil, fmt.Errorf("ml-kem decapsulate: %w", err)
+	}
+	if len(kss) != MLKEMSSLen {
+		return nil, fmt.Errorf("ml-kem ss wrong length: %d", len(kss))
+	}
+	out := &HybridSharedSecret{}
+	copy(out.X25519SS[:], xss)
+	copy(out.MLKEMSS[:], kss)
+	return out, nil
+}
+
+// Encapsulate is the server side of the handshake. Provided here purely so a Go-side end-to-end
+// test can drive both halves in-process. The standalone client never calls this.
+func (p *HybridPublicKey) Encapsulate() (*HybridCiphertext, *HybridSharedSecret, error) {
+	if len(p.MLKEM) != MLKEMEKLen {
+		return nil, nil, errors.New("hybrid pub: invalid ml-kem ek length")
+	}
+	eph, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return nil, nil, fmt.Errorf("x25519 eph keygen: %w", err)
+	}
+	peer, err := ecdh.X25519().NewPublicKey(p.X25519[:])
+	if err != nil {
+		return nil, nil, fmt.Errorf("x25519 peer: %w", err)
+	}
+	xss, err := eph.ECDH(peer)
+	if err != nil {
+		return nil, nil, fmt.Errorf("x25519 ecdh: %w", err)
+	}
+	ek, err := mlkem.NewEncapsulationKey768(p.MLKEM)
+	if err != nil {
+		return nil, nil, fmt.Errorf("ml-kem ek parse: %w", err)
+	}
+	kss, kct := ek.Encapsulate()
+
+	ct := &HybridCiphertext{MLKEMCT: kct}
+	copy(ct.X25519Eph[:], eph.PublicKey().Bytes())
+	ss := &HybridSharedSecret{}
+	copy(ss.X25519SS[:], xss)
+	copy(ss.MLKEMSS[:], kss)
+	return ct, ss, nil
+}