[client] pqkem: split handshaker Listen into per-message handlers

Reduce Listen's cognitive complexity (SonarCloud S3776, 30 -> under 25) by
extracting the offer and answer cases into handleRemoteOffer/handleRemoteAnswer,
with shared onSignalReceived/notifyListeners helpers and a pqControllerReoffer
helper for the controller re-offer branch. No functional change.

client/internal/engine.go

@@ -50,6 +50,7 @@ import (
 	icemaker "github.com/netbirdio/netbird/client/internal/peer/ice"
 	"github.com/netbirdio/netbird/client/internal/peerstore"
 	"github.com/netbirdio/netbird/client/internal/portforward"
+	"github.com/netbirdio/netbird/client/internal/pqkem"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 	"github.com/netbirdio/netbird/client/internal/relay"
 	"github.com/netbirdio/netbird/client/internal/rosenpass"
@@ -197,6 +198,10 @@ type Engine struct {
 	// rpManager is a Rosenpass manager
 	rpManager *rosenpass.Manager
 
+	// pqkemManager runs the ML-KEM post-quantum PSK exchange (gated by NB_ENABLE_PQ_MLKEM).
+	// It owns the data-path transport and peer endpoint routing.
+	pqkemManager *pqkem.Manager
+
 	// syncMsgMux is used to guarantee sequential Management Service message processing
 	syncMsgMux *sync.Mutex
 
@@ -555,7 +560,11 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL)
 	publicKey := e.config.WgPrivateKey.PublicKey()
 	e.flowManager = netflow.NewManager(e.wgInterface, publicKey[:], e.statusRecorder)
 
-	if e.config.RosenpassEnabled {
+	// Rosenpass and ML-KEM are mutually exclusive. ML-KEM (NB_ENABLE_PQ_MLKEM) takes precedence
+	if e.config.RosenpassEnabled && pqkem.Enabled() {
+		log.Warnf("rosenpass and ML-KEM post-quantum are mutually exclusive; ML-KEM is enabled, so rosenpass is disabled")
+	}
+	if e.config.RosenpassEnabled && !pqkem.Enabled() {
 		log.Infof("rosenpass is enabled")
 		if e.config.RosenpassPermissive {
 			log.Infof("running rosenpass in permissive mode")
@@ -644,6 +653,30 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL)
 		e.rpManager.SetInterface(e.wgInterface)
 	}
 
+	// Start the ML-KEM PQ manager after the interface is up so its dedicated UDP
+	// transport can bind on the WG overlay IP.
+	if pqkem.Enabled() {
+		tr, pqErr := newPQTransport(e.config.WgAddr.IP)
+		if pqErr != nil {
+			log.Errorf("pqkem: transport bind failed, exchange disabled: %v", pqErr)
+		} else {
+			cbHandler := pqCallbackHandler{
+				wg: e.wgInterface,
+				// On a persistent rekey failure, re-bootstrap the KEM over Signal: a
+				// fresh signalling offer starts a new exchange that overwrites the
+				// stalled PSK on both sides, recovering from a data-path desync.
+				reoffer: func(remoteKey string) {
+					if conn, ok := e.peerStore.PeerConn(remoteKey); ok {
+						conn.RequestReoffer()
+					}
+				},
+			}
+			e.pqkemManager = pqkem.NewManager(pqkem.LocalID(publicKey.String()), cbHandler, pqkem.NewLogger())
+			e.pqkemManager.Start(tr)
+			log.Infof("pqkem: enabled (udp port %d on overlay %s)", e.pqkemManager.LocalPort(), e.config.WgAddr.IP)
+		}
+	}
+
 	// if inbound conns are blocked there is no need to create the ACL manager
 	if e.firewall != nil && !e.config.BlockInbound {
 		e.acl = acl.NewDefaultManager(e.firewall)
@@ -907,6 +940,10 @@ func (e *Engine) removePeer(peerKey string) error {
 
 	e.connMgr.RemovePeerConn(peerKey)
 
+	if e.pqkemManager != nil {
+		e.pqkemManager.RemovePeer(pqkem.RemoteID(peerKey))
+	}
+
 	err := e.statusRecorder.RemovePeer(peerKey)
 	if err != nil {
 		log.Warnf("received error when removing peer %s from status recorder: %v", peerKey, err)
@@ -1893,6 +1930,10 @@ func (e *Engine) createPeerConn(pubKey string, allowedIPs []netip.Prefix, agentV
 		},
 		ICEConfig: e.createICEConfig(),
 	}
+	if e.pqkemManager != nil {
+		config.PQ = pqHandshaker{mgr: e.pqkemManager}
+		config.PQStrict = pqkem.Strict()
+	}
 
 	serviceDependencies := peer.ServiceDependencies{
 		StatusRecorder:     e.statusRecorder,
@@ -2076,6 +2117,10 @@ func (e *Engine) close() {
 		_ = e.rpManager.Close()
 	}
 
+	if e.pqkemManager != nil {
+		e.pqkemManager.Stop()
+	}
+
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 	if err := e.portForwardManager.GracefullyStop(ctx); err != nil {
@@ -2852,6 +2897,8 @@ func convertToOfferAnswer(msg *sProto.Message) (*peer.OfferAnswer, error) {
 		Version:         msg.GetBody().GetNetBirdVersion(),
 		RosenpassPubKey: rosenpassPubKey,
 		RosenpassAddr:   rosenpassAddr,
+		MlkemPayload:    msg.GetBody().GetMlkemPayload(),
+		MlkemPort:       int(msg.GetBody().GetMlkemPort()),
 		RelaySrvAddress: msg.GetBody().GetRelayServerAddress(),
 		RelaySrvIP:      relayIP,
 		SessionID:       sessionID,

client/internal/peer/conn.go

@@ -3,6 +3,7 @@ package peer
 import (
 	"context"
 	"fmt"
+	"math"
 	"net"
 	"net/netip"
 	"runtime"
@@ -26,6 +27,7 @@ import (
 	"github.com/netbirdio/netbird/client/internal/portforward"
 	"github.com/netbirdio/netbird/client/internal/rosenpass"
 	"github.com/netbirdio/netbird/client/internal/stdnet"
+	"github.com/netbirdio/netbird/monotime"
 	"github.com/netbirdio/netbird/route"
 	relayClient "github.com/netbirdio/netbird/shared/relay/client"
 )
@@ -74,6 +76,39 @@ type RosenpassConfig struct {
 	PermissiveMode bool
 }
 
+// PQHandshaker attaches post-quantum ML-KEM material to signalling offers/answers and
+// feeds received material back. It is implemented by the engine over the pqkem
+// manager and is nil when the PQ exchange is disabled. remoteKey is the peer's
+// WireGuard public key.
+type PQHandshaker interface {
+	// OfferPayload returns the KEM offer to embed in an outgoing offer (nil if this
+	// peer is not the KEM initiator) and the local PQ data-path port to announce.
+	OfferPayload(remoteKey string) (payload []byte, port int)
+	// ShouldSendBootstrapOffer reports whether, as the controller, we should reply to a
+	// received responder offer with our own KEM offer (true only when no exchange is
+	// already in flight — so we kick the KEM once and ignore further offers).
+	ShouldSendBootstrapOffer(remoteKey string) bool
+	// AnswerPayload processes a received KEM offer (nil if absent) and returns the KEM
+	// answer to embed in the outgoing answer (nil if none) and the local PQ port.
+	AnswerPayload(remoteKey string, recvOffer []byte) (payload []byte, port int)
+	// OnAnswer feeds a received KEM answer (nil if absent).
+	OnAnswer(remoteKey string, recvAnswer []byte)
+	// PSK returns the peer's latest derived post-quantum PSK to program at WG
+	// peer-config time (the pull path). ok is false until one has been derived.
+	PSK(remoteKey string) (wgtypes.Key, bool)
+	// SetRemoteAddr registers the peer's data-path endpoint learned from signalling:
+	// its WG overlay IP with the announced pq UDP port (port 0 means the peer omitted
+	// it and is on the default port).
+	SetRemoteAddr(remoteKey string, addr netip.AddrPort)
+	// OnDataPathRekeyed signals a fresh WireGuard handshake for the peer; it clocks the
+	// next chained PSK rotation pushed over the data path. sinceActivity is how long
+	// ago the peer last exchanged real user data, so the rotation can be skipped for
+	// idle tunnels.
+	OnDataPathRekeyed(remoteKey string, sinceActivity time.Duration)
+	// OnDataPathDown signals the peer's tunnel went down.
+	OnDataPathDown(remoteKey string)
+}
+
 // ConnConfig is a peer Connection configuration
 type ConnConfig struct {
 	// Key is a public key of a remote peer
@@ -91,6 +126,12 @@ type ConnConfig struct {
 
 	RosenpassConfig RosenpassConfig
 
+	// PQ carries post-quantum ML-KEM material on offers/answers; nil when disabled.
+	PQ PQHandshaker
+	// PQStrict fails closed: block peer traffic until the ML-KEM PSK is established,
+	// instead of letting the tunnel come up classically and upgrading to PQ later.
+	PQStrict bool
+
 	// ICEConfig ICE protocol configuration
 	ICEConfig icemaker.Config
 }
@@ -149,6 +190,11 @@ type Conn struct {
 	// pendingFirstPacket is the lazyconn-captured handshake init, replayed once the real
 	// transport is up.
 	pendingFirstPacket []byte
+
+	// pqStrictSentinelKey is a per-conn random sentinel PSK used in PQ strict mode to
+	// fail closed: it is programmed until the real ML-KEM PSK is derived, so no session
+	// can form on a non-PQ key. Per-conn random so two strict peers never match by chance.
+	pqStrictSentinelKey *wgtypes.Key
 }
 
 // injectPendingFirstPacket replays the captured handshake through the proxy if present, else
@@ -206,6 +252,14 @@ func NewConn(config ConnConfig, services ServiceDependencies) (*Conn, error) {
 		metricsRecorder:    services.MetricsRecorder,
 	}
 
+	if config.PQ != nil && config.PQStrict {
+		if k, err := wgtypes.GenerateKey(); err != nil {
+			connLog.Errorf("pqkem: failed to generate strict-mode sentinel key, strict fail-closed disabled for this peer: %v", err)
+		} else {
+			conn.pqStrictSentinelKey = &k
+		}
+	}
+
 	return conn, nil
 }
 
@@ -307,6 +361,8 @@ func (conn *Conn) Close(signalToRemote bool) {
 
 	if conn.wgWatcherCancel != nil {
 		conn.wgWatcherCancel()
+		conn.wgWatcher = nil
+		conn.wgWatcherCancel = nil
 	}
 	conn.workerRelay.CloseConn()
 	if conn.workerICE != nil {
@@ -670,6 +726,22 @@ func (conn *Conn) onGuardEvent() {
 	}
 }
 
+// RequestReoffer sends a fresh signalling offer for the peer, re-running the
+// post-quantum bootstrap over Signal. Used to recover from a persistent data-path
+// rekey failure: a new exchange overwrites the stalled PSK on both sides. No-op if the
+// connection is not open yet.
+func (conn *Conn) RequestReoffer() {
+	conn.mu.Lock()
+	h := conn.handshaker
+	conn.mu.Unlock()
+	if h == nil {
+		return
+	}
+	if err := h.SendOffer(); err != nil {
+		conn.Log.Debugf("pqkem: recovery re-offer failed: %v", err)
+	}
+}
+
 func (conn *Conn) onWGDisconnected(watcherCtx context.Context) {
 	conn.mu.Lock()
 	defer conn.mu.Unlock()
@@ -681,6 +753,10 @@ func (conn *Conn) onWGDisconnected(watcherCtx context.Context) {
 
 	conn.Log.Warnf("WireGuard handshake timeout detected, closing current connection")
 
+	if conn.config.PQ != nil {
+		conn.config.PQ.OnDataPathDown(conn.config.Key)
+	}
+
 	// Close the active connection based on current priority
 	switch conn.currentConnPriority {
 	case conntype.Relay:
@@ -723,7 +799,7 @@ func (conn *Conn) updateRelayStatus(relayServerAddr string, rosenpassPubKey []by
 		ConnStatus:         conn.evalStatus(),
 		Relayed:            conn.isRelayed(),
 		RelayServerAddress: relayServerAddr,
-		RosenpassEnabled:   isRosenpassEnabled(rosenpassPubKey),
+		RosenpassEnabled:   conn.quantumResistant(rosenpassPubKey),
 	}
 
 	err := conn.statusRecorder.UpdatePeerRelayedState(peerState)
@@ -742,7 +818,7 @@ func (conn *Conn) updateIceState(iceConnInfo ICEConnInfo, updateTime time.Time)
 		RemoteIceCandidateType:     iceConnInfo.RemoteIceCandidateType,
 		LocalIceCandidateEndpoint:  iceConnInfo.LocalIceCandidateEndpoint,
 		RemoteIceCandidateEndpoint: iceConnInfo.RemoteIceCandidateEndpoint,
-		RosenpassEnabled:           isRosenpassEnabled(iceConnInfo.RosenpassPubKey),
+		RosenpassEnabled:           conn.quantumResistant(iceConnInfo.RosenpassPubKey),
 	}
 
 	err := conn.statusRecorder.UpdatePeerICEState(peerState)
@@ -946,6 +1022,35 @@ func (conn *Conn) onWGCheckSuccess() {
 	conn.mu.Lock()
 	conn.wgTimeouts = 0
 	conn.mu.Unlock()
+
+	// A fresh WireGuard handshake clocks the post-quantum PSK rotation. Pass how long
+	// ago the peer last exchanged real user data (keepalives excluded) so the pqkem
+	// manager can skip rotation on idle tunnels — rotating then would push data-path
+	// traffic that keeps the lazy connection artificially active.
+	if conn.config.PQ != nil {
+		conn.config.PQ.OnDataPathRekeyed(conn.config.Key, conn.dataActivityAge())
+	}
+}
+
+// dataActivityAge returns how long ago the peer last exchanged real user data
+// (WireGuard keepalives excluded), per the same LastActivities signal the
+// lazy-connection inactivity monitor uses. It reports a very large duration when no
+// activity has ever been recorded, so the peer is treated as idle.
+//
+// In kernel mode there is no per-peer data-activity signal (LastActivities is
+// userspace-only), so we cannot tell active from idle. We report zero — always
+// "active" — so PSK rotation is not disabled in kernel mode. Lazy back-to-idle is
+// already limited there; the eBPF WG-activity detection (future) will supply a real
+// signal that excludes handshake/pqkem traffic.
+func (conn *Conn) dataActivityAge() time.Duration {
+	if !conn.config.WgConfig.WgInterface.IsUserspaceBind() {
+		return 0
+	}
+	last, ok := conn.config.WgConfig.WgInterface.LastActivities()[conn.config.WgConfig.RemoteKey]
+	if !ok {
+		return time.Duration(math.MaxInt64)
+	}
+	return monotime.Since(last)
 }
 
 // recordConnectionMetrics records connection stage timestamps as metrics
@@ -987,6 +1092,23 @@ func (conn *Conn) AgentVersionString() string {
 }
 
 func (conn *Conn) presharedKey(remoteRosenpassKey []byte) *wgtypes.Key {
+	// Post-quantum: once the ML-KEM exchange has derived a PSK for this peer, program
+	// it here so the peer's next WireGuard handshake adopts it. Applied at peer-config
+	// time (bootstrap / reconnect); steady-state rotation is pushed separately.
+	if conn.config.PQ != nil {
+		if psk, ok := conn.config.PQ.PSK(conn.config.Key); ok {
+			return &psk
+		}
+		if conn.config.PQStrict && conn.pqStrictSentinelKey != nil {
+			// Fail closed: program a non-matching sentinel so no session forms on a
+			// non-PQ key until the ML-KEM exchange derives the real PSK (pushed via
+			// SetPresharedKey once it converges). "pending" — turns into a "stuck"
+			// warning from the manager if the exchange keeps failing (see raiseFailure).
+			conn.Log.Debugf("pqkem: strict mode — no PQ PSK yet, blocking peer traffic until the ML-KEM exchange converges")
+			return conn.pqStrictSentinelKey
+		}
+	}
+
 	if conn.config.RosenpassConfig.PubKey == nil {
 		return conn.config.WgConfig.PreSharedKey
 	}
@@ -1026,6 +1148,21 @@ func isRosenpassEnabled(remoteRosenpassPubKey []byte) bool {
 	return remoteRosenpassPubKey != nil
 }
 
+// quantumResistant reports whether the peer's tunnel is post-quantum protected, for
+// the status "Quantum resistance" field: either Rosenpass (the remote advertised a
+// Rosenpass key) or the ML-KEM exchange (a PQ PSK has been derived for this peer).
+func (conn *Conn) quantumResistant(remoteRosenpassPubKey []byte) bool {
+	if isRosenpassEnabled(remoteRosenpassPubKey) {
+		return true
+	}
+	if conn.config.PQ != nil {
+		if _, ok := conn.config.PQ.PSK(conn.config.Key); ok {
+			return true
+		}
+	}
+	return false
+}
+
 func evalConnStatus(in connStatusInputs) guard.ConnStatus {
 	// "Relay up and needed" — the peer uses relay and the transport is connected.
 	relayUsedAndUp := in.peerUsesRelay && in.relayConnected

client/internal/peer/conn_pq_test.go

@@ -0,0 +1,86 @@
+package peer
+
+import (
+	"net/netip"
+	"testing"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+	"github.com/stretchr/testify/require"
+	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
+)
+
+// fakePQ is a minimal PQHandshaker: only PSK is exercised by presharedKey, the rest
+// are no-op stubs to satisfy the interface.
+type fakePQ struct {
+	psk wgtypes.Key
+	ok  bool
+}
+
+func (f fakePQ) OfferPayload(string) ([]byte, int)          { return nil, 0 }
+func (f fakePQ) ShouldSendBootstrapOffer(string) bool       { return false }
+func (f fakePQ) AnswerPayload(string, []byte) ([]byte, int) { return nil, 0 }
+func (f fakePQ) OnAnswer(string, []byte)                    {}
+func (f fakePQ) PSK(string) (wgtypes.Key, bool)             { return f.psk, f.ok }
+func (f fakePQ) SetRemoteAddr(string, netip.AddrPort)       {}
+func (f fakePQ) OnDataPathRekeyed(string, time.Duration)    {}
+func (f fakePQ) OnDataPathDown(string)                      {}
+
+// TestConn_presharedKey_PQ covers the post-quantum branch of presharedKey across the
+// three states that matter: a derived PSK is programmed, and — before one exists —
+// strict mode blocks with a sentinel while non-strict falls open to the ordinary key.
+func TestConn_presharedKey_PQ(t *testing.T) {
+	derivedPSK, err := wgtypes.GenerateKey()
+	require.NoError(t, err)
+	nbPSK, err := wgtypes.GenerateKey()
+	require.NoError(t, err)
+
+	newConn := func() *Conn {
+		return &Conn{
+			Log: log.WithField("peer", "pq-test"),
+			config: ConnConfig{
+				Key:             "LLHf3Ma6z6mdLbriAJbqhX7+nM/B71lgw2+91q3LfhU=",
+				LocalKey:        "RRHf3Ma6z6mdLbriAJbqhX7+nM/B71lgw2+91q3LfhU=",
+				WgConfig:        WgConfig{PreSharedKey: &nbPSK},
+				RosenpassConfig: RosenpassConfig{},
+			},
+		}
+	}
+
+	t.Run("derived PSK is programmed", func(t *testing.T) {
+		for _, strict := range []bool{false, true} {
+			c := newConn()
+			c.config.PQ = fakePQ{psk: derivedPSK, ok: true}
+			c.config.PQStrict = strict
+			if strict {
+				sentinel, _ := wgtypes.GenerateKey()
+				c.pqStrictSentinelKey = &sentinel
+			}
+			got := c.presharedKey(nil)
+			require.NotNil(t, got)
+			require.Equal(t, derivedPSK, *got, "the derived PQ PSK must win (strict=%v)", strict)
+		}
+	})
+
+	t.Run("non-strict falls open to the ordinary key before a PSK exists", func(t *testing.T) {
+		c := newConn()
+		c.config.PQ = fakePQ{ok: false}
+		c.config.PQStrict = false
+		got := c.presharedKey(nil)
+		require.NotNil(t, got, "non-strict must not block")
+		require.Equal(t, nbPSK, *got, "non-strict falls through to the NetBird PSK, not a sentinel")
+	})
+
+	t.Run("strict blocks with the per-conn sentinel before a PSK exists", func(t *testing.T) {
+		sentinel, err := wgtypes.GenerateKey()
+		require.NoError(t, err)
+		c := newConn()
+		c.config.PQ = fakePQ{ok: false}
+		c.config.PQStrict = true
+		c.pqStrictSentinelKey = &sentinel
+		got := c.presharedKey(nil)
+		require.NotNil(t, got)
+		require.Equal(t, sentinel, *got, "strict must return the blocking sentinel")
+		require.NotEqual(t, nbPSK, *got, "the sentinel must not be the ordinary key")
+	})
+}

client/internal/peer/endpoint.go

@@ -88,7 +88,7 @@ func (e *EndpointUpdater) configureAsResponder(addr *net.UDPAddr, presharedKey *
 	var ctx context.Context
 	ctx, e.cancelFunc = context.WithCancel(context.Background())
 	e.updateWg.Add(1)
-	go e.scheduleDelayedUpdate(ctx, addr, presharedKey)
+	go e.scheduleDelayedUpdate(ctx, addr)
 
 	if err := e.updateWireGuardPeer(nil, presharedKey); err != nil {
 		e.waitForCloseTheDelayedUpdate()
@@ -107,8 +107,14 @@ func (e *EndpointUpdater) waitForCloseTheDelayedUpdate() {
 	e.updateWg.Wait()
 }
 
-// scheduleDelayedUpdate waits for the fallback period before updating the endpoint
-func (e *EndpointUpdater) scheduleDelayedUpdate(ctx context.Context, addr *net.UDPAddr, presharedKey *wgtypes.Key) {
+// scheduleDelayedUpdate waits for the fallback period, then sets the responder's real
+// endpoint. It deliberately passes a nil preshared key so it only updates the endpoint
+// and leaves the current PSK untouched: the PSK captured when this was scheduled may be
+// stale by now (e.g. the post-quantum bootstrap derived a fresher PSK within the
+// fallback window, applied via SetPresharedKey), and re-applying the captured one would
+// revert WireGuard to a key the remote peer no longer uses — a mismatch that stalls the
+// handshake until the next retry.
+func (e *EndpointUpdater) scheduleDelayedUpdate(ctx context.Context, addr *net.UDPAddr) {
 	defer e.updateWg.Done()
 	t := time.NewTimer(fallbackDelay)
 	defer t.Stop()
@@ -117,7 +123,7 @@ func (e *EndpointUpdater) scheduleDelayedUpdate(ctx context.Context, addr *net.U
 	case <-ctx.Done():
 		return
 	case <-t.C:
-		if err := e.updateWireGuardPeer(addr, presharedKey); err != nil {
+		if err := e.updateWireGuardPeer(addr, nil); err != nil {
 			e.log.Errorf("failed to update WireGuard peer, address: %s, error: %v", addr, err)
 		}
 	}

client/internal/peer/handshaker.go

@@ -39,6 +39,16 @@ type OfferAnswer struct {
 	// This value is the local Rosenpass server address when sending the message
 	RosenpassAddr string
 
+	// MlkemPayload carries the post-quantum X25519MLKEM768 handshake message
+	// (pqkem-framed offer on an OFFER, answer on an ANSWER) that seeds the
+	// WireGuard PSK. Opaque here — the pqkem library frames and parses it. Nil
+	// when the peer does not run the ML-KEM PQ exchange.
+	MlkemPayload []byte
+
+	// MlkemPort is the peer's ML-KEM PQ service UDP port (bound on its WG overlay
+	// IP) where data-path rekey messages are sent. Zero when not running the exchange.
+	MlkemPort int
+
 	// relay server address
 	RelaySrvAddress string
 	// RelaySrvIP is the IP the remote peer is connected to on its
@@ -81,14 +91,20 @@ type Handshaker struct {
 
 func NewHandshaker(log *log.Entry, config ConnConfig, signaler *Signaler, ice *WorkerICE, relay *WorkerRelay, metricsStages *MetricsStages) *Handshaker {
 	h := &Handshaker{
-		log:            log,
-		config:         config,
-		signaler:       signaler,
-		ice:            ice,
-		relay:          relay,
-		metricsStages:  metricsStages,
-		remoteOffersCh: make(chan OfferAnswer),
-		remoteAnswerCh: make(chan OfferAnswer),
+		log:           log,
+		config:        config,
+		signaler:      signaler,
+		ice:           ice,
+		relay:         relay,
+		metricsStages: metricsStages,
+		// Buffered by 1: the single Listen goroutine can be busy handling an offer
+		// (sendAnswer does a blocking signal send) exactly when the matching answer
+		// arrives on the other channel. Unbuffered, that answer would hit the
+		// non-blocking send's default and be dropped — fatal for the post-quantum
+		// exchange, which needs the answer to converge. A 1-slot cushion lets it wait
+		// until Listen loops back, without ever blocking the signal receiver.
+		remoteOffersCh: make(chan OfferAnswer, 1),
+		remoteAnswerCh: make(chan OfferAnswer, 1),
 	}
 	// assume remote supports ICE until we learn otherwise from received offers
 	h.remoteICESupported.Store(ice != nil)
@@ -111,44 +127,9 @@ func (h *Handshaker) Listen(ctx context.Context) {
 	for {
 		select {
 		case remoteOfferAnswer := <-h.remoteOffersCh:
-			h.log.Infof("received offer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials())
-
-			// Record signaling received for reconnection attempts
-			if h.metricsStages != nil {
-				h.metricsStages.RecordSignalingReceived()
-			}
-
-			h.updateRemoteICEState(&remoteOfferAnswer)
-
-			if h.relayListener != nil {
-				h.relayListener.Notify(&remoteOfferAnswer)
-			}
-
-			if h.iceListener != nil && h.RemoteICESupported() {
-				h.iceListener(&remoteOfferAnswer)
-			}
-
-			if err := h.sendAnswer(); err != nil {
-				h.log.Errorf("failed to send remote offer confirmation: %s", err)
-				continue
-			}
+			h.handleRemoteOffer(remoteOfferAnswer)
 		case remoteOfferAnswer := <-h.remoteAnswerCh:
-			h.log.Infof("received answer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials())
-
-			// Record signaling received for reconnection attempts
-			if h.metricsStages != nil {
-				h.metricsStages.RecordSignalingReceived()
-			}
-
-			h.updateRemoteICEState(&remoteOfferAnswer)
-
-			if h.relayListener != nil {
-				h.relayListener.Notify(&remoteOfferAnswer)
-			}
-
-			if h.iceListener != nil && h.RemoteICESupported() {
-				h.iceListener(&remoteOfferAnswer)
-			}
+			h.handleRemoteAnswer(remoteOfferAnswer)
 		case <-ctx.Done():
 			h.log.Infof("stop listening for remote offers and answers")
 			return
@@ -156,6 +137,101 @@ func (h *Handshaker) Listen(ctx context.Context) {
 	}
 }
 
+// onSignalReceived runs the common preamble for a received offer/answer: record the
+// signalling metric, refresh the remote ICE state, and register the peer's post-quantum
+// data-path endpoint learned from the message.
+func (h *Handshaker) onSignalReceived(remoteOfferAnswer *OfferAnswer) {
+	if h.metricsStages != nil {
+		h.metricsStages.RecordSignalingReceived()
+	}
+	h.updateRemoteICEState(remoteOfferAnswer)
+	h.pqRegisterEndpoint(remoteOfferAnswer.MlkemPort)
+}
+
+// notifyListeners hands the offer/answer to the relay and ICE workers so they bring the
+// connection up.
+func (h *Handshaker) notifyListeners(remoteOfferAnswer *OfferAnswer) {
+	if h.relayListener != nil {
+		h.relayListener.Notify(remoteOfferAnswer)
+	}
+	if h.iceListener != nil && h.RemoteICESupported() {
+		h.iceListener(remoteOfferAnswer)
+	}
+}
+
+func (h *Handshaker) handleRemoteOffer(remoteOfferAnswer OfferAnswer) {
+	h.log.Infof("received offer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials())
+	h.onSignalReceived(&remoteOfferAnswer)
+
+	// If we are the controller running the KEM, a responder's offer is handled by
+	// replying with our own KEM offer, not by answering it (see pqControllerReoffer).
+	if h.pqControllerReoffer() {
+		return
+	}
+
+	// Derive+store the KEM PSK (inside sendAnswer's AnswerPayload) BEFORE bringing up the
+	// connection: the relay/ICE workers configure the WG endpoint, which pulls the PSK
+	// for the first handshake. Notifying them first would race the KEM exchange and hand
+	// the first handshake a not-yet-derived key.
+	if err := h.sendAnswer(&remoteOfferAnswer); err != nil {
+		h.log.Errorf("failed to send remote offer confirmation: %s", err)
+		return
+	}
+	h.notifyListeners(&remoteOfferAnswer)
+}
+
+func (h *Handshaker) handleRemoteAnswer(remoteOfferAnswer OfferAnswer) {
+	h.log.Infof("received answer, running version %s, remote WireGuard listen port %d, session id: %s, remote ICE supported: %t", remoteOfferAnswer.Version, remoteOfferAnswer.WgListenPort, remoteOfferAnswer.SessionIDString(), remoteOfferAnswer.hasICECredentials())
+	h.onSignalReceived(&remoteOfferAnswer)
+
+	// Feed the KEM answer (derive+store PSK) BEFORE bringing up the connection so the WG
+	// endpoint config pulls the real PSK for the first handshake instead of racing ahead
+	// of the KEM exchange.
+	if h.config.PQ != nil {
+		h.config.PQ.OnAnswer(h.config.Key, remoteOfferAnswer.MlkemPayload)
+	}
+	h.notifyListeners(&remoteOfferAnswer)
+}
+
+// pqControllerReoffer handles a responder's offer when we are the controller running the
+// KEM. The KEM material rides only the controller's offer, so the two peers derive a
+// single shared PSK (a bidirectional KEM would yield two different PSKs and WireGuard
+// would pick misaligned ones). Rather than answer the responder's (KEM-less) offer —
+// which would bring WireGuard up on a pre-PQ key before the KEM completes — we reply with
+// our own KEM offer, so the only transaction that establishes the tunnel is the one that
+// also derives the PSK. It also guarantees a responder-initiated wake still triggers a
+// KEM offer (no stuck responder). Sent exactly once per exchange; further offers while
+// one is in flight are ignored (re-sending on every responder offer would be a runaway).
+// The re-offer reuses our stable ICE session id, so the peer dedups repeats.
+//
+// Returns true when it took ownership of the offer (the caller must not answer it).
+func (h *Handshaker) pqControllerReoffer() bool {
+	if h.config.PQ == nil || !isController(h.config) {
+		return false
+	}
+	if h.config.PQ.ShouldSendBootstrapOffer(h.config.Key) {
+		h.log.Debugf("pqkem: controller received a responder offer, replying with our KEM offer instead of an answer")
+		if err := h.sendOffer(); err != nil {
+			h.log.Errorf("failed to send KEM offer in response to peer offer: %s", err)
+		}
+	} else {
+		h.log.Debugf("pqkem: controller received a responder offer but a KEM exchange is already in flight, ignoring")
+	}
+	return true
+}
+
+// pqRegisterEndpoint feeds the post-quantum handshaker the peer's data-path endpoint
+// (its WG overlay IP plus the advertised pq UDP port) learned from a remote offer/answer.
+func (h *Handshaker) pqRegisterEndpoint(remotePort int) {
+	if h.config.PQ == nil || remotePort < 0 || remotePort > 65535 || len(h.config.WgConfig.AllowedIps) == 0 {
+		return
+	}
+	// remotePort may be 0 (the peer omitted it, meaning the default port); the adapter
+	// resolves 0 to DefaultPort.
+	addr := netip.AddrPortFrom(h.config.WgConfig.AllowedIps[0].Addr(), uint16(remotePort))
+	h.config.PQ.SetRemoteAddr(h.config.Key, addr)
+}
+
 func (h *Handshaker) SendOffer() error {
 	h.mu.Lock()
 	defer h.mu.Unlock()
@@ -195,13 +271,23 @@ func (h *Handshaker) sendOffer() error {
 	}
 
 	offer := h.buildOfferAnswer()
+	if h.config.PQ != nil {
+		offer.MlkemPayload, offer.MlkemPort = h.config.PQ.OfferPayload(h.config.Key)
+	}
 	h.log.Debugf("sending offer with serial: %s", offer.SessionIDString())
 
 	return h.signaler.SignalOffer(offer, h.config.Key)
 }
 
-func (h *Handshaker) sendAnswer() error {
+func (h *Handshaker) sendAnswer(remoteOffer *OfferAnswer) error {
 	answer := h.buildOfferAnswer()
+	if h.config.PQ != nil {
+		var recvOffer []byte
+		if remoteOffer != nil {
+			recvOffer = remoteOffer.MlkemPayload
+		}
+		answer.MlkemPayload, answer.MlkemPort = h.config.PQ.AnswerPayload(h.config.Key, recvOffer)
+	}
 	h.log.Debugf("sending answer with serial: %s", answer.SessionIDString())
 
 	return h.signaler.SignalAnswer(answer, h.config.Key)

client/internal/peer/iface.go

@@ -10,6 +10,7 @@ import (
 	"github.com/netbirdio/netbird/client/iface/configurer"
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/client/iface/wgproxy"
+	"github.com/netbirdio/netbird/monotime"
 )
 
 type WGIface interface {
@@ -19,4 +20,11 @@ type WGIface interface {
 	GetProxy() wgproxy.Proxy
 	Address() wgaddr.Address
 	RemoveEndpointAddress(key string) error
+	// LastActivities returns the last real-data activity time per peer (WireGuard
+	// keepalives excluded), used to gate post-quantum PSK rotation on active tunnels.
+	LastActivities() map[string]monotime.Time
+	// IsUserspaceBind reports whether WireGuard runs in userspace. Only there does
+	// LastActivities track per-peer data activity; in kernel mode it is unavailable,
+	// so PSK rotation cannot be gated on activity.
+	IsUserspaceBind() bool
 }

client/internal/peer/signaler.go

@@ -63,6 +63,8 @@ func (s *Signaler) signalOfferAnswer(offerAnswer OfferAnswer, remoteKey string,
 		},
 		RosenpassPubKey: offerAnswer.RosenpassPubKey,
 		RosenpassAddr:   offerAnswer.RosenpassAddr,
+		MlkemPayload:    offerAnswer.MlkemPayload,
+		MlkemPort:       offerAnswer.MlkemPort,
 		RelaySrvAddress: offerAnswer.RelaySrvAddress,
 		RelaySrvIP:      offerAnswer.RelaySrvIP,
 		SessionID:       sessionIDBytes,

client/internal/pqkem/bench_test.go

@@ -0,0 +1,59 @@
+package pqkem
+
+import (
+	"crypto/ecdh"
+	"crypto/mlkem"
+	"crypto/rand"
+	"testing"
+)
+
+func BenchmarkX25519Keygen(b *testing.B) {
+	c := ecdh.X25519()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := c.GenerateKey(rand.Reader); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkX25519ECDH(b *testing.B) {
+	c := ecdh.X25519()
+	a, _ := c.GenerateKey(rand.Reader)
+	p, _ := c.GenerateKey(rand.Reader)
+	pub := p.PublicKey()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := a.ECDH(pub); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkMLKEMKeygen(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		if _, err := mlkem.GenerateKey768(); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+func BenchmarkMLKEMEncaps(b *testing.B) {
+	dk, _ := mlkem.GenerateKey768()
+	ek := dk.EncapsulationKey()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = ek.Encapsulate()
+	}
+}
+
+func BenchmarkMLKEMDecaps(b *testing.B) {
+	dk, _ := mlkem.GenerateKey768()
+	_, ct := dk.EncapsulationKey().Encapsulate()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := dk.Decapsulate(ct); err != nil {
+			b.Fatal(err)
+		}
+	}
+}

client/internal/pqkem/callbacks.go

@@ -0,0 +1,18 @@
+package pqkem
+
+// CallbackHandler is implemented by the host and invoked by the library. The
+// library only reports events; the host owns the reaction. Keeping this an
+// interface — rather than touching the transport or keying directly — is what lets
+// the KEM code be extracted as a standalone library.
+type CallbackHandler interface {
+	// OnNewPSKReady fires when a fresh post-quantum PSK has been derived for a peer
+	// and must be programmed into the consumer's secure channel. It is invoked at
+	// the commit point of each side: the initiator on receiving the answer, the
+	// responder on receiving the confirm.
+	OnNewPSKReady(remoteID RemoteID, psk PSK) error
+
+	// OnRekeyFailed fires when an exchange fails to converge within the allotted
+	// time. The host should tear the peer connection down so it re-establishes, and
+	// log a WARN. The library reports the event; it does not dictate the reaction.
+	OnRekeyFailed(remoteID RemoteID) error
+}

client/internal/pqkem/capability_test.go

@@ -0,0 +1,65 @@
+package pqkem
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestManager_NonCapablePeerNotOffered: a peer known not to run the KEM (it advertised
+// no PQ port over signalling) is never offered an exchange, and no failure is raised —
+// this is what stops the reoffer storm against non-PQ peers (e.g. Rosenpass peers).
+func TestManager_NonCapablePeerNotOffered(t *testing.T) {
+	wg := newFakeWG()
+	d := NewManager("bbbb", wg, nil) // initiator vs "aaaa"
+	d.Start(&loopback{ep: epB, sw: newSwitch()})
+	defer d.Stop()
+
+	d.MarkNonCapable("aaaa")
+
+	offer, err := d.SignalOffer("aaaa")
+	require.NoError(t, err)
+	require.Nil(t, offer, "a non-capable peer must not be offered a KEM exchange")
+	require.Empty(t, wg.failed, "a non-capable peer must not raise a rekey failure")
+}
+
+// TestManager_MarkNonCapableCancelsInFlight: if we start an exchange with a peer whose
+// capability is not yet known and then learn it does not run the KEM, the in-flight
+// exchange is cancelled and no further offer is produced (no timeout -> no failure).
+func TestManager_MarkNonCapableCancelsInFlight(t *testing.T) {
+	wg := newFakeWG()
+	d := NewManager("bbbb", wg, nil)
+	d.Start(&loopback{ep: epB, sw: newSwitch()})
+	defer d.Stop()
+
+	// Capability unknown -> the bootstrap offer goes out optimistically.
+	offer, err := d.SignalOffer("aaaa")
+	require.NoError(t, err)
+	require.NotNil(t, offer)
+
+	// Now we learn the peer is non-PQ: the exchange must be dropped.
+	d.MarkNonCapable("aaaa")
+
+	next, err := d.SignalOffer("aaaa")
+	require.NoError(t, err)
+	require.Nil(t, next, "after learning non-capability the peer is no longer offered")
+	require.Empty(t, wg.failed, "cancelling an in-flight exchange must not raise a failure")
+}
+
+// TestManager_EstablishedPeerNotDowngraded: a stray zero-port observation must not tear
+// down a peer we already have a working PQ session with.
+func TestManager_EstablishedPeerNotDowngraded(t *testing.T) {
+	dA, dB, _, wgB, _ := pair(t)
+	defer dA.Stop()
+	defer dB.Stop()
+
+	bootstrap(t, dA, dB)
+	require.NotEqual(t, PSK{}, wgB.psk("aaaa"), "established a PSK")
+
+	dB.MarkNonCapable("aaaa") // stray zero after establishment
+
+	// The peer keeps its derived PSK (MarkNonCapable is a no-op once established).
+	psk, ok := dB.PSK("aaaa")
+	require.True(t, ok, "an established peer must keep its PSK despite a stray zero")
+	require.NotEqual(t, PSK{}, psk)
+}

client/internal/pqkem/concurrency_test.go

@@ -0,0 +1,77 @@
+package pqkem
+
+import (
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestConcurrency_RecoversViaResignalAfterDataPathBreak exercises the A-light recovery:
+// a data-path rotation can no longer converge (OnRekeyFailed), and re-bootstrapping over
+// signalling resyncs both peers on a fresh PSK — even while the data path stays broken,
+// since the signal channel is independent of it.
+func TestConcurrency_RecoversViaResignalAfterDataPathBreak(t *testing.T) {
+	dA, dB, wgA, wgB, lbB := pair(t)
+	defer dA.Stop()
+	defer dB.Stop()
+
+	// Tighten B's timings and make a single rotation miss raise OnRekeyFailed. Set
+	// before any exchange loop spawns (the loop reads these fields).
+	dB.retryInterval = 5 * time.Millisecond
+	dB.maxRetries = 2
+	dB.maxRekeyFailures = 1
+
+	bootstrap(t, dA, dB)
+	dA.OnDataPathRekeyed("bbbb", 0)
+	dB.OnDataPathRekeyed("aaaa", 0)
+	psk1 := wgB.psk("aaaa")
+	require.NotEqual(t, PSK{}, psk1)
+	require.Equal(t, psk1, wgA.psk("bbbb"), "converged on the same PSK after bootstrap+rotation")
+
+	// Data path breaks: the rotation can no longer converge -> OnRekeyFailed.
+	lbB.drop.Store(true)
+	_, err := dB.startExchange("aaaa", false, ExchangeID{})
+	require.NoError(t, err)
+	require.Eventually(t, func() bool { return failedCount(wgB) >= 1 }, time.Second, 5*time.Millisecond)
+
+	// Recovery: re-bootstrap over signalling with the data path STILL broken. It must
+	// still converge (signal is independent of the data path) on a fresh PSK.
+	bootstrap(t, dA, dB)
+	psk2 := wgB.psk("aaaa")
+	require.NotEqual(t, psk1, psk2, "recovery derived a fresh PSK")
+	require.Equal(t, psk2, wgA.psk("bbbb"), "both sides resync after recovery")
+}
+
+// TestConcurrency_ConcurrentRekeysNoRace hammers both managers with concurrent rotation
+// clocks from many goroutines. Its primary job (with -race) is to prove the single-lock
+// state machine has no data races or deadlocks under contention; a final deterministic
+// bootstrap then asserts there is no split-brain (both sides on the same PSK).
+func TestConcurrency_ConcurrentRekeysNoRace(t *testing.T) {
+	dA, dB, wgA, wgB, _ := pair(t)
+	defer dA.Stop()
+	defer dB.Stop()
+
+	bootstrap(t, dA, dB)
+
+	var wg sync.WaitGroup
+	for g := 0; g < 8; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < 50; i++ {
+				dB.OnDataPathRekeyed("aaaa", 0) // initiator chains a rotation
+				dA.OnDataPathRekeyed("bbbb", 0) // responder side is a no-op, still stresses the lock
+			}
+		}()
+	}
+	wg.Wait()
+
+	// The storm may leave an exchange mid-flight (concurrent cancellation). Force a
+	// clean convergence over signalling, then assert no split-brain.
+	bootstrap(t, dA, dB)
+	a, b := wgA.psk("bbbb"), wgB.psk("aaaa")
+	require.NotEqual(t, PSK{}, b)
+	require.Equal(t, a, b, "both sides converge on the same PSK, no split-brain")
+}

client/internal/pqkem/convergence.go

@@ -0,0 +1,273 @@
+package pqkem
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"time"
+)
+
+// idHex renders an exchange ID for logs.
+func idHex(id ExchangeID) string { return hex.EncodeToString(id[:]) }
+
+// pskFingerprint is a short, non-secret digest of a derived PSK: identical on both
+// peers iff they derived the same key. Logged instead of the raw PSK so debug logs
+// never carry the actual WireGuard preshared key.
+func pskFingerprint(psk PSK) string {
+	sum := sha256.Sum256(psk[:])
+	return hex.EncodeToString(sum[:8])
+}
+
+// startExchange creates a fresh initiator exchange (acknowledging ackID, zero for a
+// bootstrap) and returns the framed offer for the caller to send — pushed over the
+// data path for a chained rekey, or handed to the host for signalling when viaSignal
+// is set. Any previous in-flight exchange for the peer is cancelled.
+func (m *Manager) startExchange(remoteID RemoteID, viaSignal bool, ackID ExchangeID) ([]byte, error) {
+	init, err := NewInitiator()
+	if err != nil {
+		return nil, err
+	}
+	id, err := newExchangeID()
+	if err != nil {
+		return nil, err
+	}
+	raw, err := (&OfferMsg{ExchangeID: id, AckID: ackID, KEMOffer: init.Offer()}).Encode()
+	if err != nil {
+		return nil, err
+	}
+
+	ctx, cancel := context.WithCancel(m.rootCtx)
+	m.mu.Lock()
+	if old := m.exchanges[remoteID]; old != nil && old.cancel != nil {
+		old.cancel()
+	}
+	m.exchanges[remoteID] = &exchangeCtl{
+		id:        id,
+		state:     stateAwaitingAnswer,
+		startedAt: time.Now(),
+		cancel:    cancel,
+		lastSent:  raw,
+		initiator: init,
+		viaSignal: viaSignal,
+	}
+	m.mu.Unlock()
+
+	m.wait.Add(1)
+	go m.initiatorLoop(ctx, remoteID, id)
+
+	via := "data-path"
+	if viaSignal {
+		via = "signal"
+	}
+	m.trace("pqkem: offer sent", "peer", remoteID, "exchange", idHex(id), "acks", idHex(ackID), "via", via)
+	return raw, nil
+}
+
+// processOffer (responder) first acknowledges the previous exchange the offer names
+// (that offer riding the data path under the freshly adopted key proves it worked),
+// then derives the PSK for the new offer, commits it optimistically, and returns the
+// framed answer. A duplicate offer returns the cached answer without re-deriving.
+func (m *Manager) processOffer(remoteID RemoteID, o *OfferMsg) ([]byte, error) {
+	m.trace("pqkem: offer received", "peer", remoteID, "exchange", idHex(o.ExchangeID), "acks", idHex(o.AckID))
+
+	if o.AckID != (ExchangeID{}) {
+		m.ackConverged(remoteID, o.AckID)
+	}
+
+	m.mu.Lock()
+	if ex := m.exchanges[remoteID]; ex != nil && ex.id == o.ExchangeID {
+		state, last := ex.state, ex.lastSent
+		m.mu.Unlock()
+		if state == stateReserved {
+			return nil, nil
+		}
+		m.trace("pqkem: duplicate offer, resending cached answer", "peer", remoteID, "exchange", idHex(o.ExchangeID))
+		return last, nil
+	}
+	// Reserve the slot so a concurrent duplicate offer bails.
+	m.exchanges[remoteID] = &exchangeCtl{id: o.ExchangeID, state: stateReserved, startedAt: time.Now()}
+	m.mu.Unlock()
+
+	answerBytes, psk, err := Respond(o.KEMOffer, m.binding(remoteID))
+	if err != nil {
+		return nil, err
+	}
+	raw, err := (&AnswerMsg{ExchangeID: o.ExchangeID, KEMAnswer: answerBytes}).Encode()
+	if err != nil {
+		return nil, err
+	}
+
+	m.mu.Lock()
+	ex := m.exchanges[remoteID]
+	if ex == nil || ex.id != o.ExchangeID {
+		m.mu.Unlock()
+		m.trace("pqkem: exchange superseded during respond, dropping answer", "peer", remoteID, "exchange", idHex(o.ExchangeID))
+		return nil, nil
+	}
+	ex.state = stateAwaitingAck
+	ex.lastSent = raw
+	ex.pendingPSK = psk
+	m.psks[remoteID] = psk
+	m.capable[remoteID] = true // a real KEM offer proves the peer runs the exchange
+	m.mu.Unlock()
+
+	m.trace("pqkem: new PSK derived", "peer", remoteID, "exchange", idHex(o.ExchangeID), "role", "responder", "psk_fp", pskFingerprint(psk))
+
+	// Commit optimistically so our data path can rekey to the new PSK.
+	if err := m.cbHandler.OnNewPSKReady(remoteID, psk); err != nil {
+		return nil, err
+	}
+	m.trace("pqkem: answer sent", "peer", remoteID, "exchange", idHex(o.ExchangeID))
+	return raw, nil
+}
+
+// processAnswer (initiator) derives and commits the PSK and parks in
+// stateAwaitingRekey; the next offer (chained from OnDataPathRekeyed) will acknowledge
+// this exchange. Only valid in stateAwaitingAnswer; advancing the state under the
+// lock makes a concurrent/duplicate answer bail.
+func (m *Manager) processAnswer(remoteID RemoteID, a *AnswerMsg) error {
+	m.mu.Lock()
+	ex := m.exchanges[remoteID]
+	if ex == nil || ex.id != a.ExchangeID || ex.state != stateAwaitingAnswer {
+		haveID := "none"
+		if ex != nil {
+			haveID = idHex(ex.id)
+		}
+		m.mu.Unlock()
+		m.trace("pqkem: unexpected answer dropped (inconsistency)", "peer", remoteID, "answer_for", idHex(a.ExchangeID), "have_exchange", haveID)
+		return nil
+	}
+	ex.state = stateAwaitingRekey
+	init := ex.initiator
+	ex.initiator = nil
+	m.mu.Unlock()
+
+	m.trace("pqkem: answer received", "peer", remoteID, "exchange", idHex(a.ExchangeID))
+
+	psk, err := init.Finish(a.KEMAnswer, m.binding(remoteID))
+	if err != nil {
+		return err
+	}
+
+	// The initiator has converged: the responder must have derived the key to answer.
+	m.mu.Lock()
+	m.established[remoteID] = true
+	m.failures[remoteID] = 0
+	m.psks[remoteID] = psk
+	m.capable[remoteID] = true // a real KEM answer proves the peer runs the exchange
+	m.mu.Unlock()
+
+	m.trace("pqkem: new PSK derived", "peer", remoteID, "exchange", idHex(a.ExchangeID), "role", "initiator", "psk_fp", pskFingerprint(psk))
+
+	return m.cbHandler.OnNewPSKReady(remoteID, psk)
+}
+
+// ackConverged (responder) records convergence of the exchange named by ackID: a
+// later offer acknowledging it proves both sides operate on that exchange's key. Only
+// acts on a matching stateAwaitingAck exchange; anything else is ignored.
+func (m *Manager) ackConverged(remoteID RemoteID, ackID ExchangeID) {
+	m.mu.Lock()
+	ex := m.exchanges[remoteID]
+	if ex == nil || ex.id != ackID || ex.state != stateAwaitingAck {
+		m.mu.Unlock()
+		m.trace("pqkem: ack for unknown/mismatched exchange, ignored (inconsistency)", "peer", remoteID, "acks", idHex(ackID))
+		return
+	}
+	delete(m.exchanges, remoteID)
+	m.established[remoteID] = true
+	m.failures[remoteID] = 0
+	_ = time.Since(ex.startedAt) // convergence latency (metrics hook, later step)
+	m.mu.Unlock()
+
+	m.trace("pqkem: previous exchange confirmed by ack", "peer", remoteID, "exchange", idHex(ackID))
+}
+
+// initiatorLoop enforces the offer->answer convergence deadline and retransmits the
+// initiator's outstanding data-path offer while awaiting the answer (a
+// signalling-bootstrapped offer is retransmitted by the host, so it is not resent
+// here). Exhausting the deadline before the answer arrives is a failure. Once the
+// answer is in (state past awaitingAnswer) the loop exits: the next rotation is driven
+// by OnDataPathRekeyed, and the idle wait for it has no deadline.
+func (m *Manager) initiatorLoop(ctx context.Context, remoteID RemoteID, id ExchangeID) {
+	defer m.wait.Done()
+	t := time.NewTicker(m.retryInterval)
+	defer t.Stop()
+
+	attempts := 0
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			m.mu.Lock()
+			ex := m.exchanges[remoteID]
+			if ex == nil || ex.id != id {
+				m.mu.Unlock()
+				return
+			}
+
+			switch ex.state {
+			case stateAwaitingAnswer:
+				if attempts >= m.maxRetries {
+					delete(m.exchanges, remoteID)
+					initial := !m.established[remoteID]
+					fail := m.registerFailureLocked(remoteID)
+					m.mu.Unlock()
+					m.raiseFailure(remoteID, fail, initial)
+					return
+				}
+				viaSignal := ex.viaSignal
+				msg := ex.lastSent
+				attempts++
+				m.mu.Unlock()
+				if !viaSignal {
+					if err := m.pushDataPath(remoteID, msg); err != nil {
+						m.logger.Warn("pqkem: offer retransmit failed", "peer", remoteID, "err", err)
+					}
+				}
+
+			default:
+				// Past awaiting the answer (converged) or superseded: the loop's job
+				// is done. The next rotation is driven externally by OnDataPathRekeyed,
+				// so there is no deadline while idle-waiting for it (that wait can be
+				// as long as the transport's natural rekey interval).
+				m.mu.Unlock()
+				return
+			}
+		}
+	}
+}
+
+// registerFailureLocked applies policy B and reports whether OnRekeyFailed is due:
+// an initial exchange (peer never established) fails immediately; a rekey tolerates
+// up to maxRekeyFailures consecutive misses (we stay on the still-valid previous
+// PSK) before failing. Assumes m.mu is held.
+func (m *Manager) registerFailureLocked(remoteID RemoteID) bool {
+	if !m.established[remoteID] {
+		return true
+	}
+	m.failures[remoteID]++
+	if m.failures[remoteID] >= m.maxRekeyFailures {
+		m.failures[remoteID] = 0
+		return true
+	}
+	return false
+}
+
+// raiseFailure reports a convergence failure. initial distinguishes a never-established
+// peer (bootstrap failed → no PQ PSK at all; in strict mode the peer stays blocked =
+// "stuck") from a rekey failure (a previous PSK is still in force and traffic continues).
+func (m *Manager) raiseFailure(remoteID RemoteID, fail, initial bool) {
+	if !fail {
+		m.logger.Warn("pqkem: rekey attempt timed out, will retry next cycle", "peer", remoteID)
+		return
+	}
+	if initial {
+		m.logger.Warn("pqkem: initial exchange failed — no PQ PSK established for peer (strict mode keeps the peer blocked until it converges)", "peer", remoteID)
+	} else {
+		m.logger.Warn("pqkem: rekey failed after retries — staying on the previous PSK", "peer", remoteID)
+	}
+	if err := m.cbHandler.OnRekeyFailed(remoteID); err != nil {
+		m.logger.Error("pqkem: OnRekeyFailed handler error", "peer", remoteID, "err", err)
+	}
+}

client/internal/pqkem/convergence_test.go

@@ -0,0 +1,74 @@
+package pqkem
+
+import (
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// dropTransport is a pqkem.Transport that silently discards everything.
+type dropTransport struct{}
+
+func (dropTransport) Send(netip.AddrPort, []byte) error { return nil }
+func (dropTransport) LocalPort() int                    { return 0 }
+func (dropTransport) Run(func(netip.AddrPort, []byte))  {}
+func (dropTransport) Close() error                      { return nil }
+
+func failedCount(f *fakeWG) int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return len(f.failed)
+}
+
+func TestManager_InitialTimeoutFailsImmediately(t *testing.T) {
+	wg := newFakeWG()
+	d := NewManager("bbbb", wg, nil) // bbbb > aaaa -> initiator
+	d.Start(dropTransport{})
+	d.retryInterval = 5 * time.Millisecond
+	d.maxRetries = 3
+	defer d.Stop()
+
+	// Bootstrap offer is produced for signalling; no answer ever comes back -> the
+	// initial exchange fails fast.
+	offer, err := d.SignalOffer("aaaa")
+	require.NoError(t, err)
+	require.NotNil(t, offer)
+
+	require.Eventually(t, func() bool { return failedCount(wg) == 1 }, time.Second, 5*time.Millisecond)
+}
+
+func TestManager_RekeyToleratesKFailures(t *testing.T) {
+	dA, dB, _, wgB, lbB := pair(t)
+	defer dA.Stop()
+	defer dB.Stop()
+
+	// Tighten B's timings before any exchange loop spawns (the loop reads these
+	// fields, so writing them after a loop is running would race).
+	dB.retryInterval = 5 * time.Millisecond
+	dB.maxRetries = 2
+
+	// Establish: bootstrap + data-path-rekeyed so B becomes established and its data
+	// path is usable.
+	bootstrap(t, dA, dB)
+	dA.OnDataPathRekeyed("bbbb", 0)
+	dB.OnDataPathRekeyed("aaaa", 0)
+	require.NotEqual(t, PSK{}, wgB.psk("aaaa"))
+
+	// Drop B's outbound so rekeys can no longer converge.
+	lbB.drop.Store(true)
+
+	// K-1 data-path rekeys must NOT raise OnRekeyFailed.
+	for i := 0; i < DefaultMaxRekeyFailures-1; i++ {
+		_, err := dB.startExchange("aaaa", false, ExchangeID{})
+		require.NoError(t, err)
+		time.Sleep(50 * time.Millisecond)
+	}
+	require.Equal(t, 0, failedCount(wgB), "no failure before K attempts")
+
+	// The K-th failure raises it once.
+	_, err := dB.startExchange("aaaa", false, ExchangeID{})
+	require.NoError(t, err)
+	require.Eventually(t, func() bool { return failedCount(wgB) == 1 }, time.Second, 5*time.Millisecond)
+}

client/internal/pqkem/env.go

@@ -0,0 +1,138 @@
+package pqkem
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"strconv"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+)
+
+// EnvEnabled is the environment variable that turns the ML-KEM post-quantum
+// exchange on for this client. Accepts on/off aliases plus anything
+// strconv.ParseBool understands (true/false/1/0).
+const EnvEnabled = "NB_ENABLE_PQ_MLKEM"
+
+// Enabled reports whether the ML-KEM PQ exchange is enabled via the environment.
+// An empty or unrecognized value is treated as disabled.
+func Enabled() bool {
+	raw := strings.ToLower(strings.TrimSpace(os.Getenv(EnvEnabled)))
+	switch raw {
+	case "":
+		return false
+	case "on":
+		return true
+	case "off":
+		return false
+	}
+	enabled, err := strconv.ParseBool(raw)
+	if err != nil {
+		log.Warnf("failed to parse %s value %q: %v", EnvEnabled, raw, err)
+		return false
+	}
+	return enabled
+}
+
+// EnvStrict enables strict (fail-closed) mode: block peer traffic until the ML-KEM
+// PSK has been established, instead of the default opportunistic behaviour that lets
+// the tunnel come up classically and upgrades to PQ once the exchange converges.
+const EnvStrict = "NB_PQ_MLKEM_STRICT"
+
+// Strict reports whether strict (fail-closed) mode is enabled via the environment.
+// An empty or unrecognized value is treated as disabled (opportunistic).
+func Strict() bool {
+	switch strings.ToLower(strings.TrimSpace(os.Getenv(EnvStrict))) {
+	case "on":
+		return true
+	case "", "off":
+		return false
+	}
+	enabled, err := strconv.ParseBool(strings.TrimSpace(os.Getenv(EnvStrict)))
+	if err != nil {
+		log.Warnf("failed to parse %s value %q: %v", EnvStrict, os.Getenv(EnvStrict), err)
+		return false
+	}
+	return enabled
+}
+
+// EnvLogLevel overrides the ML-KEM manager's slog level (trace/debug/info/warn/error).
+// Defaults to info. The verbose per-exchange lifecycle logs are emitted at trace.
+const EnvLogLevel = "NB_PQ_MLKEM_LOG_LEVEL"
+
+// LevelTrace is a custom slog level below Debug for the verbose per-exchange lifecycle
+// logs, so they stay off unless NB_PQ_MLKEM_LOG_LEVEL=trace (and the daemon log level
+// is trace, since the records are forwarded to logrus).
+const LevelTrace = slog.LevelDebug - 4
+
+// NewLogger builds the slog logger for the ML-KEM manager. It forwards records to
+// logrus so PQ logs land in the same sink as the rest of the daemon (console +
+// client.log) rather than stdout. Verbosity is gated by EnvLogLevel.
+func NewLogger() *slog.Logger {
+	return slog.New(slogToLogrus{})
+}
+
+func logLevel() slog.Level {
+	switch strings.ToLower(strings.TrimSpace(os.Getenv(EnvLogLevel))) {
+	case "trace":
+		return LevelTrace
+	case "debug":
+		return slog.LevelDebug
+	case "warn":
+		return slog.LevelWarn
+	case "error":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo
+	}
+}
+
+// slogToLogrus is a slog.Handler that forwards records to logrus, so the ML-KEM
+// manager's logs go wherever the daemon's logrus is configured (console + client.log)
+// instead of stdout. Verbosity is gated by EnvLogLevel via logLevel().
+type slogToLogrus struct {
+	fields log.Fields
+}
+
+func (h slogToLogrus) Enabled(_ context.Context, level slog.Level) bool {
+	return level >= logLevel()
+}
+
+func (h slogToLogrus) Handle(_ context.Context, r slog.Record) error {
+	fields := make(log.Fields, len(h.fields)+r.NumAttrs())
+	for k, v := range h.fields {
+		fields[k] = v
+	}
+	r.Attrs(func(a slog.Attr) bool {
+		fields[a.Key] = a.Value.Any()
+		return true
+	})
+	entry := log.WithFields(fields)
+	switch {
+	case r.Level >= slog.LevelError:
+		entry.Error(r.Message)
+	case r.Level >= slog.LevelWarn:
+		entry.Warn(r.Message)
+	case r.Level >= slog.LevelInfo:
+		entry.Info(r.Message)
+	case r.Level >= slog.LevelDebug:
+		entry.Debug(r.Message)
+	default:
+		entry.Trace(r.Message)
+	}
+	return nil
+}
+
+func (h slogToLogrus) WithAttrs(attrs []slog.Attr) slog.Handler {
+	fields := make(log.Fields, len(h.fields)+len(attrs))
+	for k, v := range h.fields {
+		fields[k] = v
+	}
+	for _, a := range attrs {
+		fields[a.Key] = a.Value.Any()
+	}
+	return slogToLogrus{fields: fields}
+}
+
+func (h slogToLogrus) WithGroup(_ string) slog.Handler { return h }

client/internal/pqkem/kem.go

@@ -0,0 +1,178 @@
+// Package pqkem is a spike (NET-1406) for a post-quantum pre-shared-key exchange
+// that could replace Rosenpass. It performs an X25519MLKEM768 hybrid key
+// encapsulation and derives a 32-byte pre-shared key (PSK).
+//
+// The exchange is a single round trip designed to ride the (already
+// authenticated) Signal offer/answer channel:
+//
+//	initiator --Offer(1216B)--> responder
+//	initiator <--Answer(1120B)-- responder
+//
+// Both sides then hold the same PSK, which is bound to the two peers' identities
+// (their peer identity keys) so the derived key cannot be transplanted
+// to a different peer pair even if the transport authentication were bypassed.
+//
+// Combiner note: this follows draft-ietf-tls-ecdhe-mlkem for X25519MLKEM768 — on
+// the wire ML-KEM ‖ X25519 (the draft deliberately reversed the share order for
+// this group), and ML-KEM_ss ‖ X25519_ss as the KDF input. The PSK is derived with
+// HKDF-SHA256 over that hybrid secret, salted with a domain-separation label and
+// bound (via the HKDF info) to the full transcript and the canonicalised peer
+// identities.
+package pqkem
+
+import (
+	"crypto/ecdh"
+	"crypto/hkdf"
+	"crypto/mlkem"
+	"crypto/rand"
+	"crypto/sha256"
+	"fmt"
+)
+
+const (
+	// OfferSize is the initiator message: ML-KEM-768 encapsulation key ‖ X25519 public key
+	// (share order per draft-ietf-tls-ecdhe-mlkem for X25519MLKEM768).
+	OfferSize = mlkem.EncapsulationKeySize768 + 32 // 1216
+	// AnswerSize is the responder message: ML-KEM-768 ciphertext ‖ X25519 public key.
+	AnswerSize = mlkem.CiphertextSize768 + 32 // 1120
+
+	pskLabel = "netbird-pq-psk-v1"
+)
+
+// PSK is the 32-byte derived pre-shared key handed to the consumer to key its channel.
+type PSK [32]byte
+
+// Binding identifies the peer pair the PSK is derived for. Callers set both
+// peer identity keys; the order does not matter (it is canonicalised).
+type Binding struct {
+	LocalID  []byte
+	RemoteID []byte
+}
+
+// Initiator holds the ephemeral secrets between Offer and Finish.
+type Initiator struct {
+	x25519  *ecdh.PrivateKey
+	mlkemDK *mlkem.DecapsulationKey768
+	offer   []byte
+}
+
+// NewInitiator generates the ephemeral X25519 + ML-KEM-768 keypairs.
+func NewInitiator() (*Initiator, error) {
+	x, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return nil, fmt.Errorf("x25519 keygen: %w", err)
+	}
+	dk, err := mlkem.GenerateKey768()
+	if err != nil {
+		return nil, fmt.Errorf("ml-kem keygen: %w", err)
+	}
+
+	offer := make([]byte, 0, OfferSize)
+	offer = append(offer, dk.EncapsulationKey().Bytes()...)
+	offer = append(offer, x.PublicKey().Bytes()...)
+
+	return &Initiator{x25519: x, mlkemDK: dk, offer: offer}, nil
+}
+
+// Offer returns the initiator message to send over Signal.
+func (i *Initiator) Offer() []byte {
+	return i.offer
+}
+
+// Finish consumes the responder's answer and derives the PSK.
+func (i *Initiator) Finish(answer []byte, b Binding) (PSK, error) {
+	if len(answer) != AnswerSize {
+		return PSK{}, fmt.Errorf("answer: got %d bytes, want %d", len(answer), AnswerSize)
+	}
+	ct := answer[:mlkem.CiphertextSize768]
+	peerX := answer[mlkem.CiphertextSize768:]
+
+	ssMLKEM, err := i.mlkemDK.Decapsulate(ct)
+	if err != nil {
+		return PSK{}, fmt.Errorf("ml-kem decapsulate: %w", err)
+	}
+	pub, err := ecdh.X25519().NewPublicKey(peerX)
+	if err != nil {
+		return PSK{}, fmt.Errorf("parse peer x25519: %w", err)
+	}
+	ssX, err := i.x25519.ECDH(pub)
+	if err != nil {
+		return PSK{}, fmt.Errorf("x25519 ecdh: %w", err)
+	}
+
+	return derivePSK(ssMLKEM, ssX, i.offer, answer, b)
+}
+
+// Respond consumes an initiator offer, produces the answer, and derives the PSK.
+func Respond(offer []byte, b Binding) (answer []byte, psk PSK, err error) {
+	if len(offer) != OfferSize {
+		return nil, PSK{}, fmt.Errorf("offer: got %d bytes, want %d", len(offer), OfferSize)
+	}
+	peerEK := offer[:mlkem.EncapsulationKeySize768]
+	peerX := offer[mlkem.EncapsulationKeySize768:]
+
+	ek, err := mlkem.NewEncapsulationKey768(peerEK)
+	if err != nil {
+		return nil, PSK{}, fmt.Errorf("parse peer ml-kem key: %w", err)
+	}
+	ssMLKEM, ct := ek.Encapsulate()
+
+	x, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		return nil, PSK{}, fmt.Errorf("x25519 keygen: %w", err)
+	}
+	pub, err := ecdh.X25519().NewPublicKey(peerX)
+	if err != nil {
+		return nil, PSK{}, fmt.Errorf("parse peer x25519: %w", err)
+	}
+	ssX, err := x.ECDH(pub)
+	if err != nil {
+		return nil, PSK{}, fmt.Errorf("x25519 ecdh: %w", err)
+	}
+
+	answer = make([]byte, 0, AnswerSize)
+	answer = append(answer, ct...)
+	answer = append(answer, x.PublicKey().Bytes()...)
+
+	// derivePSK uses the same argument order on both sides; the responder's local
+	// binding is the mirror of the initiator's, canonicalised inside derivePSK.
+	psk, err = derivePSK(ssMLKEM, ssX, offer, answer, b)
+	if err != nil {
+		return nil, PSK{}, err
+	}
+	return answer, psk, nil
+}
+
+// derivePSK runs HKDF-SHA256 over the hybrid shared secret (ML-KEM_ss ‖ X25519_ss,
+// per draft-ietf-tls-ecdhe-mlkem), salted with the domain-separation label, and binds
+// the result — via the HKDF info — to the full transcript (offer ‖ answer) and the
+// canonicalised peer identities, so the PSK cannot be transplanted to another peer
+// pair or a different exchange.
+func derivePSK(ssMLKEM, ssX, offer, answer []byte, b Binding) (PSK, error) {
+	lo, hi := canonicalPair(b.LocalID, b.RemoteID)
+
+	ikm := make([]byte, 0, len(ssMLKEM)+len(ssX))
+	ikm = append(ikm, ssMLKEM...)
+	ikm = append(ikm, ssX...)
+
+	info := make([]byte, 0, len(offer)+len(answer)+len(lo)+len(hi))
+	info = append(info, offer...)
+	info = append(info, answer...)
+	info = append(info, lo...)
+	info = append(info, hi...)
+
+	var psk PSK
+	key, err := hkdf.Key(sha256.New, ikm, []byte(pskLabel), string(info), len(psk))
+	if err != nil {
+		return PSK{}, fmt.Errorf("hkdf derive psk: %w", err)
+	}
+	copy(psk[:], key)
+	return psk, nil
+}
+
+func canonicalPair(a, b []byte) (lo, hi []byte) {
+	if string(a) <= string(b) {
+		return a, b
+	}
+	return b, a
+}

client/internal/pqkem/kem_framing_test.go

@@ -0,0 +1,105 @@
+package pqkem
+
+import (
+	"crypto/mlkem"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestExchange_TamperedCiphertextFailsClosed verifies the core fail-closed
+// property: mutating the ML-KEM ciphertext in the answer does not error (ML-KEM
+// uses implicit rejection — Decapsulate always returns a value) but yields a
+// different shared secret, so the initiator derives a PSK that does NOT match the
+// responder's. A mismatched PSK means WireGuard passes no bytes: tamper => no data.
+func TestExchange_TamperedCiphertextFailsClosed(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+
+	answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+
+	tampered := append([]byte(nil), answer...)
+	tampered[0] ^= 0xff // flip a bit in the ML-KEM ciphertext
+
+	pskA, err := init.Finish(tampered, Binding{LocalID: wgA, RemoteID: wgB})
+	require.NoError(t, err, "implicit rejection: decapsulate still succeeds")
+	require.NotEqual(t, pskB, pskA, "tampered ciphertext must not yield the responder's PSK")
+}
+
+// TestExchange_TamperedX25519ShareDiverges flips a byte in the answer's X25519
+// share: the classical half of the hybrid secret changes, so the derived PSK
+// diverges from the responder's (fail-closed on the ECDH half too).
+func TestExchange_TamperedX25519ShareDiverges(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+
+	answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+
+	tampered := append([]byte(nil), answer...)
+	tampered[mlkem.CiphertextSize768] ^= 0x01 // first byte of the X25519 public key
+
+	pskA, err := init.Finish(tampered, Binding{LocalID: wgA, RemoteID: wgB})
+	// Either the point is rejected (error) or the ECDH differs (different PSK);
+	// in both cases the honest PSK is never reproduced.
+	if err == nil {
+		require.NotEqual(t, pskB, pskA, "tampered X25519 share must not yield the responder's PSK")
+	}
+}
+
+// TestExchange_AllZeroX25519Rejected feeds an all-zero X25519 share (a low-order
+// point) in the answer. The stdlib ECDH must reject it, so Finish errors rather
+// than deriving a PSK from a degenerate secret.
+func TestExchange_AllZeroX25519Rejected(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+
+	answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+
+	bad := append([]byte(nil), answer...)
+	for i := mlkem.CiphertextSize768; i < len(bad); i++ {
+		bad[i] = 0
+	}
+
+	_, err = init.Finish(bad, Binding{LocalID: wgA, RemoteID: wgB})
+	require.Error(t, err, "all-zero X25519 share (low-order point) must be rejected")
+}
+
+// TestExchange_SizeBoundaries locks the exact-length framing checks: one byte
+// short or long on either message is rejected, not silently truncated/padded.
+func TestExchange_SizeBoundaries(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+	offer := init.Offer()
+
+	_, _, err = Respond(offer[:OfferSize-1], Binding{})
+	require.Error(t, err, "offer one byte short")
+	_, _, err = Respond(append(append([]byte(nil), offer...), 0), Binding{})
+	require.Error(t, err, "offer one byte long")
+
+	answer, _, err := Respond(offer, Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+
+	_, err = init.Finish(answer[:AnswerSize-1], Binding{LocalID: wgA, RemoteID: wgB})
+	require.Error(t, err, "answer one byte short")
+	_, err = init.Finish(append(append([]byte(nil), answer...), 0), Binding{LocalID: wgA, RemoteID: wgB})
+	require.Error(t, err, "answer one byte long")
+}
+
+// TestExchange_BindingIsSymmetric confirms the canonicalisation: the two peers
+// pass their identities in opposite (Local, Remote) order yet derive the same PSK,
+// so identity binding does not depend on who is initiator vs responder.
+func TestExchange_BindingIsSymmetric(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+
+	answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+
+	pskA, err := init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgB})
+	require.NoError(t, err)
+
+	require.Equal(t, pskB, pskA, "swapped Local/Remote order must canonicalise to the same PSK")
+}

client/internal/pqkem/kem_test.go

@@ -0,0 +1,89 @@
+package pqkem
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	wgA = []byte("peer-A-wireguard-pubkey-32bytes!")
+	wgB = []byte("peer-B-wireguard-pubkey-32bytes!")
+)
+
+func TestExchange_DerivesMatchingPSK(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+
+	require.Len(t, init.Offer(), OfferSize)
+
+	answer, pskB, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+	require.Len(t, answer, AnswerSize)
+
+	pskA, err := init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgB})
+	require.NoError(t, err)
+
+	require.Equal(t, pskB, pskA, "both sides must derive the same PSK")
+	require.NotEqual(t, PSK{}, pskA, "PSK must not be zero")
+}
+
+func TestExchange_PSKBoundToPeerIdentities(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+
+	// responder computes with the honest pair...
+	_, pskHonest, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+
+	// ...a second responder run with a different peer identity yields a different PSK,
+	// even though the KEM material would otherwise combine identically.
+	wgC := []byte("peer-C-wireguard-pubkey-32bytes!")
+	_, pskWrong, err := Respond(init.Offer(), Binding{LocalID: wgC, RemoteID: wgA})
+	require.NoError(t, err)
+
+	require.NotEqual(t, pskHonest, pskWrong, "PSK must be bound to the peer pair")
+}
+
+func TestExchange_RejectsMalformedMessages(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+
+	_, _, err = Respond(init.Offer()[:10], Binding{})
+	require.Error(t, err)
+
+	_, err = init.Finish([]byte("too short"), Binding{})
+	require.Error(t, err)
+}
+
+// TestExchange_ReportSizesAndTiming is a spike measurement, not a pass/fail gate.
+// Run with: go test -run TestExchange_ReportSizesAndTiming -v ./client/internal/pqkem/
+func TestExchange_ReportSizesAndTiming(t *testing.T) {
+	const iters = 200
+
+	var tInit, tResp, tFinish time.Duration
+	for i := 0; i < iters; i++ {
+		s0 := time.Now()
+		init, err := NewInitiator()
+		require.NoError(t, err)
+		tInit += time.Since(s0)
+
+		s1 := time.Now()
+		answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+		require.NoError(t, err)
+		tResp += time.Since(s1)
+
+		s2 := time.Now()
+		_, err = init.Finish(answer, Binding{LocalID: wgA, RemoteID: wgB})
+		require.NoError(t, err)
+		tFinish += time.Since(s2)
+	}
+
+	t.Logf("wire sizes:   offer=%d B   answer=%d B   (Rosenpass static pubkey ~524160 B)", OfferSize, AnswerSize)
+	t.Logf("total on-wire per handshake: %d B  (~%.0fx smaller than RP static key)", OfferSize+AnswerSize, 524160.0/float64(OfferSize+AnswerSize))
+	t.Logf("avg NewInitiator (keygen): %s", tInit/iters)
+	t.Logf("avg Respond (encaps+dh):   %s", tResp/iters)
+	t.Logf("avg Finish (decaps+dh):    %s", tFinish/iters)
+	t.Logf("avg full handshake CPU:    %s", (tInit+tResp+tFinish)/iters)
+}

client/internal/pqkem/manager.go

@@ -0,0 +1,460 @@
+package pqkem
+
+import (
+	"context"
+	"crypto/rand"
+	"fmt"
+	"log/slog"
+	"net/netip"
+	"sync"
+	"time"
+)
+
+const (
+	// DefaultRetryInterval is how often the initiator retransmits its outstanding
+	// data-path offer while awaiting the answer.
+	DefaultRetryInterval = 2 * time.Second
+	// DefaultMaxRetries bounds how many ticks an exchange may run before it is
+	// declared failed. The convergence deadline is thus MaxRetries * RetryInterval.
+	DefaultMaxRetries = 10
+	// DefaultMaxRekeyFailures is how many consecutive rekey (non-initial) failures
+	// are tolerated before OnRekeyFailed. The initial exchange fails immediately.
+	DefaultMaxRekeyFailures = 3
+
+	// rotationActivityWindow gates rotation on recent real-data activity: a rekey
+	// clocks a rotation only if the peer exchanged user data within this window. It
+	// must stay shorter than the data path's rekey interval (WireGuard
+	// REKEY_AFTER_TIME ~120s) so the rotation's own traffic — which itself renews the
+	// activity signal — ages out before the next rekey, letting an idle tunnel stop
+	// rotating instead of self-sustaining.
+	rotationActivityWindow = 90 * time.Second
+)
+
+// LocalID and RemoteID are peer identity keys (e.g. WireGuard public keys). They are
+// distinct types so the local and a remote identity cannot be mixed up.
+type (
+	LocalID  string
+	RemoteID string
+)
+
+// Transport is the data-path socket the Manager drives (the analogue of
+// go-rosenpass's Conn). It is a dumb mover of bytes to/from endpoints: the Manager
+// owns the remoteID<->endpoint routing and hands the transport a resolved endpoint
+// to Send, and reverse-resolves the source of each inbound datagram. Its lifecycle
+// belongs to the Manager (Run at Start, Close at Stop).
+type Transport interface {
+	// Send delivers msg to the given data-path endpoint.
+	Send(endpoint netip.AddrPort, msg []byte) error
+	// LocalPort is the bound local UDP port, announced to peers so they know where
+	// to send data-path messages.
+	LocalPort() int
+	// Run starts delivering inbound datagrams as (source endpoint, msg) to onInbound
+	// and returns immediately; it runs until Close.
+	Run(onInbound func(src netip.AddrPort, msg []byte))
+	// Close stops delivery and releases the socket.
+	Close() error
+}
+
+// exchangeState is the single source of truth for an exchange's role and phase.
+type exchangeState uint8
+
+const (
+	stateReserved       exchangeState = iota // responder: deriving the answer
+	stateAwaitingAnswer                      // initiator: offer sent, awaiting the answer
+	stateAwaitingRekey                       // initiator: PSK derived+set, awaiting OnDataPathRekeyed to chain the next offer
+	stateAwaitingAck                         // responder: answer sent, awaiting the next offer that acks this exchange
+)
+
+// exchangeCtl holds all state for one in-flight exchange with a peer, under the
+// Manager's single lock. state drives every decision. lastSent is the current
+// data-path retransmit payload (the offer, for the initiator). initiator is the
+// ephemeral handle used at Finish; pendingPSK is the responder's derived key.
+// viaSignal records that the offer went to the host for the signalling channel, so
+// the loop does not retransmit it on the data path. Only the initiator runs a
+// retransmit loop, so only it sets cancel.
+type exchangeCtl struct {
+	id         ExchangeID
+	state      exchangeState
+	startedAt  time.Time
+	cancel     context.CancelFunc
+	lastSent   []byte
+	initiator  *Initiator
+	pendingPSK PSK
+	viaSignal  bool
+}
+
+// Manager is the stateful orchestrator — the analogue of go-rosenpass's Server. It
+// drives the X25519MLKEM768 exchange, owns the peer endpoint routing and the data-path
+// transport, and surfaces the derived PSK and convergence to the host via
+// CallbackHandler. It is event-driven: the bootstrap is triggered by the host
+// (SignalOffer) and each rotation is clocked by OnDataPathRekeyed. The cryptography is
+// the pure kem.go primitives; all state lives here under one lock.
+type Manager struct {
+	localID   LocalID
+	cbHandler CallbackHandler
+	logger    *slog.Logger
+
+	retryInterval    time.Duration
+	maxRetries       int
+	maxRekeyFailures int
+
+	rootCtx    context.Context
+	rootCancel context.CancelFunc
+
+	mu          sync.Mutex
+	transport   Transport
+	exchanges   map[RemoteID]*exchangeCtl   // in-flight exchange per peer
+	established map[RemoteID]bool           // peer has completed at least one exchange
+	failures    map[RemoteID]int            // consecutive rekey failures per peer
+	psks        map[RemoteID]PSK            // latest derived PSK per peer (pulled at WG peer-config time)
+	capable     map[RemoteID]bool           // peer runs the KEM (advertised a PQ port); false = known non-capable
+	peerAddrs   map[RemoteID]netip.AddrPort // remoteID -> data-path endpoint (send routing)
+	peersByAddr map[netip.AddrPort]RemoteID // reverse: source endpoint -> remoteID (inbound)
+	wait        sync.WaitGroup
+}
+
+// NewManager builds a manager for the local peer identified by its peer identity key
+// (used for the deterministic initiator role and the identity binding). A nil logger
+// falls back to slog.Default(). Install the data-path transport with Start.
+func NewManager(localID LocalID, h CallbackHandler, logger *slog.Logger) *Manager {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	return &Manager{
+		localID:          localID,
+		cbHandler:        h,
+		logger:           logger,
+		retryInterval:    DefaultRetryInterval,
+		maxRetries:       DefaultMaxRetries,
+		maxRekeyFailures: DefaultMaxRekeyFailures,
+		rootCtx:          ctx,
+		rootCancel:       cancel,
+		exchanges:        make(map[RemoteID]*exchangeCtl),
+		established:      make(map[RemoteID]bool),
+		failures:         make(map[RemoteID]int),
+		psks:             make(map[RemoteID]PSK),
+		capable:          make(map[RemoteID]bool),
+		peerAddrs:        make(map[RemoteID]netip.AddrPort),
+		peersByAddr:      make(map[netip.AddrPort]RemoteID),
+	}
+}
+
+// Start installs the data-path transport and begins its inbound delivery. The Manager
+// owns it from here; Stop closes it.
+func (m *Manager) Start(t Transport) {
+	m.mu.Lock()
+	m.transport = t
+	m.mu.Unlock()
+	if t != nil {
+		t.Run(m.onDataPathInbound)
+	}
+}
+
+// LocalPort is the data-path transport's bound UDP port (0 if no transport), to be
+// announced to peers.
+func (m *Manager) LocalPort() int {
+	m.mu.Lock()
+	t := m.transport
+	m.mu.Unlock()
+	if t == nil {
+		return 0
+	}
+	return t.LocalPort()
+}
+
+// IsInitiator reports whether the local peer drives the exchange for this remote
+// peer. Roles are deterministic (lexicographic identity-key compare) so exactly one
+// side initiates, mirroring how Rosenpass picks its handshake initiator.
+func (m *Manager) IsInitiator(remoteID RemoteID) bool {
+	return string(m.localID) > string(remoteID)
+}
+
+// PSK returns the latest PSK derived for the peer, for the host to program at WG
+// peer-config time (the pull path). ok is false until an exchange has derived one.
+func (m *Manager) PSK(remoteID RemoteID) (PSK, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	psk, ok := m.psks[remoteID]
+	return psk, ok
+}
+
+// trace logs at LevelTrace, the verbose per-exchange lifecycle level gated by
+// NB_PQ_MLKEM_LOG_LEVEL=trace.
+func (m *Manager) trace(msg string, args ...any) {
+	m.logger.Log(context.Background(), LevelTrace, msg, args...)
+}
+
+// AddPeer registers where a peer's data-path messages are sent and received: its
+// overlay endpoint (IP:port). This is pure routing and says nothing about capability —
+// PQ capability is decided solely from the peer's KEM payload (see processOffer /
+// processAnswer / MarkNonCapable), never from an endpoint or port.
+func (m *Manager) AddPeer(remoteID RemoteID, endpoint netip.AddrPort) {
+	if !endpoint.IsValid() {
+		return
+	}
+	m.mu.Lock()
+	if old, ok := m.peerAddrs[remoteID]; ok {
+		delete(m.peersByAddr, old)
+	}
+	m.peerAddrs[remoteID] = endpoint
+	m.peersByAddr[endpoint] = remoteID
+	m.mu.Unlock()
+}
+
+// MarkNonCapable records that a peer does not run the KEM: it answered our offer with
+// no KEM material over signalling (the capability signal is the peer's payload, not its
+// optional data-path port). Any in-flight exchange is cancelled and further offers are
+// suppressed (see SignalOffer), so a non-PQ peer never drives the rekey-recovery storm.
+// An already-established peer is left untouched — a stray empty answer must not tear
+// down a working PQ session.
+func (m *Manager) MarkNonCapable(remoteID RemoteID) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.established[remoteID] {
+		return
+	}
+	if prev, ok := m.capable[remoteID]; ok && !prev {
+		return // already known non-capable, nothing to do
+	}
+	m.capable[remoteID] = false
+	if ex := m.exchanges[remoteID]; ex != nil {
+		if ex.cancel != nil {
+			ex.cancel()
+		}
+		delete(m.exchanges, remoteID)
+	}
+	m.trace("pqkem: peer advertises no PQ service — treating as non-capable, no KEM attempted", "peer", remoteID)
+}
+
+// RemovePeer stops any in-flight exchange for a peer and drops its state and routing.
+func (m *Manager) RemovePeer(remoteID RemoteID) {
+	m.mu.Lock()
+	if ex, ok := m.exchanges[remoteID]; ok {
+		if ex.cancel != nil {
+			ex.cancel()
+		}
+		delete(m.exchanges, remoteID)
+	}
+	delete(m.established, remoteID)
+	delete(m.failures, remoteID)
+	delete(m.psks, remoteID)
+	delete(m.capable, remoteID)
+	if ep, ok := m.peerAddrs[remoteID]; ok {
+		delete(m.peersByAddr, ep)
+		delete(m.peerAddrs, remoteID)
+	}
+	m.mu.Unlock()
+}
+
+// Stop cancels all in-flight exchanges, closes the transport, and waits for the
+// exchange goroutines to exit.
+func (m *Manager) Stop() {
+	m.rootCancel()
+	m.wait.Wait()
+	m.mu.Lock()
+	t := m.transport
+	m.transport = nil
+	m.exchanges = make(map[RemoteID]*exchangeCtl)
+	m.psks = make(map[RemoteID]PSK)
+	m.mu.Unlock()
+	if t != nil {
+		if err := t.Close(); err != nil {
+			m.logger.Warn("pqkem: closing data-path transport", "err", err)
+		}
+	}
+}
+
+// ---- Signalling channel (host-driven; rides the host's negotiation) ----
+
+// SignalOffer returns the KEM offer for the host to embed in its outgoing offer to
+// remoteID (bootstrap). It returns (nil, nil) when the local peer is not the
+// initiator. It is idempotent for an in-flight bootstrap: a repeat call returns the
+// same offer rather than starting a new exchange.
+//
+// A signal re-negotiation always re-bootstraps (fresh exchange): the remote may have
+// restarted and lost its PSK, so reusing a locally frozen one would desync. The derived
+// PSK still survives idle in the manager (dropped only on account-level peer removal),
+// so a pure lazy wake with no re-negotiation reuses it via the conn's WG-config pull.
+func (m *Manager) SignalOffer(remoteID RemoteID) ([]byte, error) {
+	if !m.IsInitiator(remoteID) {
+		return nil, nil
+	}
+	m.mu.Lock()
+	if capable, ok := m.capable[remoteID]; ok && !capable {
+		m.mu.Unlock()
+		return nil, nil // peer does not run the KEM; do not offer (avoids a failure/reoffer loop)
+	}
+	// Idempotent while a signalling bootstrap is in flight OR already derived a PSK but
+	// not yet chained a rotation (awaitingRekey): return the SAME offer instead of
+	// starting a new exchange. This matters when the controller both offers on its own
+	// guard AND re-offers in response to the responder's offer — without this, the
+	// second call would start a fresh exchange (a different PSK) and desync the peers.
+	if ex := m.exchanges[remoteID]; ex != nil && ex.viaSignal &&
+		(ex.state == stateAwaitingAnswer || ex.state == stateAwaitingRekey) {
+		last := ex.lastSent
+		m.mu.Unlock()
+		return last, nil
+	}
+	m.mu.Unlock()
+	// bootstrap offer acknowledges nothing (zero AckID).
+	return m.startExchange(remoteID, true, ExchangeID{})
+}
+
+// ShouldSendBootstrapOffer reports whether we should emit a fresh KEM offer to kick a
+// bootstrap for this peer. True only if we are the initiator, the peer is not known
+// non-capable, and no exchange is already in flight. The host uses this when it (as the
+// controller) receives the responder's offer: it replies with a KEM offer exactly once
+// to start the exchange, and ignores further responder offers while one is in flight,
+// avoiding an offer-per-offer runaway.
+func (m *Manager) ShouldSendBootstrapOffer(remoteID RemoteID) bool {
+	if !m.IsInitiator(remoteID) {
+		return false
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if capable, ok := m.capable[remoteID]; ok && !capable {
+		return false
+	}
+	return m.exchanges[remoteID] == nil
+}
+
+// SignalOnOffer processes a KEM offer the host extracted from an incoming offer and
+// returns the KEM answer for the host to embed in its outgoing answer.
+func (m *Manager) SignalOnOffer(remoteID RemoteID, offer []byte) ([]byte, error) {
+	typ, msg, err := Decode(offer)
+	if err != nil {
+		return nil, fmt.Errorf("decode signal offer from %s: %w", remoteID, err)
+	}
+	if typ != MsgOffer {
+		return nil, fmt.Errorf("expected offer from %s, got type %d", remoteID, typ)
+	}
+	return m.processOffer(remoteID, msg.(*OfferMsg))
+}
+
+// SignalOnAnswer processes a KEM answer the host extracted from an incoming answer.
+// There is no reply: the next offer (over the data path) acknowledges this exchange.
+func (m *Manager) SignalOnAnswer(remoteID RemoteID, answer []byte) error {
+	typ, msg, err := Decode(answer)
+	if err != nil {
+		return fmt.Errorf("decode signal answer from %s: %w", remoteID, err)
+	}
+	if typ != MsgAnswer {
+		return fmt.Errorf("expected answer from %s, got type %d", remoteID, typ)
+	}
+	return m.processAnswer(remoteID, msg.(*AnswerMsg))
+}
+
+// ---- Data path ----
+
+// onDataPathInbound is the transport's inbound handler: it reverse-resolves the
+// source endpoint to a peer and dispatches. Unknown sources are dropped.
+func (m *Manager) onDataPathInbound(src netip.AddrPort, msg []byte) {
+	m.mu.Lock()
+	remoteID, ok := m.peersByAddr[src]
+	m.mu.Unlock()
+	if !ok {
+		return
+	}
+	if err := m.OnDataPathMessage(remoteID, msg); err != nil {
+		m.trace("pqkem: inbound", "peer", remoteID, "err", err)
+	}
+}
+
+// OnDataPathMessage handles a KEM message received over the data path from remoteID
+// and pushes any reply back over the data path.
+func (m *Manager) OnDataPathMessage(remoteID RemoteID, raw []byte) error {
+	typ, msg, err := Decode(raw)
+	if err != nil {
+		return fmt.Errorf("decode data-path msg from %s: %w", remoteID, err)
+	}
+	switch typ {
+	case MsgOffer:
+		answer, err := m.processOffer(remoteID, msg.(*OfferMsg))
+		if err != nil {
+			return err
+		}
+		if answer == nil {
+			return nil
+		}
+		return m.pushDataPath(remoteID, answer)
+	case MsgAnswer:
+		return m.processAnswer(remoteID, msg.(*AnswerMsg))
+	default:
+		return fmt.Errorf("unhandled data-path message type %d from %s", typ, remoteID)
+	}
+}
+
+// OnDataPathRekeyed clocks the next chained PSK rotation on a fresh data-path rekey
+// (fired on first establishment AND every rekey). If we are the initiator that just
+// derived a PSK, it chains the next exchange: a fresh offer over the data path that
+// acknowledges the just-completed one (its arrival under the new key proves to the
+// responder the key works). sinceActivity is how long ago the peer last exchanged real
+// user data; past rotationActivityWindow the tunnel is treated as idle and rotation is
+// skipped — an idle tunnel has nothing to protect, and rotating would emit data-path
+// traffic that keeps the peer artificially active (see conn.onWGCheckSuccess).
+func (m *Manager) OnDataPathRekeyed(remoteID RemoteID, sinceActivity time.Duration) {
+	if sinceActivity >= rotationActivityWindow {
+		m.trace("pqkem: peer idle, skipping data-path rotation", "peer", remoteID, "since_activity", sinceActivity)
+		return
+	}
+
+	m.mu.Lock()
+	ex := m.exchanges[remoteID]
+	chain := ex != nil && ex.state == stateAwaitingRekey
+	var ackID ExchangeID
+	if chain {
+		ackID = ex.id
+	}
+	m.mu.Unlock()
+
+	m.trace("pqkem: data-path rekey signal", "peer", remoteID, "chaining", chain)
+	if !chain {
+		return
+	}
+	offer, err := m.startExchange(remoteID, false, ackID)
+	if err != nil {
+		m.logger.Error("pqkem: chain offer failed to start", "peer", remoteID, "err", err)
+		return
+	}
+	if err := m.pushDataPath(remoteID, offer); err != nil {
+		m.logger.Warn("pqkem: send chain offer failed", "peer", remoteID, "err", err)
+		return
+	}
+	m.trace("pqkem: chain offer sent over data path", "peer", remoteID)
+}
+
+// OnDataPathDown notifies that the peer's data path went down. Rotations resume once
+// the host re-bootstraps over signalling on reconnect; in-flight data-path sends will
+// simply fail until then. Reserved as an explicit hook.
+func (m *Manager) OnDataPathDown(remoteID RemoteID) {}
+
+// ---- internals ----
+
+// pushDataPath resolves the peer's endpoint and sends over the data-path transport,
+// erroring if the peer is unknown or no transport is set.
+func (m *Manager) pushDataPath(remoteID RemoteID, msg []byte) error {
+	m.mu.Lock()
+	ep, ok := m.peerAddrs[remoteID]
+	t := m.transport
+	m.mu.Unlock()
+	if !ok {
+		return fmt.Errorf("no data-path endpoint for peer %s", remoteID)
+	}
+	if t == nil {
+		return fmt.Errorf("no data-path transport")
+	}
+	return t.Send(ep, msg)
+}
+
+func (m *Manager) binding(remoteID RemoteID) Binding {
+	return Binding{LocalID: []byte(m.localID), RemoteID: []byte(remoteID)}
+}
+
+func newExchangeID() (ExchangeID, error) {
+	var id ExchangeID
+	if _, err := rand.Read(id[:]); err != nil {
+		return ExchangeID{}, fmt.Errorf("generate exchange id: %w", err)
+	}
+	return id, nil
+}

client/internal/pqkem/manager_test.go

@@ -0,0 +1,193 @@
+package pqkem
+
+import (
+	"fmt"
+	"net/netip"
+	"sync"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// netSwitch is an in-memory UDP fabric: transports register their endpoint and get
+// datagrams delivered to their inbound handler.
+type netSwitch struct {
+	mu sync.Mutex
+	h  map[netip.AddrPort]func(netip.AddrPort, []byte)
+}
+
+func newSwitch() *netSwitch {
+	return &netSwitch{h: map[netip.AddrPort]func(netip.AddrPort, []byte){}}
+}
+
+func (s *netSwitch) register(ep netip.AddrPort, fn func(netip.AddrPort, []byte)) {
+	s.mu.Lock()
+	s.h[ep] = fn
+	s.mu.Unlock()
+}
+
+func (s *netSwitch) deliver(dst, src netip.AddrPort, msg []byte) error {
+	s.mu.Lock()
+	fn := s.h[dst]
+	s.mu.Unlock()
+	if fn == nil {
+		return fmt.Errorf("no route to %s", dst)
+	}
+	fn(src, msg)
+	return nil
+}
+
+// loopback is an endpoint-based pqkem.Transport over a netSwitch, with a switchable
+// drop flag.
+type loopback struct {
+	ep   netip.AddrPort
+	sw   *netSwitch
+	drop atomic.Bool
+}
+
+func (l *loopback) Send(dst netip.AddrPort, msg []byte) error {
+	if l.drop.Load() {
+		return nil
+	}
+	return l.sw.deliver(dst, l.ep, append([]byte(nil), msg...))
+}
+
+func (l *loopback) LocalPort() int                             { return int(l.ep.Port()) }
+func (l *loopback) Run(onInbound func(netip.AddrPort, []byte)) { l.sw.register(l.ep, onInbound) }
+func (l *loopback) Close() error                               { return nil }
+
+type fakeWG struct {
+	mu     sync.Mutex
+	psks   map[RemoteID]PSK
+	failed []RemoteID
+}
+
+func newFakeWG() *fakeWG { return &fakeWG{psks: map[RemoteID]PSK{}} }
+
+func (f *fakeWG) OnNewPSKReady(remoteID RemoteID, psk PSK) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.psks[remoteID] = psk
+	return nil
+}
+
+func (f *fakeWG) OnRekeyFailed(remoteID RemoteID) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.failed = append(f.failed, remoteID)
+	return nil
+}
+
+func (f *fakeWG) psk(peer RemoteID) PSK {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.psks[peer]
+}
+
+var (
+	epA = netip.MustParseAddrPort("100.64.0.1:51833")
+	epB = netip.MustParseAddrPort("100.64.0.2:51833")
+)
+
+// pair builds two wired managers (B is the initiator, "bbbb" > "aaaa") sharing a
+// netSwitch, with each peer's data-path endpoint registered. lbB is B's loopback
+// (for toggling drop).
+func pair(t *testing.T) (dA, dB *Manager, wgA, wgB *fakeWG, lbB *loopback) {
+	t.Helper()
+	sw := newSwitch()
+	wgA = newFakeWG()
+	wgB = newFakeWG()
+	dA = NewManager("aaaa", wgA, nil)
+	dB = NewManager("bbbb", wgB, nil)
+	dA.Start(&loopback{ep: epA, sw: sw})
+	lbB = &loopback{ep: epB, sw: sw}
+	dB.Start(lbB)
+	dA.AddPeer("bbbb", epB)
+	dB.AddPeer("aaaa", epA)
+	return dA, dB, wgA, wgB, lbB
+}
+
+// bootstrap runs the signalling offer/answer (the test plays the host carrying bytes).
+func bootstrap(t *testing.T, dA, dB *Manager) {
+	t.Helper()
+	offer, err := dB.SignalOffer("aaaa")
+	require.NoError(t, err)
+	require.NotNil(t, offer)
+	answer, err := dA.SignalOnOffer("bbbb", offer)
+	require.NoError(t, err)
+	require.NotNil(t, answer)
+	require.NoError(t, dB.SignalOnAnswer("aaaa", answer))
+}
+
+func TestManager_BootstrapDerivesSamePSK(t *testing.T) {
+	dA, dB, wgA, wgB, _ := pair(t)
+	defer dA.Stop()
+	defer dB.Stop()
+
+	bootstrap(t, dA, dB)
+
+	pskA := wgA.psk("bbbb")
+	pskB := wgB.psk("aaaa")
+	require.NotEqual(t, PSK{}, pskA)
+	require.Equal(t, pskB, pskA, "both sides derive the same PSK from the bootstrap exchange")
+}
+
+func TestManager_ChainRotatesAndAcks(t *testing.T) {
+	dA, dB, wgA, wgB, _ := pair(t)
+	defer dA.Stop()
+	defer dB.Stop()
+
+	bootstrap(t, dA, dB)
+	psk1 := wgB.psk("aaaa")
+
+	// Data path up: B (initiator) chains the next offer over the data path, which
+	// rotates both to a fresh PSK and acknowledges A.
+	dA.OnDataPathRekeyed("bbbb", 0)
+	dB.OnDataPathRekeyed("aaaa", 0)
+
+	psk2A := wgA.psk("bbbb")
+	psk2B := wgB.psk("aaaa")
+	require.Equal(t, psk2B, psk2A, "both sides converge on the rotated PSK")
+	require.NotEqual(t, psk1, psk2B, "the chain rotated to a new PSK")
+}
+
+func TestManager_RotationSkippedWhenIdle(t *testing.T) {
+	dA, dB, wgA, wgB, _ := pair(t)
+	defer dA.Stop()
+	defer dB.Stop()
+
+	bootstrap(t, dA, dB)
+	psk1 := wgB.psk("aaaa")
+	require.NotEqual(t, PSK{}, psk1)
+
+	// Idle: the peer's last real-data activity is older than the window, so a rekey
+	// must NOT clock a rotation.
+	dA.OnDataPathRekeyed("bbbb", rotationActivityWindow)
+	dB.OnDataPathRekeyed("aaaa", rotationActivityWindow)
+	require.Equal(t, psk1, wgB.psk("aaaa"), "idle peer must not rotate the PSK")
+	require.Equal(t, psk1, wgA.psk("bbbb"), "idle peer must not rotate the PSK")
+
+	// Active: activity within the window clocks the rotation as usual.
+	dA.OnDataPathRekeyed("bbbb", rotationActivityWindow-1)
+	dB.OnDataPathRekeyed("aaaa", rotationActivityWindow-1)
+	psk2 := wgB.psk("aaaa")
+	require.NotEqual(t, psk1, psk2, "recent activity must clock a rotation")
+	require.Equal(t, psk2, wgA.psk("bbbb"), "both sides converge on the rotated PSK")
+}
+
+func TestManager_NonInitiatorReturnsNoOffer(t *testing.T) {
+	dA := NewManager("aaaa", newFakeWG(), nil)
+	defer dA.Stop()
+
+	offer, err := dA.SignalOffer("bbbb") // not the initiator vs "bbbb"
+	require.NoError(t, err)
+	require.Nil(t, offer)
+}
+
+func TestManager_StopIsIdempotent(t *testing.T) {
+	dA := NewManager("aaaa", newFakeWG(), nil)
+	dA.Start(&loopback{ep: epA, sw: newSwitch()})
+	dA.Stop()
+	dA.Stop() // must not panic or hang
+}

client/internal/pqkem/message.go

@@ -0,0 +1,121 @@
+package pqkem
+
+import (
+	"crypto/mlkem"
+	"fmt"
+)
+
+// Wire framing for the PQ-KEM exchange. Messages are self-contained, versioned,
+// transport-agnostic byte blobs: the same bytes ride the signalling channel
+// (initial bootstrap) or a data-tunnel packet (rekey). The library only ever sees
+// opaque []byte at the transport seam.
+//
+// Layout (all messages): [type:1][version:1][exchangeID:16][payload...]
+//
+// There is no confirm message: an exchange is acknowledged by the NEXT offer, which
+// carries the acked exchange's id (see OfferMsg.AckID) and — riding the data path
+// under the freshly adopted key — proves that key works.
+
+const (
+	// ProtocolVersion is bumped on any wire-incompatible change; a peer rejects
+	// messages it does not understand rather than misparsing them.
+	ProtocolVersion uint8 = 1
+
+	// ExchangeIDSize identifies one exchange so answers/acks correlate and stale
+	// messages are dropped.
+	ExchangeIDSize = 16
+
+	headerSize = 1 + 1 + ExchangeIDSize
+)
+
+// MsgType tags the two message kinds of the exchange.
+type MsgType uint8
+
+const (
+	MsgOffer MsgType = iota + 1
+	MsgAnswer
+)
+
+// ExchangeID is the per-exchange correlator. The zero value means "none" (an offer
+// that acknowledges nothing, i.e. the first exchange of a connection).
+type ExchangeID [ExchangeIDSize]byte
+
+// OfferMsg carries the initiator's public material (X25519 pub ‖ ML-KEM encap key)
+// and AckID, the id of the previous exchange this offer acknowledges (zero if none).
+type OfferMsg struct {
+	ExchangeID ExchangeID
+	AckID      ExchangeID
+	// KEMOffer is the raw Initiator.Offer() blob (OfferSize bytes).
+	KEMOffer []byte
+}
+
+// AnswerMsg carries the responder's reply (ML-KEM ciphertext ‖ X25519 pub) for the
+// round identified by ExchangeID.
+type AnswerMsg struct {
+	ExchangeID ExchangeID
+	// KEMAnswer is the raw Respond() answer blob (AnswerSize bytes).
+	KEMAnswer []byte
+}
+
+// Encode serialises the offer with its framed header (payload = AckID ‖ KEMOffer).
+func (m *OfferMsg) Encode() ([]byte, error) {
+	if len(m.KEMOffer) != OfferSize {
+		return nil, fmt.Errorf("offer payload: got %d, want %d", len(m.KEMOffer), OfferSize)
+	}
+	payload := make([]byte, 0, ExchangeIDSize+OfferSize)
+	payload = append(payload, m.AckID[:]...)
+	payload = append(payload, m.KEMOffer...)
+	return frame(MsgOffer, m.ExchangeID, payload), nil
+}
+
+// Encode serialises the answer with its framed header.
+func (m *AnswerMsg) Encode() ([]byte, error) {
+	if len(m.KEMAnswer) != AnswerSize {
+		return nil, fmt.Errorf("answer payload: got %d, want %d", len(m.KEMAnswer), AnswerSize)
+	}
+	return frame(MsgAnswer, m.ExchangeID, m.KEMAnswer), nil
+}
+
+// Decode parses a framed message into one of *OfferMsg / *AnswerMsg.
+func Decode(buf []byte) (MsgType, any, error) {
+	if len(buf) < headerSize {
+		return 0, nil, fmt.Errorf("message too short: %d bytes", len(buf))
+	}
+	typ := MsgType(buf[0])
+	if ver := buf[1]; ver != ProtocolVersion {
+		return typ, nil, fmt.Errorf("unsupported protocol version %d (want %d)", ver, ProtocolVersion)
+	}
+
+	var id ExchangeID
+	copy(id[:], buf[2:headerSize])
+	payload := buf[headerSize:]
+
+	switch typ {
+	case MsgOffer:
+		if len(payload) != ExchangeIDSize+OfferSize {
+			return typ, nil, fmt.Errorf("offer payload: got %d, want %d", len(payload), ExchangeIDSize+OfferSize)
+		}
+		var ack ExchangeID
+		copy(ack[:], payload[:ExchangeIDSize])
+		return typ, &OfferMsg{ExchangeID: id, AckID: ack, KEMOffer: payload[ExchangeIDSize:]}, nil
+	case MsgAnswer:
+		if len(payload) != AnswerSize {
+			return typ, nil, fmt.Errorf("answer payload: got %d, want %d", len(payload), AnswerSize)
+		}
+		return typ, &AnswerMsg{ExchangeID: id, KEMAnswer: payload}, nil
+	default:
+		return typ, nil, fmt.Errorf("unknown message type %d", typ)
+	}
+}
+
+func frame(typ MsgType, id ExchangeID, payload []byte) []byte {
+	buf := make([]byte, headerSize+len(payload))
+	buf[0] = byte(typ)
+	buf[1] = ProtocolVersion
+	copy(buf[2:], id[:])
+	copy(buf[headerSize:], payload)
+	return buf
+}
+
+// compile-time assurance the KEM blob sizes referenced here stay in sync with kem.go.
+var _ = [1]struct{}{}[OfferSize-(32+mlkem.EncapsulationKeySize768)]

client/internal/pqkem/message_test.go

@@ -0,0 +1,57 @@
+package pqkem
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestMessageRoundTrip(t *testing.T) {
+	init, err := NewInitiator()
+	require.NoError(t, err)
+	answer, _, err := Respond(init.Offer(), Binding{LocalID: wgB, RemoteID: wgA})
+	require.NoError(t, err)
+
+	id := ExchangeID{1, 2, 3, 4}
+	ack := ExchangeID{9, 9, 9}
+
+	offBytes, err := (&OfferMsg{ExchangeID: id, AckID: ack, KEMOffer: init.Offer()}).Encode()
+	require.NoError(t, err)
+	typ, decoded, err := Decode(offBytes)
+	require.NoError(t, err)
+	require.Equal(t, MsgOffer, typ)
+	require.Equal(t, id, decoded.(*OfferMsg).ExchangeID)
+	require.Equal(t, ack, decoded.(*OfferMsg).AckID)
+	require.Equal(t, init.Offer(), decoded.(*OfferMsg).KEMOffer)
+
+	ansBytes, err := (&AnswerMsg{ExchangeID: id, KEMAnswer: answer}).Encode()
+	require.NoError(t, err)
+	typ, decoded, err = Decode(ansBytes)
+	require.NoError(t, err)
+	require.Equal(t, MsgAnswer, typ)
+	require.Equal(t, answer, decoded.(*AnswerMsg).KEMAnswer)
+}
+
+func TestDecodeRejects(t *testing.T) {
+	// too short
+	_, _, err := Decode([]byte{1, 1})
+	require.Error(t, err)
+
+	// wrong version
+	bad := make([]byte, headerSize+ExchangeIDSize+OfferSize)
+	bad[0] = byte(MsgOffer)
+	bad[1] = ProtocolVersion + 1
+	_, _, err = Decode(bad)
+	require.Error(t, err)
+
+	// unknown type
+	bad2 := make([]byte, headerSize)
+	bad2[0] = 99
+	bad2[1] = ProtocolVersion
+	_, _, err = Decode(bad2)
+	require.Error(t, err)
+
+	// offer with wrong payload size
+	_, err = (&OfferMsg{KEMOffer: []byte{1, 2, 3}}).Encode()
+	require.Error(t, err)
+}

client/internal/pqkem_adapter.go

@@ -0,0 +1,150 @@
+package internal
+
+import (
+	"net/netip"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
+
+	"github.com/netbirdio/netbird/client/internal/pqkem"
+)
+
+// pqPresharedKeySetter is the subset of the WireGuard interface the ML-KEM callback
+// needs: programming a peer's preshared key. *iface.WGIface satisfies it.
+type pqPresharedKeySetter interface {
+	SetPresharedKey(peerKey string, psk wgtypes.Key, updateOnly bool) error
+}
+
+// pqCallbackHandler programs the derived PQ PSK onto the WireGuard peer. It is the
+// engine-side implementation of pqkem.CallbackHandler.
+type pqCallbackHandler struct {
+	wg pqPresharedKeySetter
+	// reoffer re-bootstraps the KEM over Signal for a peer (a fresh signalling offer)
+	// to recover from a persistent data-path rekey failure. Nil disables recovery.
+	reoffer func(remoteKey string)
+}
+
+// OnNewPSKReady programs the freshly derived PSK for the peer (updateOnly: a no-op
+// if the peer is not present, mirroring Rosenpass).
+func (h pqCallbackHandler) OnNewPSKReady(remoteID pqkem.RemoteID, psk pqkem.PSK) error {
+	// updateOnly: applies to an already-configured peer (rotation). At bootstrap the
+	// peer is not configured yet, so this is a no-op there and the PSK is instead
+	// pulled at peer-config time (pqHandshaker.PSK / conn.presharedKey).
+	log.Tracef("pqkem: programming PSK for peer %s", remoteID)
+	return h.wg.SetPresharedKey(string(remoteID), wgtypes.Key(psk), true)
+}
+
+// OnRekeyFailed reports a failed PQ (re)key convergence and re-bootstraps the KEM over
+// Signal to recover: a fresh signalling offer starts a new exchange that overwrites the
+// stalled PSK on both sides, resyncing after a persistent data-path desync. The tunnel
+// stays up on the previous PSK meanwhile (the Signal channel is independent of the
+// broken data path).
+func (h pqCallbackHandler) OnRekeyFailed(remoteID pqkem.RemoteID) error {
+	log.Warnf("pqkem: post-quantum rekey failed for peer %s, re-bootstrapping over signal", remoteID)
+	if h.reoffer != nil {
+		h.reoffer(string(remoteID))
+	}
+	return nil
+}
+
+// pqHandshaker adapts the pqkem manager to peer.PQHandshaker (string peer keys),
+// wiring the host's signalling offers/answers to the KEM exchange.
+type pqHandshaker struct {
+	mgr *pqkem.Manager
+}
+
+// announcedPort is the PQ data-path port to advertise to peers. It is omitted (0) when
+// the manager is on DefaultPort, since peers assume the default when no port is sent;
+// only a non-default (collision-forced) port is announced explicitly.
+func (p pqHandshaker) announcedPort() int {
+	if port := p.mgr.LocalPort(); port != DefaultPort {
+		return port
+	}
+	return 0
+}
+
+func (p pqHandshaker) OfferPayload(remoteKey string) ([]byte, int) {
+	payload, err := p.mgr.SignalOffer(pqkem.RemoteID(remoteKey))
+	if err != nil {
+		log.Warnf("pqkem: build offer for %s: %v", remoteKey, err)
+	}
+	return payload, p.announcedPort()
+}
+
+func (p pqHandshaker) ShouldSendBootstrapOffer(remoteKey string) bool {
+	return p.mgr.ShouldSendBootstrapOffer(pqkem.RemoteID(remoteKey))
+}
+
+func (p pqHandshaker) AnswerPayload(remoteKey string, recvOffer []byte) ([]byte, int) {
+	if len(recvOffer) == 0 {
+		// Capability signal (responder side): the KEM offer flows initiator->responder,
+		// so if we are the responder for this peer (it is the KEM initiator by role) an
+		// empty offer means it does not run the KEM. If we are the initiator, an empty
+		// offer is normal — the peer is the responder and puts its material in the
+		// answer — so we must not flag it.
+		if !p.mgr.IsInitiator(pqkem.RemoteID(remoteKey)) {
+			p.mgr.MarkNonCapable(pqkem.RemoteID(remoteKey))
+		}
+		return nil, p.announcedPort()
+	}
+	payload, err := p.mgr.SignalOnOffer(pqkem.RemoteID(remoteKey), recvOffer)
+	if err != nil {
+		log.Warnf("pqkem: build answer for %s: %v", remoteKey, err)
+	}
+	return payload, p.announcedPort()
+}
+
+func (p pqHandshaker) OnAnswer(remoteKey string, recvAnswer []byte) {
+	if len(recvAnswer) == 0 {
+		// Capability signal (initiator side): the KEM answer flows responder->initiator,
+		// so an empty answer to our offer means the peer does not run the KEM — mark it
+		// non-capable to stop offering (no failure/reoffer storm). Only meaningful when
+		// we are the initiator: as the responder we also receive an (empty) answer to
+		// our own non-KEM offer from a perfectly capable peer, which must not be flagged.
+		if p.mgr.IsInitiator(pqkem.RemoteID(remoteKey)) {
+			p.mgr.MarkNonCapable(pqkem.RemoteID(remoteKey))
+		}
+		return
+	}
+	if err := p.mgr.SignalOnAnswer(pqkem.RemoteID(remoteKey), recvAnswer); err != nil {
+		log.Warnf("pqkem: process answer from %s: %v", remoteKey, err)
+	}
+}
+
+// PSK exposes the peer's derived PSK for the conn to program at WG peer-config time.
+func (p pqHandshaker) PSK(remoteKey string) (wgtypes.Key, bool) {
+	psk, ok := p.mgr.PSK(pqkem.RemoteID(remoteKey))
+	if !ok {
+		return wgtypes.Key{}, false
+	}
+	return wgtypes.Key(psk), true
+}
+
+// SetRemoteAddr registers the peer's data-path endpoint learned from signalling. A
+// zero port means the peer omitted it (it is on DefaultPort), so we resolve it here —
+// DefaultPort lives in this package, not in peer. Sends only ever fire once the tunnel
+// is up (clocked by OnDataPathRekeyed), so registering here is safe even before
+// connection-up.
+func (p pqHandshaker) SetRemoteAddr(remoteKey string, addr netip.AddrPort) {
+	if !addr.Addr().IsValid() {
+		return
+	}
+	port := addr.Port()
+	if port == 0 {
+		port = DefaultPort
+	}
+	p.mgr.AddPeer(pqkem.RemoteID(remoteKey), netip.AddrPortFrom(addr.Addr(), port))
+}
+
+// OnDataPathRekeyed clocks the next chained PSK rotation on a fresh WG handshake.
+// sinceActivity is how long ago the peer last exchanged real user data; the manager
+// skips rotation for idle tunnels.
+func (p pqHandshaker) OnDataPathRekeyed(remoteKey string, sinceActivity time.Duration) {
+	p.mgr.OnDataPathRekeyed(pqkem.RemoteID(remoteKey), sinceActivity)
+}
+
+// OnDataPathDown signals the peer's tunnel went down.
+func (p pqHandshaker) OnDataPathDown(remoteKey string) {
+	p.mgr.OnDataPathDown(pqkem.RemoteID(remoteKey))
+}

client/internal/pqkem_adapter_test.go

@@ -0,0 +1,37 @@
+package internal
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/client/internal/pqkem"
+)
+
+type pqNoopHandler struct{}
+
+func (pqNoopHandler) OnNewPSKReady(pqkem.RemoteID, pqkem.PSK) error { return nil }
+func (pqNoopHandler) OnRekeyFailed(pqkem.RemoteID) error            { return nil }
+
+// TestPQAdapter_CapabilityRoleAware locks the role-aware capability signal: the KEM
+// payload only flows initiator-offer -> responder-answer, so an empty message in the
+// other direction comes from a perfectly capable peer and must NOT flag it. Only the
+// message that should carry material (the answer we receive as initiator) marks a peer
+// non-capable when empty.
+func TestPQAdapter_CapabilityRoleAware(t *testing.T) {
+	// localID "zzzz" > "aaaa" => this manager is the KEM initiator for peer "aaaa".
+	mgr := pqkem.NewManager("zzzz", pqNoopHandler{}, nil)
+	defer mgr.Stop()
+	h := pqHandshaker{mgr: mgr}
+
+	// An empty OFFER from our peer is normal here: as the initiator's responder it puts
+	// its material in the answer, not the offer. It must not disable our offering.
+	h.AnswerPayload("aaaa", nil)
+	payload, _ := h.OfferPayload("aaaa")
+	require.NotNil(t, payload, "an empty offer from a responder-role peer must not mark it non-capable")
+
+	// An empty ANSWER to our offer means the peer does not run the KEM -> stop offering.
+	h.OnAnswer("aaaa", nil)
+	payload2, _ := h.OfferPayload("aaaa")
+	require.Nil(t, payload2, "an empty answer to our offer marks the peer non-capable, so we stop offering")
+}

client/internal/pqkem_transport.go

@@ -0,0 +1,72 @@
+package internal
+
+import (
+	"fmt"
+	"net"
+	"net/netip"
+
+	log "github.com/sirupsen/logrus"
+)
+
+// DefaultPort is the preferred UDP port for the ML-KEM data-path service, bound on
+// the WG overlay IP. Since each client owns a distinct overlay IP, this port is
+// almost always free, so it need not be announced (peers assume it). A peer only
+// announces Body.mlkemPort when a collision forced it onto a different port.
+const DefaultPort = 51833
+
+// pqTransport is the ML-KEM data-path transport: a dumb UDP socket bound on the WG
+// overlay IP. It implements pqkem.Transport — the manager owns the remoteID<->endpoint
+// routing and drives this socket's lifecycle (Run / Close).
+type pqTransport struct {
+	conn *net.UDPConn
+	port int
+}
+
+// newPQTransport binds a UDP socket on the WG overlay IP, preferring DefaultPort and
+// falling back to an OS-assigned ephemeral port if it is in use. Call it after the WG
+// interface is up so the overlay IP is assigned; when the bound port is not
+// DefaultPort it must be announced to peers via Body.mlkemPort.
+func newPQTransport(overlayIP netip.Addr) (*pqTransport, error) {
+	if !overlayIP.IsValid() {
+		return nil, fmt.Errorf("invalid overlay IP for pqkem transport")
+	}
+	ip := net.IP(overlayIP.AsSlice())
+	conn, err := net.ListenUDP("udp4", &net.UDPAddr{IP: ip, Port: DefaultPort})
+	if err != nil {
+		log.Debugf("pqkem: default port %d unavailable on %s (%v), using an ephemeral port", DefaultPort, overlayIP, err)
+		conn, err = net.ListenUDP("udp4", &net.UDPAddr{IP: ip, Port: 0})
+		if err != nil {
+			return nil, fmt.Errorf("bind pqkem udp on overlay %s: %w", overlayIP, err)
+		}
+	}
+	return &pqTransport{conn: conn, port: conn.LocalAddr().(*net.UDPAddr).Port}, nil
+}
+
+// Send implements pqkem.Transport.
+func (t *pqTransport) Send(endpoint netip.AddrPort, msg []byte) error {
+	_, err := t.conn.WriteToUDPAddrPort(msg, endpoint)
+	return err
+}
+
+// LocalPort implements pqkem.Transport.
+func (t *pqTransport) LocalPort() int { return t.port }
+
+// Run implements pqkem.Transport: the receive loop, delivering each datagram as
+// (source endpoint, msg). Exits when the socket is closed.
+func (t *pqTransport) Run(onInbound func(src netip.AddrPort, msg []byte)) {
+	go func() {
+		buf := make([]byte, 2048)
+		for {
+			n, src, err := t.conn.ReadFromUDPAddrPort(buf)
+			if err != nil {
+				return
+			}
+			msg := make([]byte, n)
+			copy(msg, buf[:n])
+			onInbound(src, msg)
+		}
+	}()
+}
+
+// Close implements pqkem.Transport.
+func (t *pqTransport) Close() error { return t.conn.Close() }

go.mod

@@ -340,4 +340,4 @@ replace github.com/dexidp/dex/api/v2 => github.com/netbirdio/dex/api/v2 v2.0.0-2
 
 replace github.com/mailru/easyjson => github.com/netbirdio/easyjson v0.9.0
 
-replace github.com/wailsapp/wails/v3 => github.com/netbirdio/wails/v3 v3.0.0-beta.3.0.20260807055527-fc03f984d701
+replace github.com/wailsapp/wails/v3 => github.com/netbirdio/wails/v3 v3.0.0-beta.3.0.20260803205919-ad21e92381f4

go.sum

@@ -490,8 +490,8 @@ github.com/netbirdio/service v0.0.0-20240911161631-f62744f42502 h1:3tHlFmhTdX9ax
 github.com/netbirdio/service v0.0.0-20240911161631-f62744f42502/go.mod h1:CIMRFEJVL+0DS1a3Nx06NaMn4Dz63Ng6O7dl0qH0zVM=
 github.com/netbirdio/signal-dispatcher/dispatcher v0.0.0-20250805121659-6b4ac470ca45 h1:ujgviVYmx243Ksy7NdSwrdGPSRNE3pb8kEDSpH0QuAQ=
 github.com/netbirdio/signal-dispatcher/dispatcher v0.0.0-20250805121659-6b4ac470ca45/go.mod h1:5/sjFmLb8O96B5737VCqhHyGRzNFIaN/Bu7ZodXc3qQ=
-github.com/netbirdio/wails/v3 v3.0.0-beta.3.0.20260807055527-fc03f984d701 h1:QL9nupfRom0L9jcY7N9l/Bc6QK2PtC6pHzC+ftpTqpw=
-github.com/netbirdio/wails/v3 v3.0.0-beta.3.0.20260807055527-fc03f984d701/go.mod h1:BzATbK71VFikMMMCo434wAi0QcaI03P+xeaWgDvQvjw=
+github.com/netbirdio/wails/v3 v3.0.0-beta.3.0.20260803205919-ad21e92381f4 h1:UKztc3QjWvzU5DZk+uYaOWN0x62NSe/pkxuPvzqZIy4=
+github.com/netbirdio/wails/v3 v3.0.0-beta.3.0.20260803205919-ad21e92381f4/go.mod h1:BzATbK71VFikMMMCo434wAi0QcaI03P+xeaWgDvQvjw=
 github.com/netbirdio/wireguard-go v0.0.0-20260628102922-2834bebf6c1a h1:3CWK+yTvRKOcC0Q8VCTGy4l60TEb27CQVS7LkMxwjmw=
 github.com/netbirdio/wireguard-go v0.0.0-20260628102922-2834bebf6c1a/go.mod h1:rpwXGsirqLqN2L0JDJQlwOboGHmptD5ZD6T2VmcqhTw=
 github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=

management/internals/controllers/network_map/controller/controller.go

@@ -176,7 +176,6 @@ func (c *Controller) sendUpdateAccountPeers(ctx context.Context, accountID strin
 	semaphore := make(chan struct{}, 10)
 
 	c.injectAllProxyPolicies(ctx, account)
-	account.PrecomputePostureValidation(ctx)
 	dnsCache := &cache.DNSConfigCache{}
 	dnsDomain := c.GetDNSDomain(account.Settings)
 	peersCustomZone := account.GetPeersCustomZone(ctx, dnsDomain)
@@ -358,7 +357,6 @@ func (c *Controller) sendUpdateForAffectedPeers(ctx context.Context, accountID s
 	// network map that omitted the synth DNS zone, and the agent kept
 	// resolving against the stale or absent record.
 	c.injectAllProxyPolicies(ctx, account)
-	account.PrecomputePostureValidation(ctx)
 	dnsCache := &cache.DNSConfigCache{}
 	dnsDomain := c.GetDNSDomain(account.Settings)
 	peersCustomZone := account.GetPeersCustomZone(ctx, dnsDomain)

management/server/account.go

@@ -33,7 +33,6 @@ import (
 	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
 	"github.com/netbirdio/netbird/management/server/account"
 	"github.com/netbirdio/netbird/management/server/activity"
-	"github.com/netbirdio/netbird/management/server/affectedpeers"
 	nbcache "github.com/netbirdio/netbird/management/server/cache"
 	nbcontext "github.com/netbirdio/netbird/management/server/context"
 	"github.com/netbirdio/netbird/management/server/geolocation"
@@ -1627,9 +1626,6 @@ func (am *DefaultAccountManager) SyncUserJWTGroups(ctx context.Context, userAuth
 	var removeOldGroups []string
 	var hasChanges bool
 	var user *types.User
-	var change affectedpeers.Change
-	var snap *affectedpeers.Snapshot
-	var requiresAccountUpdate bool
 	err = am.Store.ExecuteInTransaction(ctx, func(transaction store.Store) error {
 		user, err = transaction.GetUserByUserID(ctx, store.LockingStrengthNone, userAuth.UserId)
 		if err != nil {
@@ -1668,11 +1664,6 @@ func (am *DefaultAccountManager) SyncUserJWTGroups(ctx context.Context, userAuth
 			return fmt.Errorf("error saving user: %w", err)
 		}
 
-		allGroupChanges := slices.Concat(addNewGroups, removeOldGroups)
-		// The user's auto-groups changed, so the SSH rules authorizing them ship a new
-		// group -> user mapping even when no peer moves between groups.
-		change.UserGroupIDs = allGroupChanges
-
 		// Propagate changes to peers if group propagation is enabled
 		if settings.GroupsPropagationEnabled {
 			peers, err := transaction.GetUserPeers(ctx, store.LockingStrengthNone, userAuth.AccountId, userAuth.UserId)
@@ -1681,7 +1672,6 @@ func (am *DefaultAccountManager) SyncUserJWTGroups(ctx context.Context, userAuth
 			}
 
 			for _, peer := range peers {
-				change.OutputPeerIDs = append(change.OutputPeerIDs, peer.ID)
 				for _, g := range addNewGroups {
 					if err := transaction.AddPeerToGroup(ctx, userAuth.AccountId, peer.ID, g); err != nil {
 						return fmt.Errorf("error adding peer %s to group %s: %w", peer.ID, g, err)
@@ -1694,12 +1684,7 @@ func (am *DefaultAccountManager) SyncUserJWTGroups(ctx context.Context, userAuth
 				}
 			}
 
-			change.LinkGroups = allGroupChanges
-
-			// The reconciliation reassigns IPv6 addresses across the account, which
-			// every peer that can reach the reassigned ones observes.
-			requiresAccountUpdate = ipv6ReconcileNeeded(settings, allGroupChanges)
-
+			allGroupChanges := slices.Concat(addNewGroups, removeOldGroups)
 			if err = am.reconcileIPv6ForGroupChanges(ctx, transaction, userAuth.AccountId, allGroupChanges); err != nil {
 				return fmt.Errorf("reconcile IPv6 for group changes: %w", err)
 			}
@@ -1709,10 +1694,6 @@ func (am *DefaultAccountManager) SyncUserJWTGroups(ctx context.Context, userAuth
 			}
 		}
 
-		if snap, err = affectedpeers.Load(ctx, transaction, userAuth.AccountId, change); err != nil {
-			return err
-		}
-
 		return nil
 	})
 	if err != nil {
@@ -1749,23 +1730,20 @@ func (am *DefaultAccountManager) SyncUserJWTGroups(ctx context.Context, userAuth
 		}
 	}
 
-	if requiresAccountUpdate {
-		log.WithContext(ctx).Tracef("user %s: JWT group membership changed, updating account peers", userAuth.UserId)
-		am.BufferUpdateAccountPeers(ctx, userAuth.AccountId, types.UpdateReason{Resource: types.UpdateResourceUser, Operation: types.UpdateOperationUpdate})
-		return nil
+	removedGroupAffectsPeers, err := areGroupChangesAffectPeers(ctx, am.Store, userAuth.AccountId, removeOldGroups)
+	if err != nil {
+		return err
 	}
 
-	log.WithContext(ctx).Tracef("user %s: JWT group membership changed, updating affected peers", userAuth.UserId)
-	bgCtx := context.WithoutCancel(ctx)
-	go func() {
-		affectedPeerIDs := snap.Expand(bgCtx, userAuth.AccountId, change)
-		if len(affectedPeerIDs) == 0 {
-			return
-		}
-		if err := am.networkMapController.BufferUpdateAffectedPeers(bgCtx, userAuth.AccountId, affectedPeerIDs, types.UpdateReason{Resource: types.UpdateResourceUser, Operation: types.UpdateOperationUpdate}); err != nil {
-			log.WithContext(bgCtx).Errorf("failed to update affected peers after JWT group sync for account %s: %v", userAuth.AccountId, err)
-		}
-	}()
+	newGroupsAffectsPeers, err := areGroupChangesAffectPeers(ctx, am.Store, userAuth.AccountId, addNewGroups)
+	if err != nil {
+		return err
+	}
+
+	if removedGroupAffectsPeers || newGroupsAffectsPeers {
+		log.WithContext(ctx).Tracef("user %s: JWT group membership changed, updating account peers", userAuth.UserId)
+		am.BufferUpdateAccountPeers(ctx, userAuth.AccountId, types.UpdateReason{Resource: types.UpdateResourceUser, Operation: types.UpdateOperationUpdate})
+	}
 
 	return nil
 }
@@ -2448,27 +2426,30 @@ func (am *DefaultAccountManager) reconcileIPv6ForGroupChanges(ctx context.Contex
 		return fmt.Errorf("get account settings: %w", err)
 	}
 
-	if !ipv6ReconcileNeeded(settings, groupIDs) {
+	if len(settings.IPv6EnabledGroups) == 0 {
+		return nil
+	}
+
+	enabledSet := make(map[string]struct{}, len(settings.IPv6EnabledGroups))
+	for _, gid := range settings.IPv6EnabledGroups {
+		enabledSet[gid] = struct{}{}
+	}
+
+	affected := false
+	for _, gid := range groupIDs {
+		if _, ok := enabledSet[gid]; ok {
+			affected = true
+			break
+		}
+	}
+
+	if !affected {
 		return nil
 	}
 
 	return am.updatePeerIPv6Addresses(ctx, transaction, accountID, settings)
 }
 
-// ipv6ReconcileNeeded reports whether changes to the given groups trigger an IPv6
-// reconciliation. A reconciliation reassigns addresses across the whole account, and a
-// peer's address is visible to everyone that reaches it through any of its groups, so
-// callers that otherwise compute an affected-peers set must fall back to updating the
-// whole account.
-func ipv6ReconcileNeeded(settings *types.Settings, groupIDs []string) bool {
-	for _, groupID := range groupIDs {
-		if slices.Contains(settings.IPv6EnabledGroups, groupID) {
-			return true
-		}
-	}
-	return false
-}
-
 func (am *DefaultAccountManager) ensureIPv6Subnet(ctx context.Context, transaction store.Store, accountID string, settings *types.Settings, network *types.Network) error {
 	if settings.NetworkRangeV6.IsValid() {
 		network.NetV6 = net.IPNet{

management/server/account_test.go

@@ -1757,7 +1757,6 @@ func TestAccount_Copy(t *testing.T) {
 				AccountID: "account1",
 			},
 		},
-		PostureValidation: map[string]map[string]bool{"1": {"1": true}},
 	}
 	err := hasNilField(account)
 	if err != nil {

management/server/affected_peers_jwt_test.go

@@ -1,179 +0,0 @@
-package server
-
-import (
-	"context"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
-
-	"github.com/netbirdio/netbird/management/server/affectedpeers"
-	nbpeer "github.com/netbirdio/netbird/management/server/peer"
-	"github.com/netbirdio/netbird/management/server/store"
-	"github.com/netbirdio/netbird/management/server/types"
-	"github.com/netbirdio/netbird/shared/auth"
-)
-
-// A user's auto-group change refreshes the destinations of the SSH rules authorizing
-// that group — they carry the group -> user mapping — even though no peer moved
-// between groups.
-func TestAffectedPeers_UserGroupChange_RefreshesSSHAuthorizedDestinations(t *testing.T) {
-	manager, s, accountID, peerIDs, groupIDs := setupAffectedPeersTest(t)
-	ctx := context.Background()
-
-	_, err := manager.SavePolicy(ctx, accountID, userID, &types.Policy{
-		Enabled: true,
-		Rules: []*types.PolicyRule{
-			{
-				Enabled:          true,
-				Sources:          []string{groupIDs[0]},
-				Destinations:     []string{groupIDs[1]},
-				Protocol:         types.PolicyRuleProtocolNetbirdSSH,
-				Action:           types.PolicyTrafficActionAccept,
-				AuthorizedGroups: map[string][]string{groupIDs[3]: {"root"}},
-			},
-		},
-	}, true)
-	require.NoError(t, err)
-
-	result := resolveAffected(t, s, accountID, affectedpeers.Change{UserGroupIDs: []string{groupIDs[3]}})
-	assert.ElementsMatch(t, []string{peerIDs[1]}, result,
-		"only the SSH rule's destination peers carry the changed group -> user mapping")
-
-	result = resolveAffected(t, s, accountID, affectedpeers.Change{UserGroupIDs: []string{groupIDs[4]}})
-	assert.Empty(t, result, "a group no SSH rule authorizes affects nobody")
-}
-
-// Creating, blocking or unblocking a user changes the account's allowed-user set, which
-// reaches only the destinations of the SSH rules that ship it.
-func TestAffectedPeers_AllowedUsersChange_RefreshesSSHDestinations(t *testing.T) {
-	manager, s, accountID, peerIDs, groupIDs := setupAffectedPeersTest(t)
-	ctx := context.Background()
-
-	// Ships the allowed-user set: an SSH rule naming no groups and no user.
-	_, err := manager.SavePolicy(ctx, accountID, userID, &types.Policy{
-		Enabled: true,
-		Rules: []*types.PolicyRule{{
-			Enabled:      true,
-			Sources:      []string{groupIDs[0]},
-			Destinations: []string{groupIDs[1]},
-			Protocol:     types.PolicyRuleProtocolNetbirdSSH,
-			Action:       types.PolicyTrafficActionAccept,
-		}},
-	}, true)
-	require.NoError(t, err)
-
-	// Does not ship it: an SSH rule that authorizes a specific group.
-	_, err = manager.SavePolicy(ctx, accountID, userID, &types.Policy{
-		Enabled: true,
-		Rules: []*types.PolicyRule{{
-			Enabled:          true,
-			Sources:          []string{groupIDs[2]},
-			Destinations:     []string{groupIDs[3]},
-			Protocol:         types.PolicyRuleProtocolNetbirdSSH,
-			Action:           types.PolicyTrafficActionAccept,
-			AuthorizedGroups: map[string][]string{groupIDs[0]: {"root"}},
-		}},
-	}, true)
-	require.NoError(t, err)
-
-	result := resolveAffected(t, s, accountID, affectedpeers.Change{AllowedUsersChanged: true})
-	assert.ElementsMatch(t, []string{peerIDs[1]}, result,
-		"only the destinations of the rule shipping the allowed-user set refresh")
-}
-
-// TestAffectedPeers_SyncUserJWTGroups_OnlyAffectedPeersUpdated verifies that a JWT
-// auto-group change updates only the user's peers and the peers linked to the changed
-// group through policies, instead of fanning out to the whole account.
-func TestAffectedPeers_SyncUserJWTGroups_OnlyAffectedPeersUpdated(t *testing.T) {
-	manager, updateManager, account, _, peer2, peer3 := setupNetworkMapTest(t)
-	ctx := context.Background()
-	accountID := account.Id
-
-	key, err := wgtypes.GeneratePrivateKey()
-	require.NoError(t, err)
-	userPeer, _, _, _, err := manager.AddPeer(ctx, accountID, "", userID, &nbpeer.Peer{
-		Key:  key.PublicKey().String(),
-		Meta: nbpeer.PeerSystemMeta{Hostname: "user-peer"},
-	}, false)
-	require.NoError(t, err)
-
-	policies, err := manager.Store.GetAccountPolicies(ctx, store.LockingStrengthNone, accountID)
-	require.NoError(t, err)
-	for _, p := range policies {
-		require.NoError(t, manager.Store.DeletePolicy(ctx, accountID, p.ID))
-	}
-
-	account, err = manager.Store.GetAccount(ctx, accountID)
-	require.NoError(t, err)
-	account.Settings.JWTGroupsEnabled = true
-	account.Settings.JWTGroupsClaimName = "groups"
-	account.Settings.GroupsPropagationEnabled = true
-	require.NoError(t, manager.Store.SaveAccount(ctx, account))
-
-	require.NoError(t, manager.CreateGroup(ctx, accountID, userID, &types.Group{ID: "jwt-grp", Name: "jwt-linked", Issued: types.GroupIssuedJWT, Peers: []string{}}))
-	require.NoError(t, manager.CreateGroup(ctx, accountID, userID, &types.Group{ID: "jwt-dest", Name: "jwt-dest", Peers: []string{peer2.ID}}))
-
-	_, err = manager.SavePolicy(ctx, accountID, userID, &types.Policy{
-		Enabled: true,
-		Rules: []*types.PolicyRule{
-			{
-				Enabled:       true,
-				Sources:       []string{"jwt-grp"},
-				Destinations:  []string{"jwt-dest"},
-				Bidirectional: true,
-				Action:        types.PolicyTrafficActionAccept,
-			},
-		},
-	}, true)
-	require.NoError(t, err)
-
-	updUser := updateManager.CreateChannel(ctx, userPeer.ID)
-	upd2 := updateManager.CreateChannel(ctx, peer2.ID)
-	upd3 := updateManager.CreateChannel(ctx, peer3.ID)
-	t.Cleanup(func() {
-		updateManager.CloseChannel(ctx, userPeer.ID)
-		updateManager.CloseChannel(ctx, peer2.ID)
-		updateManager.CloseChannel(ctx, peer3.ID)
-	})
-
-	userAuth := auth.UserAuth{
-		AccountId: accountID,
-		UserId:    userID,
-		Groups:    []string{"jwt-linked"},
-	}
-
-	t.Run("adding JWT group updates only linked peers", func(t *testing.T) {
-		drainPeerUpdates(updUser)
-		drainPeerUpdates(upd2)
-		drainPeerUpdates(upd3)
-
-		require.NoError(t, manager.SyncUserJWTGroups(ctx, userAuth))
-
-		peerShouldReceiveUpdate(t, updUser)
-		peerShouldReceiveUpdate(t, upd2)
-		peerShouldNotReceiveUpdate(t, upd3)
-
-		user, err := manager.Store.GetUserByUserID(ctx, store.LockingStrengthNone, userID)
-		require.NoError(t, err)
-		assert.Contains(t, user.AutoGroups, "jwt-grp")
-	})
-
-	t.Run("removing JWT group updates only linked peers", func(t *testing.T) {
-		drainPeerUpdates(updUser)
-		drainPeerUpdates(upd2)
-		drainPeerUpdates(upd3)
-
-		userAuth.Groups = nil
-		require.NoError(t, manager.SyncUserJWTGroups(ctx, userAuth))
-
-		peerShouldReceiveUpdate(t, updUser)
-		peerShouldReceiveUpdate(t, upd2)
-		peerShouldNotReceiveUpdate(t, upd3)
-
-		user, err := manager.Store.GetUserByUserID(ctx, store.LockingStrengthNone, userID)
-		require.NoError(t, err)
-		assert.NotContains(t, user.AutoGroups, "jwt-grp")
-	})
-}

management/server/affected_peers_user_test.go

@@ -1,170 +0,0 @@
-package server
-
-import (
-	"context"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
-
-	"github.com/netbirdio/netbird/management/server/activity"
-	nbpeer "github.com/netbirdio/netbird/management/server/peer"
-	"github.com/netbirdio/netbird/management/server/store"
-	"github.com/netbirdio/netbird/management/server/types"
-)
-
-// A user update refreshes only the peers its auto-group change reaches, and a user
-// update that changes no group membership refreshes nobody.
-func TestAffectedPeers_SaveUser_OnlyAffectedPeersUpdated(t *testing.T) {
-	manager, updateManager, account, _, peer2, peer3 := setupNetworkMapTest(t)
-	ctx := context.Background()
-	accountID := account.Id
-
-	const targetUserID = "target-user"
-	require.NoError(t, manager.Store.SaveUser(ctx, &types.User{
-		Id: targetUserID, AccountID: accountID, Role: types.UserRoleUser,
-	}))
-
-	key, err := wgtypes.GeneratePrivateKey()
-	require.NoError(t, err)
-	targetPeer, _, _, _, err := manager.AddPeer(ctx, accountID, "", targetUserID, &nbpeer.Peer{
-		Key:  key.PublicKey().String(),
-		Meta: nbpeer.PeerSystemMeta{Hostname: "target-peer"},
-	}, false)
-	require.NoError(t, err)
-
-	policies, err := manager.Store.GetAccountPolicies(ctx, store.LockingStrengthNone, accountID)
-	require.NoError(t, err)
-	for _, p := range policies {
-		require.NoError(t, manager.Store.DeletePolicy(ctx, accountID, p.ID))
-	}
-
-	account, err = manager.Store.GetAccount(ctx, accountID)
-	require.NoError(t, err)
-	account.Settings.GroupsPropagationEnabled = true
-	require.NoError(t, manager.Store.SaveAccount(ctx, account))
-
-	require.NoError(t, manager.CreateGroup(ctx, accountID, userID, &types.Group{ID: "ug-linked", Name: "ug-linked"}))
-	require.NoError(t, manager.CreateGroup(ctx, accountID, userID, &types.Group{ID: "ug-dest", Name: "ug-dest", Peers: []string{peer2.ID}}))
-
-	_, err = manager.SavePolicy(ctx, accountID, userID, &types.Policy{
-		Enabled: true,
-		Rules: []*types.PolicyRule{
-			{
-				Enabled:       true,
-				Sources:       []string{"ug-linked"},
-				Destinations:  []string{"ug-dest"},
-				Bidirectional: true,
-				Action:        types.PolicyTrafficActionAccept,
-			},
-		},
-	}, true)
-	require.NoError(t, err)
-
-	updTarget := updateManager.CreateChannel(ctx, targetPeer.ID)
-	upd2 := updateManager.CreateChannel(ctx, peer2.ID)
-	upd3 := updateManager.CreateChannel(ctx, peer3.ID)
-	t.Cleanup(func() {
-		updateManager.CloseChannel(ctx, targetPeer.ID)
-		updateManager.CloseChannel(ctx, peer2.ID)
-		updateManager.CloseChannel(ctx, peer3.ID)
-	})
-
-	t.Run("auto group change updates only linked peers", func(t *testing.T) {
-		drainPeerUpdates(updTarget)
-		drainPeerUpdates(upd2)
-		drainPeerUpdates(upd3)
-
-		_, err := manager.SaveUser(ctx, accountID, activity.SystemInitiator, &types.User{
-			Id: targetUserID, AccountID: accountID, Role: types.UserRoleUser,
-			AutoGroups: []string{"ug-linked"},
-		})
-		require.NoError(t, err)
-
-		peerShouldReceiveUpdate(t, updTarget)
-		peerShouldReceiveUpdate(t, upd2)
-		peerShouldNotReceiveUpdate(t, upd3)
-	})
-
-	t.Run("update without group changes refreshes nobody", func(t *testing.T) {
-		drainPeerUpdates(updTarget)
-		drainPeerUpdates(upd2)
-		drainPeerUpdates(upd3)
-
-		_, err := manager.SaveUser(ctx, accountID, activity.SystemInitiator, &types.User{
-			Id: targetUserID, AccountID: accountID, Role: types.UserRoleUser,
-			AutoGroups: []string{"ug-linked"}, Name: "renamed",
-		})
-		require.NoError(t, err)
-
-		peerShouldNotReceiveUpdate(t, updTarget)
-		peerShouldNotReceiveUpdate(t, upd2)
-		peerShouldNotReceiveUpdate(t, upd3)
-
-		user, err := manager.Store.GetUserByUserID(ctx, store.LockingStrengthNone, targetUserID)
-		require.NoError(t, err)
-		assert.Equal(t, "renamed", user.Name)
-	})
-
-	t.Run("auto group change reassigning IPv6 refreshes the whole account", func(t *testing.T) {
-		account, err := manager.Store.GetAccount(ctx, accountID)
-		require.NoError(t, err)
-		account.Settings.IPv6EnabledGroups = []string{"ug-v6"}
-		require.NoError(t, manager.Store.SaveAccount(ctx, account))
-		require.NoError(t, manager.CreateGroup(ctx, accountID, userID, &types.Group{ID: "ug-v6", Name: "ug-v6"}))
-
-		drainPeerUpdates(updTarget)
-		drainPeerUpdates(upd2)
-		drainPeerUpdates(upd3)
-
-		_, err = manager.SaveUser(ctx, accountID, activity.SystemInitiator, &types.User{
-			Id: targetUserID, AccountID: accountID, Role: types.UserRoleUser,
-			AutoGroups: []string{"ug-linked", "ug-v6"}, Name: "renamed",
-		})
-		require.NoError(t, err)
-
-		// An IPv6 reassignment is visible to every peer that can reach the reassigned
-		// ones through any group, so peer3 refreshes even though it shares no policy.
-		peerShouldReceiveUpdate(t, updTarget)
-		peerShouldReceiveUpdate(t, upd2)
-		peerShouldReceiveUpdate(t, upd3)
-	})
-
-	t.Run("unblocking a user refreshes only the SSH rule destinations", func(t *testing.T) {
-		// An SSH rule that authorizes no group of its own ships the account's
-		// allowed-user set to its destinations, so those are the peers an unblock
-		// reaches — not the whole account.
-		_, err := manager.SavePolicy(ctx, accountID, userID, &types.Policy{
-			Enabled: true,
-			Rules: []*types.PolicyRule{{
-				Enabled:      true,
-				Sources:      []string{"ug-linked"},
-				Destinations: []string{"ug-dest"},
-				Protocol:     types.PolicyRuleProtocolNetbirdSSH,
-				Action:       types.PolicyTrafficActionAccept,
-			}},
-		}, true)
-		require.NoError(t, err)
-
-		blocked, err := manager.Store.GetUserByUserID(ctx, store.LockingStrengthNone, targetUserID)
-		require.NoError(t, err)
-		blocked.Blocked = true
-		require.NoError(t, manager.Store.SaveUser(ctx, blocked))
-
-		drainPeerUpdates(updTarget)
-		drainPeerUpdates(upd2)
-		drainPeerUpdates(upd3)
-
-		// Same auto-groups as the previous subtest left them, so no group change and
-		// no IPv6 reconciliation interferes: the unblock alone drives the refresh.
-		_, err = manager.SaveUser(ctx, accountID, activity.SystemInitiator, &types.User{
-			Id: targetUserID, AccountID: accountID, Role: types.UserRoleUser,
-			AutoGroups: []string{"ug-linked", "ug-v6"}, Name: "renamed",
-		})
-		require.NoError(t, err)
-
-		peerShouldReceiveUpdate(t, upd2)
-		peerShouldNotReceiveUpdate(t, upd3)
-	})
-}

management/server/affectedpeers/resolver.go

@@ -18,7 +18,6 @@ import (
 	"context"
 
 	log "github.com/sirupsen/logrus"
-	"golang.org/x/exp/maps"
 
 	nbdns "github.com/netbirdio/netbird/dns"
 	rpservice "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/service"
@@ -84,7 +83,7 @@ func (snap *Snapshot) loadCollections(ctx context.Context, s store.Store, accoun
 	hasGroupOrPeerChange := len(c.ChangedGroupIDs) > 0 || len(c.ChangedPeerIDs) > 0 || len(c.LinkGroups) > 0 || len(c.Resources) > 0
 	hasNetworkObject := len(c.Routers) > 0 || len(c.Resources) > 0 || len(c.Networks) > 0
 	// the resource<->router bridge can fire for any of these
-	needsRoutersResources := hasGroupOrPeerChange || len(c.PostureCheckIDs) > 0 || len(c.Policies) > 0 || hasNetworkObject || len(c.UserGroupIDs) > 0 || c.AllowedUsersChanged
+	needsRoutersResources := hasGroupOrPeerChange || len(c.PostureCheckIDs) > 0 || len(c.Policies) > 0 || hasNetworkObject
 
 	if needsRoutersResources {
 		if err := snap.loadPolicyRoutersResources(ctx, s, accountID); err != nil {
@@ -220,18 +219,6 @@ type Change struct {
 	// (correct when the peer's own attributes changed, e.g. IP/status).
 	OutputPeerIDs []string
 
-	// UserGroupIDs are groups whose USER membership changed (a user's auto-groups),
-	// as opposed to their peer membership. Peers ship the group -> user mapping only
-	// for the groups an SSH rule authorizes, so these refresh the destinations of the
-	// SSH rules authorizing them — independently of any peer moving between groups.
-	UserGroupIDs []string
-
-	// AllowedUsersChanged marks a change to the set of users allowed to open SSH
-	// sessions — a user was created, blocked or unblocked. That set is account-wide,
-	// and peers receive it through the SSH rules that name no group or user of their
-	// own, so those rules' destinations refresh.
-	AllowedUsersChanged bool
-
 	// LinkGroups are groups used ONLY to match policies/routes/routers and walk to the
 	// OPPOSITE side — they are never expanded to their own members. Use this when a
 	// peer's group membership changed: pass the peer in ChangedPeerIDs and its
@@ -253,8 +240,6 @@ func (c Change) isEmpty() bool {
 		len(c.Resources) == 0 &&
 		len(c.Networks) == 0 &&
 		len(c.PostureCheckIDs) == 0 &&
-		len(c.UserGroupIDs) == 0 &&
-		!c.AllowedUsersChanged &&
 		len(c.DistributionGroupIDs) == 0 &&
 		len(c.RemovedPeersByGroup) == 0 &&
 		len(c.LinkGroups) == 0 &&
@@ -374,9 +359,6 @@ func (r *resolver) walk() {
 		r.collectFromProxyServices()
 	}
 
-	r.collectFromSSHAuthorizedGroups()
-	r.collectFromAllowedUsers()
-
 	r.collectFromChangedRoutes(r.change.Routes)
 	r.collectFromChangedRouters(r.change.Routers)
 	r.collectFromChangedResources(r.change.Resources)
@@ -829,59 +811,6 @@ func (r *resolver) collectFromNameServers() {
 	}
 }
 
-// collectFromSSHAuthorizedGroups folds the destinations of the enabled SSH rules that
-// authorize a group whose user membership changed. Those destination peers carry the
-// group -> user mapping for the groups they authorize, so they refresh even when no
-// peer moved between groups.
-func (r *resolver) collectFromSSHAuthorizedGroups() {
-	if len(r.change.UserGroupIDs) == 0 {
-		return
-	}
-
-	changed := toSet(r.change.UserGroupIDs)
-	for _, policy := range r.policies() {
-		for _, rule := range policy.Rules {
-			if !rule.Enabled || rule.Protocol != types.PolicyRuleProtocolNetbirdSSH {
-				continue
-			}
-			if !anyInSet(maps.Keys(rule.AuthorizedGroups), changed) {
-				continue
-			}
-			log.WithContext(r.ctx).Tracef("collectFromSSHAuthorizedGroups: rule %s authorizes a changed user group -> folding its destinations", rule.ID)
-			r.foldPolicySideForRule(policy, rule, sideDestination)
-		}
-	}
-}
-
-// collectFromAllowedUsers folds the destinations of the rules that make a peer carry
-// the account's allowed-user set, for a change to who is in that set.
-func (r *resolver) collectFromAllowedUsers() {
-	if !r.change.AllowedUsersChanged {
-		return
-	}
-
-	for _, policy := range r.policies() {
-		for _, rule := range policy.Rules {
-			if !rule.Enabled || !ruleShipsAllowedUsers(rule) {
-				continue
-			}
-			log.WithContext(r.ctx).Tracef("collectFromAllowedUsers: rule %s ships the allowed-user set -> folding its destinations", rule.ID)
-			r.foldPolicySideForRule(policy, rule, sideDestination)
-		}
-	}
-}
-
-// ruleShipsAllowedUsers reports whether a rule makes its destination peers carry the
-// account's allowed-user set. It mirrors the network map's SSH requirements except for
-// the destination peer's own SSH flag, which the snapshot does not hold — so it folds a
-// superset and never misses a peer.
-func ruleShipsAllowedUsers(rule *types.PolicyRule) bool {
-	if rule.Protocol == types.PolicyRuleProtocolNetbirdSSH {
-		return len(rule.AuthorizedGroups) == 0 && rule.AuthorizedUser == ""
-	}
-	return types.PolicyRuleImpliesLegacySSH(rule)
-}
-
 func (r *resolver) collectFromDNSSettings() {
 	if len(r.linkGroups) == 0 || r.snap.dnsSettings == nil {
 		return

management/server/affectedpeers/resolver_test.go

@@ -85,8 +85,6 @@ func TestChangeIsEmpty(t *testing.T) {
 	assert.False(t, Change{Resources: []*resourceTypes.NetworkResource{{ID: "r"}}}.isEmpty())
 	assert.False(t, Change{Networks: []*networkTypes.Network{{ID: "n"}}}.isEmpty())
 	assert.False(t, Change{PostureCheckIDs: []string{"pc"}}.isEmpty())
-	assert.False(t, Change{UserGroupIDs: []string{"g"}}.isEmpty())
-	assert.False(t, Change{AllowedUsersChanged: true}.isEmpty())
 }
 
 func TestPolicyReferencesPostureChecks(t *testing.T) {

management/server/types/account.go

@@ -91,8 +91,6 @@ type Account struct {
 	Onboarding       AccountOnboarding                `gorm:"foreignKey:AccountID;references:id;constraint:OnDelete:CASCADE"`
 
 	ReverseProxyFreeDomainNonce string
-
-	PostureValidation map[string]map[string]bool `gorm:"-"`
 }
 
 // this class is used by gorm only
@@ -876,7 +874,6 @@ func (a *Account) Copy() *Account {
 		Services:               services,
 		Onboarding:             a.Onboarding,
 		Domains:                domains,
-		PostureValidation:      a.PostureValidation,
 	}
 }
 

management/server/types/account_components.go

@@ -10,8 +10,6 @@ import (
 	nbdns "github.com/netbirdio/netbird/dns"
 	"github.com/netbirdio/netbird/management/internals/modules/zones"
 	routerTypes "github.com/netbirdio/netbird/management/server/networks/routers/types"
-	nbpeer "github.com/netbirdio/netbird/management/server/peer"
-	"github.com/netbirdio/netbird/management/server/posture"
 	"github.com/netbirdio/netbird/management/server/telemetry"
 	"github.com/netbirdio/netbird/route"
 )
@@ -508,8 +506,8 @@ func (a *Account) getPeersGroupsPoliciesRoutes(
 func (a *Account) getPeersFromGroups(ctx context.Context, groups []string, peerID string, sourcePostureChecksIDs []string,
 	validatedPeersMap map[string]struct{}, postureFailedPeers *map[string]map[string]struct{}) ([]string, bool) {
 	peerInGroups := false
-	var filteredPeerIDs []string
-	var seenPeerIds map[string]struct{}
+	filteredPeerIDs := make([]string, 0, len(groups))
+	seenPeerIds := make(map[string]struct{}, len(groups))
 
 	for _, gid := range groups {
 		group := a.GetGroup(gid)
@@ -549,17 +547,6 @@ func (a *Account) getPeersFromGroups(ctx context.Context, groups []string, peerI
 			return filteredPeerIDs, peerInGroups
 		}
 
-		if seenPeerIds == nil {
-			totalGroupPeers := 0
-			for _, g := range groups {
-				if grp := a.GetGroup(g); grp != nil {
-					totalGroupPeers += len(grp.Peers)
-				}
-			}
-			filteredPeerIDs = make([]string, 0, totalGroupPeers)
-			seenPeerIds = make(map[string]struct{}, totalGroupPeers)
-		}
-
 		for _, pid := range group.Peers {
 			if _, seen := seenPeerIds[pid]; seen {
 				continue
@@ -602,109 +589,21 @@ func (a *Account) validatePostureChecksOnPeerGetFailed(ctx context.Context, sour
 	}
 
 	for _, postureChecksID := range sourcePostureChecksID {
-		if valid, cached := a.cachedPostureCheckResult(postureChecksID, peerID); cached {
-			if !valid {
-				return false, postureChecksID
-			}
-			continue
-		}
-
 		postureChecks := a.GetPostureChecks(postureChecksID)
 		if postureChecks == nil {
 			continue
 		}
 
-		if !peerPassesPostureChecks(ctx, postureChecks.GetChecks(), peer) {
-			return false, postureChecksID
+		for _, check := range postureChecks.GetChecks() {
+			isValid, _ := check.Check(ctx, *peer)
+			if !isValid {
+				return false, postureChecksID
+			}
 		}
 	}
 	return true, ""
 }
 
-// PrecomputePostureValidation evaluates every posture check referenced by an enabled
-// policy once against the peers of that policy's source groups and stores the results,
-// so the per-peer network map calculations that follow look them up instead of
-// re-evaluating checks for every peer pair. It must be called before the account is
-// shared across goroutines; lookups not covered by the precomputed results fall back
-// to direct evaluation.
-func (a *Account) PrecomputePostureValidation(ctx context.Context) {
-	if len(a.PostureChecks) == 0 {
-		a.PostureValidation = nil
-		return
-	}
-
-	checkPeerIDs := make(map[string]map[string]struct{})
-	for _, policy := range a.Policies {
-		if !policy.Enabled || len(policy.SourcePostureChecks) == 0 {
-			continue
-		}
-
-		peerIDs := a.getUniquePeerIDsFromGroupsIDs(ctx, policy.SourceGroups())
-		for _, rule := range policy.Rules {
-			if rule.SourceResource.Type == ResourceTypePeer && rule.SourceResource.ID != "" {
-				peerIDs = append(peerIDs, rule.SourceResource.ID)
-			}
-		}
-
-		for _, postureChecksID := range policy.SourcePostureChecks {
-			set := checkPeerIDs[postureChecksID]
-			if set == nil {
-				set = make(map[string]struct{}, len(peerIDs))
-				checkPeerIDs[postureChecksID] = set
-			}
-			for _, pid := range peerIDs {
-				set[pid] = struct{}{}
-			}
-		}
-	}
-
-	results := make(map[string]map[string]bool, len(checkPeerIDs))
-	for postureChecksID, peerIDs := range checkPeerIDs {
-		results[postureChecksID] = a.evaluatePostureChecksForPeers(ctx, postureChecksID, peerIDs)
-	}
-	a.PostureValidation = results
-}
-
-func (a *Account) evaluatePostureChecksForPeers(ctx context.Context, postureChecksID string, peerIDs map[string]struct{}) map[string]bool {
-	postureChecks := a.GetPostureChecks(postureChecksID)
-	if postureChecks == nil {
-		return nil
-	}
-
-	checks := postureChecks.GetChecks()
-	results := make(map[string]bool, len(peerIDs))
-	for peerID := range peerIDs {
-		peer, ok := a.Peers[peerID]
-		if !ok || peer == nil {
-			continue
-		}
-		results[peerID] = peerPassesPostureChecks(ctx, checks, peer)
-	}
-	return results
-}
-
-func (a *Account) cachedPostureCheckResult(postureChecksID, peerID string) (bool, bool) {
-	results, ok := a.PostureValidation[postureChecksID]
-	if !ok {
-		return false, false
-	}
-	if results == nil {
-		return true, true
-	}
-	valid, found := results[peerID]
-	return valid, found
-}
-
-func peerPassesPostureChecks(ctx context.Context, checks []posture.Check, peer *nbpeer.Peer) bool {
-	for _, check := range checks {
-		isValid, _ := check.Check(ctx, *peer)
-		if !isValid {
-			return false
-		}
-	}
-	return true
-}
-
 func (a *Account) getPostureValidPeersSaveFailed(inputPeers []string, postureChecksIDs []string, validatedPeersMap map[string]struct{}, postureFailedPeers *map[string]map[string]struct{}) []string {
 	var dest []string
 	for _, peerID := range inputPeers {

management/server/types/account_posture_validation_test.go

@@ -1,72 +0,0 @@
-package types_test
-
-import (
-	"context"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
-	nbdns "github.com/netbirdio/netbird/dns"
-	"github.com/netbirdio/netbird/management/server/posture"
-)
-
-func TestPrecomputePostureValidation_MatchesDirectEvaluation(t *testing.T) {
-	account, validatedPeers := scalableTestAccount(60, 5)
-
-	account.PostureChecks = append(account.PostureChecks, &posture.Checks{
-		ID: "posture-check-strict", Name: "Strict version",
-		Checks: posture.ChecksDefinition{
-			NBVersionCheck: &posture.NBVersionCheck{MinVersion: "0.50.0"},
-		},
-	})
-	account.Policies[0].SourcePostureChecks = []string{"posture-check-ver", "posture-check-unknown"}
-	account.Policies[1].SourcePostureChecks = []string{"posture-check-strict"}
-	account.Policies[2].SourcePostureChecks = []string{"posture-check-ver"}
-	account.Policies[2].Enabled = false
-
-	ctx := context.Background()
-	resourcePolicies := account.GetResourcePoliciesMap()
-	routers := account.GetResourceRoutersMap()
-
-	type result struct {
-		peers              map[string]struct{}
-		postureFailedPeers map[string]map[string]struct{}
-	}
-	snapshot := func() map[string]result {
-		results := make(map[string]result, len(account.Peers))
-		for peerID := range account.Peers {
-			components := account.GetPeerNetworkMapComponents(ctx, peerID, nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, nil)
-			require.NotNil(t, components)
-			peerSet := make(map[string]struct{}, len(components.Peers))
-			for id := range components.Peers {
-				peerSet[id] = struct{}{}
-			}
-			results[peerID] = result{peers: peerSet, postureFailedPeers: components.PostureFailedPeers}
-		}
-		return results
-	}
-
-	direct := snapshot()
-	account.PrecomputePostureValidation(ctx)
-	memoized := snapshot()
-
-	require.Equal(t, len(direct), len(memoized))
-	for peerID, want := range direct {
-		got := memoized[peerID]
-		assert.Equal(t, want.peers, got.peers, "visible peers changed for %s", peerID)
-		assert.Equal(t, want.postureFailedPeers, got.postureFailedPeers, "posture failed peers changed for %s", peerID)
-	}
-}
-
-func TestPrecomputePostureValidation_NoPostureChecks(t *testing.T) {
-	account, validatedPeers := scalableTestAccount(10, 2)
-	account.PostureChecks = nil
-
-	ctx := context.Background()
-	account.PrecomputePostureValidation(ctx)
-
-	components := account.GetPeerNetworkMapComponents(ctx, "peer-0", nbdns.CustomZone{}, nil, validatedPeers, account.GetResourcePoliciesMap(), account.GetResourceRoutersMap(), nil)
-	require.NotNil(t, components)
-	assert.NotEmpty(t, components.Peers)
-}

management/server/types/networkmap_benchmark_test.go

@@ -86,43 +86,6 @@ func BenchmarkNetworkMapGeneration_AllPeers(b *testing.B) {
 			b.ReportAllocs()
 			b.ResetTimer()
 			for range b.N {
-				account.PrecomputePostureValidation(ctx)
-				for _, peerID := range peerIDs {
-					_ = account.GetPeerNetworkMapFromComponents(ctx, peerID, nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, nil, groupIDToUserIDs)
-				}
-			}
-		})
-	}
-}
-
-// BenchmarkNetworkMapGeneration_AllPeersPostureChecks benchmarks the UpdateAccountPeers
-// hot path with a posture check attached to the account-wide policy, so posture
-// validation runs for every source peer of every target peer's map.
-func BenchmarkNetworkMapGeneration_AllPeersPostureChecks(b *testing.B) {
-	skipCIBenchmark(b)
-	scales := []benchmarkScale{
-		{"500peers_20groups", 500, 20},
-		{"1000peers_50groups", 1000, 50},
-	}
-
-	for _, scale := range scales {
-		account, validatedPeers := scalableTestAccount(scale.peers, scale.groups)
-		account.Policies[0].SourcePostureChecks = []string{"posture-check-ver"}
-		ctx := context.Background()
-
-		peerIDs := make([]string, 0, len(account.Peers))
-		for peerID := range account.Peers {
-			peerIDs = append(peerIDs, peerID)
-		}
-
-		b.Run("components/"+scale.name, func(b *testing.B) {
-			resourcePolicies := account.GetResourcePoliciesMap()
-			routers := account.GetResourceRoutersMap()
-			groupIDToUserIDs := account.GetActiveGroupUsers()
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				account.PrecomputePostureValidation(ctx)
 				for _, peerID := range peerIDs {
 					_ = account.GetPeerNetworkMapFromComponents(ctx, peerID, nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, nil, groupIDToUserIDs)
 				}

management/server/user.go

@@ -593,9 +593,7 @@ func (am *DefaultAccountManager) SaveOrAddUsers(ctx context.Context, accountID,
 		return nil, err
 	}
 
-	var requiresAccountUpdate bool
-	var snaps []*affectedpeers.Snapshot
-	var changes []affectedpeers.Change
+	var updateAccountPeers bool
 	var peersToExpire []*nbpeer.Peer
 	var addUserEvents []func()
 	var usersToSave = make([]*types.User, 0, len(updates))
@@ -631,26 +629,20 @@ func (am *DefaultAccountManager) SaveOrAddUsers(ctx context.Context, accountID,
 		}
 
 		err = am.Store.ExecuteInTransaction(ctx, func(transaction store.Store) error {
-			effect, updatedUser, userPeersToExpire, userEvents, err := am.processUserUpdate(
+			_, updatedUser, userPeersToExpire, userEvents, err := am.processUserUpdate(
 				ctx, transaction, groupsMap, accountID, initiatorUserID, initiatorUser, update, addIfNotExists, settings,
 			)
 			if err != nil {
 				return fmt.Errorf("failed to process update for user %s: %w", update.Id, err)
 			}
 
+			updateAccountPeers = true
+
 			err = transaction.SaveUser(ctx, updatedUser)
 			if err != nil {
 				return fmt.Errorf("failed to save updated user %s: %w", update.Id, err)
 			}
 
-			snap, err := affectedpeers.Load(ctx, transaction, accountID, effect.change)
-			if err != nil {
-				return err
-			}
-
-			requiresAccountUpdate = requiresAccountUpdate || effect.requiresAccountUpdate
-			snaps = append(snaps, snap)
-			changes = append(changes, effect.change)
 			usersToSave = append(usersToSave, updatedUser)
 			addUserEvents = append(addUserEvents, userEvents...)
 			peersToExpire = append(peersToExpire, userPeersToExpire...)
@@ -691,15 +683,11 @@ func (am *DefaultAccountManager) SaveOrAddUsers(ctx context.Context, accountID,
 			log.WithContext(ctx).Errorf("failed update expired peers: %s", err)
 			return nil, err
 		}
-	} else if len(usersToSave) > 0 {
+	} else if updateAccountPeers {
 		if err = am.Store.IncrementNetworkSerial(ctx, accountID); err != nil {
 			return nil, fmt.Errorf("failed to increment network serial: %w", err)
 		}
-		if requiresAccountUpdate {
-			am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceUser, Operation: types.UpdateOperationUpdate})
-		} else {
-			go am.dispatchAffected(ctx, accountID, snaps, changes)
-		}
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceUser, Operation: types.UpdateOperationUpdate})
 	}
 
 	return updatedUsersInfo, globalErr
@@ -770,31 +758,20 @@ func (am *DefaultAccountManager) prepareUserUpdateEvents(ctx context.Context, ac
 	return eventsToStore
 }
 
-// userUpdateEffect describes how a user update has to reach peers. Users only enter a
-// network map through the SSH rules, so the change resolves to those rules' peers —
-// except when the update triggers an IPv6 reconciliation, which reassigns addresses
-// across the account and so has to reach everyone.
-type userUpdateEffect struct {
-	change                affectedpeers.Change
-	requiresAccountUpdate bool
-}
-
 func (am *DefaultAccountManager) processUserUpdate(ctx context.Context, transaction store.Store, groupsMap map[string]*types.Group,
-	accountID, initiatorUserId string, initiatorUser, update *types.User, addIfNotExists bool, settings *types.Settings) (userUpdateEffect, *types.User, []*nbpeer.Peer, []func(), error) {
-
-	var effect userUpdateEffect
+	accountID, initiatorUserId string, initiatorUser, update *types.User, addIfNotExists bool, settings *types.Settings) (bool, *types.User, []*nbpeer.Peer, []func(), error) {
 
 	if update == nil {
-		return effect, nil, nil, nil, status.Errorf(status.InvalidArgument, "provided user update is nil")
+		return false, nil, nil, nil, status.Errorf(status.InvalidArgument, "provided user update is nil")
 	}
 
 	oldUser, isNewUser, err := getUserOrCreateIfNotExists(ctx, transaction, accountID, update, addIfNotExists)
 	if err != nil {
-		return effect, nil, nil, nil, err
+		return false, nil, nil, nil, err
 	}
 
 	if err := validateUserUpdate(groupsMap, initiatorUser, oldUser, update); err != nil {
-		return effect, nil, nil, nil, err
+		return false, nil, nil, nil, err
 	}
 
 	// only auto groups, revoked status, and integration reference can be updated for now
@@ -815,13 +792,13 @@ func (am *DefaultAccountManager) processUserUpdate(ctx context.Context, transact
 	var transferredOwnerRole bool
 	result, err := handleOwnerRoleTransfer(ctx, transaction, initiatorUser, update)
 	if err != nil {
-		return effect, nil, nil, nil, err
+		return false, nil, nil, nil, err
 	}
 	transferredOwnerRole = result
 
 	userPeers, err := transaction.GetUserPeers(ctx, store.LockingStrengthNone, updatedUser.AccountID, update.Id)
 	if err != nil {
-		return effect, nil, nil, nil, err
+		return false, nil, nil, nil, err
 	}
 
 	var peersToExpire []*nbpeer.Peer
@@ -830,21 +807,6 @@ func (am *DefaultAccountManager) processUserUpdate(ctx context.Context, transact
 		peersToExpire = userPeers
 	}
 
-	// A user reaches a peer's network map only through the SSH rules: as part of a
-	// group -> user mapping, and as part of the account's allowed-user set. Creating,
-	// blocking or unblocking a user adds it to or removes it from both, so every group
-	// it maps into changes — including the All group that holds every active user.
-	// Otherwise only the auto-groups it joined or left do.
-	if isNewUser || oldUser.IsBlocked() != updatedUser.IsBlocked() {
-		effect.change.AllowedUsersChanged = true
-		effect.change.UserGroupIDs = slices.Concat(oldUser.AutoGroups, updatedUser.AutoGroups, allGroupIDs(groupsMap))
-	} else {
-		effect.change.UserGroupIDs = slices.Concat(
-			util.Difference(oldUser.AutoGroups, updatedUser.AutoGroups),
-			util.Difference(updatedUser.AutoGroups, oldUser.AutoGroups),
-		)
-	}
-
 	var removedGroups, addedGroups []string
 	if update.AutoGroups != nil && settings.GroupsPropagationEnabled {
 		removedGroups = util.Difference(oldUser.AutoGroups, update.AutoGroups)
@@ -852,47 +814,26 @@ func (am *DefaultAccountManager) processUserUpdate(ctx context.Context, transact
 		for _, peer := range userPeers {
 			for _, groupID := range removedGroups {
 				if err := transaction.RemovePeerFromGroup(ctx, peer.ID, groupID); err != nil {
-					return effect, nil, nil, nil, fmt.Errorf("failed to remove peer %s from group %s: %w", peer.ID, groupID, err)
+					return false, nil, nil, nil, fmt.Errorf("failed to remove peer %s from group %s: %w", peer.ID, groupID, err)
 				}
 			}
 			for _, groupID := range addedGroups {
 				if err := transaction.AddPeerToGroup(ctx, accountID, peer.ID, groupID); err != nil {
-					return effect, nil, nil, nil, fmt.Errorf("failed to add peer %s to group %s: %w", peer.ID, groupID, err)
+					return false, nil, nil, nil, fmt.Errorf("failed to add peer %s to group %s: %w", peer.ID, groupID, err)
 				}
 			}
 		}
 
 		allGroupChanges := slices.Concat(removedGroups, addedGroups)
-		if len(allGroupChanges) > 0 {
-			effect.change.LinkGroups = allGroupChanges
-			for _, peer := range userPeers {
-				effect.change.OutputPeerIDs = append(effect.change.OutputPeerIDs, peer.ID)
-			}
-		}
-
-		// The reconciliation reassigns IPv6 addresses across the account, which every
-		// peer that can reach the reassigned ones observes.
-		effect.requiresAccountUpdate = ipv6ReconcileNeeded(settings, allGroupChanges)
-
 		if err := am.reconcileIPv6ForGroupChanges(ctx, transaction, accountID, allGroupChanges); err != nil {
-			return effect, nil, nil, nil, fmt.Errorf("reconcile IPv6 for group changes: %w", err)
+			return false, nil, nil, nil, fmt.Errorf("reconcile IPv6 for group changes: %w", err)
 		}
 	}
 
+	updateAccountPeers := len(userPeers) > 0
 	userEventsToAdd := am.prepareUserUpdateEvents(ctx, updatedUser.AccountID, initiatorUserId, oldUser, updatedUser, transferredOwnerRole, isNewUser, removedGroups, addedGroups, transaction)
 
-	return effect, updatedUser, peersToExpire, userEventsToAdd, nil
-}
-
-// allGroupIDs returns the ID of the account's All group, which every active user maps
-// into, as a slice so callers can concatenate it.
-func allGroupIDs(groupsMap map[string]*types.Group) []string {
-	for _, group := range groupsMap {
-		if group.IsGroupAll() {
-			return []string{group.ID}
-		}
-	}
-	return nil
+	return updateAccountPeers, updatedUser, peersToExpire, userEventsToAdd, nil
 }
 
 // getUserOrCreateIfNotExists retrieves the existing user or creates a new one if it doesn't exist.

shared/signal/client/client.go

@@ -52,6 +52,11 @@ type CredentialPayload struct {
 	Credential      *Credential
 	RosenpassPubKey []byte
 	RosenpassAddr   string
+	// MlkemPayload is the opaque post-quantum KEM handshake message riding this
+	// OFFER/ANSWER (see Body.mlkemPayload). Nil when not running the PQ exchange.
+	MlkemPayload []byte
+	// MlkemPort is the sender's ML-KEM PQ service UDP port (0 when not running).
+	MlkemPort       int
 	RelaySrvAddress string
 	RelaySrvIP      netip.Addr
 	SessionID       []byte
@@ -89,6 +94,13 @@ func MarshalCredential(myKey wgtypes.Key, remoteKey string, p CredentialPayload)
 	if p.RelaySrvIP.IsValid() {
 		body.RelayServerIP = p.RelaySrvIP.Unmap().AsSlice()
 	}
+	if len(p.MlkemPayload) > 0 {
+		body.MlkemPayload = p.MlkemPayload
+	}
+	if p.MlkemPort > 0 {
+		port := uint32(p.MlkemPort)
+		body.MlkemPort = &port
+	}
 	return &proto.Message{
 		Key:       myKey.PublicKey().String(),
 		RemoteKey: remoteKey,

shared/signal/proto/signalexchange.pb.go

@@ -239,6 +239,16 @@ type Body struct {
 	// fallback dial target when DNS resolution of relayServerAddress fails.
 	// SNI/TLS verification still uses relayServerAddress.
 	RelayServerIP []byte `protobuf:"bytes,11,opt,name=relayServerIP,proto3,oneof" json:"relayServerIP,omitempty"`
+	// mlkemPayload carries a post-quantum X25519MLKEM768 handshake message that
+	// seeds the WireGuard PSK, riding this Body's OFFER/ANSWER: on an OFFER it is
+	// the KEM offer, on an ANSWER the KEM answer. It is opaque to signal — the
+	// pqkem library frames and parses it. Absent when the sender does not run the
+	// ML-KEM PQ exchange; unknown to older clients, which ignore it.
+	MlkemPayload []byte `protobuf:"bytes,12,opt,name=mlkemPayload,proto3,oneof" json:"mlkemPayload,omitempty"`
+	// mlkemPort is the UDP port of the sender's ML-KEM PQ service, bound on its
+	// WireGuard overlay IP. Peers send subsequent rekey messages there over the
+	// data path. Zero/absent when the ML-KEM PQ exchange is not running.
+	MlkemPort *uint32 `protobuf:"varint,13,opt,name=mlkemPort,proto3,oneof" json:"mlkemPort,omitempty"`
 }
 
 func (x *Body) Reset() {
@@ -343,6 +353,20 @@ func (x *Body) GetRelayServerIP() []byte {
 	return nil
 }
 
+func (x *Body) GetMlkemPayload() []byte {
+	if x != nil {
+		return x.MlkemPayload
+	}
+	return nil
+}
+
+func (x *Body) GetMlkemPort() uint32 {
+	if x != nil && x.MlkemPort != nil {
+		return *x.MlkemPort
+	}
+	return 0
+}
+
 // Mode indicates a connection mode
 type Mode struct {
 	state         protoimpl.MessageState
@@ -466,7 +490,7 @@ var file_signalexchange_proto_rawDesc = []byte{
 	0x52, 0x09, 0x72, 0x65, 0x6d, 0x6f, 0x74, 0x65, 0x4b, 0x65, 0x79, 0x12, 0x28, 0x0a, 0x04, 0x62,
 	0x6f, 0x64, 0x79, 0x18, 0x04, 0x20, 0x01, 0x28, 0x0b, 0x32, 0x14, 0x2e, 0x73, 0x69, 0x67, 0x6e,
 	0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x42, 0x6f, 0x64, 0x79, 0x52,
-	0x04, 0x62, 0x6f, 0x64, 0x79, 0x22, 0xd2, 0x04, 0x0a, 0x04, 0x42, 0x6f, 0x64, 0x79, 0x12, 0x2d,
+	0x04, 0x62, 0x6f, 0x64, 0x79, 0x22, 0xbd, 0x05, 0x0a, 0x04, 0x42, 0x6f, 0x64, 0x79, 0x12, 0x2d,
 	0x0a, 0x04, 0x74, 0x79, 0x70, 0x65, 0x18, 0x01, 0x20, 0x01, 0x28, 0x0e, 0x32, 0x19, 0x2e, 0x73,
 	0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x42, 0x6f,
 	0x64, 0x79, 0x2e, 0x54, 0x79, 0x70, 0x65, 0x52, 0x04, 0x74, 0x79, 0x70, 0x65, 0x12, 0x18, 0x0a,
@@ -494,39 +518,46 @@ var file_signalexchange_proto_rawDesc = []byte{
 	0x52, 0x09, 0x73, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x49, 0x64, 0x88, 0x01, 0x01, 0x12, 0x29,
 	0x0a, 0x0d, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x49, 0x50, 0x18,
 	0x0b, 0x20, 0x01, 0x28, 0x0c, 0x48, 0x02, 0x52, 0x0d, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65,
-	0x72, 0x76, 0x65, 0x72, 0x49, 0x50, 0x88, 0x01, 0x01, 0x22, 0x52, 0x0a, 0x04, 0x54, 0x79, 0x70,
-	0x65, 0x12, 0x09, 0x0a, 0x05, 0x4f, 0x46, 0x46, 0x45, 0x52, 0x10, 0x00, 0x12, 0x0a, 0x0a, 0x06,
-	0x41, 0x4e, 0x53, 0x57, 0x45, 0x52, 0x10, 0x01, 0x12, 0x0d, 0x0a, 0x09, 0x43, 0x41, 0x4e, 0x44,
-	0x49, 0x44, 0x41, 0x54, 0x45, 0x10, 0x02, 0x12, 0x08, 0x0a, 0x04, 0x4d, 0x4f, 0x44, 0x45, 0x10,
-	0x04, 0x12, 0x0b, 0x0a, 0x07, 0x47, 0x4f, 0x5f, 0x49, 0x44, 0x4c, 0x45, 0x10, 0x05, 0x12, 0x0d,
-	0x0a, 0x09, 0x48, 0x45, 0x41, 0x52, 0x54, 0x42, 0x45, 0x41, 0x54, 0x10, 0x06, 0x42, 0x15, 0x0a,
-	0x13, 0x5f, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64,
-	0x72, 0x65, 0x73, 0x73, 0x42, 0x0c, 0x0a, 0x0a, 0x5f, 0x73, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e,
-	0x49, 0x64, 0x42, 0x10, 0x0a, 0x0e, 0x5f, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76,
-	0x65, 0x72, 0x49, 0x50, 0x4a, 0x04, 0x08, 0x09, 0x10, 0x0a, 0x22, 0x2e, 0x0a, 0x04, 0x4d, 0x6f,
-	0x64, 0x65, 0x12, 0x1b, 0x0a, 0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x18, 0x01, 0x20, 0x01,
-	0x28, 0x08, 0x48, 0x00, 0x52, 0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x88, 0x01, 0x01, 0x42,
-	0x09, 0x0a, 0x07, 0x5f, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x22, 0x6d, 0x0a, 0x0f, 0x52, 0x6f,
-	0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x43, 0x6f, 0x6e, 0x66, 0x69, 0x67, 0x12, 0x28, 0x0a,
-	0x0f, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x50, 0x75, 0x62, 0x4b, 0x65, 0x79,
-	0x18, 0x01, 0x20, 0x01, 0x28, 0x0c, 0x52, 0x0f, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73,
-	0x73, 0x50, 0x75, 0x62, 0x4b, 0x65, 0x79, 0x12, 0x30, 0x0a, 0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e,
-	0x70, 0x61, 0x73, 0x73, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x18, 0x02,
-	0x20, 0x01, 0x28, 0x09, 0x52, 0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x53,
-	0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x32, 0xb9, 0x01, 0x0a, 0x0e, 0x53, 0x69,
-	0x67, 0x6e, 0x61, 0x6c, 0x45, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x12, 0x4c, 0x0a, 0x04,
-	0x53, 0x65, 0x6e, 0x64, 0x12, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63,
-	0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d,
-	0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x1a, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65,
+	0x72, 0x76, 0x65, 0x72, 0x49, 0x50, 0x88, 0x01, 0x01, 0x12, 0x27, 0x0a, 0x0c, 0x6d, 0x6c, 0x6b,
+	0x65, 0x6d, 0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61, 0x64, 0x18, 0x0c, 0x20, 0x01, 0x28, 0x0c, 0x48,
+	0x03, 0x52, 0x0c, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61, 0x64, 0x88,
+	0x01, 0x01, 0x12, 0x21, 0x0a, 0x09, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x6f, 0x72, 0x74, 0x18,
+	0x0d, 0x20, 0x01, 0x28, 0x0d, 0x48, 0x04, 0x52, 0x09, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x6f,
+	0x72, 0x74, 0x88, 0x01, 0x01, 0x22, 0x52, 0x0a, 0x04, 0x54, 0x79, 0x70, 0x65, 0x12, 0x09, 0x0a,
+	0x05, 0x4f, 0x46, 0x46, 0x45, 0x52, 0x10, 0x00, 0x12, 0x0a, 0x0a, 0x06, 0x41, 0x4e, 0x53, 0x57,
+	0x45, 0x52, 0x10, 0x01, 0x12, 0x0d, 0x0a, 0x09, 0x43, 0x41, 0x4e, 0x44, 0x49, 0x44, 0x41, 0x54,
+	0x45, 0x10, 0x02, 0x12, 0x08, 0x0a, 0x04, 0x4d, 0x4f, 0x44, 0x45, 0x10, 0x04, 0x12, 0x0b, 0x0a,
+	0x07, 0x47, 0x4f, 0x5f, 0x49, 0x44, 0x4c, 0x45, 0x10, 0x05, 0x12, 0x0d, 0x0a, 0x09, 0x48, 0x45,
+	0x41, 0x52, 0x54, 0x42, 0x45, 0x41, 0x54, 0x10, 0x06, 0x42, 0x15, 0x0a, 0x13, 0x5f, 0x72, 0x65,
+	0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x65, 0x73, 0x73,
+	0x42, 0x0c, 0x0a, 0x0a, 0x5f, 0x73, 0x65, 0x73, 0x73, 0x69, 0x6f, 0x6e, 0x49, 0x64, 0x42, 0x10,
+	0x0a, 0x0e, 0x5f, 0x72, 0x65, 0x6c, 0x61, 0x79, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72, 0x49, 0x50,
+	0x42, 0x0f, 0x0a, 0x0d, 0x5f, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61,
+	0x64, 0x42, 0x0c, 0x0a, 0x0a, 0x5f, 0x6d, 0x6c, 0x6b, 0x65, 0x6d, 0x50, 0x6f, 0x72, 0x74, 0x4a,
+	0x04, 0x08, 0x09, 0x10, 0x0a, 0x22, 0x2e, 0x0a, 0x04, 0x4d, 0x6f, 0x64, 0x65, 0x12, 0x1b, 0x0a,
+	0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x18, 0x01, 0x20, 0x01, 0x28, 0x08, 0x48, 0x00, 0x52,
+	0x06, 0x64, 0x69, 0x72, 0x65, 0x63, 0x74, 0x88, 0x01, 0x01, 0x42, 0x09, 0x0a, 0x07, 0x5f, 0x64,
+	0x69, 0x72, 0x65, 0x63, 0x74, 0x22, 0x6d, 0x0a, 0x0f, 0x52, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61,
+	0x73, 0x73, 0x43, 0x6f, 0x6e, 0x66, 0x69, 0x67, 0x12, 0x28, 0x0a, 0x0f, 0x72, 0x6f, 0x73, 0x65,
+	0x6e, 0x70, 0x61, 0x73, 0x73, 0x50, 0x75, 0x62, 0x4b, 0x65, 0x79, 0x18, 0x01, 0x20, 0x01, 0x28,
+	0x0c, 0x52, 0x0f, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x50, 0x75, 0x62, 0x4b,
+	0x65, 0x79, 0x12, 0x30, 0x0a, 0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x53,
+	0x65, 0x72, 0x76, 0x65, 0x72, 0x41, 0x64, 0x64, 0x72, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52,
+	0x13, 0x72, 0x6f, 0x73, 0x65, 0x6e, 0x70, 0x61, 0x73, 0x73, 0x53, 0x65, 0x72, 0x76, 0x65, 0x72,
+	0x41, 0x64, 0x64, 0x72, 0x32, 0xb9, 0x01, 0x0a, 0x0e, 0x53, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x45,
+	0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x12, 0x4c, 0x0a, 0x04, 0x53, 0x65, 0x6e, 0x64, 0x12,
+	0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65,
+	0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67,
+	0x65, 0x1a, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e,
+	0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73,
+	0x61, 0x67, 0x65, 0x22, 0x00, 0x12, 0x59, 0x0a, 0x0d, 0x43, 0x6f, 0x6e, 0x6e, 0x65, 0x63, 0x74,
+	0x53, 0x74, 0x72, 0x65, 0x61, 0x6d, 0x12, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65,
 	0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65,
-	0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x22, 0x00, 0x12, 0x59, 0x0a, 0x0d, 0x43, 0x6f,
-	0x6e, 0x6e, 0x65, 0x63, 0x74, 0x53, 0x74, 0x72, 0x65, 0x61, 0x6d, 0x12, 0x20, 0x2e, 0x73, 0x69,
-	0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63,
-	0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x1a, 0x20, 0x2e,
-	0x73, 0x69, 0x67, 0x6e, 0x61, 0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45,
-	0x6e, 0x63, 0x72, 0x79, 0x70, 0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x22,
-	0x00, 0x28, 0x01, 0x30, 0x01, 0x42, 0x08, 0x5a, 0x06, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62,
-	0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33,
+	0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x1a, 0x20, 0x2e, 0x73, 0x69, 0x67, 0x6e, 0x61,
+	0x6c, 0x65, 0x78, 0x63, 0x68, 0x61, 0x6e, 0x67, 0x65, 0x2e, 0x45, 0x6e, 0x63, 0x72, 0x79, 0x70,
+	0x74, 0x65, 0x64, 0x4d, 0x65, 0x73, 0x73, 0x61, 0x67, 0x65, 0x22, 0x00, 0x28, 0x01, 0x30, 0x01,
+	0x42, 0x08, 0x5a, 0x06, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74,
+	0x6f, 0x33,
 }
 
 var (

shared/signal/proto/signalexchange.proto

@@ -75,6 +75,18 @@ message Body {
   // fallback dial target when DNS resolution of relayServerAddress fails.
   // SNI/TLS verification still uses relayServerAddress.
   optional bytes relayServerIP = 11;
+
+  // mlkemPayload carries a post-quantum X25519MLKEM768 handshake message that
+  // seeds the WireGuard PSK, riding this Body's OFFER/ANSWER: on an OFFER it is
+  // the KEM offer, on an ANSWER the KEM answer. It is opaque to signal — the
+  // pqkem library frames and parses it. Absent when the sender does not run the
+  // ML-KEM PQ exchange; unknown to older clients, which ignore it.
+  optional bytes mlkemPayload = 12;
+
+  // mlkemPort is the UDP port of the sender's ML-KEM PQ service, bound on its
+  // WireGuard overlay IP. Peers send subsequent rekey messages there over the
+  // data path. Zero/absent when the ML-KEM PQ exchange is not running.
+  optional uint32 mlkemPort = 13;
 }
 
 // Mode indicates a connection mode