Skip to content

Agent Mesh

node: serve gossip to authenticated peers only, handshake before a query

Antonio Ojea66e82698b08f
diff --git a/internal/node/auth_gate.go b/internal/node/auth_gate.go
new file mode 100644
index 00000000..baa410d7
--- /dev/null
+++ b/internal/node/auth_gate.go
@@ -0,0 +1,137 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "time"
+
+ "github.com/libp2p/go-libp2p/core/host"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/libp2p/go-libp2p/core/protocol"
+)
+
+// streamScopeUnauthenticated labels a stream the gate refused: its peer
+// never authenticated while the stream waited.
+const streamScopeUnauthenticated = "unauthenticated"
+
+// authWait bounds how long a stream waits for its peer's handshake: a
+// router's auth deadline for the connection, so a peer that never
+// authenticates is cut off with it.
+const authWait = time.Minute
+
+const authPollInterval = 100 * time.Millisecond
+
+var errNotAuthenticated = errors.New("peer did not authenticate")
+
+// meshHost is the host the node's DHT and gossipsub are built on. A stream
+// a library opens to a router runs the handshake with that router first,
+// so the router serves it at once instead of holding it; a stream to another
+// member waits for that member to authenticate, as it does when it calls.
+// A stream a library serves is served only to a router this node
+// authenticated with or a peer that authenticated with this node; any other
+// waits for that, bounded, and is then refused and counted.
+type meshHost struct {
+ host.Host
+ n *AgentMeshNode
+}
+
+func (h *meshHost) SetStreamHandler(pid protocol.ID, handler network.StreamHandler) {
+ h.Host.SetStreamHandler(pid, h.n.requireAuthenticated(handler))
+}
+
+func (h *meshHost) SetStreamHandlerMatch(pid protocol.ID, match func(protocol.ID) bool, handler network.StreamHandler) {
+ h.Host.SetStreamHandlerMatch(pid, match, h.n.requireAuthenticated(handler))
+}
+
+func (h *meshHost) NewStream(ctx context.Context, p peer.ID, pids ...protocol.ID) (network.Stream, error) {
+ if err := h.n.ensurePeerAuthenticated(ctx, p); err != nil {
+ return nil, err
+ }
+ return h.Host.NewStream(ctx, p, pids...)
+}
+
+// isPeerAuthenticated reports whether p is a router this node authenticated
+// with on an open session, or a peer whose handshake with this node holds.
+func (n *AgentMeshNode) isPeerAuthenticated(p peer.ID) bool {
+ return n.isAuthenticatedAndConnected(p) || n.isAdmitted(p)
+}
+
+// ensurePeerAuthenticated returns once p is authenticated: for a router the
+// control plane lists, by running the handshake (one at a time per router,
+// shared with the one the connection notifee started). Any other peer
+// authenticates with this node when it calls it; until it has, nothing is
+// sent to it, and a lookup is not held waiting for a peer it cannot vouch
+// for.
+func (n *AgentMeshNode) ensurePeerAuthenticated(ctx context.Context, p peer.ID) error {
+ if n.isPeerAuthenticated(p) {
+ return nil
+ }
+ if !n.isCatalogRouter(p) {
+ return fmt.Errorf("%s: %w", p, errNotAuthenticated)
+ }
+ biscuitBytes, err := n.loadIdentityForAuth()
+ if err != nil {
+ return err
+ }
+ return n.authRouter(ctx, peer.AddrInfo{ID: p}, biscuitBytes)
+}
+
+// requireAuthenticated wraps a stream handler so it runs only once the
+// stream's peer is authenticated.
+func (n *AgentMeshNode) requireAuthenticated(next network.StreamHandler) network.StreamHandler {
+ return func(s network.Stream) {
+ p := s.Conn().RemotePeer()
+ if err := n.awaitPeerAuthenticated(context.Background(), p); err != nil {
+ streamsRefusedTotal.WithLabelValues(streamScopeUnauthenticated, string(s.Protocol())).Inc()
+ logger.Debugf("[AuthZ] Refusing %s stream from %s: %v", s.Protocol(), p, err)
+ _ = s.Reset()
+ return
+ }
+ next(s)
+ }
+}
+
+// awaitPeerAuthenticated returns once p is authenticated, or with an error
+// when ctx ends, p's connections are gone, or authWait passes.
+func (n *AgentMeshNode) awaitPeerAuthenticated(ctx context.Context, p peer.ID) error {
+ if n.isPeerAuthenticated(p) {
+ return nil
+ }
+ parent := ctx
+ ctx, cancel := context.WithTimeout(ctx, authWait)
+ defer cancel()
+ tick := time.NewTicker(authPollInterval)
+ defer tick.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ if parent.Err() != nil {
+ return parent.Err()
+ }
+ return errNotAuthenticated
+ case <-tick.C:
+ }
+ if n.isPeerAuthenticated(p) {
+ return nil
+ }
+ if n.Host.Network().Connectedness(p) != network.Connected {
+ return errNotAuthenticated
+ }
+ }
+}
diff --git a/internal/node/auth_gate_test.go b/internal/node/auth_gate_test.go
new file mode 100644
index 00000000..332fe540
--- /dev/null
+++ b/internal/node/auth_gate_test.go
@@ -0,0 +1,153 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "context"
+ "errors"
+ "io"
+ "testing"
+ "time"
+
+ "github.com/libp2p/go-libp2p"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/libp2p/go-libp2p/core/protocol"
+ "github.com/libp2p/go-msgio"
+ "google.golang.org/protobuf/proto"
+
+ "github.com/google/agentmesh/api"
+)
+
+const echoProtocol protocol.ID = "/test/echo/1.0.0"
+
+func echo(s network.Stream) {
+ defer func() { _ = s.Close() }()
+ _, _ = io.Copy(s, s)
+}
+
+// A stream the node opens to a listed router it has not authenticated with
+// runs the handshake first, once, shared with the one the connection
+// notifee starts; a stream to a peer the node cannot vouch for is refused
+// at once, so a lookup is never held on it.
+func TestNodeStreamsToARouterFollowItsHandshake(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+
+ r1 := newFakeRouter(t, "/ip4/127.0.0.1/tcp/0")
+ r2 := newFakeRouterWithKey(t, r1.cpPub, r1.cpPriv, "/ip4/127.0.0.1/tcp/0")
+ node := r1.startNode(t, ctx, append(r1.routerAddrs, r2.routerAddrs...), func(o *Options) { o.Routers = 1 })
+ other := r2
+ if node.attachedRouters()[0] == r2.h.ID() {
+ other = r1
+ }
+ other.h.SetStreamHandler(echoProtocol, echo)
+ gated := &meshHost{Host: node.Host, n: node}
+
+ s, err := gated.NewStream(ctx, other.h.ID(), echoProtocol)
+ if err != nil {
+ t.Fatalf("NewStream to a listed router: %v", err)
+ }
+ _ = s.Close()
+ if !node.isAuthenticatedAndConnected(other.h.ID()) {
+ t.Fatal("the stream opened before the handshake with the router")
+ }
+ if got := other.handshakes.Load(); got != 1 {
+ t.Errorf("the router saw %d handshakes, want 1", got)
+ }
+
+ stranger, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = stranger.Close() })
+ stranger.SetStreamHandler(echoProtocol, echo)
+ if err := node.Host.Connect(ctx, peer.AddrInfo{ID: stranger.ID(), Addrs: stranger.Addrs()}); err != nil {
+ t.Fatal(err)
+ }
+ start := time.Now()
+ if _, err := gated.NewStream(ctx, stranger.ID(), echoProtocol); !errors.Is(err, errNotAuthenticated) {
+ t.Fatalf("NewStream to a peer that never authenticated: err = %v, want %v", err, errNotAuthenticated)
+ }
+ if took := time.Since(start); took > time.Second {
+ t.Fatalf("the refusal took %v; a lookup must not wait on a peer the node cannot vouch for", took)
+ }
+}
+
+// A handler the node registers through its gated host serves a peer only
+// once that peer authenticated with the node; a stream that arrives first
+// waits for the handshake and is then served.
+func TestNodeServesOnlyAuthenticatedPeers(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+
+ r := newFakeRouter(t, "/ip4/127.0.0.1/tcp/0")
+ node := r.startNode(t, ctx, r.routerAddrs)
+ gated := &meshHost{Host: node.Host, n: node}
+ gated.SetStreamHandler(echoProtocol, echo)
+
+ caller, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = caller.Close() })
+ if err := caller.Connect(ctx, peer.AddrInfo{ID: node.Host.ID(), Addrs: node.Host.Addrs()}); err != nil {
+ t.Fatal(err)
+ }
+
+ s, err := caller.NewStream(ctx, node.Host.ID(), echoProtocol)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = s.Close() }()
+ if _, err := s.Write([]byte("hello")); err != nil {
+ t.Fatal(err)
+ }
+ buf := make([]byte, 5)
+ _ = s.SetReadDeadline(time.Now().Add(300 * time.Millisecond))
+ if n, err := s.Read(buf); err == nil {
+ t.Fatalf("read %q before the handshake; the stream must wait for it", buf[:n])
+ }
+
+ // The caller authenticates with the node, as it does before a call.
+ as, err := caller.NewStream(ctx, node.Host.ID(), api.AuthProtocolID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ frame, err := proto.Marshal(&api.AuthFrame{Biscuit: r.mint(caller.ID().String(), api.RoleNode)})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := msgio.NewVarintWriter(as).WriteMsg(frame); err != nil {
+ t.Fatal(err)
+ }
+ reply, err := msgio.NewVarintReaderSize(as, 1024*64).ReadMsg()
+ if err != nil {
+ t.Fatalf("handshake reply: %v", err)
+ }
+ var resp api.AuthResponse
+ if err := proto.Unmarshal(reply, &resp); err != nil || !resp.Success {
+ t.Fatalf("handshake refused: %v %s", err, resp.GetError())
+ }
+ _ = as.Close()
+
+ _ = s.SetReadDeadline(time.Now().Add(5 * time.Second))
+ if _, err := io.ReadFull(s, buf); err != nil {
+ t.Fatalf("read after the handshake: %v", err)
+ }
+ if string(buf) != "hello" {
+ t.Fatalf("got %q, want %q", buf, "hello")
+ }
+}
diff --git a/internal/node/gossip_hardening_test.go b/internal/node/gossip_hardening_test.go
index b419ba32..9d4a12c1 100644
--- a/internal/node/gossip_hardening_test.go
+++ b/internal/node/gossip_hardening_test.go
@@ -178,11 +178,14 @@ func TestGossipJunkFloodIsRejectedNotForwarded(t *testing.T) {
victim.keysMu.Unlock()
// attacker -> victim -> observer. The observer only ever hears what the
- // victim chooses to forward.
+ // victim chooses to forward. Both authenticated with the victim, as a
+ // caller does: the victim gossips with no one who did not.
attacker := newGossipPeer(t, ctx)
observer := newGossipPeer(t, ctx)
- attacker.connect(t, ctx, victim.Host)
- observer.connect(t, ctx, victim.Host)
+ for _, g := range []*gossipPeer{attacker, observer} {
+ victim.authPeers.Store(g.host.ID(), time.Now().Add(time.Hour))
+ g.connect(t, ctx, victim.Host)
+ }
var mu sync.Mutex
var forwardedJunk []string
diff --git a/internal/node/node.go b/internal/node/node.go
index f8c3c651..5125d159 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -688,8 +688,11 @@ func (n *AgentMeshNode) Start(ctx context.Context) error {
}
}
+ // The DHT and gossip are served by, and serve, authenticated peers only.
+ gated := &meshHost{Host: h, n: n}
+
// Initialize Rendezvous (DHT Client)
- kdht, err := dht.New(h, dhtOptions(n.directorySettings())...)
+ kdht, err := dht.New(gated, dhtOptions(n.directorySettings())...)
if err != nil {
return err
}
@@ -715,7 +718,7 @@ func (n *AgentMeshNode) Start(ctx context.Context) error {
// library default; it is pinned because the event validator and the
// per-author rate limit key on msg.GetFrom(), which only the signature
// makes trustworthy.
- ps, err := pubsub.NewGossipSub(ctx, h, pubsub.WithMessageSignaturePolicy(pubsub.StrictSign))
+ ps, err := pubsub.NewGossipSub(ctx, gated, pubsub.WithMessageSignaturePolicy(pubsub.StrictSign))
if err != nil {
return err
}