Skip to content

Agent Mesh

sdk/meshnet: add embedded Go SDK for Agent Mesh

Antonio Ojeaf90f2ccbcfab
diff --git a/sdk/README.md b/sdk/README.md
index d914a4c7..b8659b26 100644
--- a/sdk/README.md
+++ b/sdk/README.md
@@ -1,8 +1,14 @@
# Native SDKs
This directory holds the SDKs that let an agent join an Agent Mesh from inside
-its own process, without a `agentmesh-node` sidecar. Two languages are in scope:
-
+its own process, without a `agentmesh-node` sidecar. Three languages are in scope:
+
+- [`meshnet/`](meshnet/) — `github.com/google/agentmesh/sdk/meshnet`, Go
+ package modeled on `tailscale.com/tsnet`, built on
+ [go-libp2p](https://github.com/libp2p/go-libp2p) with in-process A2A
+ listeners (private P2P and public external HTTP ingress), `WhoIs`, outbound
+ mesh `*http.Client`, local progressive-discovery `MCPHandler()`, and
+ zero-secret OpenAI `/v1` `InferenceHandler()`.
- [`js/`](js/) — `agentmesh-p2p`, TypeScript for Node.js, built on
[js-libp2p](https://github.com/libp2p/js-libp2p).
- [`python/`](python/) — `agentmesh-p2p` (import `agent_mesh`), built on
diff --git a/sdk/meshnet/README.md b/sdk/meshnet/README.md
new file mode 100644
index 00000000..a43ff562
--- /dev/null
+++ b/sdk/meshnet/README.md
@@ -0,0 +1,118 @@
+# `sdk/meshnet` — Embedded Go SDK for Agent Mesh
+
+Package `meshnet` (`github.com/google/agentmesh/sdk/meshnet`) embeds an Agent Mesh member directly inside a Go binary—modeled on [`tailscale.com/tsnet`](https://pkg.go.dev/tailscale.com/tsnet)—with zero external `agentmesh-node` sidecar process, zero loopback bearer token, and byte-for-byte state directory compatibility (`identity.key` + `credential.json`) with `agentmesh-node`, `sdk/js`, and `sdk/python`.
+
+## Capabilities
+
+- **Lifecycle & State Compatibility (`Server.Up`, `WriteStateDir`, `ReadStateDir`):** Resumes cached credentials from `StateDir`, enrolls via `BootstrapTokenPath` / `BootstrapToken` / `JWTPath` / `TokenSource`, refreshes credentials proactively in the background, verifies signed `/keys` sets, and enforces live `/mesh/events/v1` FloodSub revocations and bans.
+- **In-Process A2A Serving (`Server.ListenA2A`):** Returns in-memory `net.Listener`s (`PrivateListener` over `/libp2p-http` and optional `PublicListener` over `/mesh/ingress/1.0.0` in `EDGE` or `PASSTHROUGH` mode) plus canonical `PrivateURL` and `PublicURL` endpoints. Automatically relativizes and rewrites A2A `AgentCard` `supportedInterfaces` URLs per caller.
+- **Unspoofable Caller Inspection (`Server.WhoIs`):** Maps `http.Request.RemoteAddr` on `PrivateListener` and `PublicListener` to the cryptographically verified `CallerInfo` (`PeerID`, `Principal`, `Roles`, `Labels`, `Task`) without trusting HTTP headers.
+- **Outbound Mesh `*http.Client` (`Server.HTTPClient`, `Server.Discover`):** Routes `http://agentmesh.local/mesh/<peer_id>/<type>/<name>[/<rest>]` over authenticated libp2p streams, verifying provider Biscuits, `allowed_publish` Datalog grants, `EgressRequireLabels`, and `X-Mesh-Required-Labels` before sending request bytes.
+- **Offline Task-Scoped Attenuation (`Server.AttenuateToken`):** Appends a validated `TaskAuthorizationRule` (`tar_block` fact, 0 Datalog rules, 0 checks) and optionally seals the Biscuit in memory to delegate task-scoped credentials to sub-agents or external workers without their own mesh client.
+- **Local Progressive-Discovery MCP Server (`Server.MCPServer`, `Server.MCPHandler`):** Exposes the 6 mesh-operating tools (`list_local_services`, `discover_remote_services`, `get_mesh_info`, `find_remote_tools`, `describe_remote_tool`, `call_remote_tool`) in-process or over Streamable HTTP (e.g. a local Unix domain socket).
+- **Zero-Secret OpenAI `/v1` Inference (`Server.InferenceHandler`):** Serves `GET /v1/models`, `POST /v1/chat/completions`, and `POST /v1/completions` routed over mesh `inference://*` providers with automatic Biscuit injection and streaming SSE pass-through.
+
+## Quickstart
+
+### 1. Serve an A2A Agent (Private P2P + Public HTTPS Ingress)
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ "log"
+ "net/http"
+
+ "github.com/a2aproject/a2a-go/v2/a2asrv"
+ "github.com/google/agentmesh/api"
+ "github.com/google/agentmesh/sdk/meshnet"
+)
+
+func main() {
+ ctx := context.Background()
+
+ srv := &meshnet.Server{
+ StateDir: "/var/lib/my-agent/agentmesh",
+ ControlPlaneURL: "https://bananas.sam-mesh.dev",
+ BootstrapTokenPath: "/run/secrets/agentmesh-join-token",
+ }
+ status, err := srv.Up(ctx)
+ if err != nil {
+ log.Fatal(err)
+ }
+ defer srv.Close()
+
+ ep, err := srv.ListenA2A(ctx, meshnet.A2AOptions{
+ Name: "coder",
+ Description: "Repository coding agent",
+ Public: true,
+ IngressAuth: api.IngressAuthMode_INGRESS_AUTH_MODE_EDGE,
+ IngressAllow: []string{"email:[email protected]"},
+ })
+ if err != nil {
+ log.Fatal(err)
+ }
+ defer ep.Close()
+
+ fmt.Printf("Peer ID: %s\n", status.PeerID)
+ fmt.Printf("Private A2A: %s\n", ep.PrivateURL)
+ if ep.PublicURL != nil {
+ fmt.Printf("Public A2A: %s\n", ep.PublicURL)
+ }
+
+ mux := http.NewServeMux()
+ mux.Handle(a2asrv.WellKnownAgentCardPath, cardHandler)
+ mux.Handle("/invoke", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if caller, ok := srv.WhoIs(r.RemoteAddr); ok {
+ log.Printf("verified caller principal=%s peer=%s task=%s", caller.Principal, caller.PeerID, caller.Task)
+ }
+ rpcHandler.ServeHTTP(w, r)
+ }))
+
+ go http.Serve(ep.PrivateListener, mux)
+ if ep.PublicListener != nil {
+ go http.Serve(ep.PublicListener, mux)
+ }
+ select {}
+}
+```
+
+### 2. Discover & Call Remote Mesh Agents with Stock `a2a-go`
+
+```go
+providers, err := srv.Discover(ctx, api.ServiceType_SERVICE_TYPE_A2A, "coder")
+if err != nil || len(providers) == 0 {
+ log.Fatalf("coder not found: %v", err)
+}
+
+meshHTTP := srv.HTTPClient()
+card, err := agentcard.NewResolver(meshHTTP).Resolve(ctx, providers[0].GetLocalProxyUrl())
+if err != nil {
+ log.Fatal(err)
+}
+client, err := a2aclient.NewFromCard(ctx, card, a2aclient.WithJSONRPCTransport(meshHTTP))
+```
+
+### 3. Expose Mesh MCP & Zero-Secret OpenAI `/v1` Over a Local Unix Socket
+
+```go
+unixLn, err := net.Listen("unix", "/run/agent/mesh.sock")
+if err != nil {
+ log.Fatal(err)
+}
+mux := http.NewServeMux()
+mux.Handle("/mcp", srv.MCPHandler())
+mux.Handle("/v1/", srv.InferenceHandler())
+go http.Serve(unixLn, mux)
+```
+
+### 4. Interoperate with `agentmesh-node` State Directories
+
+An operator can enroll interactively once with `agentmesh-node` and hand the resulting state directory directly to a Go binary embedding `meshnet.Server`:
+
+```bash
+agentmesh-node join --hub https://bananas.sam-mesh.dev
+agentmesh-node state export ~/.config/my-agent/agentmesh
+```
diff --git a/sdk/meshnet/a2a.go b/sdk/meshnet/a2a.go
new file mode 100644
index 00000000..1f2466d0
--- /dev/null
+++ b/sdk/meshnet/a2a.go
@@ -0,0 +1,1024 @@
+// 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 meshnet
+
+import (
+ "bytes"
+ "cmp"
+ "context"
+ "encoding/base64"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "maps"
+ "net"
+ "net/http"
+ "net/http/httputil"
+ "net/url"
+ "slices"
+ "strconv"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/a2aproject/a2a-go/v2/a2a"
+ "github.com/google/agentmesh/api"
+ "github.com/google/agentmesh/internal/identity"
+ gostream "github.com/libp2p/go-libp2p-gostream"
+ "github.com/libp2p/go-libp2p/core/peer"
+)
+
+const (
+ a2aAgentCardPath = ".well-known/agent-card.json"
+ maxAgentCardBytes = 1 << 20
+)
+
+// A2AOptions configures an in-process A2A service registered on a Server.
+type A2AOptions struct {
+ // Name is the service name published under a2a://<Name>. Required.
+ Name string
+ // Description is advertised in system://mesh.catalog discovery responses.
+ Description string
+ // Public exposes the service on external router HTTP ingress
+ // (/ingress/<peer_id>/a2a/<Name>) in addition to private mesh P2P.
+ Public bool
+ // IngressAuth selects edge Biscuit verification (default) or passthrough
+ // when Public is true.
+ IngressAuth api.IngressAuthMode
+ // IngressAllow optionally restricts which attested principals ("email:*",
+ // "user:*", "group:*", "idp_role:*", "node:*") may invoke the service in
+ // INGRESS_AUTH_MODE_EDGE.
+ IngressAllow []string
+ // NoAnnounce skips directory announcements while still serving streams from
+ // peers that dial this PeerID directly.
+ NoAnnounce bool
+}
+
+// Endpoints holds the in-memory listeners and canonical URLs for an A2A service
+// registered via Server.ListenA2A.
+type Endpoints struct {
+ // PrivateListener delivers HTTP requests from authenticated mesh peers over
+ // /libp2p-http. Always non-nil.
+ PrivateListener net.Listener
+ // PrivateURL is http://agentmesh.local/mesh/<peer_id>/a2a/<name>.
+ PrivateURL *url.URL
+ // PublicListener delivers external HTTP requests forwarded by enrolled
+ // routers over /mesh/ingress/1.0.0. Non-nil iff A2AOptions.Public is true.
+ PublicListener net.Listener
+ // PublicURL is <router_ingress_url>/<peer_id>/a2a/<name> when Public is
+ // true, the hub's policy ceiling admitted the ingress announcement, and at
+ // least one router in the catalog advertises an ingress_url; nil otherwise.
+ PublicURL *url.URL
+ // Close unregisters the service, withdraws its directory keys, and closes
+ // PrivateListener and PublicListener.
+ Close func() error
+}
+
+type a2aEntry struct {
+ name string
+ description string
+ noAnnounce bool
+ ingress *api.ServiceIngress
+ privateLn *inprocListener
+ publicLn *inprocListener
+ privateURL *url.URL
+
+ mu sync.RWMutex
+ publicActive bool
+ publicURL *url.URL
+}
+
+func (e *a2aEntry) setPublicState(active bool, pubURL *url.URL) {
+ e.mu.Lock()
+ e.publicActive = active
+ e.publicURL = pubURL
+ e.mu.Unlock()
+}
+
+func (e *a2aEntry) getPublicState() (bool, *url.URL) {
+ e.mu.RLock()
+ defer e.mu.RUnlock()
+ return e.publicActive, e.publicURL
+}
+
+func (e *a2aEntry) serviceInfo() *api.ServiceInfo {
+ active, _ := e.getPublicState()
+ var ing *api.ServiceIngress
+ if active && e.ingress != nil {
+ ing = &api.ServiceIngress{
+ AuthMode: e.ingress.GetAuthMode(),
+ Allow: slices.Clone(e.ingress.GetAllow()),
+ }
+ }
+ return &api.ServiceInfo{
+ Type: api.ServiceType_SERVICE_TYPE_A2A,
+ Name: e.name,
+ Description: e.description,
+ Ingress: ing,
+ }
+}
+
+type meshnetAddr string
+
+func (a meshnetAddr) Network() string { return "meshnet" }
+func (a meshnetAddr) String() string { return string(a) }
+
+type inprocListener struct {
+ addr meshnetAddr
+ conns chan net.Conn
+ closed chan struct{}
+ once sync.Once
+}
+
+func newInprocListener(label string) *inprocListener {
+ return &inprocListener{
+ addr: meshnetAddr(label),
+ conns: make(chan net.Conn),
+ closed: make(chan struct{}),
+ }
+}
+
+func (l *inprocListener) Accept() (net.Conn, error) {
+ select {
+ case <-l.closed:
+ return nil, net.ErrClosed
+ case c := <-l.conns:
+ return c, nil
+ }
+}
+
+func (l *inprocListener) Close() error {
+ l.once.Do(func() { close(l.closed) })
+ return nil
+}
+
+func (l *inprocListener) Addr() net.Addr { return l.addr }
+
+func (l *inprocListener) enqueue(ctx context.Context, c net.Conn) error {
+ select {
+ case <-l.closed:
+ _ = c.Close()
+ return net.ErrClosed
+ case <-ctx.Done():
+ _ = c.Close()
+ return ctx.Err()
+ case l.conns <- c:
+ return nil
+ }
+}
+
+type trackedConn struct {
+ net.Conn
+ local net.Addr
+ remote net.Addr
+ onClose func()
+ once sync.Once
+}
+
+func (c *trackedConn) LocalAddr() net.Addr { return c.local }
+func (c *trackedConn) RemoteAddr() net.Addr { return c.remote }
+
+func (c *trackedConn) Close() error {
+ err := c.Conn.Close()
+ c.once.Do(func() {
+ if c.onClose != nil {
+ c.onClose()
+ }
+ })
+ return err
+}
+
+// WhoIs returns the cryptographically verified mesh identity of the caller
+// behind an active HTTP request served on PrivateListener or PublicListener,
+// keyed by http.Request.RemoteAddr. Because connections are in-memory net.Pipe
+// pairs tracked in Server's active table, WhoIs cannot be spoofed by HTTP
+// headers.
+func (s *Server) WhoIs(remoteAddr string) (*CallerInfo, bool) {
+ v, ok := s.activeConns.Load(remoteAddr)
+ if !ok {
+ return nil, false
+ }
+ info, ok := v.(*CallerInfo)
+ if !ok || info == nil {
+ return nil, false
+ }
+ return &CallerInfo{
+ PeerID: info.PeerID,
+ Principal: info.Principal,
+ Roles: slices.Clone(info.Roles),
+ Labels: maps.Clone(info.Labels),
+ Task: info.Task,
+ }, true
+}
+
+// ListenA2A registers an in-process A2A service on the running Server, announces
+// it to the mesh directory (unless NoAnnounce is true), and returns the
+// in-memory listeners and canonical URLs to pass to http.Server.Serve.
+func (s *Server) ListenA2A(ctx context.Context, opts A2AOptions) (*Endpoints, error) {
+ if s.host == nil || s.dir == nil {
+ return nil, errors.New("meshnet: Server is not running (call Up first)")
+ }
+ name := strings.TrimSpace(opts.Name)
+ if name == "" {
+ return nil, errors.New("meshnet: A2AOptions.Name is required")
+ }
+ if err := api.ValidateServiceFormat(api.ServiceTypeStringA2A + "://" + name); err != nil {
+ return nil, fmt.Errorf("meshnet: invalid A2A service name %q: %w", name, err)
+ }
+
+ var ing *api.ServiceIngress
+ if opts.Public {
+ mode := opts.IngressAuth
+ if mode == api.IngressAuthMode_INGRESS_AUTH_MODE_UNSPECIFIED {
+ mode = api.IngressAuthMode_INGRESS_AUTH_MODE_EDGE
+ }
+ allow := make([]string, len(opts.IngressAllow))
+ for i, raw := range opts.IngressAllow {
+ if prefix, val, ok := strings.Cut(raw, ":"); ok && prefix == api.FactNode {
+ if id, err := peer.Decode(val); err == nil {
+ allow[i] = api.FactNode + ":" + id.String()
+ continue
+ }
+ }
+ allow[i] = raw
+ }
+ ing = &api.ServiceIngress{
+ AuthMode: mode,
+ Allow: allow,
+ }
+ if err := api.ValidateServiceIngress(api.ServiceType_SERVICE_TYPE_A2A, ing); err != nil {
+ return nil, fmt.Errorf("meshnet: service %q: %w", name, err)
+ }
+ }
+
+ privURL, err := url.Parse(s.localMeshURL(s.peerID, api.ServiceTypeStringA2A, name))
+ if err != nil {
+ return nil, err
+ }
+
+ privLn := newInprocListener("meshnet:private:a2a:" + name)
+ var pubLn *inprocListener
+ if opts.Public {
+ pubLn = newInprocListener("meshnet:public:a2a:" + name)
+ }
+
+ entry := &a2aEntry{
+ name: name,
+ description: opts.Description,
+ noAnnounce: opts.NoAnnounce,
+ ingress: ing,
+ privateLn: privLn,
+ publicLn: pubLn,
+ privateURL: privURL,
+ publicActive: opts.Public,
+ }
+
+ s.a2aMu.Lock()
+ if _, exists := s.a2aServices[name]; exists {
+ s.a2aMu.Unlock()
+ return nil, fmt.Errorf("meshnet: A2A service %q is already registered", name)
+ }
+ s.a2aServices[name] = entry
+ s.a2aMu.Unlock()
+
+ if !opts.NoAnnounce {
+ s.announceA2AEntry(ctx, entry)
+ peerCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+ _ = s.dir.provide(peerCtx, api.PeerKey(s.peerID), "")
+ cancel()
+ } else if opts.Public {
+ entry.setPublicState(true, s.computePublicURL(name))
+ }
+
+ _, pubURL := entry.getPublicState()
+ var pubNetLn net.Listener
+ if pubLn != nil {
+ pubNetLn = pubLn
+ }
+
+ var closeOnce sync.Once
+ closeFn := func() error {
+ closeOnce.Do(func() {
+ s.unregisterA2A(name, entry)
+ })
+ return nil
+ }
+
+ return &Endpoints{
+ PrivateListener: privLn,
+ PrivateURL: privURL,
+ PublicListener: pubNetLn,
+ PublicURL: pubURL,
+ Close: closeFn,
+ }, nil
+}
+
+func (s *Server) computePublicURL(name string) *url.URL {
+ urls := s.routerIngressURLs()
+ if len(urls) == 0 {
+ return nil
+ }
+ raw := fmt.Sprintf("%s/%s/%s/%s", urls[0], s.peerID.String(), api.ServiceTypeStringA2A, name)
+ u, err := url.Parse(raw)
+ if err != nil {
+ return nil
+ }
+ return u
+}
+
+func (s *Server) announceA2AEntry(ctx context.Context, entry *a2aEntry) {
+ target := api.ServiceTypeStringA2A + "://" + entry.name
+ nameKey, err := api.ServiceKey(api.ServiceType_SERVICE_TYPE_A2A, entry.name)
+ if err != nil {
+ return
+ }
+ typeKey, err := api.ServiceKey(api.ServiceType_SERVICE_TYPE_A2A, "")
+ if err != nil {
+ return
+ }
+
+ if entry.ingress != nil {
+ ingCtx, ingCancel := context.WithTimeout(ctx, 5*time.Second)
+ err := s.dir.provideWithIngress(ingCtx, nameKey, target, entry.ingress)
+ ingCancel()
+ if err == nil {
+ pubURL := s.computePublicURL(entry.name)
+ entry.setPublicState(true, pubURL)
+ if pubURL != nil {
+ s.log().Info("announced public A2A ingress endpoint", "service", target, "public_url", pubURL.String())
+ }
+ } else {
+ entry.setPublicState(false, nil)
+ if ctx.Err() == nil {
+ s.log().Warn("external ingress announcement refused; falling back to internal-only announcement",
+ "service", target,
+ "error", err,
+ )
+ }
+ fbCtx, fbCancel := context.WithTimeout(ctx, 5*time.Second)
+ if fbErr := s.dir.provide(fbCtx, nameKey, target); fbErr != nil && ctx.Err() == nil {
+ s.log().Warn("internal fallback announcement failed", "service", target, "error", fbErr)
+ }
+ fbCancel()
+ }
+ } else {
+ nameCtx, nameCancel := context.WithTimeout(ctx, 5*time.Second)
+ if err := s.dir.provide(nameCtx, nameKey, target); err != nil && ctx.Err() == nil {
+ s.log().Warn("A2A service name announcement failed", "service", target, "error", err)
+ }
+ nameCancel()
+ }
+
+ typeCtx, typeCancel := context.WithTimeout(ctx, 5*time.Second)
+ if err := s.dir.provide(typeCtx, typeKey, target); err != nil && ctx.Err() == nil {
+ s.log().Warn("A2A service type announcement failed", "service", target, "error", err)
+ }
+ typeCancel()
+}
+
+func (s *Server) unregisterA2A(name string, entry *a2aEntry) {
+ s.a2aMu.Lock()
+ cur, ok := s.a2aServices[name]
+ if ok && cur == entry {
+ delete(s.a2aServices, name)
+ }
+ stillHasA2A := len(s.a2aServices) > 0
+ s.a2aMu.Unlock()
+
+ _ = entry.privateLn.Close()
+ if entry.publicLn != nil {
+ _ = entry.publicLn.Close()
+ }
+
+ if ok && cur == entry && !entry.noAnnounce && s.dir != nil {
+ wCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+ if nameKey, err := api.ServiceKey(api.ServiceType_SERVICE_TYPE_A2A, name); err == nil {
+ _ = s.dir.withdraw(wCtx, nameKey)
+ }
+ if !stillHasA2A {
+ if typeKey, err := api.ServiceKey(api.ServiceType_SERVICE_TYPE_A2A, ""); err == nil {
+ _ = s.dir.withdraw(wCtx, typeKey)
+ }
+ }
+ }
+}
+
+func (s *Server) getA2AEntry(name string) (*a2aEntry, bool) {
+ s.a2aMu.RLock()
+ defer s.a2aMu.RUnlock()
+ e, ok := s.a2aServices[name]
+ return e, ok
+}
+
+func (s *Server) listA2AEntries() []*a2aEntry {
+ s.a2aMu.RLock()
+ defer s.a2aMu.RUnlock()
+ out := make([]*a2aEntry, 0, len(s.a2aServices))
+ for _, e := range s.a2aServices {
+ out = append(out, e)
+ }
+ slices.SortFunc(out, func(a, b *a2aEntry) int { return cmp.Compare(a.name, b.name) })
+ return out
+}
+
+func (s *Server) listLocalServiceInfos(typeFilter api.ServiceType) []*api.ServiceInfo {
+ if typeFilter != api.ServiceType_SERVICE_TYPE_UNSPECIFIED && typeFilter != api.ServiceType_SERVICE_TYPE_A2A {
+ return []*api.ServiceInfo{}
+ }
+ entries := s.listA2AEntries()
+ out := make([]*api.ServiceInfo, 0, len(entries))
+ for _, e := range entries {
+ out = append(out, e.serviceInfo())
+ }
+ return out
+}
+
+func (s *Server) deliverHTTP(w http.ResponseWriter, r *http.Request, ln *inprocListener, caller *CallerInfo, modifyResp func(*http.Response) error) {
+ id := s.nextConnSeq.Add(1)
+ remoteAddr := fmt.Sprintf("meshnet-conn-%d", id)
+ if caller != nil {
+ s.activeConns.Store(remoteAddr, caller)
+ }
+
+ clientSide, serverSide := net.Pipe()
+ serverConn := &trackedConn{
+ Conn: serverSide,
+ local: ln.Addr(),
+ remote: meshnetAddr(remoteAddr),
+ onClose: func() {
+ s.activeConns.Delete(remoteAddr)
+ },
+ }
+ clientConn := &trackedConn{
+ Conn: clientSide,
+ local: meshnetAddr(remoteAddr),
+ remote: ln.Addr(),
+ onClose: func() {
+ s.activeConns.Delete(remoteAddr)
+ },
+ }
+
+ var dialOnce sync.Once
+ transport := &http.Transport{
+ DisableKeepAlives: true,
+ DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+ var conn net.Conn
+ var err error
+ dialOnce.Do(func() {
+ if qErr := ln.enqueue(ctx, serverConn); qErr != nil {
+ _ = clientConn.Close()
+ err = qErr
+ return
+ }
+ conn = clientConn
+ })
+ if err != nil {
+ return nil, err
+ }
+ if conn == nil {
+ return nil, errors.New("in-process connection already consumed")
+ }
+ return conn, nil
+ },
+ }
+ defer transport.CloseIdleConnections()
+
+ proxy := &httputil.ReverseProxy{
+ FlushInterval: -1,
+ Transport: transport,
+ Rewrite: func(pr *httputil.ProxyRequest) {
+ noTrailingSlash := pr.In.Header.Get(api.HeaderMeshNoTrailingSlash) == "true"
+ pr.Out.URL.Scheme = "http"
+ pr.Out.URL.Host = pr.In.Host
+ if pr.Out.URL.Host == "" {
+ pr.Out.URL.Host = "agentmesh.local"
+ }
+ pr.Out.Host = pr.Out.URL.Host
+ pr.Out.Header.Del(api.HeaderMeshNoTrailingSlash)
+ if noTrailingSlash && pr.Out.URL.Path == "/" {
+ pr.Out.URL.Path = "/"
+ }
+ },
+ ModifyResponse: modifyResp,
+ ErrorHandler: func(rw http.ResponseWriter, _ *http.Request, pErr error) {
+ s.activeConns.Delete(remoteAddr)
+ _ = clientConn.Close()
+ _ = serverConn.Close()
+ s.log().Warn("local A2A handler delivery failed", "error", pErr)
+ http.Error(rw, "Bad Gateway", http.StatusBadGateway)
+ },
+ }
+ proxy.ServeHTTP(w, r)
+}
+
+func (s *Server) startHTTPServers(ctx context.Context) error {
+ privListener, err := gostream.Listen(s.host, "/libp2p-http")
+ if err != nil {
+ return fmt.Errorf("listen /libp2p-http: %w", err)
+ }
+ privServer := &http.Server{
+ ReadHeaderTimeout: 10 * time.Second,
+ IdleTimeout: 120 * time.Second,
+ Handler: s.privateHTTPHandler(),
+ }
+
+ gatedRouter := &routerHost{meshHost{Host: s.host, s: s}}
+ pubListener, err := gostream.Listen(gatedRouter, api.IngressProtocolID)
+ if err != nil {
+ _ = privListener.Close()
+ return fmt.Errorf("listen %s: %w", api.IngressProtocolID, err)
+ }
+ pubServer := &http.Server{
+ ReadHeaderTimeout: 10 * time.Second,
+ IdleTimeout: 120 * time.Second,
+ Handler: s.externalIngressHandler(),
+ }
+
+ go func() {
+ if sErr := privServer.Serve(privListener); sErr != nil && !errors.Is(sErr, http.ErrServerClosed) {
+ s.log().Error("private /libp2p-http server error", "error", sErr)
+ }
+ }()
+ go func() {
+ if sErr := pubServer.Serve(pubListener); sErr != nil && !errors.Is(sErr, http.ErrServerClosed) {
+ s.log().Error("external ingress server error", "error", sErr)
+ }
+ }()
+ go func() {
+ <-ctx.Done()
+ _ = privServer.Close()
+ _ = privListener.Close()
+ _ = pubServer.Close()
+ _ = pubListener.Close()
+ }()
+ return nil
+}
+
+func (s *Server) privateHTTPHandler() http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ path := r.URL.Path
+ if api.HasDotSegment(path) {
+ http.Error(w, "Invalid path", http.StatusBadRequest)
+ return
+ }
+ parts := strings.SplitN(strings.TrimPrefix(path, "/"), "/", 3)
+ if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+ http.Error(w, "Invalid path", http.StatusBadRequest)
+ return
+ }
+ svcTypeStr := strings.ToLower(parts[0])
+ svcName := parts[1]
+ upstreamPath := ""
+ if len(parts) > 2 {
+ upstreamPath = parts[2]
+ }
+ svcType, err := api.ParseServiceType(svcTypeStr)
+ if err != nil || svcType == api.ServiceType_SERVICE_TYPE_UNSPECIFIED {
+ http.Error(w, "Invalid service type", http.StatusBadRequest)
+ return
+ }
+
+ biscuitB64 := r.Header.Get(api.HeaderMeshBiscuit)
+ if biscuitB64 == "" {
+ http.Error(w, "Missing X-Mesh-Biscuit header", http.StatusUnauthorized)
+ return
+ }
+ biscuitBytes, err := base64.StdEncoding.DecodeString(biscuitB64)
+ if err != nil {
+ biscuitBytes, err = identity.DecodeBase64Biscuit(biscuitB64)
+ if err != nil {
+ http.Error(w, "Invalid X-Mesh-Biscuit encoding", http.StatusBadRequest)
+ return
+ }
+ }
+
+ remotePeer, err := peer.Decode(r.RemoteAddr)
+ if err != nil {
+ http.Error(w, "Invalid remote peer", http.StatusBadRequest)
+ return
+ }
+ if s.rateLimiter != nil && !s.rateLimiter.Allow(remotePeer.String()) {
+ http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
+ return
+ }
+
+ target := svcTypeStr + "://" + svcName
+ backendPath := "/" + upstreamPath
+ // Authorize BEFORE checking whether svcName is registered so an
+ // unauthorized peer learns nothing about hosted service names.
+ caller, err := s.authorizeInbound(biscuitBytes, remotePeer, target, "/libp2p-http", &httpRequestFacts{
+ method: r.Method,
+ path: backendPath,
+ })
+ if err != nil {
+ http.Error(w, "Authorization failed", http.StatusForbidden)
+ return
+ }
+
+ if svcType != api.ServiceType_SERVICE_TYPE_A2A {
+ http.Error(w, "Service not found", http.StatusNotFound)
+ return
+ }
+ entry, ok := s.getA2AEntry(svcName)
+ if !ok {
+ http.Error(w, "Service not found", http.StatusNotFound)
+ return
+ }
+
+ for h := range r.Header {
+ lower := strings.ToLower(h)
+ if lower == "cookie" || strings.HasPrefix(lower, "x-mesh-") {
+ delete(r.Header, h)
+ }
+ }
+ r.Header.Set(api.HeaderPeerID, remotePeer.String())
+ if caller.Principal != "" {
+ r.Header.Set(api.HeaderMeshPrincipal, caller.Principal)
+ }
+ if len(caller.Roles) > 0 {
+ r.Header.Set(api.HeaderMeshRoles, strings.Join(caller.Roles, ","))
+ }
+ if caller.Task != "" {
+ r.Header.Set(api.HeaderMeshTask, caller.Task)
+ }
+
+ rewriteInboundRequestPath(r, parts, upstreamPath)
+ roots := s.candidateCardRoots(entry)
+ s.deliverHTTP(w, r, entry.privateLn, caller, relativizeAgentCardResponse(entry.name, roots))
+ })
+}
+
+func (s *Server) externalIngressHandler() http.Handler {
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ path := r.URL.Path
+ if api.HasDotSegment(path) {
+ http.Error(w, "Invalid path", http.StatusBadRequest)
+ return
+ }
+ parts := strings.SplitN(strings.TrimPrefix(path, "/"), "/", 3)
+ if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+ http.Error(w, "Invalid path", http.StatusBadRequest)
+ return
+ }
+ svcTypeStr := strings.ToLower(parts[0])
+ svcName := parts[1]
+ upstreamPath := ""
+ if len(parts) > 2 {
+ upstreamPath = parts[2]
+ }
+ svcType, err := api.ParseServiceType(svcTypeStr)
+ if err != nil {
+ http.Error(w, "Invalid service type", http.StatusBadRequest)
+ return
+ }
+ if !api.IsInboundServiceType(svcType) {
+ http.Error(w, "Service not found", http.StatusNotFound)
+ return
+ }
+
+ remotePeer, err := peer.Decode(r.RemoteAddr)
+ if err != nil {
+ http.Error(w, "Invalid remote peer", http.StatusBadRequest)
+ return
+ }
+ if s.isPeerBanned(remotePeer) {
+ http.Error(w, "Peer is revoked", http.StatusForbidden)
+ return
+ }
+ if s.externalIngressLimiter != nil && !s.externalIngressLimiter.Allow(remotePeer.String()) {
+ http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
+ return
+ }
+
+ routerBiscuitHeader := r.Header.Get(api.HeaderMeshBiscuit)
+ if routerBiscuitHeader == "" {
+ http.Error(w, "Missing X-Mesh-Biscuit header", http.StatusUnauthorized)
+ return
+ }
+ routerBiscuitBytes, err := identity.DecodeBase64Biscuit(routerBiscuitHeader)
+ if err != nil {
+ http.Error(w, "Invalid X-Mesh-Biscuit encoding", http.StatusBadRequest)
+ return
+ }
+ routerClaims, err := s.verifyLocalBiscuit(routerBiscuitBytes)
+ if err != nil {
+ s.log().Warn("router biscuit verification failed on external ingress", "router_peer_id", remotePeer.String(), "error", err)
+ http.Error(w, "Router authentication failed", http.StatusForbidden)
+ return
+ }
+ if err := identity.RequireAuthorityBinding(routerClaims.Biscuit, remotePeer); err != nil {
+ s.log().Warn("router biscuit binding mismatch on external ingress", "router_peer_id", remotePeer.String(), "error", err)
+ http.Error(w, "Router authentication failed", http.StatusForbidden)
+ return
+ }
+ if !slices.Contains(routerClaims.Roles, api.RoleRouter) {
+ s.log().Warn("non-router peer attempted external ingress", "peer_id", remotePeer.String())
+ http.Error(w, "Forbidden: only enrolled routers may forward external ingress", http.StatusForbidden)
+ return
+ }
+
+ if svcType != api.ServiceType_SERVICE_TYPE_A2A {
+ http.Error(w, "Service not found", http.StatusNotFound)
+ return
+ }
+ entry, ok := s.getA2AEntry(svcName)
+ if !ok || entry.ingress == nil || entry.publicLn == nil {
+ http.Error(w, "Service not found", http.StatusNotFound)
+ return
+ }
+ if active, _ := entry.getPublicState(); !active {
+ http.Error(w, "Service not found", http.StatusNotFound)
+ return
+ }
+
+ effectiveMode := api.EffectiveIngressAuthMode(entry.ingress)
+ modeStr, err := api.IngressAuthModeToString(effectiveMode)
+ if err != nil {
+ http.Error(w, "Unsupported service ingress auth mode", http.StatusForbidden)
+ return
+ }
+ if wireMode := strings.TrimSpace(r.Header.Get(api.HeaderMeshIngress)); wireMode != "" && wireMode != modeStr {
+ http.Error(w, "Ingress auth mode mismatch", http.StatusForbidden)
+ return
+ }
+
+ target := svcTypeStr + "://" + svcName
+ backendPath := "/" + upstreamPath
+ roots := s.candidateCardRoots(entry)
+
+ if effectiveMode == api.IngressAuthMode_INGRESS_AUTH_MODE_PASSTHROUGH {
+ api.SanitizeExternalIngressHeaders(r.Header, false)
+ r.Header.Set(api.HeaderPeerID, remotePeer.String())
+ r.Header.Set(api.HeaderMeshIngress, api.IngressAuthModeStringPassthrough)
+ s.log().Info("external ingress border crossing",
+ "mode", api.IngressAuthModeStringPassthrough,
+ "router_peer_id", remotePeer.String(),
+ "target", target,
+ "method", r.Method,
+ "path", backendPath,
+ )
+ caller := &CallerInfo{
+ PeerID: remotePeer.String(),
+ Principal: "passthrough",
+ }
+ rewriteInboundRequestPath(r, parts, upstreamPath)
+ s.deliverHTTP(w, r, entry.publicLn, caller, relativizeAgentCardResponse(entry.name, roots))
+ return
+ }
+
+ callerBiscuitHeader := strings.TrimSpace(r.Header.Get(api.HeaderMeshIngressCallerBiscuit))
+ if r.Method == http.MethodGet && upstreamPath == a2aAgentCardPath && callerBiscuitHeader == "" {
+ api.SanitizeExternalIngressHeaders(r.Header, true)
+ r.Header.Set(api.HeaderPeerID, remotePeer.String())
+ r.Header.Set(api.HeaderMeshIngress, api.IngressAuthModeStringEdge)
+ s.log().Info("external ingress border crossing",
+ "mode", api.IngressAuthModeStringEdge,
+ "router_peer_id", remotePeer.String(),
+ "principal", "anonymous:agent-card",
+ "target", target,
+ "method", r.Method,
+ "path", backendPath,
+ )
+ caller := &CallerInfo{
+ PeerID: remotePeer.String(),
+ Principal: "anonymous:agent-card",
+ }
+ rewriteInboundRequestPath(r, parts, upstreamPath)
+ s.deliverHTTP(w, r, entry.publicLn, caller, relativizeAgentCardResponse(entry.name, roots))
+ return
+ }
+
+ if callerBiscuitHeader == "" {
+ http.Error(w, "Missing caller credentials on edge ingress request", http.StatusUnauthorized)
+ return
+ }
+ callerBiscuitBytes, err := identity.DecodeBase64Biscuit(callerBiscuitHeader)
+ if err != nil {
+ http.Error(w, "Invalid caller biscuit encoding", http.StatusBadRequest)
+ return
+ }
+ verifiedCaller, err := s.verifyLocalBiscuit(callerBiscuitBytes)
+ if err != nil {
+ s.log().Warn("external ingress caller verification failed", "router_peer_id", remotePeer.String(), "target", target, "error", err)
+ http.Error(w, "Authorization failed", http.StatusForbidden)
+ return
+ }
+
+ evalParams, err := s.buildExternalIngressEvalParams(svcTypeStr, svcName, r.Method, backendPath, entry.ingress.GetAllow())
+ if err != nil {
+ s.log().Warn("failed building external ingress evaluation params", "target", target, "error", err)
+ http.Error(w, "Authorization failed", http.StatusForbidden)
+ return
+ }
+ callerRes, err := identity.AuthorizeIngressDelegatedBiscuit(verifiedCaller, evalParams)
+ if err != nil {
+ s.log().Warn("external ingress authorization denied", "router_peer_id", remotePeer.String(), "target", target, "error", err)
+ http.Error(w, "Authorization failed", http.StatusForbidden)
+ return
+ }
+
+ api.SanitizeExternalIngressHeaders(r.Header, true)
+ r.Header.Set(api.HeaderPeerID, remotePeer.String())
+ r.Header.Set(api.HeaderMeshIngress, api.IngressAuthModeStringEdge)
+ if callerRes.Principal != "" {
+ r.Header.Set(api.HeaderMeshPrincipal, callerRes.Principal)
+ }
+ if len(callerRes.Roles) > 0 {
+ r.Header.Set(api.HeaderMeshRoles, strings.Join(callerRes.Roles, ","))
+ }
+ if callerRes.TaskName != "" {
+ r.Header.Set(api.HeaderMeshTask, callerRes.TaskName)
+ }
+
+ s.log().Info("external ingress border crossing",
+ "mode", api.IngressAuthModeStringEdge,
+ "router_peer_id", remotePeer.String(),
+ "principal", callerRes.Principal,
+ "roles", callerRes.Roles,
+ "task", callerRes.TaskName,
+ "target", target,
+ "method", r.Method,
+ "path", backendPath,
+ )
+
+ caller := &CallerInfo{
+ PeerID: callerRes.ActorNodeID,
+ Principal: callerRes.Principal,
+ Roles: slices.Clone(callerRes.Roles),
+ Task: callerRes.TaskName,
+ }
+ if caller.PeerID == "" {
+ caller.PeerID = remotePeer.String()
+ }
+ rewriteInboundRequestPath(r, parts, upstreamPath)
+ s.deliverHTTP(w, r, entry.publicLn, caller, relativizeAgentCardResponse(entry.name, roots))
+ })
+}
+
+func (s *Server) buildExternalIngressEvalParams(serviceType, serviceName, method, path string, allow []string) (identity.IngressEvalParams, error) {
+ pol, err := s.meshPolicy()
+ if err != nil {
+ return identity.IngressEvalParams{}, err
+ }
+ return identity.IngressEvalParams{
+ ServiceType: serviceType,
+ ServiceName: serviceName,
+ Method: method,
+ Path: path,
+ TargetFacts: pol.TargetFacts,
+ MeshPolicyRules: pol.MeshRules,
+ Allow: allow,
+ Timeout: s.biscuitTimeout(),
+ }, nil
+}
+
+func rewriteInboundRequestPath(r *http.Request, parts []string, upstreamPath string) {
+ if upstreamPath == "" {
+ r.URL.Path = "/"
+ if len(parts) == 2 {
+ r.Header.Set(api.HeaderMeshNoTrailingSlash, "true")
+ }
+ } else {
+ r.URL.Path = "/" + upstreamPath
+ }
+ r.URL.RawPath = ""
+}
+
+func (s *Server) candidateCardRoots(entry *a2aEntry) []string {
+ roots := []string{"/mesh/" + s.peerID.String() + "/" + api.ServiceTypeStringA2A + "/" + entry.name}
+ if _, pubURL := entry.getPublicState(); pubURL != nil {
+ if p := strings.TrimSuffix(pubURL.EscapedPath(), "/"); p != "" && !slices.Contains(roots, p) {
+ roots = append(roots, p)
+ }
+ }
+ for _, base := range s.routerIngressURLs() {
+ if u, err := url.Parse(base); err == nil {
+ p := strings.TrimSuffix(u.EscapedPath(), "/") + "/" + s.peerID.String() + "/" + api.ServiceTypeStringA2A + "/" + entry.name
+ if !slices.Contains(roots, p) {
+ roots = append(roots, p)
+ }
+ }
+ }
+ slices.SortStableFunc(roots, func(a, b string) int { return cmp.Compare(len(b), len(a)) })
+ roots = append(roots, "")
+ return roots
+}
+
+func relativizeAgentCardResponse(service string, roots []string) func(*http.Response) error {
+ cardPath := "/" + a2aAgentCardPath
+ return func(resp *http.Response) error {
+ if resp.Request == nil || resp.Request.Method != http.MethodGet || resp.Request.URL.EscapedPath() != cardPath ||
+ resp.StatusCode != http.StatusOK {
+ return nil
+ }
+ if resp.Header.Get("Content-Encoding") != "" {
+ return nil
+ }
+ raw, err := io.ReadAll(io.LimitReader(resp.Body, maxAgentCardBytes+1))
+ if err != nil {
+ return fmt.Errorf("read agent card of %q: %w", service, err)
+ }
+ if len(raw) > maxAgentCardBytes {
+ resp.Body = struct {
+ io.Reader
+ io.Closer
+ }{io.MultiReader(bytes.NewReader(raw), resp.Body), resp.Body}
+ return nil
+ }
+ _ = resp.Body.Close()
+ out, err := relativizeAgentCardMultiRoot(raw, roots)
+ if err != nil {
+ out = raw
+ }
+ resp.Body = io.NopCloser(bytes.NewReader(out))
+ resp.ContentLength = int64(len(out))
+ resp.Header.Set("Content-Length", strconv.Itoa(len(out)))
+ return nil
+ }
+}
+
+func relativizeAgentCardMultiRoot(raw []byte, roots []string) ([]byte, error) {
+ var card map[string]json.RawMessage
+ if err := json.Unmarshal(raw, &card); err != nil {
+ return nil, fmt.Errorf("card is not a JSON object: %w", err)
+ }
+ ifacesRaw, ok := card["supportedInterfaces"]
+ if !ok {
+ return raw, nil
+ }
+ var ifaces []map[string]json.RawMessage
+ if err := json.Unmarshal(ifacesRaw, &ifaces); err != nil {
+ return nil, fmt.Errorf("supportedInterfaces is not a list of objects: %w", err)
+ }
+ for _, iface := range ifaces {
+ var u, binding string
+ if iface == nil || json.Unmarshal(iface["url"], &u) != nil || json.Unmarshal(iface["protocolBinding"], &binding) != nil ||
+ !a2aBindingOverHTTP(a2a.TransportProtocol(binding)) {
+ continue
+ }
+ for _, root := range roots {
+ if rel, ok := relativeToRoot(u, root); ok {
+ enc, err := json.Marshal(rel)
+ if err != nil {
+ return nil, err
+ }
+ iface["url"] = enc
+ break
+ }
+ }
+ }
+ enc, err := json.Marshal(ifaces)
+ if err != nil {
+ return nil, err
+ }
+ card["supportedInterfaces"] = enc
+ return json.Marshal(card)
+}
+
+func relativeToRoot(raw, root string) (string, bool) {
+ u, err := url.Parse(raw)
+ if err != nil || !u.IsAbs() || u.Opaque != "" {
+ return "", false
+ }
+ p := u.EscapedPath()
+ var rest string
+ switch {
+ case root == "" && (p == "" || p == "/"):
+ case root == "" && strings.HasPrefix(p, "/"):
+ rest = strings.TrimPrefix(p, "/")
+ case p == root || p == root+"/":
+ case strings.HasPrefix(p, root+"/"):
+ rest = strings.TrimPrefix(p, root+"/")
+ default:
+ return "", false
+ }
+ if api.HasDotSegment(rest) {
+ return "", false
+ }
+ if u.RawQuery != "" {
+ rest += "?" + u.RawQuery
+ }
+ return rest, true
+}
+
+func a2aBindingOverHTTP(binding a2a.TransportProtocol) bool {
+ switch strings.ToUpper(string(binding)) {
+ case string(a2a.TransportProtocolJSONRPC), string(a2a.TransportProtocolHTTPJSON):
+ return true
+ }
+ return false
+}
diff --git a/sdk/meshnet/auth_gate.go b/sdk/meshnet/auth_gate.go
new file mode 100644
index 00000000..c8e1435c
--- /dev/null
+++ b/sdk/meshnet/auth_gate.go
@@ -0,0 +1,383 @@
+// 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 meshnet
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "runtime/debug"
+ "time"
+
+ "github.com/google/agentmesh/api"
+ "github.com/google/agentmesh/internal/identity"
+ "github.com/google/agentmesh/internal/p2plimits"
+ "github.com/libp2p/go-libp2p/core/connmgr"
+ "github.com/libp2p/go-libp2p/core/control"
+ "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"
+ rcmgr "github.com/libp2p/go-libp2p/p2p/host/resource-manager"
+ "github.com/libp2p/go-msgio"
+ "github.com/multiformats/go-multiaddr"
+ "github.com/prometheus/client_golang/prometheus"
+ "google.golang.org/protobuf/proto"
+)
+
+const (
+ streamScopeUnauthenticated = "unauthenticated"
+ streamScopeNotRouter = "not_router"
+
+ authWait = time.Minute
+ authPollInterval = 100 * time.Millisecond
+ authHandshakeTimeout = 10 * time.Second
+ goAwayMaxRetryAfter = time.Hour
+ defaultShunDuration = 5 * time.Minute
+
+ connLowWaterMark = 96
+ connHighWaterMark = 128
+ peerStreamCap = 256
+)
+
+var errNotAuthenticated = errors.New("peer did not authenticate")
+
+var _ connmgr.ConnectionGater = (*connGate)(nil)
+
+type connGate struct {
+ s *Server
+}
+
+func (g *connGate) InterceptPeerDial(p peer.ID) bool {
+ if g.s.isPeerBanned(p) {
+ g.s.log().Warn("refusing outbound dial to banned peer", "peer_id", p.String())
+ return false
+ }
+ return true
+}
+
+func (g *connGate) InterceptAddrDial(_ peer.ID, _ multiaddr.Multiaddr) bool {
+ return true
+}
+
+func (g *connGate) InterceptAccept(_ network.ConnMultiaddrs) bool {
+ return true
+}
+
+func (g *connGate) InterceptSecured(dir network.Direction, p peer.ID, _ network.ConnMultiaddrs) bool {
+ if g.s.isPeerBanned(p) {
+ g.s.log().Warn("refusing secured connection with banned peer", "peer_id", p.String(), "direction", dir.String())
+ return false
+ }
+ return true
+}
+
+func (g *connGate) InterceptUpgraded(_ network.Conn) (bool, control.DisconnectReason) {
+ return true, 0
+}
+
+type meshHost struct {
+ host.Host
+ s *Server
+}
+
+func (h *meshHost) SetStreamHandler(pid protocol.ID, handler network.StreamHandler) {
+ h.Host.SetStreamHandler(pid, h.s.requireAuthenticated(handler))
+}
+
+func (h *meshHost) SetStreamHandlerMatch(pid protocol.ID, match func(protocol.ID) bool, handler network.StreamHandler) {
+ h.Host.SetStreamHandlerMatch(pid, match, h.s.requireAuthenticated(handler))
+}
+
+func (h *meshHost) NewStream(ctx context.Context, p peer.ID, pids ...protocol.ID) (network.Stream, error) {
+ if err := h.s.ensurePeerAuthenticated(ctx, p); err != nil {
+ return nil, err
+ }
+ return h.Host.NewStream(ctx, p, pids...)
+}
+
+type routerHost struct {
+ meshHost
+}
+
+func (h *routerHost) SetStreamHandler(pid protocol.ID, handler network.StreamHandler) {
+ h.Host.SetStreamHandler(pid, h.s.requireRouter(handler))
+}
+
+func (h *routerHost) SetStreamHandlerMatch(pid protocol.ID, match func(protocol.ID) bool, handler network.StreamHandler) {
+ h.Host.SetStreamHandlerMatch(pid, match, h.s.requireRouter(handler))
+}
+
+func (s *Server) isPeerAuthenticated(p peer.ID) bool {
+ return s.isAuthenticatedAndConnected(p) || s.isAdmitted(p)
+}
+
+func (s *Server) isAuthenticatedRouter(p peer.ID) bool {
+ return s.isAuthenticatedAndConnected(p) || s.isAdmittedRouter(p)
+}
+
+func (s *Server) isAdmitted(p peer.ID) bool {
+ return admissionHolds(&s.authPeers, p)
+}
+
+func (s *Server) isAdmittedRouter(p peer.ID) bool {
+ return admissionHolds(&s.authRouters, p)
+}
+
+func (s *Server) admitPeer(p peer.ID, expiry time.Time, router bool) {
+ s.authPeers.Store(p, expiry)
+ if router {
+ s.authRouters.Store(p, expiry)
+ } else {
+ s.authRouters.Delete(p)
+ }
+}
+
+func (s *Server) forgetAdmission(p peer.ID) {
+ s.authPeers.Delete(p)
+ s.authRouters.Delete(p)
+}
+
+func admissionHolds(m interface {
+ Load(any) (any, bool)
+ Delete(any)
+}, p peer.ID) bool {
+ v, ok := m.Load(p)
+ if !ok {
+ return false
+ }
+ expiry, ok := v.(time.Time)
+ if !ok || !time.Now().Before(expiry) {
+ m.Delete(p)
+ return false
+ }
+ return true
+}
+
+func (s *Server) ensurePeerAuthenticated(ctx context.Context, p peer.ID) error {
+ if s.isPeerAuthenticated(p) {
+ return nil
+ }
+ if !s.isCatalogRouter(p) || s.isAttached(p) {
+ return fmt.Errorf("%s: %w", p, errNotAuthenticated)
+ }
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return errors.New("missing member credential")
+ }
+ return s.authRouter(ctx, peer.AddrInfo{ID: p}, biscuitBytes)
+}
+
+func (s *Server) requireAuthenticated(next network.StreamHandler) network.StreamHandler {
+ return func(st network.Stream) {
+ p := st.Conn().RemotePeer()
+ if err := s.awaitPeerAuthenticated(context.Background(), p); err != nil {
+ s.incRefusedStream(streamScopeUnauthenticated, st.Protocol())
+ s.log().Debug("refusing unauthenticated stream", "protocol", string(st.Protocol()), "peer_id", p.String(), "error", err)
+ _ = st.Reset()
+ return
+ }
+ next(st)
+ }
+}
+
+func (s *Server) requireRouter(next network.StreamHandler) network.StreamHandler {
+ return s.requireAuthenticated(func(st network.Stream) {
+ p := st.Conn().RemotePeer()
+ if !s.isAuthenticatedRouter(p) {
+ s.incRefusedStream(streamScopeNotRouter, st.Protocol())
+ s.log().Warn("refusing router-only stream from non-router peer", "protocol", string(st.Protocol()), "peer_id", p.String())
+ _ = st.Reset()
+ return
+ }
+ next(st)
+ })
+}
+
+func (s *Server) awaitPeerAuthenticated(ctx context.Context, p peer.ID) error {
+ if s.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 s.isPeerAuthenticated(p) {
+ return nil
+ }
+ if s.host.Network().Connectedness(p) != network.Connected {
+ return errNotAuthenticated
+ }
+ }
+}
+
+func (s *Server) incRefusedStream(scope string, protoID protocol.ID) {
+ key := scope + "|" + string(protoID)
+ s.refusedMu.Lock()
+ s.refusedStreams[key]++
+ s.refusedMu.Unlock()
+}
+
+func (s *Server) refusedStreamCount(scope string, protoID protocol.ID) uint64 {
+ key := scope + "|" + string(protoID)
+ s.refusedMu.Lock()
+ defer s.refusedMu.Unlock()
+ return s.refusedStreams[key]
+}
+
+func (s *Server) recoverStream(name string, next network.StreamHandler) network.StreamHandler {
+ return func(st network.Stream) {
+ defer func() {
+ if r := recover(); r != nil {
+ s.log().Error("recovered panic in stream handler",
+ "handler", name,
+ "peer_id", st.Conn().RemotePeer().String(),
+ "panic", fmt.Sprint(r),
+ "stack", string(debug.Stack()),
+ )
+ _ = st.Reset()
+ }
+ }()
+ next(st)
+ }
+}
+
+func (s *Server) handleAuthHandshake(st network.Stream) {
+ defer func() { _ = st.Close() }()
+ remotePeer := st.Conn().RemotePeer()
+
+ if s.isPeerBanned(remotePeer) {
+ s.log().Warn("refusing auth handshake from banned peer", "peer_id", remotePeer.String())
+ _ = st.Reset()
+ return
+ }
+ if s.handshakeLimiter != nil && !s.handshakeLimiter.Allow(remotePeer.String()) {
+ s.log().Warn("handshake rate limit exceeded", "peer_id", remotePeer.String())
+ _ = st.Reset()
+ return
+ }
+ _ = st.SetDeadline(time.Now().Add(authHandshakeTimeout))
+
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ s.log().Debug("failed reading auth frame", "peer_id", remotePeer.String(), "error", err)
+ return
+ }
+ defer reader.ReleaseMsg(msg)
+
+ var exchange api.AuthFrame
+ if err := proto.Unmarshal(msg, &exchange); err != nil {
+ s.log().Warn("invalid protobuf in auth handshake", "peer_id", remotePeer.String())
+ return
+ }
+
+ b, verifyingKey, expiry, err := identity.VerifyBiscuitAdmission(exchange.GetBiscuit(), remotePeer, s.trustedPublicKeys(), s.biscuitTimeout())
+ if err != nil {
+ s.log().Warn("auth handshake rejected", "peer_id", remotePeer.String(), "error", err)
+ return
+ }
+ if s.isBiscuitRevoked(b) {
+ s.log().Warn("auth handshake rejected: biscuit is revoked", "peer_id", remotePeer.String())
+ return
+ }
+
+ isRouter := identity.RequireRole(b, verifyingKey, api.RoleRouter, s.biscuitTimeout()) == nil
+ s.admitPeer(remotePeer, expiry, isRouter)
+ s.log().Info("admitted mesh peer", "peer_id", remotePeer.String(), "is_router", isRouter)
+
+ respBytes, err := proto.Marshal(&api.AuthResponse{Success: true, Biscuit: s.currentBiscuit()})
+ if err != nil {
+ return
+ }
+ if err := msgio.NewVarintWriter(st).WriteMsg(respBytes); err != nil {
+ s.log().Debug("failed writing auth handshake ACK", "peer_id", remotePeer.String(), "error", err)
+ }
+}
+
+func (s *Server) handleGoAway(ctx context.Context, st network.Stream) {
+ defer func() { _ = st.Close() }()
+ router := st.Conn().RemotePeer()
+ if !s.isAttached(router) {
+ _ = st.Reset()
+ return
+ }
+ _ = st.SetReadDeadline(time.Now().Add(5 * time.Second))
+ msg, err := msgio.NewVarintReaderSize(st, 1024).ReadMsg()
+ if err != nil {
+ _ = st.Reset()
+ return
+ }
+ var goAway api.RouterGoAway
+ if err := proto.Unmarshal(msg, &goAway); err != nil {
+ _ = st.Reset()
+ return
+ }
+ retryAfter := goAway.GetRetryAfter().AsDuration()
+ if retryAfter <= 0 {
+ retryAfter = defaultShunDuration
+ }
+ retryAfter = min(retryAfter, goAwayMaxRetryAfter)
+ s.log().Info("router sent go-away; failing over",
+ "router_peer_id", router.String(),
+ "reason", goAway.GetReason().String(),
+ "retry_after", retryAfter,
+ )
+ s.shun(router, retryAfter)
+ s.detach(router)
+ s.mu.Lock()
+ delete(s.authenticatedRouters, router)
+ s.mu.Unlock()
+ go s.topUpRouters(ctx)
+}
+
+func (s *Server) newResourceManager() (network.ResourceManager, error) {
+ total := connHighWaterMark * peerStreamCap
+ cfg := rcmgr.PartialLimitConfig{
+ System: rcmgr.ResourceLimits{
+ Streams: rcmgr.LimitVal(2 * total),
+ StreamsInbound: rcmgr.LimitVal(total),
+ StreamsOutbound: rcmgr.LimitVal(total),
+ Conns: rcmgr.LimitVal(2 * connHighWaterMark),
+ ConnsInbound: rcmgr.LimitVal(connHighWaterMark),
+ ConnsOutbound: rcmgr.LimitVal(2 * connHighWaterMark),
+ FD: rcmgr.LimitVal(2 * connHighWaterMark),
+ Memory: rcmgr.LimitVal64(int64(2*total) * p2plimits.StreamWindow),
+ },
+ PeerDefault: p2plimits.Streams(peerStreamCap),
+ }.Build(rcmgr.DefaultLimits.AutoScale())
+
+ // Unregistered per-Server counter so multiple embedded meshnet.Server
+ // instances never collide on prometheus.DefaultRegisterer.
+ refusedCounter := prometheus.NewCounterVec(prometheus.CounterOpts{
+ Name: "agentmesh_meshnet_connections_refused_total",
+ Help: "Inbound libp2p connections refused by the resource manager.",
+ }, []string{"reason"})
+
+ perIP := p2plimits.DefaultConnsPerSourceIP(connHighWaterMark)
+ return p2plimits.New(cfg, perIP, refusedCounter, func(format string, args ...any) {
+ s.log().Warn(fmt.Sprintf(format, args...))
+ })
+}
diff --git a/sdk/meshnet/authorizer.go b/sdk/meshnet/authorizer.go
new file mode 100644
index 00000000..92609ab5
--- /dev/null
+++ b/sdk/meshnet/authorizer.go
@@ -0,0 +1,513 @@
+// 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 meshnet
+
+import (
+ "context"
+ "crypto/ed25519"
+ "encoding/base64"
+ "errors"
+ "fmt"
+ "net/http"
+ "sort"
+ "strings"
+ "time"
+
+ "github.com/eclipse-biscuit/biscuit-go/v2"
+ "github.com/google/agentmesh/api"
+ "github.com/google/agentmesh/internal/identity"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/libp2p/go-msgio"
+ "google.golang.org/protobuf/proto"
+ "google.golang.org/protobuf/types/known/timestamppb"
+)
+
+const (
+ labelGateCacheSize = 1024
+ labelGateTTL = 5 * time.Minute
+ labelGateDialTimeout = 10 * time.Second
+)
+
+var (
+ errProviderUnreachable = errors.New("provider unreachable")
+ errProviderNotGranted = errors.New("provider not granted the service")
+)
+
+type httpRequestFacts struct {
+ method string
+ path string
+}
+
+func (s *Server) policyRules() []biscuit.Rule {
+ s.policyMu.RLock()
+ defer s.policyMu.RUnlock()
+ return s.meshPolicyRules
+}
+
+// meshPolicy builds the shared identity.MeshPolicy used by both in-mesh stream
+// authorization and external router HTTP ingress, keeping every PEP on the
+// single identity.AuthorizeMeshRequest assembly.
+func (s *Server) meshPolicy() (identity.MeshPolicy, error) {
+ var targetFacts []biscuit.Fact
+ if ourIdentity := s.currentBiscuit(); len(ourIdentity) > 0 {
+ ourB, err := biscuit.Unmarshal(ourIdentity)
+ if err != nil {
+ return identity.MeshPolicy{}, fmt.Errorf("unmarshal local identity: %w", err)
+ }
+ tf, err := identity.TargetFactsFromBiscuit(ourB, s.trustedPublicKeys(), s.biscuitTimeout())
+ if err != nil {
+ return identity.MeshPolicy{}, fmt.Errorf("extract local target facts: %w", err)
+ }
+ targetFacts = tf
+ }
+ return identity.MeshPolicy{
+ TargetFacts: targetFacts,
+ MeshRules: s.policyRules(),
+ }, nil
+}
+
+func (s *Server) authorizeInbound(rawToken []byte, remotePeer peer.ID, target, protocol string, httpFacts *httpRequestFacts) (*CallerInfo, error) {
+ if s.isPeerBanned(remotePeer) {
+ s.log().Warn("refusing inbound request from banned peer", "peer_id", remotePeer.String(), "target", target)
+ return nil, errors.New("peer is banned")
+ }
+ keys := s.trustedPublicKeys()
+ if len(keys) == 0 {
+ return nil, errors.New("no trusted control plane keys loaded")
+ }
+
+ var lastErr error
+ for _, pubKey := range keys {
+ info, err := s.authorizeInboundWithKey(rawToken, remotePeer, target, protocol, httpFacts, pubKey)
+ if err == nil {
+ return info, nil
+ }
+ lastErr = err
+ if !errors.Is(err, biscuit.ErrInvalidSignature) {
+ break
+ }
+ }
+ return nil, lastErr
+}
+
+func (s *Server) authorizeInboundWithKey(rawToken []byte, remotePeer peer.ID, target, protocol string, httpFacts *httpRequestFacts, pubKey ed25519.PublicKey) (*CallerInfo, error) {
+ b, taskRules, err := identity.UnmarshalInbound(rawToken)
+ if err != nil {
+ return nil, fmt.Errorf("invalid biscuit: %w", err)
+ }
+ if s.isBiscuitRevoked(b) {
+ s.log().Info("inbound authorization denied", "peer_id", remotePeer.String(), "target", target, "reason", "biscuit is revoked")
+ return nil, errors.New("biscuit is revoked")
+ }
+ if err := identity.RequireAuthorityRequestBinding(b, remotePeer); err != nil {
+ return nil, err
+ }
+
+ authorizer, err := b.Authorizer(pubKey, identity.AuthorizerOptions(s.biscuitTimeout())...)
+ if err != nil {
+ return nil, err
+ }
+
+ var opType, opName string
+ if target == "" {
+ opType = api.SystemNamespace
+ opName = protocol
+ } else {
+ opType, opName = api.ParseServiceTarget(target)
+ }
+ meshReq := identity.MeshRequest{
+ ServiceType: opType,
+ ServiceName: opName,
+ ConnectionPeer: remotePeer,
+ AllowMCPStreamInit: httpFacts == nil && protocol == string(api.MCPProtocolID),
+ }
+ if httpFacts != nil {
+ meshReq.HasHTTP = true
+ meshReq.Method = httpFacts.method
+ meshReq.Path = httpFacts.path
+ }
+
+ pol, err := s.meshPolicy()
+ if err != nil {
+ return nil, err
+ }
+ if err := identity.AuthorizeMeshRequest(authorizer, meshReq, pol); err != nil {
+ s.log().Info("inbound authorization denied", "peer_id", remotePeer.String(), "target", target, "protocol", protocol, "reason", err.Error())
+ return nil, err
+ }
+
+ if len(taskRules) > 0 {
+ if err := api.EvaluateTaskRules(taskRules, meshReq.TaskRequest(), time.Now()); err != nil {
+ s.log().Info("inbound task rule denied", "peer_id", remotePeer.String(), "target", target, "reason", err.Error())
+ return nil, err
+ }
+ }
+
+ actorNode := queryFirstString(authorizer, api.FactActorNode)
+ if actorNode != "" {
+ if actorPID, pErr := peer.Decode(actorNode); pErr == nil && s.isPeerBanned(actorPID) {
+ s.log().Info("inbound authorization denied", "peer_id", remotePeer.String(), "target", target, "reason", "actor_node is banned")
+ return nil, fmt.Errorf("actor_node %s is banned", actorPID.String())
+ }
+ }
+
+ email := queryFirstString(authorizer, api.FactEmail)
+ user := queryFirstString(authorizer, api.FactUser)
+ nodeFact := queryFirstString(authorizer, api.FactNode)
+ clientPeer := queryFirstString(authorizer, api.FactClientPeerID)
+ roles := queryAllStrings(authorizer, api.FactRole)
+ labels := queryLabels(authorizer)
+
+ principal := email
+ switch {
+ case principal != "":
+ case user != "":
+ principal = user
+ case nodeFact != "":
+ principal = "node:" + nodeFact
+ case clientPeer != "":
+ principal = "peer:" + clientPeer
+ default:
+ principal = "node:" + remotePeer.String()
+ }
+
+ var taskName string
+ if len(taskRules) > 0 {
+ taskName = taskRules[len(taskRules)-1].GetName()
+ }
+
+ s.log().Info("inbound authorization allowed",
+ "peer_id", remotePeer.String(),
+ "principal", principal,
+ "roles", roles,
+ "task", taskName,
+ "target", target,
+ "protocol", protocol,
+ )
+
+ return &CallerInfo{
+ PeerID: remotePeer.String(),
+ Principal: principal,
+ Roles: roles,
+ Labels: labels,
+ Task: taskName,
+ }, nil
+}
+
+func queryAllStrings(authorizer biscuit.Authorizer, factName string) []string {
+ facts, err := authorizer.Query(biscuit.Rule{
+ Head: biscuit.Predicate{Name: "q", IDs: []biscuit.Term{biscuit.Variable("v")}},
+ Body: []biscuit.Predicate{{Name: factName, IDs: []biscuit.Term{biscuit.Variable("v")}}},
+ })
+ if err != nil {
+ return nil
+ }
+ var out []string
+ for _, f := range facts {
+ if len(f.IDs) == 1 {
+ if str, ok := f.IDs[0].(biscuit.String); ok {
+ out = append(out, string(str))
+ }
+ }
+ }
+ sort.Strings(out)
+ return out
+}
+
+func queryFirstString(authorizer biscuit.Authorizer, factName string) string {
+ vals := queryAllStrings(authorizer, factName)
+ if len(vals) == 0 {
+ return ""
+ }
+ return vals[0]
+}
+
+func queryLabels(authorizer biscuit.Authorizer) map[string]string {
+ facts, err := authorizer.Query(biscuit.Rule{
+ Head: biscuit.Predicate{Name: "q_lbl", IDs: []biscuit.Term{biscuit.Variable("k"), biscuit.Variable("v")}},
+ Body: []biscuit.Predicate{{Name: api.FactLabel, IDs: []biscuit.Term{biscuit.Variable("k"), biscuit.Variable("v")}}},
+ })
+ if err != nil || len(facts) == 0 {
+ return nil
+ }
+ out := make(map[string]string, len(facts))
+ for _, f := range facts {
+ if len(f.IDs) == 2 {
+ k, okK := f.IDs[0].(biscuit.String)
+ v, okV := f.IDs[1].(biscuit.String)
+ if okK && okV {
+ out[string(k)] = string(v)
+ }
+ }
+ }
+ if len(out) == 0 {
+ return nil
+ }
+ return out
+}
+
+func (s *Server) verifyLocalBiscuit(rawToken []byte) (*identity.VerifiedBiscuitClaims, error) {
+ claims, err := identity.InspectVerifiedBiscuit(rawToken, s.trustedPublicKeys(), s.biscuitTimeout())
+ if err != nil {
+ return nil, err
+ }
+ if s.isBiscuitRevoked(claims.Biscuit) {
+ return nil, errors.New("biscuit is revoked")
+ }
+ if claims.NodePeerID != "" {
+ if pid, pErr := peer.Decode(claims.NodePeerID); pErr == nil && s.isPeerBanned(pid) {
+ return nil, fmt.Errorf("peer %s is banned", pid)
+ }
+ }
+ if claims.ActorNodePeerID != "" {
+ if pid, pErr := peer.Decode(claims.ActorNodePeerID); pErr == nil && s.isPeerBanned(pid) {
+ return nil, fmt.Errorf("actor_node %s is banned", pid)
+ }
+ }
+ return claims, nil
+}
+
+// parseRequiredLabels splits X-Mesh-Required-Labels ("k1=v1,k2=v2") into a
+// validated map, rejecting malformed entries fail-closed.
+func parseRequiredLabels(h string) (map[string]string, error) {
+ if strings.TrimSpace(h) == "" {
+ return nil, nil
+ }
+ var out map[string]string
+ for _, part := range strings.Split(h, ",") {
+ part = strings.TrimSpace(part)
+ if part == "" {
+ continue
+ }
+ k, v, ok := strings.Cut(part, "=")
+ if !ok {
+ return nil, fmt.Errorf("invalid label %q: expected key=value", part)
+ }
+ k, v = strings.TrimSpace(k), strings.TrimSpace(v)
+ if err := api.ValidateLabelKey(k); err != nil {
+ return nil, err
+ }
+ if err := api.ValidateLabelValue(v); err != nil {
+ return nil, err
+ }
+ if out == nil {
+ out = make(map[string]string)
+ }
+ if _, exists := out[k]; exists {
+ return nil, fmt.Errorf("duplicate label key %q", k)
+ }
+ out[k] = v
+ }
+ if len(out) == 0 {
+ return nil, fmt.Errorf("invalid required labels %q: expected at least one key=value pair", h)
+ }
+ return out, nil
+}
+
+func labelGateStatus(err error, denied string) (string, int) {
+ if errors.Is(err, errProviderUnreachable) {
+ return "Bad Gateway: destination did not answer", http.StatusBadGateway
+ }
+ return denied, http.StatusForbidden
+}
+
+func labelGateKey(peerID peer.ID, required, floor map[string]string, service string) string {
+ render := func(sb *strings.Builder, m map[string]string) {
+ keys := make([]string, 0, len(m))
+ for k := range m {
+ keys = append(keys, k)
+ }
+ sort.Strings(keys)
+ for _, k := range keys {
+ sb.WriteByte('|')
+ sb.WriteString(k)
+ sb.WriteByte('=')
+ sb.WriteString(m[k])
+ }
+ }
+ var sb strings.Builder
+ sb.WriteString(peerID.String())
+ render(&sb, required)
+ sb.WriteString("#floor")
+ render(&sb, floor)
+ sb.WriteString("=svc=")
+ sb.WriteString(service)
+ return sb.String()
+}
+
+func (s *Server) verifyProvider(ctx context.Context, peerID peer.ID, required map[string]string, service string) error {
+ key := labelGateKey(peerID, required, s.EgressRequireLabels, service)
+ if s.peerLabelGate != nil {
+ if until, ok := s.peerLabelGate.Get(key); ok && time.Now().Before(until) {
+ return nil
+ }
+ }
+
+ providerBiscuit, err := s.fetchPeerBiscuit(ctx, peerID)
+ if err != nil {
+ return fmt.Errorf("provider %s unreachable: %w: %w", peerID, errProviderUnreachable, err)
+ }
+ if err := s.checkProvider(providerBiscuit, peerID, required, service); err != nil {
+ return err
+ }
+ if s.peerLabelGate != nil {
+ s.peerLabelGate.Add(key, time.Now().Add(labelGateTTL))
+ }
+ return nil
+}
+
+func (s *Server) checkProvider(providerBiscuit []byte, peerID peer.ID, required map[string]string, service string) error {
+ if len(providerBiscuit) == 0 {
+ return fmt.Errorf("provider %s returned no identity biscuit", peerID)
+ }
+ trusted := s.trustedPublicKeys()
+ if len(trusted) == 0 {
+ return errors.New("no trusted control plane keys loaded")
+ }
+ b, key, err := identity.VerifyBiscuitAndGetKey(providerBiscuit, peerID, trusted, s.biscuitTimeout())
+ if err != nil {
+ return fmt.Errorf("provider %s biscuit verification failed: %w", peerID, err)
+ }
+ if err := identity.RequireRole(b, key, api.RoleNode, s.biscuitTimeout()); err != nil {
+ return fmt.Errorf("provider %s is not enrolled as a node: %w", peerID, err)
+ }
+
+ authorizer, err := b.Authorizer(key, identity.AuthorizerOptions(s.biscuitTimeout())...)
+ if err != nil {
+ return fmt.Errorf("provider %s authorizer failed: %w", peerID, err)
+ }
+ if len(required) > 0 {
+ check, err := api.LabelCheck(required)
+ if err != nil {
+ return err
+ }
+ authorizer.AddCheck(check)
+ }
+ if len(s.EgressRequireLabels) > 0 {
+ check, err := api.LabelCheck(s.EgressRequireLabels)
+ if err != nil {
+ return err
+ }
+ authorizer.AddCheck(check)
+ }
+ authorizer.AddPolicy(api.AllowIfTruePolicy)
+ if err := authorizer.Authorize(); err != nil {
+ return fmt.Errorf("provider %s does not attest required labels: %w", peerID, err)
+ }
+
+ if service != "" && service != "system://"+api.CatalogTarget {
+ svcType, svcName := api.ParseServiceTarget(service)
+ if svcType == "" || svcName == "" {
+ return fmt.Errorf("service %q must be <type>://<name>", service)
+ }
+ if err := identity.RequirePublish(b, key, svcType, svcName, s.policyRules(), s.biscuitTimeout()); err != nil {
+ return fmt.Errorf("%w: %w", errProviderNotGranted, err)
+ }
+ }
+ return nil
+}
+
+func (s *Server) fetchPeerBiscuit(ctx context.Context, peerID peer.ID) ([]byte, error) {
+ ourBiscuit := s.currentBiscuit()
+ if len(ourBiscuit) == 0 {
+ return nil, errors.New("missing local member biscuit")
+ }
+ s.preparePeerAddrs(ctx, peerID)
+ dialCtx, cancel := context.WithTimeout(network.WithAllowLimitedConn(ctx, "label-gate"), labelGateDialTimeout)
+ defer cancel()
+
+ st, err := s.host.NewStream(dialCtx, peerID, api.AuthProtocolID)
+ if err != nil {
+ return nil, fmt.Errorf("open auth stream: %w", err)
+ }
+ defer func() { _ = st.Close() }()
+ _ = st.SetDeadline(time.Now().Add(labelGateDialTimeout))
+
+ if st.Conn().RemotePeer() != peerID {
+ return nil, fmt.Errorf("authenticated connection peer %s does not match requested peer %s", st.Conn().RemotePeer(), peerID)
+ }
+ authBytes, err := proto.Marshal(&api.AuthFrame{Biscuit: ourBiscuit})
+ if err != nil {
+ return nil, err
+ }
+ if err := msgio.NewVarintWriter(st).WriteMsg(authBytes); err != nil {
+ return nil, fmt.Errorf("write auth frame: %w", err)
+ }
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ return nil, fmt.Errorf("read auth response: %w", err)
+ }
+ defer reader.ReleaseMsg(msg)
+
+ var resp api.AuthResponse
+ if err := proto.Unmarshal(msg, &resp); err != nil {
+ return nil, fmt.Errorf("invalid auth response: %w", err)
+ }
+ if !resp.GetSuccess() {
+ return nil, fmt.Errorf("auth rejected: %s", resp.GetError())
+ }
+ return resp.GetBiscuit(), nil
+}
+
+// AttenuateToken appends a validated TaskAuthorizationRule (`tar_block` fact,
+// 0 rules, 0 checks) to the member's current Biscuit in memory without a
+// control-plane round trip, optionally sealing it so downstream holders cannot
+// append further blocks. Use it to delegate a task-scoped credential to a
+// sub-agent or an external worker without its own mesh identity; callers
+// already running a Server call peers directly through Server.HTTPClient().
+func (s *Server) AttenuateToken(rule *api.TaskAuthorizationRule, ttl time.Duration, seal bool) (string, time.Time, error) {
+ if rule == nil {
+ return "", time.Time{}, errors.New("meshnet: TaskAuthorizationRule is required")
+ }
+ raw := s.currentBiscuit()
+ if len(raw) == 0 {
+ return "", time.Time{}, errors.New("meshnet: no member credential loaded (call Up first)")
+ }
+
+ cloned := proto.Clone(rule).(*api.TaskAuthorizationRule)
+ now := time.Now()
+ exp := s.credentialExpireTime()
+ if exp.IsZero() {
+ exp = now.Add(api.BiscuitTokenTTL)
+ }
+ if ttl > 0 {
+ if candidate := now.Add(ttl); candidate.Before(exp) {
+ exp = candidate
+ }
+ }
+ if cloned.GetExpireTime() != nil {
+ if ruleExp := cloned.GetExpireTime().AsTime(); ruleExp.Before(exp) {
+ exp = ruleExp
+ }
+ }
+ if !now.Before(exp) {
+ return "", time.Time{}, errors.New("meshnet: attenuated token expiration is in the past")
+ }
+ cloned.ExpireTime = timestamppb.New(exp)
+
+ out, err := identity.AttenuateBiscuit(raw, cloned)
+ if err != nil {
+ return "", time.Time{}, err
+ }
+ if seal {
+ out, err = identity.SealBiscuit(out)
+ if err != nil {
+ return "", time.Time{}, err
+ }
+ }
+ return base64.RawURLEncoding.EncodeToString(out), exp, nil
+}
diff --git a/sdk/meshnet/directory.go b/sdk/meshnet/directory.go
new file mode 100644
index 00000000..f4a3590d
--- /dev/null
+++ b/sdk/meshnet/directory.go
@@ -0,0 +1,657 @@
+// 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 meshnet
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "log/slog"
+ "math/rand/v2"
+ "slices"
+ "sort"
+ "sync"
+ "time"
+
+ "github.com/google/agentmesh/api"
+ "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/peerstore"
+ "github.com/libp2p/go-libp2p/core/routing"
+ "github.com/libp2p/go-libp2p/p2p/net/swarm"
+ "github.com/libp2p/go-msgio"
+ "github.com/multiformats/go-multiaddr"
+ "google.golang.org/protobuf/proto"
+)
+
+const (
+ directoryRequestTimeout = 10 * time.Second
+ directoryMaxMessage = 64 * 1024
+ directoryDefaultLimit = 20
+ dhtLookupTimeout = 5 * time.Second
+ discoveryFanoutTimeout = 30 * time.Second
+ discoveryConcurrency = 10
+ peerstoreKeyPrivateIPFailed = "mesh_private_ip_failed"
+ transitCatalogRefreshInterval = 10 * time.Second
+)
+
+var errNoDirectoryRouter = errors.New("meshnet: no attached router available for directory request")
+
+type routerDirectory struct {
+ host host.Host
+ routers func() []peer.ID
+ addrs func() []multiaddr.Multiaddr
+ log func() *slog.Logger
+}
+
+func (d *routerDirectory) provide(ctx context.Context, key []byte, service string) error {
+ return d.provideWithIngress(ctx, key, service, nil)
+}
+
+func (d *routerDirectory) provideWithIngress(ctx context.Context, key []byte, service string, ingress *api.ServiceIngress) error {
+ addrs := d.addrs()
+ if len(addrs) > api.DirectoryMaxAddrs {
+ addrs = addrs[:api.DirectoryMaxAddrs]
+ }
+ rec := &api.DirectoryProvide{
+ Key: key,
+ Service: service,
+ Addrs: make([]string, 0, len(addrs)),
+ Ingress: ingress,
+ }
+ for _, a := range addrs {
+ rec.Addrs = append(rec.Addrs, a.String())
+ }
+ _, err := d.request(ctx, "provide", &api.DirectoryRequest{
+ Request: &api.DirectoryRequest_Provide{Provide: rec},
+ })
+ return err
+}
+
+func (d *routerDirectory) withdraw(ctx context.Context, key []byte) error {
+ _, err := d.request(ctx, "withdraw", &api.DirectoryRequest{
+ Request: &api.DirectoryRequest_Withdraw{Withdraw: &api.DirectoryWithdraw{Key: key}},
+ })
+ return err
+}
+
+func (d *routerDirectory) findProviders(ctx context.Context, key []byte, limit int) ([]peer.AddrInfo, error) {
+ if limit <= 0 {
+ limit = directoryDefaultLimit
+ }
+ resp, err := d.request(ctx, "find_providers", &api.DirectoryRequest{
+ Request: &api.DirectoryRequest_FindProviders{
+ FindProviders: &api.DirectoryFindProviders{Key: key, Limit: uint32(limit)},
+ },
+ })
+ if err != nil {
+ return nil, err
+ }
+ out := make([]peer.AddrInfo, 0, len(resp.GetProviders()))
+ for _, rec := range resp.GetProviders() {
+ info, err := addrInfoOf(rec)
+ if err != nil {
+ d.log().Warn("skipping malformed provider record from router", "error", err)
+ continue
+ }
+ out = append(out, info)
+ }
+ return out, nil
+}
+
+func (d *routerDirectory) findPeer(ctx context.Context, p peer.ID) (peer.AddrInfo, error) {
+ resp, err := d.request(ctx, "find_peer", &api.DirectoryRequest{
+ Request: &api.DirectoryRequest_FindPeer{
+ FindPeer: &api.DirectoryFindPeer{PeerId: p.String()},
+ },
+ })
+ if err != nil {
+ return peer.AddrInfo{}, err
+ }
+ if resp.GetPeer() == nil {
+ return peer.AddrInfo{ID: p}, routing.ErrNotFound
+ }
+ info, err := addrInfoOf(resp.GetPeer())
+ if err != nil {
+ return peer.AddrInfo{ID: p}, err
+ }
+ if info.ID != p {
+ return peer.AddrInfo{ID: p}, fmt.Errorf("router answered for %s instead of %s", info.ID, p)
+ }
+ return info, nil
+}
+
+func (d *routerDirectory) request(ctx context.Context, op string, req *api.DirectoryRequest) (*api.DirectoryResponse, error) {
+ data, err := proto.Marshal(req)
+ if err != nil {
+ return nil, err
+ }
+ routers := d.routers()
+ if len(routers) == 0 {
+ return nil, errNoDirectoryRouter
+ }
+ lookup := op == "find_providers" || op == "find_peer"
+ var lastErr error
+ var empty *api.DirectoryResponse
+ for _, router := range routers {
+ resp, err := d.ask(ctx, router, data)
+ if err == nil {
+ if lookup && len(resp.GetProviders()) == 0 && resp.GetPeer() == nil {
+ empty = resp
+ continue
+ }
+ return resp, nil
+ }
+ lastErr = err
+ d.log().Warn("directory request through router failed", "op", op, "router_peer_id", router.String(), "error", err)
+ if ctx.Err() != nil {
+ break
+ }
+ }
+ if empty != nil {
+ return empty, nil
+ }
+ return nil, fmt.Errorf("%s: no attached router answered: %w", op, lastErr)
+}
+
+func (d *routerDirectory) ask(ctx context.Context, router peer.ID, data []byte) (*api.DirectoryResponse, error) {
+ ctx, cancel := context.WithTimeout(ctx, directoryRequestTimeout)
+ defer cancel()
+ st, err := d.host.NewStream(ctx, router, api.DirectoryProtocolID)
+ if err != nil {
+ return nil, err
+ }
+ defer func() { _ = st.Close() }()
+ if deadline, ok := ctx.Deadline(); ok {
+ _ = st.SetDeadline(deadline)
+ }
+ if err := msgio.NewVarintWriter(st).WriteMsg(data); err != nil {
+ _ = st.Reset()
+ return nil, err
+ }
+ reader := msgio.NewVarintReaderSize(st, directoryMaxMessage)
+ frame, err := reader.ReadMsg()
+ if err != nil {
+ _ = st.Reset()
+ return nil, err
+ }
+ defer reader.ReleaseMsg(frame)
+ var resp api.DirectoryResponse
+ if err := proto.Unmarshal(frame, &resp); err != nil {
+ return nil, err
+ }
+ if resp.GetError() != "" {
+ return nil, errors.New(resp.GetError())
+ }
+ return &resp, nil
+}
+
+func addrInfoOf(rec *api.PeerRecord) (peer.AddrInfo, error) {
+ p, err := peer.Decode(rec.GetPeerId())
+ if err != nil {
+ return peer.AddrInfo{}, fmt.Errorf("peer %q: %w", rec.GetPeerId(), err)
+ }
+ info := peer.AddrInfo{ID: p}
+ for _, a := range rec.GetAddrs() {
+ ma, err := multiaddr.NewMultiaddr(a)
+ if err != nil {
+ return peer.AddrInfo{}, fmt.Errorf("address %q of %s: %w", a, p, err)
+ }
+ transport, named := peer.SplitAddr(ma)
+ if named != "" && named != p {
+ continue
+ }
+ if transport != nil {
+ info.Addrs = append(info.Addrs, transport)
+ }
+ }
+ return info, nil
+}
+
+func rememberAddrs(ps peerstore.Peerstore, infos ...peer.AddrInfo) {
+ for _, info := range infos {
+ if len(info.Addrs) > 0 {
+ ps.AddAddrs(info.ID, info.Addrs, peerstore.TempAddrTTL)
+ }
+ }
+}
+
+// Discover looks up mesh providers for svcType. Pass an empty name to browse
+// all reachable services of that type (fanning out over system://mesh.catalog),
+// or pass a specific service name for a targeted directory lookup.
+//
+// Each returned DiscoveredProvider has LocalProxyUrl populated with a synthetic
+// mesh URL ("http://agentmesh.local/mesh/<peer_id>/<type>/<name>") directly
+// usable with s.HTTPClient() and stock A2A/OpenAI clients.
+func (s *Server) Discover(ctx context.Context, svcType api.ServiceType, name string) ([]*api.DiscoveredProvider, error) {
+ if s.host == nil || s.dir == nil {
+ return nil, errors.New("meshnet: Server is not running (call Up first)")
+ }
+ typeStr, err := api.ServiceTypeToString(svcType)
+ if err != nil || svcType == api.ServiceType_SERVICE_TYPE_UNSPECIFIED {
+ return nil, fmt.Errorf("meshnet: invalid service type %v", svcType)
+ }
+ if name != "" {
+ return s.discoverByName(ctx, svcType, typeStr, name)
+ }
+ return s.discoverByType(ctx, svcType, typeStr)
+}
+
+func (s *Server) localMeshURL(peerID peer.ID, typeStr, svcName string) string {
+ return fmt.Sprintf("http://agentmesh.local/mesh/%s/%s/%s", peerID.String(), typeStr, svcName)
+}
+
+func (s *Server) findProviders(ctx context.Context, key []byte) ([]peer.AddrInfo, error) {
+ if s.dir == nil {
+ return nil, errors.New("meshnet: directory is not initialized")
+ }
+ lookupCtx, cancel := context.WithTimeout(ctx, dhtLookupTimeout)
+ defer cancel()
+ found, err := s.dir.findProviders(lookupCtx, key, directoryDefaultLimit)
+ if errors.Is(err, errNoDirectoryRouter) {
+ return nil, nil
+ }
+ if err != nil {
+ return nil, err
+ }
+ providers := make([]peer.AddrInfo, 0, len(found))
+ for _, p := range found {
+ if s.isPeerBanned(p.ID) {
+ continue
+ }
+ rememberAddrs(s.host.Peerstore(), p)
+ providers = append(providers, p)
+ }
+ return providers, nil
+}
+
+func (s *Server) discoverByName(ctx context.Context, svcType api.ServiceType, typeStr, name string) ([]*api.DiscoveredProvider, error) {
+ key, err := api.ServiceKey(svcType, name)
+ if err != nil {
+ return nil, err
+ }
+ peers, err := s.findProviders(ctx, key)
+ if err != nil {
+ return nil, err
+ }
+ out := make([]*api.DiscoveredProvider, 0, len(peers))
+ for _, p := range peers {
+ if p.ID == s.peerID {
+ continue
+ }
+ out = append(out, &api.DiscoveredProvider{
+ PeerId: p.ID.String(),
+ LocalProxyUrl: s.localMeshURL(p.ID, typeStr, name),
+ SrvName: name,
+ })
+ }
+ return out, nil
+}
+
+func (s *Server) discoverByType(ctx context.Context, svcType api.ServiceType, typeStr string) ([]*api.DiscoveredProvider, error) {
+ key, err := api.ServiceKey(svcType, "")
+ if err != nil {
+ return nil, err
+ }
+ peers, err := s.findProviders(ctx, key)
+ if err != nil {
+ return nil, err
+ }
+
+ fanoutCtx, cancel := context.WithTimeout(ctx, discoveryFanoutTimeout)
+ defer cancel()
+
+ type peerCatalog struct {
+ peerID peer.ID
+ services []*api.ServiceInfo
+ }
+ results := make(chan peerCatalog, len(peers))
+ sem := make(chan struct{}, discoveryConcurrency)
+ var wg sync.WaitGroup
+ for _, p := range peers {
+ if p.ID == s.peerID {
+ continue
+ }
+ wg.Add(1)
+ go func(peerID peer.ID) {
+ defer wg.Done()
+ select {
+ case sem <- struct{}{}:
+ defer func() { <-sem }()
+ case <-fanoutCtx.Done():
+ return
+ }
+ services, err := s.fetchRemoteServiceCatalog(fanoutCtx, peerID, typeStr)
+ if err != nil {
+ s.log().Debug("remote catalog fetch failed during discovery", "peer_id", peerID.String(), "error", err)
+ return
+ }
+ results <- peerCatalog{peerID: peerID, services: services}
+ }(p.ID)
+ }
+ go func() {
+ wg.Wait()
+ close(results)
+ }()
+
+ out := []*api.DiscoveredProvider{}
+ for r := range results {
+ for _, info := range r.services {
+ if info == nil {
+ continue
+ }
+ out = append(out, &api.DiscoveredProvider{
+ PeerId: r.peerID.String(),
+ LocalProxyUrl: s.localMeshURL(r.peerID, typeStr, info.GetName()),
+ SrvName: info.GetName(),
+ SrvDescription: info.GetDescription(),
+ })
+ }
+ }
+ return out, nil
+}
+
+func (s *Server) preparePeerAddrs(ctx context.Context, targetPeer peer.ID) {
+ if s.host == nil || s.dir == nil {
+ return
+ }
+ cond := s.host.Network().Connectedness(targetPeer)
+ if cond == network.Connected || cond == network.Limited {
+ conns := s.host.Network().ConnsToPeer(targetPeer)
+ hasDirectPrivateIP := false
+ for _, c := range conns {
+ remoteAddr := c.RemoteMultiaddr()
+ if isPrivateIP(remoteAddr) && !hasCircuit(remoteAddr) {
+ hasDirectPrivateIP = true
+ break
+ }
+ }
+ _ = s.host.Peerstore().Put(targetPeer, peerstoreKeyPrivateIPFailed, !hasDirectPrivateIP)
+ }
+
+ changed := false
+ addrs := s.host.Peerstore().Addrs(targetPeer)
+ if len(addrs) == 0 {
+ findCtx, cancel := context.WithTimeout(ctx, dhtLookupTimeout)
+ addrInfo, err := s.dir.findPeer(findCtx, targetPeer)
+ cancel()
+ addrs = addrInfo.Addrs
+ if len(addrs) > 0 {
+ changed = true
+ } else if err != nil && !errors.Is(err, routing.ErrNotFound) {
+ s.log().Debug("directory find_peer failed", "peer_id", targetPeer.String(), "error", err)
+ }
+ }
+
+ var validAddrs []multiaddr.Multiaddr
+ seen := make(map[string]struct{}, len(addrs))
+ addUnique := func(ma multiaddr.Multiaddr) bool {
+ str := ma.String()
+ if _, ok := seen[str]; !ok {
+ seen[str] = struct{}{}
+ validAddrs = append(validAddrs, ma)
+ return true
+ }
+ return false
+ }
+
+ for _, ma := range addrs {
+ parts := multiaddr.Split(ma)
+ isCircuit := len(parts) >= 2 && parts[len(parts)-1].Protocol().Code == multiaddr.P_CIRCUIT
+ if !isCircuit {
+ if isPrivateIP(ma) && !s.AllowInsecure {
+ if val, err := s.host.Peerstore().Get(targetPeer, peerstoreKeyPrivateIPFailed); err == nil {
+ if failed, ok := val.(bool); ok && failed {
+ changed = true
+ continue
+ }
+ }
+ }
+ addUnique(ma)
+ continue
+ }
+
+ addUnique(ma)
+ p2pPart := parts[len(parts)-2]
+ if p2pPart.Protocol().Code != multiaddr.P_P2P {
+ continue
+ }
+ relayID, err := peer.Decode(p2pPart.Value())
+ if err != nil {
+ continue
+ }
+ if len(s.host.Peerstore().Addrs(relayID)) == 0 {
+ findCtx, cancel := context.WithTimeout(ctx, dhtLookupTimeout)
+ if addrInfo, err := s.dir.findPeer(findCtx, relayID); err == nil {
+ rememberAddrs(s.host.Peerstore(), addrInfo)
+ }
+ cancel()
+ }
+ if circuitAddr, err := multiaddr.NewMultiaddr(fmt.Sprintf("/p2p/%s/p2p-circuit", relayID.String())); err == nil {
+ if addUnique(circuitAddr) {
+ changed = true
+ }
+ }
+ }
+
+ if !slices.ContainsFunc(validAddrs, func(ma multiaddr.Multiaddr) bool { return circuitRelay(ma) != "" }) {
+ for _, router := range s.authenticatedRouterIDs() {
+ if circuitAddr, err := multiaddr.NewMultiaddr(fmt.Sprintf("/p2p/%s/p2p-circuit", router.String())); err == nil {
+ if addUnique(circuitAddr) {
+ changed = true
+ }
+ }
+ }
+ }
+
+ if kept := s.selectTransit(ctx, validAddrs); len(kept) != len(validAddrs) {
+ validAddrs = kept
+ changed = true
+ }
+
+ if changed && len(validAddrs) > 0 {
+ s.host.Peerstore().ClearAddrs(targetPeer)
+ s.host.Peerstore().AddAddrs(targetPeer, validAddrs, peerstore.TempAddrTTL)
+ if sw, ok := s.host.Network().(*swarm.Swarm); ok {
+ sw.Backoff().Clear(targetPeer)
+ }
+ }
+}
+
+func circuitRelay(ma multiaddr.Multiaddr) peer.ID {
+ parts := multiaddr.Split(ma)
+ if len(parts) < 2 || parts[len(parts)-1].Protocol().Code != multiaddr.P_CIRCUIT || parts[len(parts)-2].Protocol().Code != multiaddr.P_P2P {
+ return ""
+ }
+ relayID, err := peer.Decode(parts[len(parts)-2].Value())
+ if err != nil {
+ return ""
+ }
+ return relayID
+}
+
+func relayTransportAddr(ma multiaddr.Multiaddr) multiaddr.Multiaddr {
+ if circuitRelay(ma) == "" {
+ return nil
+ }
+ parts := multiaddr.Split(ma)
+ if len(parts) < 3 {
+ return nil
+ }
+ return multiaddr.Multiaddr(slices.Clone(parts[:len(parts)-2]))
+}
+
+func (s *Server) selectTransit(ctx context.Context, addrs []multiaddr.Multiaddr) []multiaddr.Multiaddr {
+ var relays []peer.ID
+ relayAddrs := map[peer.ID][]multiaddr.Multiaddr{}
+ for _, ma := range addrs {
+ relay := circuitRelay(ma)
+ if relay == "" {
+ continue
+ }
+ if _, seen := relayAddrs[relay]; !seen {
+ relays = append(relays, relay)
+ }
+ if via := relayTransportAddr(ma); via != nil {
+ relayAddrs[relay] = append(relayAddrs[relay], via)
+ } else if _, seen := relayAddrs[relay]; !seen {
+ relayAddrs[relay] = nil
+ }
+ }
+ if len(relays) == 0 {
+ return addrs
+ }
+
+ routers := map[peer.ID]routerCandidate{}
+ for _, c := range s.routerCandidates() {
+ routers[c.ID] = c
+ }
+ var unlisted []peer.ID
+ for _, r := range relays {
+ if _, isRouter := routers[r]; !isRouter {
+ unlisted = append(unlisted, r)
+ }
+ }
+ if len(unlisted) > 0 && s.refreshCatalogForTransit(ctx) {
+ routers = map[peer.ID]routerCandidate{}
+ for _, c := range s.routerCandidates() {
+ routers[c.ID] = c
+ }
+ unlisted = unlisted[:0]
+ for _, r := range relays {
+ if _, isRouter := routers[r]; !isRouter {
+ unlisted = append(unlisted, r)
+ }
+ }
+ }
+ var viaRouters []peer.ID
+ for _, r := range relays {
+ if _, isRouter := routers[r]; isRouter {
+ viaRouters = append(viaRouters, r)
+ }
+ }
+
+ usable := map[peer.ID]bool{}
+ for _, r := range relays {
+ if s.isAuthenticatedAndConnected(r) {
+ usable[r] = true
+ }
+ }
+ if len(usable) == 0 {
+ sort.SliceStable(viaRouters, func(i, j int) bool {
+ return routers[viaRouters[i]].loadRatio() < routers[viaRouters[j]].loadRatio()
+ })
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return addrs
+ }
+ for _, r := range append(viaRouters, unlisted...) {
+ router := peer.AddrInfo{ID: r, Addrs: append(s.host.Peerstore().Addrs(r), relayAddrs[r]...)}
+ if err := s.authRouter(ctx, router, biscuitBytes); err != nil {
+ s.log().Warn("transit router did not admit member", "router_peer_id", r.String(), "error", err)
+ continue
+ }
+ usable[r] = true
+ break
+ }
+ if len(usable) == 0 {
+ return addrs
+ }
+ }
+
+ kept := make([]multiaddr.Multiaddr, 0, len(addrs))
+ for _, ma := range addrs {
+ relay := circuitRelay(ma)
+ if _, isRouter := routers[relay]; relay != "" && isRouter && !usable[relay] {
+ continue
+ }
+ kept = append(kept, ma)
+ }
+ return kept
+}
+
+func (s *Server) refreshCatalogForTransit(ctx context.Context) bool {
+ s.mu.Lock()
+ due := time.Since(s.transitCatalogRefreshedAt) >= transitCatalogRefreshInterval
+ if due {
+ s.transitCatalogRefreshedAt = time.Now()
+ }
+ s.mu.Unlock()
+ if !due {
+ return false
+ }
+ ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
+ defer cancel()
+ return s.syncMeshInfo(ctx) == nil
+}
+
+func (s *Server) triggerReprovide() {
+ if s.reprovideTrigger == nil {
+ return
+ }
+ select {
+ case s.reprovideTrigger <- struct{}{}:
+ default:
+ }
+}
+
+func (s *Server) reprovideInterval() time.Duration {
+ s.mu.Lock()
+ d := s.dirSettings.Reprovide
+ s.mu.Unlock()
+ if d <= 0 {
+ return api.DefaultReprovideInterval
+ }
+ return d
+}
+
+func (s *Server) startReprovideLoop(ctx context.Context) {
+ go func() {
+ s.announceAll(ctx)
+ for {
+ interval := s.reprovideInterval()
+ jitter := time.Duration(rand.Int64N(int64(interval/5) + 1))
+ timer := time.NewTimer(interval + jitter)
+ select {
+ case <-ctx.Done():
+ timer.Stop()
+ return
+ case <-timer.C:
+ case <-s.reprovideTrigger:
+ timer.Stop()
+ }
+ s.announceAll(ctx)
+ }
+ }()
+}
+
+func (s *Server) announceAll(ctx context.Context) {
+ if s.dir == nil || s.host == nil {
+ return
+ }
+ peerCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+ if err := s.dir.provide(peerCtx, api.PeerKey(s.peerID), ""); err != nil && ctx.Err() == nil && !errors.Is(err, errNoDirectoryRouter) {
+ s.log().Debug("peer directory announcement failed", "error", err)
+ }
+ cancel()
+
+ for _, entry := range s.listA2AEntries() {
+ if entry.noAnnounce {
+ continue
+ }
+ s.announceA2AEntry(ctx, entry)
+ }
+}
diff --git a/sdk/meshnet/httpclient.go b/sdk/meshnet/httpclient.go
new file mode 100644
index 00000000..956467a1
--- /dev/null
+++ b/sdk/meshnet/httpclient.go
@@ -0,0 +1,329 @@
+// 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 meshnet
+
+import (
+ "bytes"
+ "context"
+ "crypto/sha256"
+ "encoding/base64"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "strconv"
+ "strings"
+
+ "github.com/a2aproject/a2a-go/v2/a2a"
+ "github.com/google/agentmesh/api"
+ libp2phttp "github.com/libp2p/go-libp2p-http"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+)
+
+// HTTPClient returns an *http.Client whose Transport routes mesh URLs of the
+// form http://<any-host>/mesh/<peer_id>/<type>/<name>[/<path>] directly over
+// authenticated libp2p /libp2p-http streams (performing provider Biscuit +
+// label + publish-grant verification before sending request bytes, and
+// rewriting A2A AgentCard interface URLs back onto the local mesh URL).
+//
+// No client-wide Timeout is set so Server-Sent Events (SSE) and streaming
+// completions run unbounded; connection establishment and header reads are
+// bounded by the underlying libp2p swarm and stream deadlines.
+func (s *Server) HTTPClient() *http.Client {
+ return &http.Client{
+ Transport: &meshRoundTripper{s: s},
+ }
+}
+
+type meshRoundTripper struct {
+ s *Server
+}
+
+func (rt *meshRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+ s := rt.s
+ if s.host == nil {
+ return nil, errors.New("meshnet: Server is not running (call Up first)")
+ }
+ if req.URL == nil {
+ return nil, errors.New("meshnet: nil request URL")
+ }
+
+ path := req.URL.Path
+ if api.HasDotSegment(path) {
+ return httpErrorResponse(req, http.StatusBadRequest, "Invalid path"), nil
+ }
+ trimmed := strings.TrimPrefix(path, "/")
+ if !strings.HasPrefix(trimmed, "mesh/") {
+ return httpErrorResponse(req, http.StatusBadRequest, "meshnet HTTPClient expects /mesh/<peer_id>/<type>/<name> paths"), nil
+ }
+ parts := strings.SplitN(strings.TrimPrefix(trimmed, "mesh/"), "/", 4)
+ if len(parts) < 3 || parts[0] == "" || parts[1] == "" || parts[2] == "" {
+ return httpErrorResponse(req, http.StatusBadRequest, "Invalid mesh path: expected /mesh/<peer_id>/<type>/<name>"), nil
+ }
+
+ peerIDStr := parts[0]
+ svcTypeStr := strings.ToLower(parts[1])
+ svcName := parts[2]
+ upstreamPath := ""
+ if len(parts) > 3 {
+ upstreamPath = parts[3]
+ }
+
+ pid, err := peer.Decode(peerIDStr)
+ if err != nil {
+ return httpErrorResponse(req, http.StatusBadRequest, "Invalid peer ID"), nil
+ }
+ if s.isPeerBanned(pid) {
+ return httpErrorResponse(req, http.StatusForbidden, "Target peer is banned"), nil
+ }
+ svcType, err := api.ParseServiceType(svcTypeStr)
+ if err != nil || svcType == api.ServiceType_SERVICE_TYPE_UNSPECIFIED {
+ return httpErrorResponse(req, http.StatusBadRequest, "Invalid service type"), nil
+ }
+
+ required, err := parseRequiredLabels(req.Header.Get(api.HeaderMeshRequiredLabels))
+ if err != nil {
+ return httpErrorResponse(req, http.StatusBadRequest, fmt.Sprintf("Invalid %s header: %v", api.HeaderMeshRequiredLabels, err)), nil
+ }
+
+ // Verify provider identity, required labels, egress floor, and publish grant
+ // BEFORE sending any request bytes.
+ if err := s.verifyProvider(req.Context(), pid, required, svcTypeStr+"://"+svcName); err != nil {
+ text, code := labelGateStatus(err, "Provider failed verification")
+ s.log().Warn("outbound mesh HTTP provider verification failed",
+ "peer_id", pid.String(),
+ "service", svcTypeStr+"://"+svcName,
+ "error", err,
+ )
+ return httpErrorResponse(req, code, text), nil
+ }
+
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return nil, errors.New("meshnet: missing local member credential")
+ }
+
+ p2pTr := libp2phttp.NewTransport(s.host)
+ ctx := network.WithAllowLimitedConn(req.Context(), "meshnet-egress")
+ s.preparePeerAddrs(ctx, pid)
+
+ if svcType == api.ServiceType_SERVICE_TYPE_A2A && req.Method == http.MethodGet &&
+ (upstreamPath == "" || upstreamPath == a2aAgentCardPath) {
+ return s.roundTripAgentCard(ctx, p2pTr, req, pid, svcTypeStr, svcName, biscuitBytes)
+ }
+
+ targetPath := fmt.Sprintf("/%s/%s", svcTypeStr, svcName)
+ if upstreamPath != "" {
+ targetPath += "/" + upstreamPath
+ } else if strings.HasSuffix(path, "/") {
+ targetPath += "/"
+ }
+ targetURL := "libp2p://" + pid.String() + targetPath
+ if req.URL.RawQuery != "" {
+ targetURL += "?" + req.URL.RawQuery
+ }
+
+ outReq, err := http.NewRequestWithContext(ctx, req.Method, targetURL, req.Body)
+ if err != nil {
+ return nil, err
+ }
+ outReq.ContentLength = req.ContentLength
+ outReq.Header = sanitizeOutboundMeshHeaders(req.Header, biscuitBytes)
+ outReq.Host = pid.String()
+
+ resp, err := (&http.Client{Transport: p2pTr}).Do(outReq)
+ if err != nil {
+ _ = s.host.Peerstore().Put(pid, peerstoreKeyPrivateIPFailed, true)
+ return httpErrorResponse(req, http.StatusBadGateway, fmt.Sprintf("Bad Gateway: %v", err)), nil
+ }
+ return resp, nil
+}
+
+func (s *Server) roundTripAgentCard(ctx context.Context, p2pTr http.RoundTripper, req *http.Request, pid peer.ID, svcTypeStr, svcName string, biscuitBytes []byte) (*http.Response, error) {
+ cardURL := fmt.Sprintf("libp2p://%s/%s/%s/%s", pid.String(), svcTypeStr, svcName, a2aAgentCardPath)
+ outReq, err := http.NewRequestWithContext(ctx, http.MethodGet, cardURL, nil)
+ if err != nil {
+ return nil, err
+ }
+ outReq.Header = sanitizeOutboundMeshHeaders(req.Header, biscuitBytes)
+ outReq.Header.Del("Accept-Encoding")
+ outReq.Header.Del("If-None-Match")
+ outReq.Header.Del("If-Modified-Since")
+ outReq.Host = pid.String()
+
+ resp, err := (&http.Client{Transport: p2pTr}).Do(outReq)
+ if err != nil {
+ _ = s.host.Peerstore().Put(pid, peerstoreKeyPrivateIPFailed, true)
+ return httpErrorResponse(req, http.StatusBadGateway, "Bad Gateway: agent card fetch failed"), nil
+ }
+ if resp.StatusCode != http.StatusOK {
+ return resp, nil
+ }
+ defer func() { _ = resp.Body.Close() }()
+
+ var card a2a.AgentCard
+ if err := json.NewDecoder(io.LimitReader(resp.Body, maxAgentCardBytes)).Decode(&card); err != nil {
+ return httpErrorResponse(req, http.StatusBadGateway, "Bad Gateway: agent card is not valid JSON"), nil
+ }
+
+ scheme := req.URL.Scheme
+ if scheme == "" {
+ scheme = "http"
+ }
+ hostHeader := req.Host
+ if hostHeader == "" {
+ hostHeader = req.URL.Host
+ }
+ if hostHeader == "" {
+ hostHeader = "agentmesh.local"
+ }
+ base := fmt.Sprintf("%s://%s/mesh/%s/%s/%s", scheme, hostHeader, pid.String(), svcTypeStr, svcName)
+ if err := regenerateAgentCardForMesh(&card, base); err != nil {
+ return httpErrorResponse(req, http.StatusBadGateway, fmt.Sprintf("Bad Gateway: %v", err)), nil
+ }
+ out, err := json.Marshal(&card)
+ if err != nil {
+ return httpErrorResponse(req, http.StatusInternalServerError, "Internal Server Error"), nil
+ }
+
+ hdr := make(http.Header)
+ for _, h := range []string{"Cache-Control", "Last-Modified"} {
+ if v := resp.Header.Get(h); v != "" {
+ hdr.Set(h, v)
+ }
+ }
+ etag := agentCardETag(out)
+ hdr.Set("ETag", etag)
+ if etagMatches(req.Header.Get("If-None-Match"), etag) {
+ return &http.Response{
+ StatusCode: http.StatusNotModified,
+ Status: fmt.Sprintf("%d %s", http.StatusNotModified, http.StatusText(http.StatusNotModified)),
+ Proto: "HTTP/1.1",
+ ProtoMajor: 1,
+ ProtoMinor: 1,
+ Header: hdr,
+ Body: http.NoBody,
+ Request: req,
+ }, nil
+ }
+
+ hdr.Set("Content-Type", "application/json")
+ hdr.Set("Content-Length", strconv.Itoa(len(out)))
+ return &http.Response{
+ StatusCode: http.StatusOK,
+ Status: "200 OK",
+ Proto: "HTTP/1.1",
+ ProtoMajor: 1,
+ ProtoMinor: 1,
+ Header: hdr,
+ Body: io.NopCloser(bytes.NewReader(out)),
+ ContentLength: int64(len(out)),
+ Request: req,
+ }, nil
+}
+
+func regenerateAgentCardForMesh(card *a2a.AgentCard, base string) error {
+ kept := make([]*a2a.AgentInterface, 0, len(card.SupportedInterfaces))
+ for _, iface := range card.SupportedInterfaces {
+ if iface == nil || !a2aBindingOverHTTP(iface.ProtocolBinding) {
+ continue
+ }
+ iface.URL = meshInterfaceURL(base, iface.URL)
+ kept = append(kept, iface)
+ }
+ if len(kept) == 0 {
+ return errors.New("agent card advertises no HTTP interface (JSONRPC or HTTP+JSON)")
+ }
+ card.SupportedInterfaces = kept
+ card.Signatures = nil
+ if card.Skills == nil {
+ card.Skills = []a2a.AgentSkill{}
+ }
+ if card.DefaultInputModes == nil {
+ card.DefaultInputModes = []string{}
+ }
+ if card.DefaultOutputModes == nil {
+ card.DefaultOutputModes = []string{}
+ }
+ return nil
+}
+
+func meshInterfaceURL(base, raw string) string {
+ ref, err := url.Parse(raw)
+ if err != nil || ref.Scheme != "" || ref.Host != "" || ref.User != nil || ref.Opaque != "" ||
+ strings.HasPrefix(ref.Path, "/") || api.HasDotSegment(ref.Path) {
+ return base
+ }
+ out := base
+ if ref.Path != "" {
+ out += "/" + ref.EscapedPath()
+ }
+ if ref.RawQuery != "" {
+ out += "?" + ref.RawQuery
+ }
+ return out
+}
+
+func agentCardETag(card []byte) string {
+ sum := sha256.Sum256(card)
+ return `"` + hex.EncodeToString(sum[:16]) + `"`
+}
+
+func etagMatches(header, etag string) bool {
+ for _, candidate := range strings.Split(header, ",") {
+ candidate = strings.TrimSpace(candidate)
+ if candidate == "*" || strings.TrimPrefix(candidate, "W/") == etag {
+ return true
+ }
+ }
+ return false
+}
+
+func sanitizeOutboundMeshHeaders(in http.Header, biscuitBytes []byte) http.Header {
+ out := in.Clone()
+ if out == nil {
+ out = make(http.Header)
+ }
+ for k := range out {
+ lower := strings.ToLower(k)
+ if lower == "cookie" || strings.HasPrefix(lower, "x-mesh-") || strings.EqualFold(k, api.HeaderPeerID) {
+ delete(out, k)
+ }
+ }
+ out.Set(api.HeaderMeshBiscuit, base64.StdEncoding.EncodeToString(biscuitBytes))
+ return out
+}
+
+func httpErrorResponse(req *http.Request, code int, msg string) *http.Response {
+ body := msg + "\n"
+ hdr := make(http.Header)
+ hdr.Set("Content-Type", "text/plain; charset=utf-8")
+ hdr.Set("Content-Length", strconv.Itoa(len(body)))
+ return &http.Response{
+ StatusCode: code,
+ Status: fmt.Sprintf("%d %s", code, http.StatusText(code)),
+ Proto: "HTTP/1.1",
+ ProtoMajor: 1,
+ ProtoMinor: 1,
+ Header: hdr,
+ Body: io.NopCloser(strings.NewReader(body)),
+ ContentLength: int64(len(body)),
+ Request: req,
+ }
+}
diff --git a/sdk/meshnet/inference.go b/sdk/meshnet/inference.go
new file mode 100644
index 00000000..7b957b31
--- /dev/null
+++ b/sdk/meshnet/inference.go
@@ -0,0 +1,426 @@
+// 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 meshnet
+
+import (
+ "bytes"
+ "context"
+ "encoding/base64"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "net/http"
+ "sort"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/google/agentmesh/api"
+ libp2phttp "github.com/libp2p/go-libp2p-http"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+)
+
+const (
+ modelRegistryTTL = 30 * time.Second
+ remoteModelProbeTimeout = 10 * time.Second
+ remoteProbeConcurrency = 10
+ maxInferenceBodyBytes = 16 << 20 // 16 MiB
+ providerBackoffDuration = 15 * time.Second
+)
+
+type modelProvider struct {
+ peerID string
+ service string
+}
+
+type inferenceFacade struct {
+ s *Server
+ client *http.Client
+
+ mu sync.Mutex
+ models map[string][]modelProvider
+ expires time.Time
+
+ backoffMu sync.Mutex
+ backoff map[string]time.Time
+ rr atomic.Uint64
+}
+
+// InferenceHandler returns an OpenAI-compatible http.Handler serving
+// GET /v1/models, POST /v1/chat/completions, and POST /v1/completions backed by
+// remote inference://* services across the mesh. Point any OpenAI SDK or coding
+// harness at this handler over a local Unix socket or loopback listener so the
+// sandbox needs zero upstream LLM API keys.
+func (s *Server) InferenceHandler() http.Handler {
+ f := &inferenceFacade{
+ s: s,
+ client: s.HTTPClient(),
+ }
+ mux := http.NewServeMux()
+ mux.HandleFunc("/v1/models", f.handleModels)
+ mux.HandleFunc("/v1/chat/completions", f.handleCompletions)
+ mux.HandleFunc("/v1/completions", f.handleCompletions)
+ return mux
+}
+
+func (f *inferenceFacade) handleModels(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ writeOpenAIError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only GET is supported")
+ return
+ }
+ type openAIModel struct {
+ ID string `json:"id"`
+ Object string `json:"object"`
+ Created int64 `json:"created"`
+ OwnedBy string `json:"owned_by"`
+ }
+ view := f.modelsView(r.Context())
+ data := make([]openAIModel, 0, len(view))
+ for id, providers := range view {
+ ownedBy := "mesh"
+ if len(providers) > 0 && providers[0].peerID != "" {
+ ownedBy = providers[0].peerID
+ }
+ data = append(data, openAIModel{ID: id, Object: "model", OwnedBy: ownedBy})
+ }
+ sort.Slice(data, func(i, j int) bool { return data[i].ID < data[j].ID })
+
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(map[string]any{"object": "list", "data": data})
+}
+
+func (f *inferenceFacade) handleCompletions(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ writeOpenAIError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only POST is supported")
+ return
+ }
+ body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, maxInferenceBodyBytes))
+ if err != nil {
+ var maxErr *http.MaxBytesError
+ if errors.As(err, &maxErr) {
+ writeOpenAIError(w, http.StatusRequestEntityTooLarge, "request_too_large", "request body exceeds limit")
+ return
+ }
+ writeOpenAIError(w, http.StatusBadRequest, "invalid_request", "failed to read request body")
+ return
+ }
+
+ var reqBody struct {
+ Model string `json:"model"`
+ }
+ if err := json.Unmarshal(body, &reqBody); err != nil {
+ writeOpenAIError(w, http.StatusBadRequest, "invalid_request", "request body is not valid JSON")
+ return
+ }
+ if reqBody.Model == "" {
+ writeOpenAIError(w, http.StatusBadRequest, "invalid_request", "missing required field: model")
+ return
+ }
+
+ requiredLabels, err := parseRequiredLabels(r.Header.Get(api.HeaderMeshRequiredLabels))
+ if err != nil {
+ writeOpenAIError(w, http.StatusBadRequest, "invalid_request", err.Error())
+ return
+ }
+
+ providers := f.providersFor(r.Context(), reqBody.Model)
+ if len(providers) == 0 {
+ writeOpenAIError(w, http.StatusNotFound, "model_not_found",
+ fmt.Sprintf("model %q is not served by any provider on the mesh", reqBody.Model))
+ return
+ }
+
+ ranked := f.rankProviders(providers)
+ if len(ranked) == 0 {
+ writeOpenAIError(w, http.StatusServiceUnavailable, "no_eligible_provider",
+ fmt.Sprintf("model %q has no eligible provider", reqBody.Model))
+ return
+ }
+
+ maxAttempts := min(3, len(ranked))
+ verifiedAny := false
+ for i := range maxAttempts {
+ p := ranked[i]
+ pid, err := peer.Decode(p.peerID)
+ if err != nil {
+ continue
+ }
+ if err := f.s.verifyProvider(r.Context(), pid, requiredLabels, api.ServiceTypeStringInference+"://"+p.service); err != nil {
+ f.s.log().Warn("inference provider failed verification; trying next",
+ "peer_id", p.peerID,
+ "service", p.service,
+ "error", err,
+ )
+ continue
+ }
+ verifiedAny = true
+
+ targetURL := fmt.Sprintf("http://agentmesh.local/mesh/%s/%s/%s%s", p.peerID, api.ServiceTypeStringInference, p.service, r.URL.Path)
+ if r.URL.RawQuery != "" {
+ targetURL += "?" + r.URL.RawQuery
+ }
+ outReq, err := http.NewRequestWithContext(r.Context(), http.MethodPost, targetURL, bytes.NewReader(body))
+ if err != nil {
+ continue
+ }
+ outReq.ContentLength = int64(len(body))
+ outReq.Header = r.Header.Clone()
+ outReq.Header.Del(api.HeaderMeshAuthentication)
+ outReq.Header.Del(api.HeaderMeshRequiredLabels)
+
+ resp, err := f.client.Do(outReq)
+ if err != nil {
+ f.recordBackoff(p)
+ f.s.log().Warn("inference request failed; trying next provider", "peer_id", p.peerID, "service", p.service, "error", err)
+ continue
+ }
+ if retryableStatus(resp.StatusCode) {
+ _ = resp.Body.Close()
+ f.recordBackoff(p)
+ f.s.log().Warn("inference provider returned retryable status; trying next",
+ "peer_id", p.peerID,
+ "service", p.service,
+ "status", resp.StatusCode,
+ )
+ continue
+ }
+
+ copyResponse(w, resp)
+ return
+ }
+
+ if !verifiedAny {
+ writeOpenAIError(w, http.StatusServiceUnavailable, "no_eligible_provider",
+ fmt.Sprintf("model %q has no provider satisfying required labels", reqBody.Model))
+ return
+ }
+ writeOpenAIError(w, http.StatusServiceUnavailable, "no_available_provider",
+ fmt.Sprintf("all providers for model %q are currently unavailable", reqBody.Model))
+}
+
+func copyResponse(w http.ResponseWriter, resp *http.Response) {
+ defer func() { _ = resp.Body.Close() }()
+ for k, vv := range resp.Header {
+ for _, v := range vv {
+ w.Header().Add(k, v)
+ }
+ }
+ w.WriteHeader(resp.StatusCode)
+ flusher, canFlush := w.(http.Flusher)
+ buf := make([]byte, 32*1024)
+ for {
+ n, err := resp.Body.Read(buf)
+ if n > 0 {
+ if _, wErr := w.Write(buf[:n]); wErr != nil {
+ return
+ }
+ if canFlush {
+ flusher.Flush()
+ }
+ }
+ if err != nil {
+ return
+ }
+ }
+}
+
+func (f *inferenceFacade) modelsView(ctx context.Context) map[string][]modelProvider {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ if len(f.models) == 0 || time.Now().After(f.expires) {
+ f.models = f.collectModels(ctx)
+ f.expires = time.Now().Add(modelRegistryTTL)
+ }
+ return f.models
+}
+
+func (f *inferenceFacade) providersFor(ctx context.Context, model string) []modelProvider {
+ f.mu.Lock()
+ refreshed := false
+ if len(f.models) == 0 || time.Now().After(f.expires) {
+ f.models = f.collectModels(ctx)
+ f.expires = time.Now().Add(modelRegistryTTL)
+ refreshed = true
+ }
+ if providers := f.models[model]; len(providers) > 0 {
+ f.mu.Unlock()
+ return providers
+ }
+ if !refreshed {
+ f.models = f.collectModels(ctx)
+ f.expires = time.Now().Add(modelRegistryTTL)
+ }
+ out := f.models[model]
+ f.mu.Unlock()
+ return out
+}
+
+func (f *inferenceFacade) collectModels(ctx context.Context) map[string][]modelProvider {
+ models := map[string][]modelProvider{}
+ providers, err := f.s.Discover(ctx, api.ServiceType_SERVICE_TYPE_INFERENCE, "")
+ if err != nil {
+ f.s.log().Debug("inference discovery failed", "error", err)
+ return models
+ }
+
+ var (
+ mu sync.Mutex
+ wg sync.WaitGroup
+ sem = make(chan struct{}, remoteProbeConcurrency)
+ )
+ for _, p := range providers {
+ wg.Add(1)
+ go func(peerID, srvName string) {
+ defer wg.Done()
+ select {
+ case sem <- struct{}{}:
+ defer func() { <-sem }()
+ case <-ctx.Done():
+ return
+ }
+ ids, err := f.probeRemoteModels(ctx, peerID, srvName)
+ if err != nil {
+ f.s.log().Debug("remote model probe failed", "peer_id", peerID, "service", srvName, "error", err)
+ return
+ }
+ mu.Lock()
+ for _, id := range ids {
+ models[id] = append(models[id], modelProvider{peerID: peerID, service: srvName})
+ }
+ mu.Unlock()
+ }(p.GetPeerId(), p.GetSrvName())
+ }
+ wg.Wait()
+ return models
+}
+
+func (f *inferenceFacade) probeRemoteModels(ctx context.Context, peerID, srvName string) ([]string, error) {
+ if f.s.host == nil {
+ return nil, errors.New("server not running")
+ }
+ pid, err := peer.Decode(peerID)
+ if err != nil {
+ return nil, err
+ }
+ biscuitBytes := f.s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return nil, errors.New("missing local credential")
+ }
+ if err := f.s.verifyProvider(ctx, pid, nil, api.ServiceTypeStringInference+"://"+srvName); err != nil {
+ return nil, err
+ }
+ probeCtx, cancel := context.WithTimeout(network.WithAllowLimitedConn(ctx, "openai-facade"), remoteModelProbeTimeout)
+ defer cancel()
+ f.s.preparePeerAddrs(probeCtx, pid)
+
+ u := fmt.Sprintf("libp2p://%s/%s/%s/v1/models", pid.String(), api.ServiceTypeStringInference, srvName)
+ req, err := http.NewRequestWithContext(probeCtx, http.MethodGet, u, nil)
+ if err != nil {
+ return nil, err
+ }
+ req.Header.Set(api.HeaderMeshBiscuit, base64.StdEncoding.EncodeToString(biscuitBytes))
+ req.Host = pid.String()
+
+ p2pClient := &http.Client{Transport: libp2phttp.NewTransport(f.s.host)}
+ resp, err := p2pClient.Do(req)
+ if err != nil {
+ return nil, err
+ }
+ defer func() { _ = resp.Body.Close() }()
+ if resp.StatusCode != http.StatusOK {
+ return nil, fmt.Errorf("provider %s/%s returned status %d for /v1/models", peerID, srvName, resp.StatusCode)
+ }
+ var list struct {
+ Data []struct {
+ ID string `json:"id"`
+ } `json:"data"`
+ }
+ if err := json.NewDecoder(io.LimitReader(resp.Body, 4<<20)).Decode(&list); err != nil {
+ return nil, err
+ }
+ out := make([]string, 0, len(list.Data))
+ for _, m := range list.Data {
+ if m.ID != "" {
+ out = append(out, m.ID)
+ }
+ }
+ return out, nil
+}
+
+func (f *inferenceFacade) rankProviders(providers []modelProvider) []modelProvider {
+ var remotes []modelProvider
+ for _, p := range providers {
+ pid, err := peer.Decode(p.peerID)
+ if err != nil || f.s.isPeerBanned(pid) || f.inBackoff(p) {
+ continue
+ }
+ remotes = append(remotes, p)
+ }
+ if len(remotes) >= 2 {
+ offset := int(f.rr.Add(1) % uint64(len(remotes)))
+ head := append([]modelProvider(nil), remotes...)
+ for i := range remotes {
+ remotes[i] = head[(i+offset)%len(remotes)]
+ }
+ }
+ return remotes
+}
+
+func (f *inferenceFacade) inBackoff(p modelProvider) bool {
+ key := p.peerID + "|" + p.service
+ f.backoffMu.Lock()
+ defer f.backoffMu.Unlock()
+ until, ok := f.backoff[key]
+ if !ok {
+ return false
+ }
+ if time.Now().After(until) {
+ delete(f.backoff, key)
+ return false
+ }
+ return true
+}
+
+func (f *inferenceFacade) recordBackoff(p modelProvider) {
+ key := p.peerID + "|" + p.service
+ f.backoffMu.Lock()
+ if f.backoff == nil {
+ f.backoff = map[string]time.Time{}
+ }
+ f.backoff[key] = time.Now().Add(providerBackoffDuration)
+ f.backoffMu.Unlock()
+}
+
+func retryableStatus(code int) bool {
+ switch code {
+ case http.StatusTooManyRequests, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
+ return true
+ }
+ return false
+}
+
+func writeOpenAIError(w http.ResponseWriter, status int, code, msg string) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(status)
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "error": map[string]any{
+ "message": msg,
+ "type": "invalid_request_error",
+ "code": code,
+ },
+ })
+}
diff --git a/sdk/meshnet/mcp.go b/sdk/meshnet/mcp.go
new file mode 100644
index 00000000..0f8491a9
--- /dev/null
+++ b/sdk/meshnet/mcp.go
@@ -0,0 +1,769 @@
+// 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 meshnet
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "net/http"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/google/agentmesh/api"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/libp2p/go-msgio"
+ "github.com/modelcontextprotocol/go-sdk/jsonrpc"
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+ "github.com/multiformats/go-multiaddr"
+ "google.golang.org/protobuf/proto"
+)
+
+const meshMCPInstructions = `This MCP server connects this agent to an Agent Mesh: a zero-trust peer-to-peer network of remote agents, MCP tool servers, and OpenAI-compatible inference providers.
+
+To discover and call remote MCP tools efficiently without loading every schema upfront:
+ 1. find_remote_tools — discover what tools exist across the mesh (returns peer_id + namespaced tool_name + description). Optionally narrow by service_name, peer_id, or tool_name.
+ 2. describe_remote_tool — fetch a specific tool's input_schema before calling it so you know the exact argument shape.
+ 3. call_remote_tool — invoke it. Pass peer_id, the namespaced tool_name ('mcp://<service>/<tool>'), and arguments as a JSON object matching input_schema.
+
+Other tools:
+ - discover_remote_services — browse reachable services by type ('mcp', 'inference', or 'a2a').
+ - list_local_services — list A2A services hosted by this embedded meshnet.Server.
+ - get_mesh_info — inspect this member's PeerID, attached routers, and credential expiration.
+
+Inference ('inference://...') and A2A ('a2a://...') services are HTTP endpoints, NOT MCP tools: invoke inference via the host's OpenAI-compatible /v1 endpoint (Server.InferenceHandler) and A2A agents via Server.HTTPClient using each provider's local_proxy_url.`
+
+var (
+ errAuthRejected = errors.New("auth rejected")
+ streamableMCPOpts = &mcp.StreamableHTTPOptions{Stateless: true}
+)
+
+type streamTransport struct {
+ st network.Stream
+ r msgio.ReadCloser
+ w msgio.WriteCloser
+}
+
+func newStreamTransport(st network.Stream) *streamTransport {
+ return &streamTransport{
+ st: st,
+ r: msgio.NewVarintReader(st),
+ w: msgio.NewVarintWriter(st),
+ }
+}
+
+func (t *streamTransport) Connect(_ context.Context) (mcp.Connection, error) {
+ return t, nil
+}
+
+func (t *streamTransport) SessionID() string {
+ return t.st.Conn().RemotePeer().String()
+}
+
+func (t *streamTransport) Read(_ context.Context) (jsonrpc.Message, error) {
+ msg, err := t.r.ReadMsg()
+ if err != nil {
+ return nil, err
+ }
+ defer t.r.ReleaseMsg(msg)
+ return jsonrpc.DecodeMessage(msg)
+}
+
+func (t *streamTransport) Write(_ context.Context, msg jsonrpc.Message) error {
+ data, err := jsonrpc.EncodeMessage(msg)
+ if err != nil {
+ return err
+ }
+ return t.w.WriteMsg(data)
+}
+
+func (t *streamTransport) Close() error {
+ return t.st.Close()
+}
+
+// MCPServer returns an in-process *mcp.Server exposing the 6 mesh-operating
+// tools (find_remote_tools, describe_remote_tool, call_remote_tool,
+// discover_remote_services, list_local_services, and get_mesh_info) for local
+// coding agents, sandboxes, or Go agent frameworks (ADK, Genkit).
+func (s *Server) MCPServer() *mcp.Server {
+ srv := mcp.NewServer(&mcp.Implementation{
+ Name: "agentmesh-meshnet-mcp",
+ Version: "0.1.0",
+ }, &mcp.ServerOptions{Instructions: meshMCPInstructions})
+
+ mcp.AddTool(srv, &mcp.Tool{
+ Name: "list_local_services",
+ Description: "List services registered on this embedded meshnet.Server. Optionally filter by type.",
+ }, s.handleListLocalServices)
+
+ mcp.AddTool(srv, &mcp.Tool{
+ Name: "discover_remote_services",
+ Description: "Discover remote services in the mesh. Provide only `type` ('mcp', 'inference', or 'a2a') to browse all services of that type, or add `name` for a specific service.",
+ }, s.handleDiscoverRemoteServices)
+
+ mcp.AddTool(srv, &mcp.Tool{
+ Name: "get_mesh_info",
+ Description: "Get information about this meshnet member and its mesh connectivity.",
+ }, s.handleGetMeshInfoLocal)
+
+ mcp.AddTool(srv, &mcp.Tool{
+ Name: "call_remote_tool",
+ Description: "Call an MCP tool on a remote mesh peer.",
+ }, s.handleCallRemoteTool)
+
+ mcp.AddTool(srv, &mcp.Tool{
+ Name: "find_remote_tools",
+ Description: "Discover MCP tools hosted across the mesh (returns peer_id, namespaced tool_name, and description without full schemas).",
+ }, s.handleFindRemoteTools)
+
+ mcp.AddTool(srv, &mcp.Tool{
+ Name: "describe_remote_tool",
+ Description: "Return the description, input_schema, and output_schema for a specific namespaced 'mcp://<service>/<tool>' tool on a remote peer.",
+ }, s.handleDescribeRemoteTool)
+
+ return srv
+}
+
+// MCPHandler returns a stateless StreamableHTTP http.Handler serving
+// Server.MCPServer() (accepting requests at "/mcp" or "/", so callers can
+// mount it directly or behind http.StripPrefix).
+func (s *Server) MCPHandler() http.Handler {
+ mcpSrv := s.MCPServer()
+ streamable := mcp.NewStreamableHTTPHandler(func(_ *http.Request) *mcp.Server {
+ return mcpSrv
+ }, streamableMCPOpts)
+
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/", "/mcp", "/mcp/":
+ streamable.ServeHTTP(w, r)
+ default:
+ http.NotFound(w, r)
+ }
+ })
+}
+
+func (s *Server) handleMCPStream(st network.Stream) {
+ defer func() { _ = st.Close() }()
+ remotePeer := st.Conn().RemotePeer()
+
+ if s.rateLimiter != nil && !s.rateLimiter.Allow(remotePeer.String()) {
+ s.log().Warn("MCP stream rate limit exceeded", "peer_id", remotePeer.String())
+ _ = st.Reset()
+ return
+ }
+ _ = st.SetReadDeadline(time.Now().Add(authHandshakeTimeout))
+
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ s.log().Debug("failed reading MCP auth frame", "peer_id", remotePeer.String(), "error", err)
+ return
+ }
+ defer reader.ReleaseMsg(msg)
+
+ var authFrame api.AuthFrame
+ if err := proto.Unmarshal(msg, &authFrame); err != nil {
+ s.log().Warn("invalid protobuf in MCP auth frame", "peer_id", remotePeer.String())
+ return
+ }
+
+ writer := msgio.NewVarintWriter(st)
+ if _, err := s.authorizeInbound(authFrame.GetBiscuit(), remotePeer, authFrame.GetTargetService(), string(api.MCPProtocolID), nil); err != nil {
+ respBytes, _ := proto.Marshal(&api.AuthResponse{Success: false, Error: err.Error()})
+ _ = writer.WriteMsg(respBytes)
+ return
+ }
+
+ respBytes, err := proto.Marshal(&api.AuthResponse{Success: true, Biscuit: s.currentBiscuit()})
+ if err != nil {
+ return
+ }
+ if err := writer.WriteMsg(respBytes); err != nil {
+ return
+ }
+ _ = st.SetReadDeadline(time.Time{})
+
+ target := authFrame.GetTargetService()
+ _, targetName := api.ParseServiceTarget(target)
+ if target != "" && targetName != api.CatalogTarget {
+ s.log().Warn("closing MCP stream for unknown local service", "peer_id", remotePeer.String(), "target", target)
+ _ = st.Reset()
+ return
+ }
+
+ catalogSrv := mcp.NewServer(&mcp.Implementation{
+ Name: "agentmesh-node-catalog",
+ Version: "0.1.0",
+ }, nil)
+ mcp.AddTool(catalogSrv, &mcp.Tool{
+ Name: "list_local_services",
+ Description: "List services registered on the local node. Optionally filter by type.",
+ }, s.handleListLocalServices)
+ mcp.AddTool(catalogSrv, &mcp.Tool{
+ Name: "get_mesh_info",
+ Description: "Get information about the mesh network",
+ }, s.handleGetMeshInfoRemote)
+
+ if err := catalogSrv.Run(context.Background(), newStreamTransport(st)); err != nil {
+ s.log().Debug("catalog MCP session ended", "peer_id", remotePeer.String(), "error", err)
+ }
+}
+
+type listLocalServicesParams struct {
+ Type string `json:"type,omitempty" jsonschema:"Optional service type filter (mcp, inference, a2a). Empty means all types."`
+}
+
+func (s *Server) handleListLocalServices(_ context.Context, _ *mcp.CallToolRequest, params listLocalServicesParams) (*mcp.CallToolResult, any, error) {
+ typeFilter := api.ServiceType_SERVICE_TYPE_UNSPECIFIED
+ if params.Type != "" {
+ parsed, err := api.ParseServiceType(params.Type)
+ if err != nil {
+ return nil, nil, err
+ }
+ typeFilter = parsed
+ }
+ services := s.listLocalServiceInfos(typeFilter)
+ data, err := json.Marshal(services)
+ if err != nil {
+ return nil, nil, err
+ }
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(data)}},
+ }, nil, nil
+}
+
+type discoverRemoteServicesParams struct {
+ Type string `json:"type" jsonschema:"Required. One of: mcp, inference, a2a."`
+ Name string `json:"name,omitempty" jsonschema:"Optional service name. Omit to list all services of the given type."`
+ Limit int `json:"limit,omitempty" jsonschema:"Optional limit for pagination. Defaults to 20."`
+ Offset int `json:"offset,omitempty" jsonschema:"Optional offset for pagination. Defaults to 0."`
+}
+
+func (s *Server) handleDiscoverRemoteServices(ctx context.Context, _ *mcp.CallToolRequest, params discoverRemoteServicesParams) (*mcp.CallToolResult, any, error) {
+ svcType, err := api.ParseServiceType(params.Type)
+ if err != nil || svcType == api.ServiceType_SERVICE_TYPE_UNSPECIFIED {
+ return nil, nil, fmt.Errorf("invalid or unspecified service type: %s", params.Type)
+ }
+ providers, err := s.Discover(ctx, svcType, params.Name)
+ if err != nil {
+ return nil, nil, err
+ }
+ limit := params.Limit
+ if limit <= 0 {
+ limit = 20
+ }
+ offset := max(params.Offset, 0)
+ if offset >= len(providers) {
+ providers = []*api.DiscoveredProvider{}
+ } else {
+ end := offset + limit
+ if end > len(providers) || end < offset {
+ end = len(providers)
+ }
+ providers = providers[offset:end]
+ }
+ data, err := json.Marshal(providers)
+ if err != nil {
+ return nil, nil, err
+ }
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(data)}},
+ }, nil, nil
+}
+
+type getMeshInfoParams struct{}
+
+func (s *Server) handleGetMeshInfoLocal(_ context.Context, _ *mcp.CallToolRequest, _ getMeshInfoParams) (*mcp.CallToolResult, any, error) {
+ st := s.Status()
+ payload := struct {
+ PeerID string `json:"peer_id"`
+ ControlPlaneURL string `json:"control_plane_url"`
+ AttachedRouters []string `json:"attached_routers"`
+ IngressURLs []string `json:"ingress_urls,omitempty"`
+ ExpireTime string `json:"expire_time,omitempty"`
+ }{
+ PeerID: st.PeerID,
+ ControlPlaneURL: st.ControlPlaneURL,
+ AttachedRouters: st.AttachedRouters,
+ IngressURLs: st.IngressURLs,
+ }
+ if !st.ExpireTime.IsZero() {
+ payload.ExpireTime = st.ExpireTime.UTC().Format(time.RFC3339)
+ }
+ data, err := json.Marshal(payload)
+ if err != nil {
+ return nil, nil, err
+ }
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(data)}},
+ }, nil, nil
+}
+
+func (s *Server) handleGetMeshInfoRemote(_ context.Context, _ *mcp.CallToolRequest, _ getMeshInfoParams) (*mcp.CallToolResult, any, error) {
+ data, err := json.Marshal(struct {
+ PeerID string `json:"peer_id"`
+ }{PeerID: s.peerID.String()})
+ if err != nil {
+ return nil, nil, err
+ }
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(data)}},
+ }, nil, nil
+}
+
+type callRemoteToolParams struct {
+ PeerID string `json:"peer_id" jsonschema:"The Peer ID of the target agent."`
+ ToolName string `json:"tool_name" jsonschema:"Namespaced tool name ('mcp://<service>/<tool>')."`
+ Arguments map[string]any `json:"arguments,omitempty" jsonschema:"Tool arguments as a JSON object matching input_schema."`
+ RequiredLabels string `json:"required_labels,omitempty" jsonschema:"Optional comma-separated key=value pairs attested on the provider's Biscuit."`
+}
+
+func (s *Server) handleCallRemoteTool(ctx context.Context, _ *mcp.CallToolRequest, params callRemoteToolParams) (*mcp.CallToolResult, any, error) {
+ targetPeer, err := peer.Decode(params.PeerID)
+ if err != nil {
+ return nil, nil, err
+ }
+ required, err := parseRequiredLabels(params.RequiredLabels)
+ if err != nil {
+ return nil, nil, fmt.Errorf("invalid required_labels: %w", err)
+ }
+ res, err := s.callMCPTool(ctx, targetPeer, params.ToolName, params.Arguments, required)
+ if err != nil {
+ return nil, nil, err
+ }
+ return res, nil, nil
+}
+
+type findRemoteToolsParams struct {
+ Intent string `json:"intent,omitempty" jsonschema:"Optional natural-language intent (reserved for future ranking)."`
+ PeerID string `json:"peer_id,omitempty" jsonschema:"Restrict the search to a single peer. Empty searches the whole mesh."`
+ ServiceName string `json:"service_name,omitempty" jsonschema:"Restrict results to tools on this MCP service (e.g. 'code-reviewer')."`
+ ToolName string `json:"tool_name,omitempty" jsonschema:"Exact bare tool name to locate across the mesh."`
+}
+
+type remoteToolRow struct {
+ PeerID string `json:"peer_id"`
+ ToolName string `json:"tool_name,omitempty"`
+ Description string `json:"description,omitempty"`
+ Labels map[string]string `json:"labels,omitempty"`
+ Error string `json:"error,omitempty"`
+}
+
+func (s *Server) handleFindRemoteTools(ctx context.Context, _ *mcp.CallToolRequest, params findRemoteToolsParams) (*mcp.CallToolResult, any, error) {
+ if s.host == nil {
+ return nil, nil, errors.New("meshnet: Server is not running")
+ }
+ selfID := s.peerID.String()
+ if params.PeerID != "" && params.PeerID == selfID {
+ return nil, nil, fmt.Errorf("peer_id %q is this member; find_remote_tools searches remote peers", params.PeerID)
+ }
+ serviceFilter, err := normalizeMCPServiceFilter(params.ServiceName)
+ if err != nil {
+ return nil, nil, err
+ }
+
+ var rows []remoteToolRow
+ if params.PeerID != "" {
+ pid, err := peer.Decode(params.PeerID)
+ if err != nil {
+ return nil, nil, fmt.Errorf("invalid peer_id %q: %w", params.PeerID, err)
+ }
+ rows, err = s.fetchRemoteToolCatalogue(ctx, pid, serviceFilter)
+ if err != nil {
+ return nil, nil, err
+ }
+ } else {
+ providers, err := s.Discover(ctx, api.ServiceType_SERVICE_TYPE_MCP, "")
+ if err != nil {
+ return nil, nil, fmt.Errorf("discover MCP providers: %w", err)
+ }
+ seen := map[string]bool{}
+ var peerIDs []peer.ID
+ for _, p := range providers {
+ if p.GetPeerId() == selfID || seen[p.GetPeerId()] {
+ continue
+ }
+ seen[p.GetPeerId()] = true
+ if pid, err := peer.Decode(p.GetPeerId()); err == nil {
+ peerIDs = append(peerIDs, pid)
+ }
+ }
+ rows = s.fanOutFetchTools(ctx, peerIDs, serviceFilter)
+ }
+
+ if params.ToolName != "" {
+ var filtered []remoteToolRow
+ for _, row := range rows {
+ if row.Error == "" && row.ToolName[strings.LastIndex(row.ToolName, "/")+1:] == params.ToolName {
+ filtered = append(filtered, row)
+ }
+ }
+ rows = filtered
+ }
+ if rows == nil {
+ rows = []remoteToolRow{}
+ }
+ data, err := json.Marshal(rows)
+ if err != nil {
+ return nil, nil, err
+ }
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(data)}},
+ }, nil, nil
+}
+
+func normalizeMCPServiceFilter(name string) (string, error) {
+ switch {
+ case name == "":
+ return "", nil
+ case !strings.Contains(name, "://"):
+ return api.MCPServicePrefix + name, nil
+ case strings.HasPrefix(name, api.MCPServicePrefix):
+ return name, nil
+ default:
+ return "", fmt.Errorf("service_name %q: find_remote_tools searches MCP services only", name)
+ }
+}
+
+type describeRemoteToolParams struct {
+ PeerID string `json:"peer_id" jsonschema:"Peer ID of the node hosting the MCP service. Required."`
+ ToolName string `json:"tool_name" jsonschema:"Namespaced tool name as returned by find_remote_tools ('mcp://<service>/<tool>'). Required."`
+}
+
+type remoteToolDescription struct {
+ PeerID string `json:"peer_id,omitempty"`
+ ToolName string `json:"tool_name"`
+ Description string `json:"description"`
+ InputSchema any `json:"input_schema,omitempty"`
+ OutputSchema any `json:"output_schema,omitempty"`
+}
+
+func (s *Server) handleDescribeRemoteTool(ctx context.Context, _ *mcp.CallToolRequest, params describeRemoteToolParams) (*mcp.CallToolResult, any, error) {
+ if params.PeerID == "" {
+ return nil, nil, errors.New("peer_id is required")
+ }
+ if params.ToolName == "" {
+ return nil, nil, errors.New("tool_name is required")
+ }
+ pid, err := peer.Decode(params.PeerID)
+ if err != nil {
+ return nil, nil, fmt.Errorf("invalid peer_id: %w", err)
+ }
+ desc, err := s.fetchRemoteToolDescription(ctx, pid, params.ToolName)
+ if err != nil {
+ return nil, nil, err
+ }
+ data, err := json.Marshal(desc)
+ if err != nil {
+ return nil, nil, err
+ }
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(data)}},
+ }, nil, nil
+}
+
+func (s *Server) connectMCPSession(ctx context.Context, targetPeer peer.ID, targetService string, requiredLabels map[string]string) (*mcp.ClientSession, func(), error) {
+ if s.host == nil {
+ return nil, nil, errors.New("meshnet: Server is not running")
+ }
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return nil, nil, errors.New("meshnet: missing local member credential")
+ }
+
+ dialCtx, cancel := context.WithTimeout(network.WithAllowLimitedConn(ctx, "mcp"), 15*time.Second)
+ defer cancel()
+
+ st, err := s.host.NewStream(dialCtx, targetPeer, api.MCPProtocolID)
+ if err != nil {
+ _ = s.host.Peerstore().Put(targetPeer, peerstoreKeyPrivateIPFailed, true)
+ return nil, nil, fmt.Errorf("open MCP stream to %s: %w", targetPeer, err)
+ }
+
+ if remoteAddr := st.Conn().RemoteMultiaddr(); remoteAddr != nil {
+ parts := multiaddr.Split(remoteAddr)
+ isCircuit := len(parts) >= 2 && parts[len(parts)-1].Protocol().Code == multiaddr.P_CIRCUIT
+ _ = s.host.Peerstore().Put(targetPeer, peerstoreKeyPrivateIPFailed, isCircuit || !isPrivateIP(remoteAddr))
+ }
+
+ cleanup := func() { _ = st.Close() }
+
+ authBytes, err := proto.Marshal(&api.AuthFrame{
+ Biscuit: biscuitBytes,
+ TargetService: targetService,
+ })
+ if err != nil {
+ cleanup()
+ return nil, nil, err
+ }
+
+ _ = st.SetDeadline(time.Now().Add(authHandshakeTimeout))
+ if err := msgio.NewVarintWriter(st).WriteMsg(authBytes); err != nil {
+ cleanup()
+ return nil, nil, fmt.Errorf("write MCP auth frame to %s: %w", targetPeer, err)
+ }
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ cleanup()
+ return nil, nil, fmt.Errorf("read MCP auth response from %s: %w", targetPeer, err)
+ }
+ defer reader.ReleaseMsg(msg)
+ _ = st.SetDeadline(time.Time{})
+
+ var resp api.AuthResponse
+ if err := proto.Unmarshal(msg, &resp); err != nil {
+ cleanup()
+ return nil, nil, fmt.Errorf("decode MCP auth response from %s: %w", targetPeer, err)
+ }
+ if !resp.GetSuccess() {
+ cleanup()
+ return nil, nil, fmt.Errorf("%w by %s: %s", errAuthRejected, targetPeer, resp.GetError())
+ }
+
+ if err := s.checkProvider(resp.GetBiscuit(), targetPeer, requiredLabels, targetService); err != nil {
+ cleanup()
+ return nil, nil, err
+ }
+
+ client := mcp.NewClient(&mcp.Implementation{Name: "agentmesh-meshnet-mcp-client", Version: "0.1.0"}, nil)
+ session, err := client.Connect(ctx, newStreamTransport(st), nil)
+ if err != nil {
+ cleanup()
+ return nil, nil, fmt.Errorf("connect MCP client: %w", err)
+ }
+ return session, func() {
+ _ = session.Close()
+ cleanup()
+ }, nil
+}
+
+func (s *Server) callMCPTool(ctx context.Context, targetPeer peer.ID, toolName string, args any, requiredLabels map[string]string) (*mcp.CallToolResult, error) {
+ targetService, bareTool, err := api.SplitToolName(toolName)
+ if err != nil {
+ return nil, err
+ }
+ s.preparePeerAddrs(ctx, targetPeer)
+
+ backoff := time.Second
+ var lastErr error
+ for attempt := 0; attempt < 3; attempt++ {
+ session, cleanup, err := s.connectMCPSession(ctx, targetPeer, targetService, requiredLabels)
+ if err == nil {
+ res, callErr := session.CallTool(ctx, &mcp.CallToolParams{
+ Name: bareTool,
+ Arguments: args,
+ })
+ cleanup()
+ if callErr == nil {
+ return res, nil
+ }
+ err = fmt.Errorf("call tool %s: %w", toolName, callErr)
+ }
+ lastErr = err
+ if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) ||
+ errors.Is(err, errAuthRejected) || errors.Is(err, errProviderNotGranted) {
+ return nil, err
+ }
+ if attempt == 2 {
+ break
+ }
+ timer := time.NewTimer(backoff)
+ select {
+ case <-ctx.Done():
+ timer.Stop()
+ return nil, ctx.Err()
+ case <-timer.C:
+ }
+ backoff *= 2
+ }
+ return nil, fmt.Errorf("failed after 3 attempts: %w", lastErr)
+}
+
+func (s *Server) fetchRemoteServiceCatalog(ctx context.Context, peerID peer.ID, typeStr string) ([]*api.ServiceInfo, error) {
+ s.preparePeerAddrs(ctx, peerID)
+ session, cleanup, err := s.connectMCPSession(ctx, peerID, "system://"+api.CatalogTarget, nil)
+ if err != nil {
+ return nil, err
+ }
+ defer cleanup()
+
+ res, err := session.CallTool(ctx, &mcp.CallToolParams{
+ Name: "list_local_services",
+ Arguments: map[string]string{"type": typeStr},
+ })
+ if err != nil {
+ return nil, fmt.Errorf("call list_local_services: %w", err)
+ }
+ if res == nil || len(res.Content) == 0 {
+ return nil, errors.New("empty catalog response")
+ }
+ text, ok := res.Content[0].(*mcp.TextContent)
+ if !ok {
+ return nil, fmt.Errorf("unexpected catalog content %T", res.Content[0])
+ }
+ var services []*api.ServiceInfo
+ if err := json.Unmarshal([]byte(text.Text), &services); err != nil {
+ return nil, fmt.Errorf("unmarshal catalog: %w", err)
+ }
+ return services, nil
+}
+
+func (s *Server) fetchRemoteToolCatalogue(ctx context.Context, targetPeer peer.ID, serviceFilter string) ([]remoteToolRow, error) {
+ services, err := s.fetchRemoteServiceCatalog(ctx, targetPeer, "MCP")
+ if err != nil {
+ return nil, fmt.Errorf("fetch remote service catalog: %w", err)
+ }
+ var rows []remoteToolRow
+ for _, svc := range services {
+ if svc == nil || svc.GetType() != api.ServiceType_SERVICE_TYPE_MCP {
+ continue
+ }
+ connectService := svc.GetName()
+ if !strings.Contains(connectService, "://") && !strings.Contains(connectService, ":") {
+ connectService = api.MCPServicePrefix + connectService
+ }
+ if err := ctx.Err(); err != nil {
+ return nil, err
+ }
+ rows = append(rows, s.fetchToolsForRemoteService(ctx, targetPeer, connectService, svc.GetName(), serviceFilter)...)
+ }
+ return rows, nil
+}
+
+func (s *Server) fetchToolsForRemoteService(ctx context.Context, targetPeer peer.ID, connectService, rawName, serviceFilter string) []remoteToolRow {
+ s.preparePeerAddrs(ctx, targetPeer)
+ session, cleanup, err := s.connectMCPSession(ctx, targetPeer, connectService, nil)
+ if err != nil {
+ if errors.Is(err, errAuthRejected) {
+ return nil
+ }
+ if serviceFilter == "" || connectService == serviceFilter {
+ return []remoteToolRow{{
+ PeerID: targetPeer.String(),
+ ToolName: connectService,
+ Error: fmt.Sprintf("failed to connect: %v", err),
+ }}
+ }
+ return nil
+ }
+ defer cleanup()
+
+ listRes, err := session.ListTools(ctx, nil)
+ if err != nil {
+ if serviceFilter == "" || connectService == serviceFilter {
+ return []remoteToolRow{{
+ PeerID: targetPeer.String(),
+ ToolName: rawName,
+ Error: fmt.Sprintf("failed to list tools: %v", err),
+ }}
+ }
+ return nil
+ }
+ if listRes == nil {
+ return nil
+ }
+ var rows []remoteToolRow
+ for _, t := range listRes.Tools {
+ if t == nil {
+ continue
+ }
+ fullName := connectService + "/" + t.Name
+ if serviceFilter != "" && !strings.HasPrefix(fullName, serviceFilter+"/") {
+ continue
+ }
+ rows = append(rows, remoteToolRow{
+ PeerID: targetPeer.String(),
+ ToolName: fullName,
+ Description: t.Description,
+ })
+ }
+ return rows
+}
+
+func (s *Server) fanOutFetchTools(ctx context.Context, peers []peer.ID, serviceFilter string) []remoteToolRow {
+ const maxConcurrent = 8
+ sem := make(chan struct{}, maxConcurrent)
+ var (
+ mu sync.Mutex
+ rows []remoteToolRow
+ wg sync.WaitGroup
+ )
+ for _, pid := range peers {
+ wg.Add(1)
+ go func(p peer.ID) {
+ defer wg.Done()
+ sem <- struct{}{}
+ defer func() { <-sem }()
+
+ peerCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+ defer cancel()
+ peerRows, err := s.fetchRemoteToolCatalogue(peerCtx, p, serviceFilter)
+ mu.Lock()
+ defer mu.Unlock()
+ if err != nil {
+ rows = append(rows, remoteToolRow{
+ PeerID: p.String(),
+ Error: fmt.Sprintf("failed to fetch tool catalogue: %v", err),
+ })
+ return
+ }
+ rows = append(rows, peerRows...)
+ }(pid)
+ }
+ wg.Wait()
+ return rows
+}
+
+func (s *Server) fetchRemoteToolDescription(ctx context.Context, pid peer.ID, toolName string) (*remoteToolDescription, error) {
+ serviceName, actualToolName, err := api.SplitToolName(toolName)
+ if err != nil {
+ return nil, err
+ }
+ if serviceName == "system://"+api.CatalogTarget {
+ return nil, errors.New("cannot describe system catalog tools via describe_remote_tool")
+ }
+ s.preparePeerAddrs(ctx, pid)
+
+ session, cleanup, err := s.connectMCPSession(ctx, pid, serviceName, nil)
+ if err != nil {
+ return nil, err
+ }
+ defer cleanup()
+
+ listRes, err := session.ListTools(ctx, nil)
+ if err != nil {
+ return nil, err
+ }
+ if listRes == nil {
+ return nil, errors.New("list tools response was nil")
+ }
+ for _, tool := range listRes.Tools {
+ if tool != nil && tool.Name == actualToolName {
+ return &remoteToolDescription{
+ PeerID: pid.String(),
+ ToolName: toolName,
+ Description: tool.Description,
+ InputSchema: tool.InputSchema,
+ OutputSchema: tool.OutputSchema,
+ }, nil
+ }
+ }
+ return nil, errors.New("tool not found on peer")
+}
diff --git a/sdk/meshnet/meshnet_test.go b/sdk/meshnet/meshnet_test.go
new file mode 100644
index 00000000..12133afe
--- /dev/null
+++ b/sdk/meshnet/meshnet_test.go
@@ -0,0 +1,646 @@
+// 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 meshnet
+
+import (
+ "bytes"
+ "context"
+ "crypto/ed25519"
+ "crypto/rand"
+ "encoding/base64"
+ "encoding/json"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/a2aproject/a2a-go/v2/a2a"
+ "github.com/google/agentmesh/api"
+ "github.com/google/agentmesh/internal/identity"
+ "github.com/libp2p/go-libp2p"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/libp2p/go-msgio"
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+ "google.golang.org/protobuf/proto"
+)
+
+func TestAttenuateToken(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+ defer cancel()
+
+ t.Run("rejects_before_up_and_nil_rule", func(t *testing.T) {
+ var unstarted Server
+ if _, _, err := unstarted.AttenuateToken(&api.TaskAuthorizationRule{Name: "t1"}, time.Minute, false); err == nil {
+ t.Fatal("AttenuateToken succeeded before Up, want error")
+ }
+ env := newStartedTestServer(t, ctx)
+ if _, _, err := env.server.AttenuateToken(nil, time.Minute, false); err == nil {
+ t.Fatal("AttenuateToken(nil) succeeded, want error")
+ }
+ })
+
+ t.Run("attenuates_caps_ttl_and_seals", func(t *testing.T) {
+ env := newStartedTestServer(t, ctx)
+ rule := &api.TaskAuthorizationRule{
+ Name: "review-pr-42",
+ DisplayName: "Review PR 42",
+ Rules: []*api.TaskRule{
+ {
+ AllowedServices: []string{"a2a://coder"},
+ Operation: &api.TaskOperation{AllowedMethods: []string{"POST"}},
+ },
+ },
+ }
+
+ unsealedB64, exp, err := env.server.AttenuateToken(rule, 5*time.Minute, false)
+ if err != nil {
+ t.Fatalf("AttenuateToken(seal=false): %v", err)
+ }
+ if d := time.Until(exp); d <= 0 || d > 5*time.Minute+time.Second {
+ t.Errorf("attenuated expiry delta = %v, want (0, 5m]", d)
+ }
+ rawUnsealed, err := base64.RawURLEncoding.DecodeString(unsealedB64)
+ if err != nil {
+ t.Fatalf("DecodeString: %v", err)
+ }
+ rules, err := identity.ExtractTaskRules(rawUnsealed)
+ if err != nil || len(rules) != 1 || rules[0].GetName() != "review-pr-42" {
+ t.Fatalf("ExtractTaskRules = %v, err=%v; want [review-pr-42]", rules, err)
+ }
+
+ // A second attenuation succeeds on an unsealed token.
+ if _, err := identity.AttenuateBiscuit(rawUnsealed, &api.TaskAuthorizationRule{
+ Name: "narrower",
+ ExpireTime: rules[0].GetExpireTime(),
+ Rules: rules[0].GetRules(),
+ }); err != nil {
+ t.Fatalf("expected unsealed token to allow further attenuation: %v", err)
+ }
+
+ // With seal=true, downstream holders cannot append another block.
+ sealedB64, _, err := env.server.AttenuateToken(rule, 5*time.Minute, true)
+ if err != nil {
+ t.Fatalf("AttenuateToken(seal=true): %v", err)
+ }
+ rawSealed, err := base64.RawURLEncoding.DecodeString(sealedB64)
+ if err != nil {
+ t.Fatalf("DecodeString(sealed): %v", err)
+ }
+ if _, err := identity.AttenuateBiscuit(rawSealed, &api.TaskAuthorizationRule{
+ Name: "forged-append",
+ ExpireTime: rules[0].GetExpireTime(),
+ Rules: rules[0].GetRules(),
+ }); err == nil {
+ t.Fatal("AttenuateBiscuit succeeded on a sealed token, want error")
+ }
+ })
+}
+
+func TestAgentCardRelativizeAndRegenerate(t *testing.T) {
+ peerID := "12D3KooWExamplePeer"
+ privRoot := "/mesh/" + peerID + "/a2a/coder"
+ pubRoot := "/ingress/" + peerID + "/a2a/coder"
+ roots := []string{pubRoot, privRoot, ""}
+
+ orig := &a2a.AgentCard{
+ Name: "coder",
+ Description: "Laptop coder",
+ Version: "1.0.0",
+ SupportedInterfaces: []*a2a.AgentInterface{
+ {URL: "https://bananas.sam-mesh.dev" + pubRoot + "/invoke?mode=fast", ProtocolBinding: a2a.TransportProtocolJSONRPC, ProtocolVersion: "1.0"},
+ {URL: "http://agentmesh.local" + privRoot, ProtocolBinding: a2a.TransportProtocolHTTPJSON, ProtocolVersion: "1.0"},
+ {URL: "http://127.0.0.1:9090/v1/rpc", ProtocolBinding: a2a.TransportProtocolJSONRPC, ProtocolVersion: "1.0"},
+ {URL: "127.0.0.1:50051", ProtocolBinding: a2a.TransportProtocolGRPC, ProtocolVersion: "1.0"},
+ },
+ Signatures: []a2a.AgentCardSignature{{Protected: "hdr", Signature: "sig"}},
+ }
+ rawOrig, err := json.Marshal(orig)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ relBytes, err := relativizeAgentCardMultiRoot(rawOrig, roots)
+ if err != nil {
+ t.Fatalf("relativizeAgentCardMultiRoot: %v", err)
+ }
+ var relCard a2a.AgentCard
+ if err := json.Unmarshal(relBytes, &relCard); err != nil {
+ t.Fatalf("Unmarshal relativized card: %v", err)
+ }
+ if got := relCard.SupportedInterfaces[0].URL; got != "invoke?mode=fast" {
+ t.Errorf("interface[0].URL = %q, want %q", got, "invoke?mode=fast")
+ }
+ if got := relCard.SupportedInterfaces[1].URL; got != "" {
+ t.Errorf("interface[1].URL = %q, want empty relative root", got)
+ }
+ if got := relCard.SupportedInterfaces[2].URL; got != "v1/rpc" {
+ t.Errorf("interface[2].URL = %q, want %q", got, "v1/rpc")
+ }
+
+ base := "http://agentmesh.local" + privRoot
+ if err := regenerateAgentCardForMesh(&relCard, base); err != nil {
+ t.Fatalf("regenerateAgentCardForMesh: %v", err)
+ }
+ if len(relCard.SupportedInterfaces) != 3 {
+ t.Fatalf("len(SupportedInterfaces) = %d, want 3 (gRPC dropped)", len(relCard.SupportedInterfaces))
+ }
+ if got := relCard.SupportedInterfaces[0].URL; got != base+"/invoke?mode=fast" {
+ t.Errorf("regenerated[0] = %q, want %q", got, base+"/invoke?mode=fast")
+ }
+ if got := relCard.SupportedInterfaces[1].URL; got != base {
+ t.Errorf("regenerated[1] = %q, want %q", got, base)
+ }
+ if got := relCard.SupportedInterfaces[2].URL; got != base+"/v1/rpc" {
+ t.Errorf("regenerated[2] = %q, want %q", got, base+"/v1/rpc")
+ }
+ if len(relCard.Signatures) != 0 {
+ t.Errorf("Signatures = %v, want stripped", relCard.Signatures)
+ }
+
+ // Dot-segments (including backslash-separated segments) are never preserved.
+ for _, bad := range []string{"../admin", "..\\admin"} {
+ if got := meshInterfaceURL(base, bad); got != base {
+ t.Errorf("meshInterfaceURL(%q) = %q, want %q", bad, got, base)
+ }
+ }
+
+ etag := agentCardETag(relBytes)
+ if !etagMatches(etag, etag) || !etagMatches("W/"+etag, etag) || !etagMatches("*", etag) {
+ t.Errorf("etagMatches failed for %s", etag)
+ }
+ if etagMatches(`"other"`, etag) {
+ t.Errorf("etagMatches matched unrelated tag")
+ }
+
+ inHdr := http.Header{
+ "Authorization": {"Bearer app-token"},
+ "Cookie": {"sid=secret"},
+ "X-Mesh-Principal": {"spoofed"},
+ api.HeaderPeerID: {"spoofed-peer"},
+ }
+ sanitized := sanitizeOutboundMeshHeaders(inHdr, []byte("biscuit-bytes"))
+ if sanitized.Get("Cookie") != "" || sanitized.Get("X-Mesh-Principal") != "" || sanitized.Get(api.HeaderPeerID) != "" {
+ t.Errorf("sanitizeOutboundMeshHeaders leaked restricted headers: %v", sanitized)
+ }
+ if sanitized.Get("Authorization") != "Bearer app-token" {
+ t.Errorf("Authorization header was dropped: %v", sanitized)
+ }
+ if sanitized.Get(api.HeaderMeshBiscuit) == "" {
+ t.Error("X-Mesh-Biscuit not injected")
+ }
+}
+
+func TestParseRequiredLabels(t *testing.T) {
+ cases := []struct {
+ name string
+ header string
+ want map[string]string
+ wantErr bool
+ }{
+ {name: "empty", header: "", want: nil},
+ {name: "whitespace", header: " ", want: nil},
+ {name: "valid_pair", header: "env=prod, region = us-central1", want: map[string]string{"env": "prod", "region": "us-central1"}},
+ {name: "trailing_comma_tolerated", header: "env=prod,", want: map[string]string{"env": "prod"}},
+ {name: "lone_commas_rejected", header: ",,", wantErr: true},
+ {name: "missing_equals", header: "env-prod", wantErr: true},
+ {name: "duplicate_key", header: "env=prod,env=staging", wantErr: true},
+ {name: "invalid_key", header: "BAD KEY!=val", wantErr: true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ got, err := parseRequiredLabels(tc.header)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("parseRequiredLabels(%q) = %v, want error", tc.header, got)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("parseRequiredLabels(%q) unexpected error: %v", tc.header, err)
+ }
+ if len(got) != len(tc.want) {
+ t.Fatalf("parseRequiredLabels(%q) = %v, want %v", tc.header, got, tc.want)
+ }
+ for k, v := range tc.want {
+ if got[k] != v {
+ t.Errorf("got[%q] = %q, want %q", k, got[k], v)
+ }
+ }
+ })
+ }
+}
+
+func TestListenA2AWhoIsDiscoverAndHTTPClient(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+
+ mesh := newInProcessMeshPair(t, ctx)
+ provider := mesh.provider
+ caller := mesh.caller
+
+ ep, err := provider.ListenA2A(ctx, A2AOptions{
+ Name: "coder",
+ Description: "In-process coding agent",
+ })
+ if err != nil {
+ t.Fatalf("ListenA2A: %v", err)
+ }
+ if ep.PublicURL != nil {
+ t.Fatalf("PublicURL = %v, want nil when Public=false", ep.PublicURL)
+ }
+
+ var seenCaller CallerInfo
+ var seenRemoteAddr string
+ var callerMu sync.Mutex
+
+ mux := http.NewServeMux()
+ mux.HandleFunc("/.well-known/agent-card.json", func(w http.ResponseWriter, _ *http.Request) {
+ card := &a2a.AgentCard{
+ Name: "coder",
+ Description: "In-process coding agent",
+ Version: "1.0.0",
+ SupportedInterfaces: []*a2a.AgentInterface{
+ {URL: ep.PrivateURL.String() + "/invoke", ProtocolBinding: a2a.TransportProtocolJSONRPC, ProtocolVersion: "1.0"},
+ },
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(card)
+ })
+ mux.HandleFunc("/invoke", func(w http.ResponseWriter, r *http.Request) {
+ info, ok := provider.WhoIs(r.RemoteAddr)
+ if !ok || info == nil {
+ http.Error(w, "missing WhoIs", http.StatusInternalServerError)
+ return
+ }
+ // Mutate returned copy to verify WhoIs returns a defensive copy.
+ if len(info.Roles) > 0 {
+ info.Roles[0] = "mutated"
+ }
+ info.Labels["env"] = "mutated"
+
+ fresh, ok := provider.WhoIs(r.RemoteAddr)
+ if !ok {
+ http.Error(w, "missing second WhoIs", http.StatusInternalServerError)
+ return
+ }
+ callerMu.Lock()
+ seenCaller = *fresh
+ seenRemoteAddr = r.RemoteAddr
+ callerMu.Unlock()
+
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"ok":true}`))
+ })
+ httpSrv := &http.Server{Handler: mux}
+ go func() { _ = httpSrv.Serve(ep.PrivateListener) }()
+ t.Cleanup(func() {
+ _ = httpSrv.Close()
+ _ = ep.Close()
+ })
+
+ // 1. Targeted discovery & type-wide catalog discovery.
+ byName, err := caller.Discover(ctx, api.ServiceType_SERVICE_TYPE_A2A, "coder")
+ if err != nil {
+ t.Fatalf("Discover(by name): %v", err)
+ }
+ if len(byName) != 1 || byName[0].GetLocalProxyUrl() != ep.PrivateURL.String() {
+ t.Fatalf("Discover(by name) = %v, want [%s]", byName, ep.PrivateURL.String())
+ }
+
+ byType, err := caller.Discover(ctx, api.ServiceType_SERVICE_TYPE_A2A, "")
+ if err != nil {
+ t.Fatalf("Discover(by type): %v", err)
+ }
+ if len(byType) != 1 || byType[0].GetSrvDescription() != "In-process coding agent" {
+ t.Fatalf("Discover(by type) = %v, want description 'In-process coding agent'", byType)
+ }
+
+ // 2. AgentCard fetch via caller.HTTPClient() rewrites URL & supports ETag/304.
+ hc := caller.HTTPClient()
+ cardResp, err := hc.Get(ep.PrivateURL.String() + "/.well-known/agent-card.json")
+ if err != nil {
+ t.Fatalf("GET agent-card.json: %v", err)
+ }
+ cardBody, _ := io.ReadAll(cardResp.Body)
+ _ = cardResp.Body.Close()
+ if cardResp.StatusCode != http.StatusOK {
+ t.Fatalf("agent-card status = %d: %s", cardResp.StatusCode, cardBody)
+ }
+ var gotCard a2a.AgentCard
+ if err := json.Unmarshal(cardBody, &gotCard); err != nil {
+ t.Fatalf("unmarshal card: %v", err)
+ }
+ if len(gotCard.SupportedInterfaces) != 1 || gotCard.SupportedInterfaces[0].URL != ep.PrivateURL.String()+"/invoke" {
+ t.Fatalf("SupportedInterfaces = %+v, want %s/invoke", gotCard.SupportedInterfaces, ep.PrivateURL.String())
+ }
+ etag := cardResp.Header.Get("ETag")
+ if etag == "" {
+ t.Fatal("missing ETag header on regenerated AgentCard")
+ }
+
+ req304, _ := http.NewRequestWithContext(ctx, http.MethodGet, ep.PrivateURL.String()+"/.well-known/agent-card.json", nil)
+ req304.Header.Set("If-None-Match", etag)
+ resp304, err := hc.Do(req304)
+ if err != nil {
+ t.Fatalf("GET agent-card with If-None-Match: %v", err)
+ }
+ _ = resp304.Body.Close()
+ if resp304.StatusCode != http.StatusNotModified {
+ t.Fatalf("If-None-Match status = %d, want 304", resp304.StatusCode)
+ }
+
+ // 3. POST /invoke verifies WhoIs caller identity, defensive copy, and post-close cleanup.
+ invReq, _ := http.NewRequestWithContext(ctx, http.MethodPost, ep.PrivateURL.String()+"/invoke", strings.NewReader(`{}`))
+ invReq.Header.Set(api.HeaderMeshRequiredLabels, "env=prod")
+ invResp, err := hc.Do(invReq)
+ if err != nil {
+ t.Fatalf("POST /invoke: %v", err)
+ }
+ _, _ = io.ReadAll(invResp.Body)
+ _ = invResp.Body.Close()
+ if invResp.StatusCode != http.StatusOK {
+ t.Fatalf("POST /invoke status = %d, want 200", invResp.StatusCode)
+ }
+
+ callerMu.Lock()
+ gotCaller := seenCaller
+ remoteAddr := seenRemoteAddr
+ callerMu.Unlock()
+
+ if gotCaller.PeerID != caller.Status().PeerID {
+ t.Errorf("WhoIs PeerID = %q, want %q", gotCaller.PeerID, caller.Status().PeerID)
+ }
+ if gotCaller.Principal != "[email protected]" {
+ t.Errorf("WhoIs Principal = %q, want %q", gotCaller.Principal, "[email protected]")
+ }
+ if len(gotCaller.Roles) != 1 || gotCaller.Roles[0] != api.RoleNode {
+ t.Errorf("WhoIs Roles = %v, want [%s]", gotCaller.Roles, api.RoleNode)
+ }
+ if gotCaller.Labels["env"] != "prod" {
+ t.Errorf("WhoIs Labels[env] = %q, want prod", gotCaller.Labels["env"])
+ }
+
+ // Wait briefly for trackedConn.Close() to evict remoteAddr from activeConns.
+ deadline := time.Now().Add(2 * time.Second)
+ for time.Now().Before(deadline) {
+ if _, still := provider.WhoIs(remoteAddr); !still {
+ break
+ }
+ time.Sleep(10 * time.Millisecond)
+ }
+ if _, still := provider.WhoIs(remoteAddr); still {
+ t.Errorf("WhoIs(%q) still present after connection closed", remoteAddr)
+ }
+
+ // 4. Required-label mismatch fails closed BEFORE sending request bytes.
+ badLabelReq, _ := http.NewRequestWithContext(ctx, http.MethodPost, ep.PrivateURL.String()+"/invoke", strings.NewReader(`{}`))
+ badLabelReq.Header.Set(api.HeaderMeshRequiredLabels, "env=staging")
+ badLabelResp, err := hc.Do(badLabelReq)
+ if err != nil {
+ t.Fatalf("POST with mismatched required label: %v", err)
+ }
+ _ = badLabelResp.Body.Close()
+ if badLabelResp.StatusCode != http.StatusForbidden {
+ t.Fatalf("mismatched required label status = %d, want 403", badLabelResp.StatusCode)
+ }
+}
+
+func TestLocalMCPAndInferenceHandlers(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+
+ mesh := newInProcessMeshPair(t, ctx)
+ _, err := mesh.provider.ListenA2A(ctx, A2AOptions{Name: "helper", Description: "Helper agent"})
+ if err != nil {
+ t.Fatalf("ListenA2A: %v", err)
+ }
+
+ // 1. Local MCPServer + MCPHandler over StreamableHTTP.
+ if mesh.caller.MCPServer() == nil {
+ t.Fatal("MCPServer() returned nil")
+ }
+ mcpHTTP := httptest.NewServer(mesh.caller.MCPHandler())
+ t.Cleanup(mcpHTTP.Close)
+
+ client := mcp.NewClient(&mcp.Implementation{Name: "test-caller", Version: "1.0.0"}, nil)
+ sess, err := client.Connect(ctx, &mcp.StreamableClientTransport{Endpoint: mcpHTTP.URL + "/mcp"}, nil)
+ if err != nil {
+ t.Fatalf("MCP Connect: %v", err)
+ }
+ t.Cleanup(func() { _ = sess.Close() })
+
+ toolsRes, err := sess.ListTools(ctx, nil)
+ if err != nil {
+ t.Fatalf("ListTools: %v", err)
+ }
+ if len(toolsRes.Tools) != 6 {
+ t.Fatalf("len(Tools) = %d, want 6 mesh tools", len(toolsRes.Tools))
+ }
+
+ infoRes, err := sess.CallTool(ctx, &mcp.CallToolParams{Name: "get_mesh_info"})
+ if err != nil || infoRes.IsError {
+ t.Fatalf("get_mesh_info failed: err=%v res=%+v", err, infoRes)
+ }
+
+ discRes, err := sess.CallTool(ctx, &mcp.CallToolParams{
+ Name: "discover_remote_services",
+ Arguments: map[string]any{"type": "a2a"},
+ })
+ if err != nil || discRes.IsError {
+ t.Fatalf("discover_remote_services failed: err=%v res=%+v", err, discRes)
+ }
+ discText := discRes.Content[0].(*mcp.TextContent).Text
+ if !strings.Contains(discText, "helper") {
+ t.Errorf("discover_remote_services = %s, want helper", discText)
+ }
+
+ localRes, err := sess.CallTool(ctx, &mcp.CallToolParams{Name: "list_local_services"})
+ if err != nil || localRes.IsError {
+ t.Fatalf("list_local_services failed: err=%v res=%+v", err, localRes)
+ }
+
+ // 2. Local InferenceHandler routes and validation.
+ infHTTP := httptest.NewServer(mesh.caller.InferenceHandler())
+ t.Cleanup(infHTTP.Close)
+
+ modelsResp, err := http.Get(infHTTP.URL + "/v1/models")
+ if err != nil {
+ t.Fatalf("GET /v1/models: %v", err)
+ }
+ modelsBody, _ := io.ReadAll(modelsResp.Body)
+ _ = modelsResp.Body.Close()
+ if modelsResp.StatusCode != http.StatusOK || !strings.Contains(string(modelsBody), `"object":"list"`) {
+ t.Fatalf("GET /v1/models = %d: %s", modelsResp.StatusCode, modelsBody)
+ }
+
+ resp405, err := http.Post(infHTTP.URL+"/v1/models", "application/json", strings.NewReader(`{}`))
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = resp405.Body.Close()
+ if resp405.StatusCode != http.StatusMethodNotAllowed {
+ t.Errorf("POST /v1/models = %d, want 405", resp405.StatusCode)
+ }
+
+ resp404, err := http.Get(infHTTP.URL + "/v1/unknown")
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = resp404.Body.Close()
+ if resp404.StatusCode != http.StatusNotFound {
+ t.Errorf("GET /v1/unknown = %d, want 404", resp404.StatusCode)
+ }
+
+ resp400, err := http.Post(infHTTP.URL+"/v1/chat/completions", "application/json", strings.NewReader(`{}`))
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = resp400.Body.Close()
+ if resp400.StatusCode != http.StatusBadRequest {
+ t.Errorf("POST /v1/chat/completions missing model = %d, want 400", resp400.StatusCode)
+ }
+
+ respUnknownModel, err := http.Post(infHTTP.URL+"/v1/chat/completions", "application/json", bytes.NewReader([]byte(`{"model":"gpt-4o"}`)))
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = respUnknownModel.Body.Close()
+ if respUnknownModel.StatusCode != http.StatusNotFound {
+ t.Errorf("POST /v1/chat/completions with unknown model = %d, want 404", respUnknownModel.StatusCode)
+ }
+}
+
+type inProcessMeshPair struct {
+ provider *Server
+ caller *Server
+}
+
+func newInProcessMeshPair(t *testing.T, ctx context.Context) *inProcessMeshPair {
+ t.Helper()
+ cpPub, cpPriv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ rh, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = rh.Close() })
+
+ var dirMu sync.Mutex
+ providersByKey := map[string]map[peer.ID]*api.PeerRecord{}
+ peersByID := map[peer.ID]*api.PeerRecord{}
+
+ routerBiscuit := mintTestBiscuit(t, cpPriv, rh.ID().String(), api.RoleRouter, time.Now().Add(24*time.Hour))
+ rh.SetStreamHandler(api.AuthProtocolID, func(st network.Stream) {
+ defer func() { _ = st.Close() }()
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ return
+ }
+ reader.ReleaseMsg(msg)
+ reply, _ := proto.Marshal(&api.AuthResponse{Success: true, Biscuit: routerBiscuit})
+ _ = msgio.NewVarintWriter(st).WriteMsg(reply)
+ })
+ rh.SetStreamHandler(api.DirectoryProtocolID, func(st network.Stream) {
+ defer func() { _ = st.Close() }()
+ remote := st.Conn().RemotePeer()
+
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ return
+ }
+ var req api.DirectoryRequest
+ _ = proto.Unmarshal(msg, &req)
+ reader.ReleaseMsg(msg)
+
+ resp := &api.DirectoryResponse{}
+ dirMu.Lock()
+ entry := peersByID[remote]
+ if entry == nil {
+ var addrs []string
+ for _, ma := range rh.Peerstore().Addrs(remote) {
+ addrs = append(addrs, ma.String())
+ }
+ entry = &api.PeerRecord{PeerId: remote.String(), Addrs: addrs}
+ peersByID[remote] = entry
+ }
+ switch op := req.GetRequest().(type) {
+ case *api.DirectoryRequest_Provide:
+ k := string(op.Provide.GetKey())
+ if providersByKey[k] == nil {
+ providersByKey[k] = map[peer.ID]*api.PeerRecord{}
+ }
+ providersByKey[k][remote] = entry
+ case *api.DirectoryRequest_Withdraw:
+ delete(providersByKey[string(op.Withdraw.GetKey())], remote)
+ case *api.DirectoryRequest_FindProviders:
+ for _, p := range providersByKey[string(op.FindProviders.GetKey())] {
+ resp.Providers = append(resp.Providers, p)
+ }
+ case *api.DirectoryRequest_FindPeer:
+ if pid, err := peer.Decode(op.FindPeer.GetPeerId()); err == nil {
+ resp.Peer = peersByID[pid]
+ }
+ }
+ dirMu.Unlock()
+
+ reply, _ := proto.Marshal(resp)
+ _ = msgio.NewVarintWriter(st).WriteMsg(reply)
+ })
+
+ var routerAddrs []string
+ for _, a := range rh.Addrs() {
+ routerAddrs = append(routerAddrs, a.String()+"/p2p/"+rh.ID().String())
+ }
+ cp := newFakeControlPlaneHTTPWithKeys(t, cpPub, cpPriv, routerAddrs)
+
+ startOne := func() *Server {
+ s := &Server{
+ StateDir: t.TempDir(),
+ ControlPlaneURL: cp.srv.URL,
+ BootstrapToken: "boot-secret",
+ ListenAddrs: []string{"/ip4/127.0.0.1/tcp/0"},
+ AllowInsecure: true,
+ }
+ if _, err := s.Up(ctx); err != nil {
+ t.Fatalf("Server.Up: %v", err)
+ }
+ t.Cleanup(func() { _ = s.Close() })
+ return s
+ }
+
+ p := startOne()
+ c := startOne()
+ // Ensure router peerstore has listen multiaddrs of both peers for FindProviders/FindPeer.
+ dirMu.Lock()
+ for _, srv := range []*Server{p, c} {
+ var maddrs []string
+ for _, ma := range srv.host.Addrs() {
+ maddrs = append(maddrs, ma.String())
+ }
+ peersByID[srv.host.ID()] = &api.PeerRecord{PeerId: srv.host.ID().String(), Addrs: maddrs}
+ }
+ dirMu.Unlock()
+
+ return &inProcessMeshPair{provider: p, caller: c}
+}
diff --git a/sdk/meshnet/protocol_inventory_test.go b/sdk/meshnet/protocol_inventory_test.go
new file mode 100644
index 00000000..299550e8
--- /dev/null
+++ b/sdk/meshnet/protocol_inventory_test.go
@@ -0,0 +1,331 @@
+// 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 meshnet
+
+import (
+ "bufio"
+ "context"
+ "crypto/ed25519"
+ "crypto/rand"
+ "net/http"
+ "slices"
+ "testing"
+ "time"
+
+ "github.com/google/agentmesh/api"
+ "github.com/libp2p/go-libp2p"
+ pubsub "github.com/libp2p/go-libp2p-pubsub"
+ "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"
+ "github.com/libp2p/go-libp2p/p2p/protocol/autonatv2"
+ circuit "github.com/libp2p/go-libp2p/p2p/protocol/circuitv2/proto"
+ "github.com/libp2p/go-libp2p/p2p/protocol/identify"
+ "github.com/libp2p/go-libp2p/p2p/protocol/ping"
+ "github.com/libp2p/go-msgio"
+ "google.golang.org/protobuf/proto"
+)
+
+// Every protocol a started meshnet.Server registers on its libp2p host belongs
+// to exactly one of these three sets (mirroring internal/node/protocol_inventory_test.go).
+var (
+ handshakeProtocols = []protocol.ID{
+ api.AuthProtocolID,
+ identify.ID,
+ identify.IDPush,
+ ping.ID,
+ autonatv2.DialProtocol,
+ autonatv2.DialBackProtocol,
+ circuit.ProtoIDv2Stop,
+ }
+
+ credentialProtocols = []protocol.ID{
+ api.MCPProtocolID,
+ api.GoAwayProtocolID,
+ "/libp2p-http",
+ }
+
+ gatedProtocols = []protocol.ID{
+ api.IngressProtocolID,
+ pubsub.FloodSubID,
+ }
+)
+
+func TestServerProtocolInventoryIsClassified(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+
+ env := newStartedTestServer(t, ctx)
+ s := env.server
+
+ registered := s.host.Mux().Protocols()
+ slices.Sort(registered)
+ var unclassified []protocol.ID
+ var gated []protocol.ID
+ for _, p := range registered {
+ switch {
+ case slices.Contains(handshakeProtocols, p), slices.Contains(credentialProtocols, p):
+ case slices.Contains(gatedProtocols, p):
+ gated = append(gated, p)
+ default:
+ unclassified = append(unclassified, p)
+ }
+ }
+ if len(unclassified) > 0 {
+ t.Fatalf("meshnet.Server registers unclassified protocols: %v\n"+
+ "Classify each into handshakeProtocols, credentialProtocols, or gatedProtocols.", unclassified)
+ }
+ if !slices.Contains(gated, api.IngressProtocolID) {
+ t.Fatalf("%s is not registered on a started Server; registered: %v", api.IngressProtocolID, registered)
+ }
+
+ stranger, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = stranger.Close() })
+ if err := stranger.Connect(ctx, peer.AddrInfo{ID: s.host.ID(), Addrs: s.host.Addrs()}); err != nil {
+ t.Fatal(err)
+ }
+
+ for _, p := range gated {
+ t.Run(string(p), func(t *testing.T) {
+ before := s.refusedStreamCount(streamScopeUnauthenticated, p)
+
+ st, err := stranger.NewStream(ctx, s.host.ID(), p)
+ if err != nil {
+ t.Fatalf("open %s: %v", p, err)
+ }
+ defer func() { _ = st.Reset() }()
+ if _, err := st.Write([]byte("GET / HTTP/1.1\r\nHost: x\r\n\r\n")); err != nil {
+ t.Fatalf("write: %v", err)
+ }
+ buf := make([]byte, 64)
+ _ = st.SetReadDeadline(time.Now().Add(300 * time.Millisecond))
+ if n, err := st.Read(buf); err == nil {
+ t.Fatalf("%s answered %q to an unauthenticated peer", p, buf[:n])
+ }
+
+ if err := stranger.Network().ClosePeer(s.host.ID()); err != nil {
+ t.Fatal(err)
+ }
+ waitForCount(t, func() uint64 {
+ return s.refusedStreamCount(streamScopeUnauthenticated, p)
+ }, before+1, 5*time.Second)
+
+ if err := stranger.Connect(ctx, peer.AddrInfo{ID: s.host.ID(), Addrs: s.host.Addrs()}); err != nil {
+ t.Fatal(err)
+ }
+ })
+ }
+}
+
+func TestExternalIngressProtocolServesOnlyRouters(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+
+ env := newStartedTestServer(t, ctx)
+ s := env.server
+
+ request := "GET /a2a/assistant/.well-known/agent-card.json HTTP/1.1\r\nHost: mesh\r\n\r\n"
+
+ t.Run("member_is_refused_at_the_gate", func(t *testing.T) {
+ member := newAdmittedTestPeer(t, ctx, s, env.cpPriv, api.RoleNode)
+ if !s.isAdmitted(member.ID()) || s.isAdmittedRouter(member.ID()) {
+ t.Fatalf("member admitted=%v router=%v, want true/false", s.isAdmitted(member.ID()), s.isAdmittedRouter(member.ID()))
+ }
+ before := s.refusedStreamCount(streamScopeNotRouter, api.IngressProtocolID)
+
+ st, err := member.NewStream(ctx, s.host.ID(), api.IngressProtocolID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = st.Reset() }()
+ if _, err := st.Write([]byte(request)); err != nil {
+ t.Fatal(err)
+ }
+ buf := make([]byte, 64)
+ _ = st.SetReadDeadline(time.Now().Add(5 * time.Second))
+ if n, err := st.Read(buf); err == nil {
+ t.Fatalf("ingress protocol answered a non-router member %q; gate must reset stream", buf[:n])
+ }
+ waitForCount(t, func() uint64 {
+ return s.refusedStreamCount(streamScopeNotRouter, api.IngressProtocolID)
+ }, before+1, 5*time.Second)
+ })
+
+ t.Run("router_reaches_the_handler", func(t *testing.T) {
+ router := newAdmittedTestPeer(t, ctx, s, env.cpPriv, api.RoleRouter)
+ if !s.isAdmittedRouter(router.ID()) {
+ t.Fatal("peer admitted with RoleRouter is not recorded as a router")
+ }
+
+ st, err := router.NewStream(ctx, s.host.ID(), api.IngressProtocolID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = st.Close() }()
+ if _, err := st.Write([]byte(request)); err != nil {
+ t.Fatal(err)
+ }
+ _ = st.SetReadDeadline(time.Now().Add(5 * time.Second))
+ resp, err := http.ReadResponse(bufio.NewReader(st), nil)
+ if err != nil {
+ t.Fatalf("read HTTP response from ingress handler: %v", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ if resp.StatusCode != http.StatusUnauthorized {
+ t.Fatalf("status = %d, want %d from handler's own credential check", resp.StatusCode, http.StatusUnauthorized)
+ }
+ })
+
+ t.Run("ban_withdraws_router_standing", func(t *testing.T) {
+ router := newAdmittedTestPeer(t, ctx, s, env.cpPriv, api.RoleRouter)
+ s.banPeer(router.ID(), time.Now().UnixMilli())
+ if s.isAdmitted(router.ID()) || s.isAdmittedRouter(router.ID()) {
+ t.Fatal("banned peer still admitted")
+ }
+ })
+}
+
+type startedTestEnv struct {
+ cpPub ed25519.PublicKey
+ cpPriv ed25519.PrivateKey
+ routerHost host.Host
+ cp *fakeControlPlaneHTTP
+ server *Server
+}
+
+func newStartedTestServer(t *testing.T, ctx context.Context) *startedTestEnv {
+ t.Helper()
+ cpPub, cpPriv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ rh, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = rh.Close() })
+
+ routerBiscuit := mintTestBiscuit(t, cpPriv, rh.ID().String(), api.RoleRouter, time.Now().Add(24*time.Hour))
+ rh.SetStreamHandler(api.AuthProtocolID, func(st network.Stream) {
+ defer func() { _ = st.Close() }()
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ return
+ }
+ reader.ReleaseMsg(msg)
+ reply, _ := proto.Marshal(&api.AuthResponse{Success: true, Biscuit: routerBiscuit})
+ _ = msgio.NewVarintWriter(st).WriteMsg(reply)
+ })
+ rh.SetStreamHandler(api.DirectoryProtocolID, func(st network.Stream) {
+ defer func() { _ = st.Close() }()
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ return
+ }
+ var req api.DirectoryRequest
+ _ = proto.Unmarshal(msg, &req)
+ reader.ReleaseMsg(msg)
+ reply, _ := proto.Marshal(&api.DirectoryResponse{})
+ _ = msgio.NewVarintWriter(st).WriteMsg(reply)
+ })
+
+ var routerAddrs []string
+ for _, a := range rh.Addrs() {
+ routerAddrs = append(routerAddrs, a.String()+"/p2p/"+rh.ID().String())
+ }
+
+ cp := newFakeControlPlaneHTTPWithKeys(t, cpPub, cpPriv, routerAddrs)
+ s := &Server{
+ StateDir: t.TempDir(),
+ ControlPlaneURL: cp.srv.URL,
+ BootstrapToken: "boot-secret",
+ ListenAddrs: []string{"/ip4/127.0.0.1/tcp/0"},
+ AllowInsecure: true,
+ }
+ upSt, err := s.Up(ctx)
+ if err != nil {
+ t.Fatalf("Server.Up: %v", err)
+ }
+ t.Cleanup(func() { _ = s.Close() })
+
+ st := s.Status()
+ if upSt.PeerID == "" || st.PeerID == "" || len(st.AttachedRouters) < 1 {
+ t.Fatalf("unexpected Status after Up: %+v", st)
+ }
+
+ return &startedTestEnv{
+ cpPub: cpPub,
+ cpPriv: cpPriv,
+ routerHost: rh,
+ cp: cp,
+ server: s,
+ }
+}
+
+func newAdmittedTestPeer(t *testing.T, ctx context.Context, s *Server, cpPriv ed25519.PrivateKey, role string) host.Host {
+ t.Helper()
+ h, err := libp2p.New(libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { _ = h.Close() })
+ if err := h.Connect(ctx, peer.AddrInfo{ID: s.host.ID(), Addrs: s.host.Addrs()}); err != nil {
+ t.Fatal(err)
+ }
+ st, err := h.NewStream(ctx, s.host.ID(), api.AuthProtocolID)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = st.Close() }()
+ frame, err := proto.Marshal(&api.AuthFrame{
+ Biscuit: mintTestBiscuit(t, cpPriv, h.ID().String(), role, time.Now().Add(time.Hour)),
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := msgio.NewVarintWriter(st).WriteMsg(frame); err != nil {
+ t.Fatal(err)
+ }
+ reply, err := msgio.NewVarintReaderSize(st, 64*1024).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())
+ }
+ return h
+}
+
+func waitForCount(t *testing.T, get func() uint64, want uint64, within time.Duration) {
+ t.Helper()
+ deadline := time.Now().Add(within)
+ var got uint64
+ for time.Now().Before(deadline) {
+ got = get()
+ if got >= want {
+ return
+ }
+ time.Sleep(20 * time.Millisecond)
+ }
+ t.Fatalf("counter = %d, want >= %d", got, want)
+}
diff --git a/sdk/meshnet/routers.go b/sdk/meshnet/routers.go
new file mode 100644
index 00000000..fd0f257c
--- /dev/null
+++ b/sdk/meshnet/routers.go
@@ -0,0 +1,1232 @@
+// 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 meshnet
+
+import (
+ "bytes"
+ "context"
+ "crypto/ed25519"
+ "encoding/base64"
+ "encoding/hex"
+ "errors"
+ "fmt"
+ "math/rand/v2"
+ "net"
+ "net/http"
+ "slices"
+ "sort"
+ "strings"
+ "time"
+
+ "github.com/eclipse-biscuit/biscuit-go/v2"
+ "github.com/google/agentmesh/api"
+ cpclient "github.com/google/agentmesh/internal/controlplane/client"
+ "github.com/google/agentmesh/internal/identity"
+ pubsub "github.com/libp2p/go-libp2p-pubsub"
+ "github.com/libp2p/go-libp2p/core/network"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/libp2p/go-libp2p/core/peerstore"
+ "github.com/libp2p/go-msgio"
+ "github.com/multiformats/go-multiaddr"
+ madns "github.com/multiformats/go-multiaddr-dns"
+ "google.golang.org/protobuf/proto"
+)
+
+const (
+ routerTag = "agentmesh-router"
+ autorelayTag = "autorelay"
+
+ routerConnectTimeout = 10 * time.Second
+ routerRedialDelay = 2 * time.Second
+ routerRedialAttempts = 3
+ routerAuthAttempts = 4
+ controlPlaneSyncDefault = 30 * time.Second
+ eventFreshnessThreshold = 5 * time.Minute
+ keyGracePeriod = 24 * time.Hour
+ reEnrollMinInterval = time.Minute
+)
+
+var (
+ errFatalAuth = errors.New("fatal router auth failure")
+ readmitRetryDelays = []time.Duration{500 * time.Millisecond, time.Second, 2 * time.Second}
+)
+
+type routerCandidate struct {
+ peer.AddrInfo
+ Labels map[string]string
+ Connections int
+ ConnectionLimit int
+ IngressURL string
+}
+
+func (c routerCandidate) loadRatio() float64 {
+ if c.ConnectionLimit <= 0 {
+ return 0.5
+ }
+ return float64(c.Connections) / float64(c.ConnectionLimit)
+}
+
+func candidatesFromInfo(ctx context.Context, info *api.ControlPlaneInfoResponse) []routerCandidate {
+ if len(info.GetRouters()) == 0 {
+ return candidatesFromAddrs(ctx, parseMultiaddrs(info.GetRouterAddresses()))
+ }
+ var out []routerCandidate
+ seen := map[peer.ID]bool{}
+ for _, r := range info.GetRouters() {
+ id, err := peer.Decode(r.GetPeerId())
+ if err != nil || seen[id] {
+ continue
+ }
+ for _, pi := range routerPeers(ctx, parseMultiaddrs(r.GetAddresses())) {
+ if pi.ID != id {
+ continue
+ }
+ seen[id] = true
+ out = append(out, routerCandidate{
+ AddrInfo: pi,
+ Labels: r.GetLabels(),
+ Connections: int(r.GetConnections()),
+ ConnectionLimit: int(r.GetConnectionLimit()),
+ IngressURL: r.GetIngressUrl(),
+ })
+ }
+ }
+ return out
+}
+
+func candidatesFromAddrs(ctx context.Context, addrs []multiaddr.Multiaddr) []routerCandidate {
+ peers := routerPeers(ctx, addrs)
+ out := make([]routerCandidate, 0, len(peers))
+ for _, pi := range peers {
+ out = append(out, routerCandidate{AddrInfo: pi})
+ }
+ return out
+}
+
+func parseMultiaddrs(addrs []string) []multiaddr.Multiaddr {
+ out := make([]multiaddr.Multiaddr, 0, len(addrs))
+ for _, raw := range addrs {
+ ma, err := multiaddr.NewMultiaddr(raw)
+ if err != nil {
+ continue
+ }
+ out = append(out, ma)
+ }
+ return out
+}
+
+func stripP2pFromDnsaddr(addr multiaddr.Multiaddr) multiaddr.Multiaddr {
+ if _, err := addr.ValueForProtocol(multiaddr.P_DNSADDR); err != nil {
+ return addr
+ }
+ parts := multiaddr.Split(addr)
+ var components []multiaddr.Multiaddrer
+ for _, p := range parts {
+ if _, err := p.ValueForProtocol(multiaddr.P_P2P); err != nil {
+ components = append(components, multiaddr.Multiaddr{p})
+ }
+ }
+ if len(components) > 0 {
+ return multiaddr.Join(components...)
+ }
+ return addr
+}
+
+func resolveAddrIfNeeded(ctx context.Context, addr multiaddr.Multiaddr) ([]multiaddr.Multiaddr, error) {
+ if _, err := addr.ValueForProtocol(multiaddr.P_DNSADDR); err != nil {
+ return []multiaddr.Multiaddr{addr}, nil
+ }
+ return madns.DefaultResolver.Resolve(ctx, stripP2pFromDnsaddr(addr))
+}
+
+func routerPeers(ctx context.Context, addrs []multiaddr.Multiaddr) []peer.AddrInfo {
+ var order []peer.ID
+ byPeer := map[peer.ID]*peer.AddrInfo{}
+ for _, addr := range addrs {
+ resolved, err := resolveAddrIfNeeded(ctx, addr)
+ if err != nil {
+ resolved = []multiaddr.Multiaddr{addr}
+ }
+ for _, r := range resolved {
+ info, err := peer.AddrInfoFromP2pAddr(r)
+ if err != nil || info.ID == "" {
+ continue
+ }
+ known, seen := byPeer[info.ID]
+ if !seen {
+ byPeer[info.ID] = info
+ order = append(order, info.ID)
+ continue
+ }
+ for _, a := range info.Addrs {
+ if !slices.ContainsFunc(known.Addrs, a.Equal) {
+ known.Addrs = append(known.Addrs, a)
+ }
+ }
+ }
+ }
+ out := make([]peer.AddrInfo, 0, len(order))
+ for _, id := range order {
+ out = append(out, *byPeer[id])
+ }
+ return out
+}
+
+func selectRouters(cands []routerCandidate, k int, selector, prefer map[string]string, exclude map[peer.ID]bool) ([]peer.AddrInfo, int) {
+ type scored struct {
+ routerCandidate
+ preferred int
+ load float64
+ }
+ var eligible []scored
+ matched := 0
+ for _, c := range cands {
+ if len(selector) > 0 && !api.LabelsSatisfy(selector, c.Labels) {
+ continue
+ }
+ matched++
+ if exclude[c.ID] {
+ continue
+ }
+ preferred := 0
+ for key, val := range prefer {
+ if c.Labels[key] == val {
+ preferred++
+ }
+ }
+ load := c.loadRatio() + rand.Float64()*0.05
+ eligible = append(eligible, scored{c, preferred, load})
+ }
+ sort.SliceStable(eligible, func(i, j int) bool {
+ if eligible[i].preferred != eligible[j].preferred {
+ return eligible[i].preferred > eligible[j].preferred
+ }
+ return eligible[i].load < eligible[j].load
+ })
+ if k > len(eligible) {
+ k = len(eligible)
+ }
+ out := make([]peer.AddrInfo, 0, k)
+ for _, item := range eligible[:k] {
+ out = append(out, item.AddrInfo)
+ }
+ return out, matched
+}
+
+func (s *Server) setRouterCatalog(cands []routerCandidate) {
+ s.mu.Lock()
+ s.routerCatalog = cands
+ s.mu.Unlock()
+ if s.host != nil {
+ for _, c := range cands {
+ s.host.Peerstore().AddAddrs(c.ID, c.Addrs, peerstore.PermanentAddrTTL)
+ }
+ }
+}
+
+func (s *Server) routerCandidates() []routerCandidate {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ return slices.Clone(s.routerCatalog)
+}
+
+func (s *Server) isCatalogRouter(p peer.ID) bool {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ for _, c := range s.routerCatalog {
+ if c.ID == p {
+ return true
+ }
+ }
+ return false
+}
+
+func (s *Server) routerIngressURLs() []string {
+ cands := s.routerCandidates()
+ seen := make(map[string]bool, len(cands))
+ var out []string
+ for _, c := range cands {
+ u := strings.TrimSuffix(strings.TrimSpace(c.IngressURL), "/")
+ if u == "" || seen[u] {
+ continue
+ }
+ seen[u] = true
+ out = append(out, u)
+ }
+ sort.Strings(out)
+ return out
+}
+
+func (s *Server) wantRouters() int {
+ target := s.Routers
+ if target <= 0 {
+ target = 2
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ matched := 0
+ for _, c := range s.routerCatalog {
+ if len(s.RouterSelector) == 0 || api.LabelsSatisfy(s.RouterSelector, c.Labels) {
+ matched++
+ }
+ }
+ return min(target, matched)
+}
+
+func (s *Server) attachedRouters() []peer.ID {
+ if s.host == nil {
+ return nil
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ var out []peer.ID
+ for pid := range s.attached {
+ if s.authenticatedRouters[pid] && s.host.Network().Connectedness(pid) == network.Connected {
+ out = append(out, pid)
+ }
+ }
+ return out
+}
+
+func (s *Server) authenticatedRouterIDs() []peer.ID {
+ if s.host == nil {
+ return nil
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ out := make([]peer.ID, 0, len(s.authenticatedRouters))
+ for pid := range s.authenticatedRouters {
+ if s.host.Network().Connectedness(pid) == network.Connected {
+ out = append(out, pid)
+ }
+ }
+ return out
+}
+
+func (s *Server) isAuthenticatedAndConnected(router peer.ID) bool {
+ if s.host == nil {
+ return false
+ }
+ s.mu.Lock()
+ authed := s.authenticatedRouters[router]
+ s.mu.Unlock()
+ return authed && s.host.Network().Connectedness(router) == network.Connected
+}
+
+func (s *Server) isAttached(router peer.ID) bool {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ return s.attached[router]
+}
+
+func (s *Server) attach(router peer.ID) {
+ s.mu.Lock()
+ if s.attached == nil {
+ s.attached = map[peer.ID]bool{}
+ }
+ s.attached[router] = true
+ s.mu.Unlock()
+ if s.connMgr != nil {
+ s.connMgr.Protect(router, routerTag)
+ }
+ s.refreshRelays()
+ s.triggerReprovide()
+}
+
+func (s *Server) detach(router peer.ID) {
+ s.mu.Lock()
+ delete(s.attached, router)
+ s.mu.Unlock()
+ if s.connMgr != nil {
+ s.connMgr.Unprotect(router, routerTag)
+ }
+ s.refreshRelays()
+}
+
+func (s *Server) refreshRelays() {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ var relays []peer.AddrInfo
+ for _, c := range s.routerCatalog {
+ if s.attached[c.ID] {
+ relays = append(relays, c.AddrInfo)
+ }
+ }
+ s.currentRelays = relays
+}
+
+func (s *Server) shun(router peer.ID, d time.Duration) {
+ s.mu.Lock()
+ if s.shunned == nil {
+ s.shunned = map[peer.ID]time.Time{}
+ }
+ s.shunned[router] = time.Now().Add(d)
+ s.mu.Unlock()
+}
+
+func (s *Server) pickRouters(k int) []peer.AddrInfo {
+ cands := s.routerCandidates()
+ s.mu.Lock()
+ exclude := make(map[peer.ID]bool, len(s.attached)+len(s.shunned))
+ for pid := range s.attached {
+ exclude[pid] = true
+ }
+ now := time.Now()
+ for pid, until := range s.shunned {
+ if now.Before(until) {
+ exclude[pid] = true
+ } else {
+ delete(s.shunned, pid)
+ }
+ }
+ s.mu.Unlock()
+
+ picked, matched := selectRouters(cands, k, s.RouterSelector, s.RouterPrefer, exclude)
+ if matched == 0 && len(cands) > 0 && len(s.RouterSelector) > 0 {
+ s.log().Warn("no router attests RouterSelector", "selector", s.RouterSelector)
+ }
+ return picked
+}
+
+func (s *Server) admitByRouters(ctx context.Context) error {
+ if len(s.routerCandidates()) == 0 {
+ return errors.New("meshnet: control plane lists no routers")
+ }
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return errors.New("meshnet: missing member biscuit")
+ }
+ delay := routerRedialDelay
+ for attempt := 1; ; attempt++ {
+ if attempt > 1 {
+ _ = s.syncMeshInfo(ctx)
+ }
+ targets := s.pickRouters(s.wantRouters())
+ var fatal error
+ if len(targets) > 0 {
+ results := s.dialAndAttach(ctx, targets, biscuitBytes)
+ for range targets {
+ err := <-results
+ if err == nil {
+ return nil
+ }
+ if errors.Is(err, errFatalAuth) {
+ fatal = err
+ }
+ }
+ }
+ if fatal != nil {
+ return fatal
+ }
+ if attempt >= routerAuthAttempts {
+ return errors.New("meshnet: failed to authenticate with any router")
+ }
+ s.log().Warn("no router admitted member; retrying", "attempt", attempt, "delay", delay)
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ case <-time.After(delay):
+ }
+ delay *= 2
+ }
+}
+
+func (s *Server) dialAndAttach(ctx context.Context, routers []peer.AddrInfo, biscuitBytes []byte) <-chan error {
+ results := make(chan error, len(routers))
+ for _, r := range routers {
+ go func() {
+ err := s.authRouter(ctx, r, biscuitBytes)
+ if err != nil {
+ s.log().Warn("failed to connect and authenticate with router", "router_peer_id", r.ID.String(), "error", err)
+ } else {
+ s.attach(r.ID)
+ }
+ results <- err
+ }()
+ }
+ return results
+}
+
+func (s *Server) topUpRouters(ctx context.Context) {
+ have := len(s.attachedRouters())
+ want := s.wantRouters()
+ if have >= want {
+ return
+ }
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return
+ }
+ targets := s.pickRouters(want - have)
+ if len(targets) == 0 {
+ return
+ }
+ results := s.dialAndAttach(ctx, targets, biscuitBytes)
+ for range targets {
+ <-results
+ }
+}
+
+func (s *Server) authRouter(ctx context.Context, router peer.AddrInfo, biscuitBytes []byte) error {
+ if s.isAuthenticatedAndConnected(router.ID) {
+ return nil
+ }
+ s.mu.Lock()
+ if done, inFlight := s.handshaking[router.ID]; inFlight {
+ s.mu.Unlock()
+ select {
+ case <-done:
+ case <-ctx.Done():
+ return ctx.Err()
+ }
+ if s.isAuthenticatedAndConnected(router.ID) {
+ return nil
+ }
+ return fmt.Errorf("router %s: concurrent handshake did not succeed", router.ID)
+ }
+ if s.handshaking == nil {
+ s.handshaking = map[peer.ID]chan struct{}{}
+ }
+ done := make(chan struct{})
+ s.handshaking[router.ID] = done
+ s.mu.Unlock()
+ defer func() {
+ s.mu.Lock()
+ delete(s.handshaking, router.ID)
+ s.mu.Unlock()
+ close(done)
+ }()
+
+ routerCtx, cancel := context.WithTimeout(ctx, routerConnectTimeout)
+ defer cancel()
+ if len(router.Addrs) == 0 && s.host != nil {
+ router.Addrs = s.host.Peerstore().Addrs(router.ID)
+ }
+ if err := s.host.Connect(routerCtx, router); err != nil {
+ if strings.Contains(err.Error(), "peer id mismatch") {
+ return fmt.Errorf("%w: %w", errFatalAuth, err)
+ }
+ return fmt.Errorf("connect to router %s: %w", router.ID, err)
+ }
+ if err := s.authenticateRouterSession(routerCtx, router.ID, biscuitBytes); err != nil {
+ return fmt.Errorf("router %s: %w", router.ID, err)
+ }
+ s.authOnce.Do(func() {
+ close(s.authSuccess)
+ })
+ return nil
+}
+
+func (s *Server) authenticateRouterSession(ctx context.Context, router peer.ID, biscuitBytes []byte) error {
+ st, err := s.host.NewStream(ctx, router, api.AuthProtocolID)
+ if err != nil {
+ return fmt.Errorf("open auth stream: %w", err)
+ }
+ _ = st.SetDeadline(time.Now().Add(5 * time.Second))
+ if err := s.performRouterAuthHandshake(st, biscuitBytes, router); err != nil {
+ _ = st.Reset()
+ return err
+ }
+ _ = st.Close()
+
+ s.mu.Lock()
+ if st.Conn().IsClosed() {
+ s.mu.Unlock()
+ return fmt.Errorf("router %s closed connection immediately after admission", router)
+ }
+ if s.authenticatedRouters == nil {
+ s.authenticatedRouters = map[peer.ID]bool{}
+ }
+ s.authenticatedRouters[router] = true
+ s.mu.Unlock()
+ s.log().Info("authenticated with router", "router_peer_id", router.String())
+ return nil
+}
+
+func (s *Server) performRouterAuthHandshake(st network.Stream, biscuitBytes []byte, expectedRouter peer.ID) error {
+ data, err := proto.Marshal(&api.AuthFrame{Biscuit: biscuitBytes})
+ if err != nil {
+ return err
+ }
+ if err := msgio.NewVarintWriter(st).WriteMsg(data); err != nil {
+ return fmt.Errorf("write auth frame: %w", err)
+ }
+ reader := msgio.NewVarintReaderSize(st, 64*1024)
+ respMsg, err := reader.ReadMsg()
+ if err != nil {
+ return fmt.Errorf("read auth response: %w", err)
+ }
+ defer reader.ReleaseMsg(respMsg)
+
+ var resp api.AuthResponse
+ if err := proto.Unmarshal(respMsg, &resp); err != nil {
+ return fmt.Errorf("decode auth response: %w", err)
+ }
+ if !resp.GetSuccess() {
+ return fmt.Errorf("%w: %s", errFatalAuth, resp.GetError())
+ }
+ if len(resp.GetBiscuit()) == 0 {
+ return fmt.Errorf("%w: router returned empty biscuit", errFatalAuth)
+ }
+ trusted := s.trustedPublicKeys()
+ if len(trusted) == 0 {
+ return fmt.Errorf("%w: no trusted control plane keys loaded", errFatalAuth)
+ }
+ b, verifyingKey, err := identity.VerifyBiscuitAndGetKey(resp.GetBiscuit(), expectedRouter, trusted, s.biscuitTimeout())
+ if err != nil {
+ return fmt.Errorf("%w: verify router biscuit: %w", errFatalAuth, err)
+ }
+ if err := identity.RequireRole(b, verifyingKey, api.RoleRouter, s.biscuitTimeout()); err != nil {
+ return fmt.Errorf("%w: peer lacks router role: %w", errFatalAuth, err)
+ }
+ return nil
+}
+
+func (s *Server) readmitRouters(ctx context.Context) {
+ if s.host == nil {
+ return
+ }
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return
+ }
+ for _, router := range s.authenticatedRouterIDs() {
+ s.readmitRouter(ctx, router, biscuitBytes)
+ }
+}
+
+func (s *Server) readmitRouter(ctx context.Context, router peer.ID, biscuitBytes []byte) {
+ for attempt := 0; ; attempt++ {
+ rCtx, cancel := context.WithTimeout(ctx, routerConnectTimeout)
+ err := s.authenticateRouterSession(rCtx, router, biscuitBytes)
+ cancel()
+ if err == nil {
+ return
+ }
+ if attempt >= len(readmitRetryDelays) {
+ s.log().Warn("router did not accept refreshed credential; clearing session", "router_peer_id", router.String(), "error", err)
+ s.mu.Lock()
+ delete(s.authenticatedRouters, router)
+ s.mu.Unlock()
+ return
+ }
+ select {
+ case <-ctx.Done():
+ return
+ case <-time.After(readmitRetryDelays[attempt]):
+ }
+ }
+}
+
+func (s *Server) redialRouter(ctx context.Context, router peer.ID) {
+ s.mu.Lock()
+ if s.redialing == nil {
+ s.redialing = map[peer.ID]bool{}
+ }
+ if s.redialing[router] {
+ s.mu.Unlock()
+ return
+ }
+ s.redialing[router] = true
+ s.mu.Unlock()
+
+ go func() {
+ if s.redialUntilUp(ctx, router) {
+ return
+ }
+ s.mu.Lock()
+ delete(s.redialing, router)
+ s.mu.Unlock()
+ s.topUpRouters(ctx)
+ }()
+}
+
+func (s *Server) redialUntilUp(ctx context.Context, router peer.ID) bool {
+ biscuitBytes := s.currentBiscuit()
+ if len(biscuitBytes) == 0 {
+ return false
+ }
+ delay := routerRedialDelay
+ for attempt := 1; attempt <= routerRedialAttempts; attempt++ {
+ select {
+ case <-ctx.Done():
+ return false
+ case <-time.After(delay):
+ }
+ if s.releaseRedialIfUp(router) {
+ return true
+ }
+ if !s.isAttached(router) {
+ return false
+ }
+ addrs := s.host.Peerstore().Addrs(router)
+ if len(addrs) == 0 {
+ s.detach(router)
+ return false
+ }
+ err := s.authRouter(ctx, peer.AddrInfo{ID: router, Addrs: addrs}, biscuitBytes)
+ if err == nil && s.releaseRedialIfUp(router) {
+ s.triggerReprovide()
+ return true
+ }
+ if errors.Is(err, errFatalAuth) {
+ s.detach(router)
+ s.shun(router, defaultShunDuration)
+ return false
+ }
+ delay *= 2
+ }
+ s.detach(router)
+ s.shun(router, defaultShunDuration)
+ return false
+}
+
+func (s *Server) releaseRedialIfUp(router peer.ID) bool {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if !s.authenticatedRouters[router] || s.host.Network().Connectedness(router) != network.Connected {
+ return false
+ }
+ delete(s.redialing, router)
+ return true
+}
+
+func (s *Server) announceFilter(addrs []multiaddr.Multiaddr) []multiaddr.Multiaddr {
+ if !s.AllowInsecure {
+ var filtered []multiaddr.Multiaddr
+ for _, addr := range addrs {
+ if hasCircuit(addr) {
+ filtered = append(filtered, addr)
+ continue
+ }
+ if isLoopbackOrLinkLocal(addr) {
+ continue
+ }
+ filtered = append(filtered, addr)
+ }
+ addrs = filtered
+ }
+ extra := s.reservedCircuitAddrs(addrs)
+ if len(extra) == 0 {
+ return addrs
+ }
+ out := make([]multiaddr.Multiaddr, 0, len(addrs)+len(extra))
+ out = append(out, addrs...)
+ return append(out, extra...)
+}
+
+func (s *Server) reservedCircuitAddrs(have []multiaddr.Multiaddr) []multiaddr.Multiaddr {
+ if s.connMgr == nil {
+ return nil
+ }
+ seen := make(map[string]bool, len(have))
+ for _, a := range have {
+ seen[a.String()] = true
+ }
+ var out []multiaddr.Multiaddr
+ for _, c := range s.routerCandidates() {
+ if !s.connMgr.IsProtected(c.ID, autorelayTag) {
+ continue
+ }
+ circuit := multiaddr.StringCast("/p2p/" + c.ID.String() + "/p2p-circuit")
+ for _, addr := range c.Addrs {
+ full := addr.Encapsulate(circuit)
+ if !seen[full.String()] {
+ seen[full.String()] = true
+ out = append(out, full)
+ }
+ }
+ }
+ return out
+}
+
+func isLoopbackOrLinkLocal(addr multiaddr.Multiaddr) bool {
+ for _, p := range addr.Protocols() {
+ if p.Code != multiaddr.P_IP4 && p.Code != multiaddr.P_IP6 {
+ continue
+ }
+ val, err := addr.ValueForProtocol(p.Code)
+ if err != nil {
+ continue
+ }
+ ip := net.ParseIP(val)
+ if ip != nil && (ip.IsLoopback() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()) {
+ return true
+ }
+ }
+ return false
+}
+
+func isPrivateIP(addr multiaddr.Multiaddr) bool {
+ for _, p := range addr.Protocols() {
+ if p.Code != multiaddr.P_IP4 && p.Code != multiaddr.P_IP6 {
+ continue
+ }
+ val, err := addr.ValueForProtocol(p.Code)
+ if err != nil {
+ continue
+ }
+ ip := net.ParseIP(val)
+ if ip != nil && ip.IsPrivate() {
+ return true
+ }
+ }
+ return false
+}
+
+func hasCircuit(addr multiaddr.Multiaddr) bool {
+ for _, p := range addr.Protocols() {
+ if p.Code == multiaddr.P_CIRCUIT {
+ return true
+ }
+ }
+ return false
+}
+
+func tcpFirstDialRanker(addrs []multiaddr.Multiaddr) []network.AddrDelay {
+ out := make([]network.AddrDelay, 0, len(addrs))
+ hasDirectTCP := false
+ for _, a := range addrs {
+ if !hasCircuit(a) {
+ if _, err := a.ValueForProtocol(multiaddr.P_TCP); err == nil {
+ hasDirectTCP = true
+ break
+ }
+ }
+ }
+ for _, a := range addrs {
+ var delay time.Duration
+ switch {
+ case hasCircuit(a):
+ delay = 250 * time.Millisecond
+ case hasDirectTCP:
+ if _, err := a.ValueForProtocol(multiaddr.P_QUIC_V1); err == nil {
+ delay = 50 * time.Millisecond
+ }
+ }
+ out = append(out, network.AddrDelay{Addr: a, Delay: delay})
+ }
+ return out
+}
+
+// Control-plane pull sync & GossipSub events.
+
+func (s *Server) syncControlPlane(ctx context.Context) error {
+ err := s.syncControlPlaneOnce(ctx)
+ if err != nil && controlPlaneForgotUs(err) && s.recoverEnrollment(ctx) {
+ return s.syncControlPlaneOnce(ctx)
+ }
+ return err
+}
+
+func controlPlaneForgotUs(err error) bool {
+ var statusErr *cpclient.StatusError
+ return errors.As(err, &statusErr) && statusErr.Code == http.StatusUnauthorized
+}
+
+func (s *Server) recoverEnrollment(ctx context.Context) bool {
+ s.reenrollMu.Lock()
+ defer s.reenrollMu.Unlock()
+ if time.Since(s.lastReenroll) < reEnrollMinInterval {
+ return false
+ }
+ kind, tok, err := s.resolveJoinSecret(ctx)
+ if err != nil || kind != joinSecretBootstrap {
+ return false
+ }
+ s.lastReenroll = time.Now()
+ if err := s.enrollBootstrap(ctx, tok, true); err != nil {
+ s.log().Warn("control plane re-enrollment failed", "error", err)
+ return false
+ }
+ return true
+}
+
+func (s *Server) syncControlPlaneOnce(ctx context.Context) error {
+ var errs []error
+ if err := s.syncTrustedKeys(ctx); err != nil {
+ errs = append(errs, fmt.Errorf("keys: %w", err))
+ } else if s.identityPredatesRotation() {
+ if err := s.Refresh(ctx); err != nil {
+ errs = append(errs, fmt.Errorf("refresh after key rotation: %w", err))
+ }
+ }
+ if err := s.syncMeshInfo(ctx); err != nil {
+ errs = append(errs, fmt.Errorf("info: %w", err))
+ }
+ if err := s.syncMeshPolicy(ctx); err != nil {
+ errs = append(errs, fmt.Errorf("policy: %w", err))
+ }
+ if err := s.syncRevocations(ctx); err != nil {
+ errs = append(errs, fmt.Errorf("revocations: %w", err))
+ }
+ return errors.Join(errs...)
+}
+
+func (s *Server) syncTrustedKeys(ctx context.Context) error {
+ s.keysMu.RLock()
+ existing := slices.Clone(s.trustedKeys)
+ trustedPubs := s.publicKeysLocked()
+ s.keysMu.RUnlock()
+ if len(trustedPubs) == 0 {
+ return errors.New("no trusted control plane keys loaded")
+ }
+
+ keys, err := s.cpClient().FetchKeys(ctx, trustedPubs)
+ if err != nil {
+ return err
+ }
+ if len(keys) == 0 {
+ return errors.New("/keys returned no keys")
+ }
+
+ now := time.Now()
+ merged := make([]trustedKey, 0, len(keys))
+ for _, k := range keys {
+ recv := now
+ for _, prev := range existing {
+ if bytes.Equal(prev.key, k) {
+ recv = prev.receivedAt
+ break
+ }
+ }
+ merged = append(merged, trustedKey{key: slices.Clone(k), receivedAt: recv})
+ }
+ merged = pruneTrustedKeys(merged, now, keyGracePeriod)
+
+ s.keysMu.Lock()
+ s.trustedKeys = merged
+ s.keysMu.Unlock()
+ _ = s.persistState()
+ return nil
+}
+
+func pruneTrustedKeys(keys []trustedKey, now time.Time, grace time.Duration) []trustedKey {
+ if len(keys) == 0 {
+ return keys
+ }
+ newest := 0
+ for i, tk := range keys {
+ if tk.receivedAt.After(keys[newest].receivedAt) {
+ newest = i
+ }
+ }
+ out := make([]trustedKey, 0, len(keys))
+ for i, tk := range keys {
+ if i == newest || now.Sub(tk.receivedAt) <= grace {
+ out = append(out, tk)
+ }
+ }
+ return out
+}
+
+func (s *Server) identityPredatesRotation() bool {
+ if len(s.currentBiscuit()) == 0 {
+ return false
+ }
+ s.keysMu.RLock()
+ defer s.keysMu.RUnlock()
+ if len(s.issuedUnderKeys) == 0 {
+ return false
+ }
+ for _, tk := range s.trustedKeys {
+ found := false
+ for _, issued := range s.issuedUnderKeys {
+ if issued.Equal(tk.key) {
+ found = true
+ break
+ }
+ }
+ if !found {
+ return true
+ }
+ }
+ return false
+}
+
+func (s *Server) syncMeshInfo(ctx context.Context) error {
+ fetchedAt := time.Now()
+ info, err := s.cpClient().FetchInfo(ctx)
+ if err != nil {
+ return err
+ }
+ if len(info.GetRouterAddresses()) > 0 || len(info.GetRouters()) > 0 {
+ if len(info.GetRouterAddresses()) > 0 {
+ s.credMu.Lock()
+ s.storedRouterAddrs = slices.Clone(info.GetRouterAddresses())
+ s.credMu.Unlock()
+ _ = s.persistState()
+ }
+ s.setRouterCatalog(candidatesFromInfo(ctx, info))
+ }
+ settings := api.DirectorySettingsFrom(info.GetDirectory())
+ s.mu.Lock()
+ s.dirSettings = settings
+ s.mu.Unlock()
+ s.reconcileBannedPeers(info.GetBannedPeerIds(), fetchedAt)
+ return nil
+}
+
+func (s *Server) syncMeshPolicy(ctx context.Context) error {
+ tok := s.currentBiscuit()
+ if len(tok) == 0 {
+ return nil
+ }
+ resp, err := s.cpClient().FetchPolicy(ctx, tok)
+ if err != nil {
+ return err
+ }
+ if len(resp.ProtoReflect().GetUnknown()) > 0 {
+ return fmt.Errorf("control plane %s predates datalog_rules", s.cpURL)
+ }
+ rules, err := api.ParseDatalogRules(resp.GetDatalogRules())
+ if err != nil {
+ return fmt.Errorf("parse mesh policy datalog: %w", err)
+ }
+ s.policyMu.Lock()
+ changed := s.meshPolicyTexts != nil && !slices.Equal(s.meshPolicyTexts, resp.GetDatalogRules())
+ s.meshPolicyRules = rules
+ s.meshPolicyTexts = slices.Clone(resp.GetDatalogRules())
+ s.policyMu.Unlock()
+
+ if changed {
+ s.triggerReprovide()
+ }
+ return nil
+}
+
+func (s *Server) syncRevocations(ctx context.Context) error {
+ tok := s.currentBiscuit()
+ if len(tok) == 0 {
+ return nil
+ }
+ fetchedAt := time.Now()
+ resp, err := s.cpClient().FetchRevocations(ctx, tok)
+ if errors.Is(err, cpclient.ErrNotFound) {
+ return nil
+ }
+ if err != nil {
+ return err
+ }
+ expiry := fetchedAt.Add(24 * time.Hour)
+ for _, revID := range resp.GetRevocationIds() {
+ s.revokeBiscuitID(revID, expiry)
+ }
+ if len(resp.GetBannedPeerIds()) > 0 {
+ s.reconcileBannedPeers(resp.GetBannedPeerIds(), fetchedAt)
+ }
+ return nil
+}
+
+func (s *Server) startControlPlaneSyncLoop(ctx context.Context) {
+ interval := s.syncInterval
+ if interval <= 0 {
+ interval = controlPlaneSyncDefault
+ }
+ go func() {
+ for {
+ jitter := time.Duration(rand.Int64N(int64(interval/5) + 1))
+ timer := time.NewTimer(interval + jitter)
+ select {
+ case <-ctx.Done():
+ timer.Stop()
+ return
+ case <-timer.C:
+ case <-s.syncTrigger:
+ timer.Stop()
+ }
+ if err := s.syncControlPlane(ctx); err != nil && ctx.Err() == nil {
+ s.log().Warn("control plane sync completed with errors", "error", err)
+ }
+ s.topUpRouters(ctx)
+ }
+ }()
+}
+
+func (s *Server) triggerControlPlaneSync() {
+ select {
+ case s.syncTrigger <- struct{}{}:
+ default:
+ }
+}
+
+func (s *Server) reconcileBannedPeers(peerIDs []string, fetchedAt time.Time) {
+ if s.revokedPeers == nil {
+ return
+ }
+ banned := make(map[string]peer.ID, len(peerIDs))
+ for _, id := range peerIDs {
+ p, err := peer.Decode(id)
+ if err != nil {
+ continue
+ }
+ banned[p.String()] = p
+ }
+ fetchedAtMs := fetchedAt.UnixMilli()
+ for _, key := range s.revokedPeers.Keys() {
+ if _, still := banned[key]; still {
+ continue
+ }
+ if bannedAt, ok := s.revokedPeers.Peek(key); ok && bannedAt >= fetchedAtMs {
+ continue
+ }
+ s.revokedPeers.Remove(key)
+ }
+ for key, p := range banned {
+ if s.revokedPeers.Contains(key) {
+ continue
+ }
+ s.banPeer(p, fetchedAtMs)
+ }
+}
+
+func (s *Server) banPeer(p peer.ID, bannedAtMs int64) {
+ if s.revokedPeers != nil {
+ s.revokedPeers.Add(p.String(), bannedAtMs)
+ }
+ s.forgetAdmission(p)
+ if s.host != nil {
+ _ = s.host.Network().ClosePeer(p)
+ }
+ s.log().Info("banned peer evicted", "peer_id", p.String())
+}
+
+func (s *Server) isPeerBanned(p peer.ID) bool {
+ return s.revokedPeers != nil && s.revokedPeers.Contains(p.String())
+}
+
+func (s *Server) revokeBiscuitID(revocationID string, expiry time.Time) {
+ if revocationID == "" || s.revokedTokens == nil {
+ return
+ }
+ if expiry.IsZero() {
+ expiry = time.Now().Add(api.BiscuitTokenTTL)
+ }
+ s.revokedTokens.Add(revocationID, expiry)
+ if raw, err := hex.DecodeString(revocationID); err == nil && len(raw) > 0 {
+ s.revokedTokens.Add(base64.RawURLEncoding.EncodeToString(raw), expiry)
+ }
+}
+
+func (s *Server) isBiscuitRevoked(b *biscuit.Biscuit) bool {
+ if s.revokedTokens == nil || b == nil {
+ return false
+ }
+ now := time.Now()
+ for _, id := range b.RevocationIds() {
+ key := base64.RawURLEncoding.EncodeToString(id)
+ if exp, ok := s.revokedTokens.Get(key); ok {
+ if now.Before(exp) {
+ return true
+ }
+ s.revokedTokens.Remove(key)
+ }
+ }
+ return false
+}
+
+func (s *Server) validateMeshEvent(_ context.Context, from peer.ID, msg *pubsub.Message) pubsub.ValidationResult {
+ var evt api.MeshEvent
+ if err := proto.Unmarshal(msg.Data, &evt); err != nil {
+ s.log().Warn("rejecting undecodable gossip event", "peer_id", from.String())
+ return pubsub.ValidationReject
+ }
+ if !s.verifyEventSignature(&evt) {
+ s.log().Warn("rejecting gossip event with invalid signature", "peer_id", from.String())
+ return pubsub.ValidationReject
+ }
+ if evt.GetEventTime() == nil {
+ return pubsub.ValidationReject
+ }
+ t := evt.GetEventTime().AsTime()
+ if time.Since(t) > eventFreshnessThreshold || time.Until(t) > eventFreshnessThreshold {
+ return pubsub.ValidationIgnore
+ }
+ return pubsub.ValidationAccept
+}
+
+func (s *Server) verifyEventSignature(evt *api.MeshEvent) bool {
+ cloned := proto.Clone(evt).(*api.MeshEvent)
+ sig := cloned.Signature
+ cloned.Signature = nil
+ data, err := proto.MarshalOptions{Deterministic: true}.Marshal(cloned)
+ if err != nil {
+ return false
+ }
+ for _, k := range s.trustedPublicKeys() {
+ if len(k) == ed25519.PublicKeySize && ed25519.Verify(k, data, sig) {
+ return true
+ }
+ }
+ return false
+}
+
+func (s *Server) listenForControlPlaneEvents(ctx context.Context) {
+ if s.pubsub == nil {
+ return
+ }
+ topic, err := s.pubsub.Join(api.GossipEvents)
+ if err != nil {
+ return
+ }
+ defer func() { _ = topic.Close() }()
+
+ sub, err := topic.Subscribe()
+ if err != nil {
+ return
+ }
+ defer sub.Cancel()
+
+ for {
+ msg, err := sub.Next(ctx)
+ if err != nil {
+ return
+ }
+ if s.rateLimiter != nil && !s.rateLimiter.Allow(msg.GetFrom().String()) {
+ continue
+ }
+ var evt api.MeshEvent
+ if err := proto.Unmarshal(msg.Data, &evt); err != nil {
+ continue
+ }
+ switch evt.GetType() {
+ case api.MeshEvent_BANNED:
+ p, err := peer.Decode(evt.GetPeerId())
+ if err != nil {
+ continue
+ }
+ canonical := p.String()
+ eventMs := evt.GetEventTime().AsTime().UnixMilli()
+ s.mu.Lock()
+ if s.peerLastEventTime == nil {
+ s.peerLastEventTime = map[string]int64{}
+ }
+ if eventMs < s.peerLastEventTime[canonical] {
+ s.mu.Unlock()
+ continue
+ }
+ s.peerLastEventTime[canonical] = eventMs
+ s.mu.Unlock()
+ s.banPeer(p, eventMs)
+ case api.MeshEvent_KEY_ROTATION:
+ if len(evt.GetNewPublicKey()) == ed25519.PublicKeySize {
+ s.addTrustedKey(ed25519.PublicKey(slices.Clone(evt.GetNewPublicKey())))
+ s.triggerControlPlaneSync()
+ }
+ case api.MeshEvent_POLICY_UPDATE:
+ s.triggerControlPlaneSync()
+ }
+ }
+}
diff --git a/sdk/meshnet/server.go b/sdk/meshnet/server.go
new file mode 100644
index 00000000..7891025a
--- /dev/null
+++ b/sdk/meshnet/server.go
@@ -0,0 +1,583 @@
+// 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 meshnet embeds an Agent Mesh member directly inside a Go program
+// (modeled on tailscale.com/tsnet), providing in-process A2A listeners
+// (private P2P and public external HTTP ingress), a mesh-routing *http.Client,
+// unspoofable WhoIs caller inspection, a local progressive-discovery MCP
+// server, and a zero-secret OpenAI-compatible /v1 inference handler without an
+// external agentmesh-node sidecar binary.
+package meshnet
+
+import (
+ "context"
+ "crypto/ed25519"
+ "errors"
+ "fmt"
+ "log/slog"
+ "math/rand/v2"
+ "slices"
+ "sort"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/eclipse-biscuit/biscuit-go/v2"
+ "github.com/google/agentmesh/api"
+ "github.com/google/agentmesh/internal/identity"
+ "github.com/google/agentmesh/internal/ratelimit"
+ lru "github.com/hashicorp/golang-lru/v2"
+ "github.com/libp2p/go-libp2p"
+ pubsub "github.com/libp2p/go-libp2p-pubsub"
+ "github.com/libp2p/go-libp2p/core/crypto"
+ "github.com/libp2p/go-libp2p/core/event"
+ "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/peerstore"
+ "github.com/libp2p/go-libp2p/p2p/host/autorelay"
+ "github.com/libp2p/go-libp2p/p2p/net/connmgr"
+ "github.com/libp2p/go-libp2p/p2p/net/swarm"
+ "github.com/libp2p/go-libp2p/p2p/security/noise"
+ libp2ptls "github.com/libp2p/go-libp2p/p2p/security/tls"
+)
+
+const (
+ rateLimiterSize = 1024
+ revocationCacheSize = 4096
+ withdrawTimeout = 5 * time.Second
+)
+
+// Server is an embedded Agent Mesh node. Configure its exported fields and call
+// Up (or ListenA2A after Up) to join the mesh in-process.
+type Server struct {
+ // StateDir persists identity.key and credential.json (0700/0600, byte-for-byte
+ // compatible with sdk/js, sdk/python, and `agentmesh-node state export|import`).
+ // When empty, Server runs with an ephemeral in-memory Ed25519 identity.
+ StateDir string
+
+ // ControlPlaneURL is the Agent Mesh hub URL (e.g. "https://bananas.sam-mesh.dev").
+ // Optional when resuming from a populated StateDir that already records
+ // control_plane_url.
+ ControlPlaneURL string
+
+ // BootstrapTokenPath reads a bootstrap enrollment token from disk when no
+ // valid credential exists in StateDir. Preferred over BootstrapToken so
+ // secrets stay in files rather than process arguments.
+ BootstrapTokenPath string
+
+ // BootstrapToken supplies an in-memory bootstrap enrollment token (for
+ // example read from an environment variable or secret manager).
+ BootstrapToken string
+
+ // JWTPath reads a platform OIDC / Kubernetes ServiceAccount / SPIFFE JWT from
+ // disk for POST /register enrollment and POST /refresh re-attestation.
+ JWTPath string
+
+ // TokenSource dynamically fetches a fresh platform JWT for POST /register
+ // enrollment and proactive POST /refresh renewal.
+ TokenSource func(ctx context.Context) (string, error)
+
+ // Labels are operator-declared key=value pairs requested at enrollment time
+ // (signed into Block 0 only when permitted by PolicyRole.allowed_labels).
+ Labels map[string]string
+
+ // EgressRequireLabels sets a consumer-side label floor enforced on every
+ // outbound provider's Biscuit before request data leaves this Server.
+ EgressRequireLabels map[string]string
+
+ // Routers is the target number of mesh routers to stay attached to (default 2).
+ Routers int
+
+ // RouterSelector filters candidate routers to those attesting all key=value pairs.
+ RouterSelector map[string]string
+
+ // RouterPrefer ranks routers matching more key=value pairs first.
+ RouterPrefer map[string]string
+
+ // ListenAddrs overrides the libp2p listen multiaddrs. When empty, Server
+ // binds ephemeral UDP QUIC and TCP ports on all interfaces so direct P2P and
+ // hole-punching work alongside Circuit Relay v2.
+ ListenAddrs []string
+
+ // AllowInsecure opts into http:// control-plane URLs on loopback and keeps
+ // loopback/private peer multiaddrs during local development and integration tests.
+ AllowInsecure bool
+
+ // Logger receives structured mesh events. Defaults to slog.Default().
+ Logger *slog.Logger
+
+ // Internal state initialized by Up.
+ lifecycleMu sync.Mutex
+ started bool
+ closed bool
+ bgCancel context.CancelFunc
+ addrSub event.Subscription
+
+ privKey crypto.PrivKey
+ privKeyBytes []byte
+ peerID peer.ID
+ cpURL string
+
+ keysMu sync.RWMutex
+ trustedKeys []trustedKey
+ issuedUnderKeys []ed25519.PublicKey
+
+ credMu sync.RWMutex
+ biscuit []byte
+ expireTime time.Time
+ storedRouterAddrs []string
+ oidcSession *api.OIDCSession
+
+ refreshMu sync.Mutex
+ reenrollMu sync.Mutex
+ lastReenroll time.Time
+
+ host host.Host
+ connMgr *connmgr.BasicConnMgr
+ pubsub *pubsub.PubSub
+ dir *routerDirectory
+
+ mu sync.Mutex
+ routerCatalog []routerCandidate
+ attached map[peer.ID]bool
+ authenticatedRouters map[peer.ID]bool
+ shunned map[peer.ID]time.Time
+ handshaking map[peer.ID]chan struct{}
+ redialing map[peer.ID]bool
+ currentRelays []peer.AddrInfo
+ dirSettings api.DirectorySettings
+ peerLastEventTime map[string]int64
+ transitCatalogRefreshedAt time.Time
+
+ authPeers sync.Map
+ authRouters sync.Map
+ authSuccess chan struct{}
+ authOnce sync.Once
+
+ policyMu sync.RWMutex
+ meshPolicyRules []biscuit.Rule
+ meshPolicyTexts []string
+
+ revokedPeers *lru.Cache[string, int64]
+ revokedTokens *lru.Cache[string, time.Time]
+ peerLabelGate *lru.Cache[string, time.Time]
+
+ rateLimiter *ratelimit.PeerRateLimiter
+ handshakeLimiter *ratelimit.PeerRateLimiter
+ externalIngressLimiter *ratelimit.PeerRateLimiter
+
+ refusedMu sync.Mutex
+ refusedStreams map[string]uint64
+
+ syncInterval time.Duration
+ syncTrigger chan struct{}
+ reprovideTrigger chan struct{}
+
+ a2aMu sync.RWMutex
+ a2aServices map[string]*a2aEntry
+
+ activeConns sync.Map
+ nextConnSeq atomic.Uint64
+}
+
+// Status describes the live mesh connectivity and credential state of a Server.
+type Status struct {
+ PeerID string
+ ControlPlaneURL string
+ AttachedRouters []string
+ IngressURLs []string
+ ExpireTime time.Time
+}
+
+// CallerInfo carries the cryptographically verified mesh identity of an inbound
+// caller returned by Server.WhoIs.
+type CallerInfo struct {
+ PeerID string
+ Principal string
+ Roles []string
+ Labels map[string]string
+ Task string
+}
+
+func (s *Server) log() *slog.Logger {
+ if s.Logger != nil {
+ return s.Logger
+ }
+ return slog.Default()
+}
+
+func (s *Server) biscuitTimeout() time.Duration {
+ return identity.DefaultAuthorizerTimeout
+}
+
+// Up loads or enrolls the member credential, syncs mesh trust material and
+// policy from the control plane, starts the gated libp2p host, authenticates
+// with mesh routers, and starts background renewal, sync, and reprovide loops.
+func (s *Server) Up(ctx context.Context) (*Status, error) {
+ s.lifecycleMu.Lock()
+ defer s.lifecycleMu.Unlock()
+
+ if s.closed {
+ return nil, errors.New("meshnet: Server has been closed")
+ }
+ if s.started {
+ st := s.Status()
+ return &st, nil
+ }
+
+ if err := api.ValidateLabels(s.Labels); err != nil {
+ return nil, fmt.Errorf("meshnet: invalid Labels: %w", err)
+ }
+ if err := api.ValidateLabels(s.EgressRequireLabels); err != nil {
+ return nil, fmt.Errorf("meshnet: invalid EgressRequireLabels: %w", err)
+ }
+ if err := api.ValidateLabels(s.RouterSelector); err != nil {
+ return nil, fmt.Errorf("meshnet: invalid RouterSelector: %w", err)
+ }
+ if err := api.ValidateLabels(s.RouterPrefer); err != nil {
+ return nil, fmt.Errorf("meshnet: invalid RouterPrefer: %w", err)
+ }
+
+ if err := s.initCaches(); err != nil {
+ return nil, err
+ }
+
+ if err := s.ensureCredential(ctx); err != nil {
+ return nil, err
+ }
+
+ if err := s.syncControlPlane(ctx); err != nil {
+ s.log().Warn("initial control plane sync completed with errors; falling back to cached state where available", "error", err)
+ }
+ if len(s.routerCandidates()) == 0 {
+ s.credMu.RLock()
+ stored := slices.Clone(s.storedRouterAddrs)
+ s.credMu.RUnlock()
+ if len(stored) > 0 {
+ s.setRouterCatalog(candidatesFromAddrs(ctx, parseMultiaddrs(stored)))
+ }
+ }
+
+ cm, err := connmgr.NewConnManager(connLowWaterMark, connHighWaterMark, connmgr.WithGracePeriod(time.Minute))
+ if err != nil {
+ return nil, fmt.Errorf("create connection manager: %w", err)
+ }
+ s.connMgr = cm
+
+ rm, err := s.newResourceManager()
+ if err != nil {
+ _ = cm.Close()
+ return nil, fmt.Errorf("create resource manager: %w", err)
+ }
+
+ listenAddrs := s.ListenAddrs
+ if len(listenAddrs) == 0 {
+ listenAddrs = []string{
+ "/ip4/0.0.0.0/udp/0/quic-v1",
+ "/ip4/0.0.0.0/tcp/0",
+ "/ip6/::/udp/0/quic-v1",
+ "/ip6/::/tcp/0",
+ }
+ }
+
+ numRelays := s.Routers
+ if numRelays <= 0 {
+ numRelays = 2
+ }
+
+ opts := []libp2p.Option{
+ libp2p.Identity(s.privKey),
+ libp2p.DefaultTransports,
+ libp2p.Security(libp2ptls.ID, libp2ptls.New),
+ libp2p.Security(noise.ID, noise.New),
+ libp2p.ConnectionGater(&connGate{s: s}),
+ libp2p.ListenAddrStrings(listenAddrs...),
+ libp2p.EnableNATService(),
+ libp2p.EnableAutoNATv2(),
+ libp2p.EnableRelay(),
+ libp2p.EnableHolePunching(),
+ libp2p.ForceReachabilityPrivate(),
+ libp2p.ConnectionManager(cm),
+ libp2p.ResourceManager(rm),
+ libp2p.SwarmOpts(swarm.WithDialTimeout(15*time.Second), swarm.WithDialRanker(tcpFirstDialRanker)),
+ libp2p.AddrsFactory(s.announceFilter),
+ }
+
+ if len(s.routerCandidates()) > 0 {
+ opts = append(opts, libp2p.EnableAutoRelayWithPeerSource(
+ func(pCtx context.Context, _ int) <-chan peer.AddrInfo {
+ c := make(chan peer.AddrInfo, numRelays)
+ go func() {
+ defer close(c)
+ select {
+ case <-pCtx.Done():
+ return
+ case <-s.authSuccess:
+ }
+ s.mu.Lock()
+ relays := slices.Clone(s.currentRelays)
+ s.mu.Unlock()
+ rand.Shuffle(len(relays), func(i, j int) {
+ relays[i], relays[j] = relays[j], relays[i]
+ })
+ for _, r := range relays {
+ select {
+ case c <- r:
+ case <-pCtx.Done():
+ return
+ }
+ }
+ }()
+ return c
+ },
+ autorelay.WithNumRelays(numRelays),
+ autorelay.WithBootDelay(0),
+ autorelay.WithBackoff(5*time.Second),
+ autorelay.WithMinInterval(5*time.Second),
+ ))
+ }
+
+ h, err := libp2p.New(opts...)
+ if err != nil {
+ _ = cm.Close()
+ return nil, fmt.Errorf("create libp2p host: %w", err)
+ }
+ s.host = h
+
+ for _, c := range s.routerCandidates() {
+ h.Peerstore().AddAddrs(c.ID, c.Addrs, peerstore.PermanentAddrTTL)
+ }
+
+ bgCtx, bgCancel := context.WithCancel(context.Background())
+ s.bgCancel = bgCancel
+
+ cleanupOnErr := func() {
+ bgCancel()
+ _ = h.Close()
+ _ = cm.Close()
+ s.host = nil
+ s.connMgr = nil
+ }
+
+ h.Network().Notify(&network.NotifyBundle{
+ ConnectedF: func(_ network.Network, c network.Conn) {
+ remoteAddr := c.RemoteMultiaddr()
+ if hasCircuit(remoteAddr) || !isPrivateIP(remoteAddr) {
+ _ = h.Peerstore().Put(c.RemotePeer(), peerstoreKeyPrivateIPFailed, true)
+ }
+ },
+ DisconnectedF: func(_ network.Network, c network.Conn) {
+ remotePeer := c.RemotePeer()
+ if len(h.Network().ConnsToPeer(remotePeer)) > 0 {
+ return
+ }
+ s.mu.Lock()
+ _, wasAuth := s.authenticatedRouters[remotePeer]
+ delete(s.authenticatedRouters, remotePeer)
+ attached := s.attached[remotePeer]
+ s.mu.Unlock()
+ if wasAuth {
+ s.log().Warn("router disconnected; clearing authenticated session", "router_peer_id", remotePeer.String())
+ if attached {
+ s.redialRouter(bgCtx, remotePeer)
+ }
+ }
+ },
+ })
+
+ gated := &meshHost{Host: h, s: s}
+ s.dir = &routerDirectory{
+ host: gated,
+ routers: s.attachedRouters,
+ addrs: h.Addrs,
+ log: s.log,
+ }
+
+ // Register handshake and credential-gated stream handlers BEFORE dialing
+ // routers so incoming streams during or immediately after router admission
+ // find every protocol ready.
+ h.SetStreamHandler(api.AuthProtocolID, s.recoverStream("auth", s.handleAuthHandshake))
+ h.SetStreamHandler(api.GoAwayProtocolID, s.recoverStream("goaway", func(st network.Stream) {
+ s.handleGoAway(bgCtx, st)
+ }))
+ h.SetStreamHandler(api.MCPProtocolID, s.recoverStream("mcp", s.handleMCPStream))
+
+ if err := s.startHTTPServers(bgCtx); err != nil {
+ cleanupOnErr()
+ return nil, err
+ }
+
+ ps, err := pubsub.NewFloodSub(bgCtx, gated, pubsub.WithMessageSignaturePolicy(pubsub.StrictSign))
+ if err != nil {
+ cleanupOnErr()
+ return nil, fmt.Errorf("init floodsub: %w", err)
+ }
+ if err := ps.RegisterTopicValidator(api.GossipEvents, s.validateMeshEvent); err != nil {
+ cleanupOnErr()
+ return nil, fmt.Errorf("register gossip validator: %w", err)
+ }
+ s.pubsub = ps
+ go s.listenForControlPlaneEvents(bgCtx)
+
+ if err := s.admitByRouters(ctx); err != nil {
+ cleanupOnErr()
+ return nil, err
+ }
+
+ if sub, subErr := h.EventBus().Subscribe(new(event.EvtLocalAddressesUpdated)); subErr == nil {
+ s.addrSub = sub
+ go func() {
+ for {
+ select {
+ case <-bgCtx.Done():
+ return
+ case _, ok := <-sub.Out():
+ if !ok {
+ return
+ }
+ s.triggerReprovide()
+ }
+ }
+ }()
+ }
+
+ s.startReprovideLoop(bgCtx)
+ s.startControlPlaneSyncLoop(bgCtx)
+ s.startRenewalLoop(bgCtx)
+
+ s.started = true
+ st := s.Status()
+ return &st, nil
+}
+
+func (s *Server) initCaches() error {
+ s.attached = make(map[peer.ID]bool)
+ s.authenticatedRouters = make(map[peer.ID]bool)
+ s.shunned = make(map[peer.ID]time.Time)
+ s.handshaking = make(map[peer.ID]chan struct{})
+ s.redialing = make(map[peer.ID]bool)
+ s.peerLastEventTime = make(map[string]int64)
+ s.dirSettings = api.DefaultDirectorySettings()
+ s.authSuccess = make(chan struct{})
+ s.syncTrigger = make(chan struct{}, 1)
+ s.reprovideTrigger = make(chan struct{}, 1)
+ s.refusedStreams = make(map[string]uint64)
+ s.a2aServices = make(map[string]*a2aEntry)
+
+ var err error
+ if s.rateLimiter, err = ratelimit.NewPeerRateLimiterWithRate(rateLimiterSize, 20, 30); err != nil {
+ return err
+ }
+ if s.handshakeLimiter, err = ratelimit.NewPeerRateLimiter(rateLimiterSize); err != nil {
+ return err
+ }
+ if s.externalIngressLimiter, err = ratelimit.NewPeerRateLimiterWithRate(rateLimiterSize, 200, 400); err != nil {
+ return err
+ }
+ if s.revokedPeers, err = lru.New[string, int64](revocationCacheSize); err != nil {
+ return err
+ }
+ if s.revokedTokens, err = lru.New[string, time.Time](revocationCacheSize); err != nil {
+ return err
+ }
+ if s.peerLabelGate, err = lru.New[string, time.Time](labelGateCacheSize); err != nil {
+ return err
+ }
+ return nil
+}
+
+// Status returns a snapshot of the member's PeerID, control-plane URL,
+// attached routers, public router ingress base URLs, and credential expiry.
+func (s *Server) Status() Status {
+ routers := s.attachedRouters()
+ routerStrs := make([]string, 0, len(routers))
+ for _, r := range routers {
+ routerStrs = append(routerStrs, r.String())
+ }
+ sort.Strings(routerStrs)
+
+ var peerIDStr string
+ if s.peerID != "" {
+ peerIDStr = s.peerID.String()
+ }
+ return Status{
+ PeerID: peerIDStr,
+ ControlPlaneURL: s.cpURL,
+ AttachedRouters: routerStrs,
+ IngressURLs: s.routerIngressURLs(),
+ ExpireTime: s.credentialExpireTime(),
+ }
+}
+
+// Close withdraws directory records (bounded to 5s), closes all registered
+// A2A listeners, stops background loops, and shuts down the libp2p host.
+func (s *Server) Close() error {
+ s.lifecycleMu.Lock()
+ defer s.lifecycleMu.Unlock()
+
+ if s.closed {
+ return nil
+ }
+ s.closed = true
+
+ entries := s.listA2AEntries()
+ for _, e := range entries {
+ _ = e.privateLn.Close()
+ if e.publicLn != nil {
+ _ = e.publicLn.Close()
+ }
+ }
+
+ if s.dir != nil && s.host != nil {
+ wCtx, cancel := context.WithTimeout(context.Background(), withdrawTimeout)
+ hasAnnouncedA2A := false
+ for _, e := range entries {
+ if e.noAnnounce {
+ continue
+ }
+ hasAnnouncedA2A = true
+ if nameKey, err := api.ServiceKey(api.ServiceType_SERVICE_TYPE_A2A, e.name); err == nil {
+ _ = s.dir.withdraw(wCtx, nameKey)
+ }
+ }
+ if hasAnnouncedA2A {
+ if typeKey, err := api.ServiceKey(api.ServiceType_SERVICE_TYPE_A2A, ""); err == nil {
+ _ = s.dir.withdraw(wCtx, typeKey)
+ }
+ }
+ _ = s.dir.withdraw(wCtx, api.PeerKey(s.peerID))
+ cancel()
+ }
+
+ if s.addrSub != nil {
+ _ = s.addrSub.Close()
+ }
+ if s.bgCancel != nil {
+ s.bgCancel()
+ }
+
+ var errs []error
+ if s.host != nil {
+ if err := s.host.Close(); err != nil {
+ errs = append(errs, err)
+ }
+ }
+ if s.connMgr != nil {
+ if err := s.connMgr.Close(); err != nil {
+ errs = append(errs, err)
+ }
+ }
+ return errors.Join(errs...)
+}
diff --git a/sdk/meshnet/statedir.go b/sdk/meshnet/statedir.go
new file mode 100644
index 00000000..a170e01b
--- /dev/null
+++ b/sdk/meshnet/statedir.go
@@ -0,0 +1,998 @@
+// 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 meshnet
+
+import (
+ "bytes"
+ "context"
+ "crypto/ed25519"
+ "crypto/sha256"
+ "encoding/base64"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "os"
+ "path/filepath"
+ "slices"
+ "strings"
+ "time"
+
+ "github.com/google/agentmesh/api"
+ cpclient "github.com/google/agentmesh/internal/controlplane/client"
+ "github.com/google/agentmesh/internal/identity"
+ "github.com/libp2p/go-libp2p/core/crypto"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "google.golang.org/protobuf/encoding/protojson"
+ "google.golang.org/protobuf/proto"
+ "google.golang.org/protobuf/types/known/timestamppb"
+)
+
+// State directory filenames, matching sdk/js, sdk/python, and
+// `agentmesh-node state export|import`.
+const (
+ StateDirIdentityFile = "identity.key"
+ StateDirCredentialFile = "credential.json"
+)
+
+const (
+ minResumeLifetime = 5 * time.Minute
+ renewalThreshold = 10 * time.Minute
+ renewalBuffer = 5 * time.Minute
+ defaultRenewalFallback = 5 * time.Minute
+ controlPlaneTimeout = 30 * time.Second
+ defaultPollInterval = 2 * time.Second
+)
+
+// ErrCredentialRetired indicates that the persisted credential's control-plane
+// signing key was rotated past its grace period while this member was offline,
+// and no join token or TokenSource was supplied to re-enroll.
+var ErrCredentialRetired = errors.New("meshnet: saved credential signing key retired; provide a join token to re-enroll")
+
+var stateDirMarshal = protojson.MarshalOptions{UseProtoNames: true, Multiline: true, Indent: " "}
+
+type trustedKey struct {
+ key ed25519.PublicKey
+ receivedAt time.Time
+}
+
+// WriteStateDir writes a member's libp2p private key and MemberCredential to
+// dir with owner-only permissions (0700 directory, 0600 files).
+func WriteStateDir(dir string, privKey []byte, c *api.MemberCredential) error {
+ if _, err := crypto.UnmarshalPrivateKey(privKey); err != nil {
+ return fmt.Errorf("private key is not a libp2p key: %w", err)
+ }
+ if err := os.MkdirAll(dir, 0o700); err != nil {
+ return err
+ }
+ credential, err := stateDirMarshal.Marshal(c)
+ if err != nil {
+ return err
+ }
+ if err := writeOwnerOnly(filepath.Join(dir, StateDirIdentityFile), privKey); err != nil {
+ return err
+ }
+ return writeOwnerOnly(filepath.Join(dir, StateDirCredentialFile), append(credential, '\n'))
+}
+
+// ReadStateDir loads a member's libp2p private key and MemberCredential from
+// dir, rejecting unknown fields in credential.json.
+func ReadStateDir(dir string) ([]byte, *api.MemberCredential, error) {
+ privKey, err := os.ReadFile(filepath.Join(dir, StateDirIdentityFile))
+ if err != nil {
+ if errors.Is(err, os.ErrNotExist) {
+ return nil, nil, fmt.Errorf("no identity in %s: %w", dir, err)
+ }
+ return nil, nil, err
+ }
+ if _, err := crypto.UnmarshalPrivateKey(privKey); err != nil {
+ return nil, nil, fmt.Errorf("%s: not a libp2p private key: %w", filepath.Join(dir, StateDirIdentityFile), err)
+ }
+ raw, err := os.ReadFile(filepath.Join(dir, StateDirCredentialFile))
+ if err != nil {
+ if errors.Is(err, os.ErrNotExist) {
+ return nil, nil, fmt.Errorf("no credential in %s: %w", dir, err)
+ }
+ return nil, nil, err
+ }
+ c := &api.MemberCredential{}
+ if err := protojson.Unmarshal(raw, c); err != nil {
+ return nil, nil, fmt.Errorf("%s: %w", filepath.Join(dir, StateDirCredentialFile), err)
+ }
+ return privKey, c, nil
+}
+
+func writeOwnerOnly(path string, data []byte) error {
+ tmp := path + ".tmp"
+ if err := os.WriteFile(tmp, data, 0o600); err != nil {
+ return err
+ }
+ return os.Rename(tmp, path)
+}
+
+func normalizeControlPlaneURL(raw string) string {
+ raw = strings.TrimSpace(raw)
+ if raw == "" {
+ return ""
+ }
+ if !strings.HasPrefix(raw, "http://") && !strings.HasPrefix(raw, "https://") {
+ raw = "https://" + raw
+ }
+ return strings.TrimSuffix(raw, "/")
+}
+
+func (s *Server) cpHTTPClient(timeout time.Duration) *http.Client {
+ return cpclient.NewHTTPClient(timeout, func() bool { return s.AllowInsecure }, "agentmesh-meshnet")
+}
+
+func (s *Server) cpClient() *cpclient.Client {
+ c := cpclient.New(s.cpURL, s.cpHTTPClient(controlPlaneTimeout))
+ if s.privKey != nil && s.peerID != "" {
+ c = c.WithIdentity(s.peerID.String(), s.privKey)
+ }
+ return c
+}
+
+func (s *Server) loadOrCreateIdentity() (*api.MemberCredential, error) {
+ if s.StateDir != "" {
+ keyPath := filepath.Join(s.StateDir, StateDirIdentityFile)
+ keyBytes, err := os.ReadFile(keyPath)
+ if err == nil {
+ priv, uErr := crypto.UnmarshalPrivateKey(keyBytes)
+ if uErr != nil {
+ return nil, fmt.Errorf("%s: not a libp2p private key: %w", keyPath, uErr)
+ }
+ pid, pErr := peer.IDFromPrivateKey(priv)
+ if pErr != nil {
+ return nil, fmt.Errorf("derive peer ID: %w", pErr)
+ }
+ s.privKey = priv
+ s.privKeyBytes = keyBytes
+ s.peerID = pid
+
+ credPath := filepath.Join(s.StateDir, StateDirCredentialFile)
+ rawCred, cErr := os.ReadFile(credPath)
+ if cErr != nil {
+ if errors.Is(cErr, os.ErrNotExist) {
+ return nil, nil
+ }
+ return nil, cErr
+ }
+ cred := &api.MemberCredential{}
+ if err := protojson.Unmarshal(rawCred, cred); err != nil {
+ return nil, fmt.Errorf("%s: %w", credPath, err)
+ }
+ return cred, nil
+ }
+ if !errors.Is(err, os.ErrNotExist) {
+ return nil, err
+ }
+ }
+
+ priv, _, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
+ if err != nil {
+ return nil, fmt.Errorf("generate ed25519 identity: %w", err)
+ }
+ raw, err := crypto.MarshalPrivateKey(priv)
+ if err != nil {
+ return nil, fmt.Errorf("marshal private key: %w", err)
+ }
+ pid, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ return nil, fmt.Errorf("derive peer ID: %w", err)
+ }
+ s.privKey = priv
+ s.privKeyBytes = raw
+ s.peerID = pid
+ if s.StateDir != "" {
+ if err := os.MkdirAll(s.StateDir, 0o700); err != nil {
+ return nil, err
+ }
+ if err := writeOwnerOnly(filepath.Join(s.StateDir, StateDirIdentityFile), raw); err != nil {
+ return nil, err
+ }
+ }
+ return nil, nil
+}
+
+func (s *Server) ensureCredential(ctx context.Context) error {
+ cred, err := s.loadOrCreateIdentity()
+ if err != nil {
+ return err
+ }
+
+ explicitCP := normalizeControlPlaneURL(s.ControlPlaneURL)
+ storedCP := ""
+ if cred != nil {
+ storedCP = normalizeControlPlaneURL(cred.GetControlPlaneUrl())
+ }
+
+ switch {
+ case explicitCP != "":
+ s.cpURL = explicitCP
+ case storedCP != "":
+ s.cpURL = storedCP
+ default:
+ return errors.New("meshnet: ControlPlaneURL is required when no saved credential exists")
+ }
+
+ if err := api.ValidateControlPlaneTransport(s.cpURL, s.AllowInsecure); err != nil {
+ return err
+ }
+
+ if cred != nil && len(cred.GetBiscuit()) > 0 && (storedCP == "" || storedCP == s.cpURL) {
+ s.adoptLoadedCredential(cred)
+
+ keysErr := s.syncTrustedKeys(ctx)
+ roleOK := s.verifySavedRole() == nil
+ remaining := time.Until(s.credentialExpireTime())
+
+ if keysErr == nil && roleOK && remaining > minResumeLifetime && !s.identityPredatesRotation() {
+ s.log().Info("resumed mesh credential from state directory",
+ "peer_id", s.peerID.String(),
+ "control_plane", s.cpURL,
+ "expires_in", remaining.Round(time.Second),
+ )
+ return nil
+ }
+
+ refreshErr := s.Refresh(ctx)
+ if refreshErr == nil {
+ s.log().Info("refreshed mesh credential on startup", "peer_id", s.peerID.String())
+ return nil
+ }
+
+ // Try OIDC refresh_token recovery if stored in credential.json.
+ if jwtStr, oidcErr := s.renewFromOIDCSession(ctx); oidcErr == nil && jwtStr != "" {
+ if regErr := s.enrollJWT(ctx, jwtStr); regErr == nil {
+ s.log().Info("re-enrolled via saved OIDC session", "peer_id", s.peerID.String())
+ return nil
+ }
+ }
+
+ // Try operator-supplied join token / TokenSource re-enrollment.
+ kind, tok, tokErr := s.resolveJoinSecret(ctx)
+ if tokErr != nil {
+ return tokErr
+ }
+ if kind != joinSecretNone {
+ return s.enrollWithSecret(ctx, kind, tok, false)
+ }
+
+ // If the control plane was unreachable (not a retired key error) and the
+ // saved token still verifies locally with time remaining, proceed with
+ // cached state so transient hub outages do not break restarts.
+ if keysErr != nil && roleOK && remaining > 0 && !isRetiredVerificationError(keysErr) {
+ s.log().Warn("control plane unreachable at startup; continuing with cached credential",
+ "error", keysErr,
+ "expires_in", remaining.Round(time.Second),
+ )
+ return nil
+ }
+ return fmt.Errorf("%w: refresh failed (%v)", ErrCredentialRetired, refreshErr)
+ }
+
+ kind, tok, err := s.resolveJoinSecret(ctx)
+ if err != nil {
+ return err
+ }
+ if kind == joinSecretNone {
+ if cred != nil && storedCP != "" && storedCP != s.cpURL {
+ return fmt.Errorf("meshnet: saved credential belongs to %s, not %s; provide a join token to switch meshes", storedCP, s.cpURL)
+ }
+ return errors.New("meshnet: no saved credential and no join token configured (set TokenSource, JWTPath, BootstrapTokenPath, or BootstrapToken)")
+ }
+ return s.enrollWithSecret(ctx, kind, tok, false)
+}
+
+func isRetiredVerificationError(err error) bool {
+ return err != nil && strings.Contains(err.Error(), "/keys response rejected")
+}
+
+func (s *Server) adoptLoadedCredential(c *api.MemberCredential) {
+ now := time.Now()
+ var tks []trustedKey
+ for _, k := range c.GetTrustedKeys() {
+ if len(k.GetPublicKey()) != ed25519.PublicKeySize {
+ continue
+ }
+ recv := now
+ if k.GetReceiveTime() != nil {
+ recv = k.GetReceiveTime().AsTime()
+ }
+ tks = append(tks, trustedKey{
+ key: ed25519.PublicKey(slices.Clone(k.GetPublicKey())),
+ receivedAt: recv,
+ })
+ }
+ var issued []ed25519.PublicKey
+ for _, raw := range c.GetIssuedUnderKeys() {
+ if len(raw) == ed25519.PublicKeySize {
+ issued = append(issued, ed25519.PublicKey(slices.Clone(raw)))
+ }
+ }
+
+ s.keysMu.Lock()
+ s.trustedKeys = tks
+ s.issuedUnderKeys = issued
+ s.keysMu.Unlock()
+
+ s.credMu.Lock()
+ s.biscuit = slices.Clone(c.GetBiscuit())
+ if c.GetExpireTime() != nil {
+ s.expireTime = c.GetExpireTime().AsTime()
+ } else {
+ s.expireTime = time.Time{}
+ }
+ s.storedRouterAddrs = slices.Clone(c.GetRouterAddresses())
+ if c.GetOidcSession() != nil {
+ s.oidcSession = proto.Clone(c.GetOidcSession()).(*api.OIDCSession)
+ }
+ s.credMu.Unlock()
+}
+
+func (s *Server) persistState() error {
+ if s.StateDir == "" {
+ return nil
+ }
+ s.keysMu.RLock()
+ protoKeys := make([]*api.TrustedSigningKey, 0, len(s.trustedKeys))
+ for _, tk := range s.trustedKeys {
+ protoKeys = append(protoKeys, &api.TrustedSigningKey{
+ PublicKey: slices.Clone(tk.key),
+ ReceiveTime: timestamppb.New(tk.receivedAt),
+ })
+ }
+ issued := make([][]byte, 0, len(s.issuedUnderKeys))
+ for _, k := range s.issuedUnderKeys {
+ issued = append(issued, slices.Clone(k))
+ }
+ s.keysMu.RUnlock()
+
+ s.credMu.RLock()
+ biscuitCopy := slices.Clone(s.biscuit)
+ exp := s.expireTime
+ routerAddrs := slices.Clone(s.storedRouterAddrs)
+ var oidcCopy *api.OIDCSession
+ if s.oidcSession != nil {
+ oidcCopy = proto.Clone(s.oidcSession).(*api.OIDCSession)
+ }
+ s.credMu.RUnlock()
+
+ var expProto *timestamppb.Timestamp
+ if !exp.IsZero() {
+ expProto = timestamppb.New(exp)
+ }
+ cred := &api.MemberCredential{
+ ControlPlaneUrl: s.cpURL,
+ Biscuit: biscuitCopy,
+ ExpireTime: expProto,
+ TrustedKeys: protoKeys,
+ IssuedUnderKeys: issued,
+ RouterAddresses: routerAddrs,
+ OidcSession: oidcCopy,
+ }
+ return WriteStateDir(s.StateDir, s.privKeyBytes, cred)
+}
+
+type joinSecretKind int
+
+const (
+ joinSecretNone joinSecretKind = iota
+ joinSecretJWT
+ joinSecretBootstrap
+)
+
+func (s *Server) resolveJoinSecret(ctx context.Context) (joinSecretKind, string, error) {
+ if s.TokenSource != nil {
+ tok, err := s.TokenSource(ctx)
+ if err != nil {
+ return joinSecretNone, "", fmt.Errorf("TokenSource: %w", err)
+ }
+ tok = strings.TrimSpace(tok)
+ if tok == "" {
+ return joinSecretNone, "", errors.New("TokenSource returned an empty token")
+ }
+ return joinSecretJWT, tok, nil
+ }
+ if s.JWTPath != "" {
+ raw, err := os.ReadFile(s.JWTPath)
+ if err != nil {
+ return joinSecretNone, "", fmt.Errorf("read JWTPath %s: %w", s.JWTPath, err)
+ }
+ tok := strings.TrimSpace(string(raw))
+ if tok == "" {
+ return joinSecretNone, "", fmt.Errorf("JWTPath %s is empty", s.JWTPath)
+ }
+ return joinSecretJWT, tok, nil
+ }
+ if s.BootstrapTokenPath != "" {
+ raw, err := os.ReadFile(s.BootstrapTokenPath)
+ if err != nil {
+ return joinSecretNone, "", fmt.Errorf("read BootstrapTokenPath %s: %w", s.BootstrapTokenPath, err)
+ }
+ tok := strings.TrimSpace(string(raw))
+ if tok == "" {
+ return joinSecretNone, "", fmt.Errorf("BootstrapTokenPath %s is empty", s.BootstrapTokenPath)
+ }
+ return joinSecretBootstrap, tok, nil
+ }
+ if tok := strings.TrimSpace(s.BootstrapToken); tok != "" {
+ return joinSecretBootstrap, tok, nil
+ }
+ return joinSecretNone, "", nil
+}
+
+func (s *Server) enrollWithSecret(ctx context.Context, kind joinSecretKind, tok string, trustedOnly bool) error {
+ switch kind {
+ case joinSecretJWT:
+ return s.enrollJWT(ctx, tok)
+ case joinSecretBootstrap:
+ return s.enrollBootstrap(ctx, tok, trustedOnly)
+ default:
+ return errors.New("no enrollment secret")
+ }
+}
+
+func (s *Server) enrollJWT(ctx context.Context, jwtStr string) error {
+ pubBytes, err := crypto.MarshalPublicKey(s.privKey.GetPublic())
+ if err != nil {
+ return fmt.Errorf("marshal public key: %w", err)
+ }
+ client := s.cpHTTPClient(controlPlaneTimeout)
+ regURL := s.cpURL + "/register"
+
+ resp, err := cpclient.DoWithChallengeRetry(ctx, client, time.Now, cpclient.DefaultEnrollBackoff, func(ts int64) (*http.Request, error) {
+ sig, err := s.privKey.Sign(api.RegisterChallenge(s.peerID.String(), ts))
+ if err != nil {
+ return nil, fmt.Errorf("sign register challenge: %w", err)
+ }
+ req := &api.EnrollRequest{
+ Jwt: jwtStr,
+ PeerId: s.peerID.String(),
+ PublicKey: pubBytes,
+ RequestedRole: api.RoleNode,
+ Labels: s.Labels,
+ ChallengeUnixMs: ts,
+ ChallengeSignature: sig,
+ }
+ data, err := proto.Marshal(req)
+ if err != nil {
+ return nil, err
+ }
+ httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, regURL, bytes.NewReader(data))
+ if err != nil {
+ return nil, err
+ }
+ httpReq.Header.Set("Content-Type", "application/x-protobuf")
+ return httpReq, nil
+ })
+ if err != nil {
+ return fmt.Errorf("POST /register: %w", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+
+ if resp.StatusCode != http.StatusOK {
+ body, _ := cpclient.ReadBody(resp.Body)
+ return fmt.Errorf("POST /register failed (%s): %s", resp.Status, strings.TrimSpace(string(body)))
+ }
+ respData, err := cpclient.ReadBody(resp.Body)
+ if err != nil {
+ return fmt.Errorf("read /register response: %w", err)
+ }
+ var enrollResp api.EnrollResponse
+ if err := proto.Unmarshal(respData, &enrollResp); err != nil {
+ return fmt.Errorf("decode /register response: %w", err)
+ }
+ if enrollResp.GetErrorMessage() != "" {
+ return fmt.Errorf("enrollment failed: %s", enrollResp.GetErrorMessage())
+ }
+ return s.adoptEnrollment(ctx, enrollResp.GetBiscuitToken(), enrollResp.GetControlPlanePublicKey(), enrollResp.GetExpireTime(), enrollResp.GetRouterAddresses(), false)
+}
+
+func (s *Server) enrollBootstrap(ctx context.Context, bootstrapToken string, trustedOnly bool) error {
+ pubBytes, err := crypto.MarshalPublicKey(s.privKey.GetPublic())
+ if err != nil {
+ return fmt.Errorf("marshal public key: %w", err)
+ }
+ client := s.cpHTTPClient(controlPlaneTimeout)
+ enrollURL := s.cpURL + "/enroll"
+
+ resp, err := cpclient.DoWithChallengeRetry(ctx, client, time.Now, cpclient.DefaultEnrollBackoff, func(ts int64) (*http.Request, error) {
+ sig, err := s.privKey.Sign(api.EnrollChallenge(s.peerID.String(), ts))
+ if err != nil {
+ return nil, fmt.Errorf("sign enroll challenge: %w", err)
+ }
+ req := &api.BootstrapEnrollRequest{
+ BootstrapToken: bootstrapToken,
+ PeerId: s.peerID.String(),
+ PublicKey: pubBytes,
+ RequestedRole: api.RoleNode,
+ Labels: s.Labels,
+ ChallengeUnixMs: ts,
+ ChallengeSignature: sig,
+ }
+ data, err := proto.Marshal(req)
+ if err != nil {
+ return nil, err
+ }
+ httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, enrollURL, bytes.NewReader(data))
+ if err != nil {
+ return nil, err
+ }
+ httpReq.Header.Set("Content-Type", "application/x-protobuf")
+ return httpReq, nil
+ })
+ if err != nil {
+ return fmt.Errorf("POST /enroll: %w", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+
+ if resp.StatusCode != http.StatusOK {
+ body, _ := cpclient.ReadBody(resp.Body)
+ return fmt.Errorf("POST /enroll failed (%s): %s", resp.Status, strings.TrimSpace(string(body)))
+ }
+ respData, err := cpclient.ReadBody(resp.Body)
+ if err != nil {
+ return fmt.Errorf("read /enroll response: %w", err)
+ }
+ enrollResp := &api.BootstrapEnrollResponse{}
+ if err := proto.Unmarshal(respData, enrollResp); err != nil {
+ return fmt.Errorf("decode /enroll response: %w", err)
+ }
+ if enrollResp.GetErrorMessage() != "" {
+ return fmt.Errorf("enrollment failed: %s", enrollResp.GetErrorMessage())
+ }
+
+ if enrollResp.GetStatus() == api.EnrollmentStatus_ENROLLMENT_STATUS_PENDING {
+ s.log().Info("bootstrap enrollment pending administrator approval; polling status", "peer_id", s.peerID.String())
+ approved, err := s.pollBootstrapStatus(ctx, client, enrollResp.GetPollIntervalSeconds())
+ if err != nil {
+ return err
+ }
+ enrollResp = approved
+ }
+ if enrollResp.GetStatus() == api.EnrollmentStatus_ENROLLMENT_STATUS_REJECTED {
+ return errors.New("bootstrap enrollment was rejected by administrator")
+ }
+
+ return s.adoptEnrollment(ctx, enrollResp.GetBiscuitToken(), enrollResp.GetControlPlanePublicKey(), enrollResp.GetExpireTime(), enrollResp.GetRouterAddresses(), trustedOnly)
+}
+
+func (s *Server) pollBootstrapStatus(ctx context.Context, client *http.Client, pollSec int32) (*api.BootstrapEnrollResponse, error) {
+ u, err := url.Parse(s.cpURL)
+ if err != nil {
+ return nil, fmt.Errorf("parse control plane URL: %w", err)
+ }
+ u = u.JoinPath("enroll", "status")
+ q := u.Query()
+ q.Set("peer_id", s.peerID.String())
+ u.RawQuery = q.Encode()
+ statusURL := u.String()
+
+ interval := defaultPollInterval
+ if pollSec > 0 {
+ interval = time.Duration(pollSec) * time.Second
+ }
+ ticker := time.NewTicker(interval)
+ defer ticker.Stop()
+
+ for {
+ select {
+ case <-ctx.Done():
+ return nil, ctx.Err()
+ case <-ticker.C:
+ hResp, err := cpclient.DoWithChallenge(client, time.Now, func(ts int64) (*http.Request, error) {
+ hReq, err := http.NewRequestWithContext(ctx, http.MethodGet, statusURL, nil)
+ if err != nil {
+ return nil, err
+ }
+ if err := cpclient.SetChallengeHeaders(hReq, s.privKey, api.EnrollStatusChallenge(s.peerID.String(), ts), ts); err != nil {
+ return nil, err
+ }
+ return hReq, nil
+ })
+ if err != nil {
+ s.log().Warn("enrollment status check failed", "error", err)
+ continue
+ }
+ if hResp.StatusCode != http.StatusOK {
+ body, _ := cpclient.ReadBody(hResp.Body)
+ _ = hResp.Body.Close()
+ s.log().Warn("enrollment status returned non-OK", "status", hResp.Status, "body", strings.TrimSpace(string(body)))
+ continue
+ }
+ data, err := cpclient.ReadBody(hResp.Body)
+ _ = hResp.Body.Close()
+ if err != nil {
+ s.log().Warn("enrollment status read failed", "error", err)
+ continue
+ }
+ statusResp := &api.BootstrapEnrollResponse{}
+ if err := proto.Unmarshal(data, statusResp); err != nil {
+ s.log().Warn("enrollment status decode failed", "error", err)
+ continue
+ }
+ if statusResp.GetErrorMessage() != "" {
+ return nil, fmt.Errorf("enrollment failed: %s", statusResp.GetErrorMessage())
+ }
+ switch statusResp.GetStatus() {
+ case api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED:
+ return statusResp, nil
+ case api.EnrollmentStatus_ENROLLMENT_STATUS_REJECTED:
+ return nil, errors.New("bootstrap enrollment was rejected by administrator")
+ }
+ }
+ }
+}
+
+func (s *Server) adoptEnrollment(ctx context.Context, biscuitToken, cpPubKey []byte, exp *timestamppb.Timestamp, routerAddrs []string, trustedOnly bool) error {
+ if len(biscuitToken) == 0 {
+ return errors.New("enrollment returned an empty biscuit token")
+ }
+ if len(cpPubKey) != ed25519.PublicKeySize {
+ return fmt.Errorf("enrollment returned invalid control plane public key size %d", len(cpPubKey))
+ }
+ if exp == nil {
+ return errors.New("enrollment response missing expire_time")
+ }
+
+ if trustedOnly {
+ if !s.isTrustedKey(cpPubKey) {
+ sum := sha256.Sum256(cpPubKey)
+ return fmt.Errorf("re-enrollment answer names untrusted control plane key %s", hex.EncodeToString(sum[:8]))
+ }
+ if err := s.verifyOwnBiscuit(biscuitToken); err != nil {
+ return fmt.Errorf("re-enrollment biscuit failed verification: %w", err)
+ }
+ } else {
+ if _, _, err := identity.VerifyBiscuitAndGetKey(biscuitToken, s.peerID, []ed25519.PublicKey{ed25519.PublicKey(cpPubKey)}, s.biscuitTimeout()); err != nil {
+ return fmt.Errorf("enrolled biscuit verification failed: %w", err)
+ }
+ if err := identity.VerifyBiscuitRole(biscuitToken, ed25519.PublicKey(cpPubKey), api.RoleNode, s.biscuitTimeout()); err != nil {
+ return fmt.Errorf("enrolled biscuit lacks role %q: %w", api.RoleNode, err)
+ }
+ }
+
+ s.addTrustedKey(ed25519.PublicKey(slices.Clone(cpPubKey)))
+ if err := s.syncTrustedKeys(ctx); err != nil {
+ s.log().Warn("could not fetch full /keys set after enrollment; continuing with enrollment key", "error", err)
+ }
+
+ s.keysMu.Lock()
+ s.issuedUnderKeys = s.publicKeysLocked()
+ s.keysMu.Unlock()
+
+ s.credMu.Lock()
+ s.biscuit = slices.Clone(biscuitToken)
+ s.expireTime = exp.AsTime()
+ if len(routerAddrs) > 0 {
+ s.storedRouterAddrs = slices.Clone(routerAddrs)
+ }
+ s.credMu.Unlock()
+
+ if err := s.persistState(); err != nil {
+ return fmt.Errorf("persist state: %w", err)
+ }
+ s.readmitRouters(ctx)
+ return nil
+}
+
+// Refresh exchanges the member's current Biscuit for a freshly minted one at
+// POST /refresh, persists the updated state directory, and presents the new
+// credential on every live router session.
+func (s *Server) Refresh(ctx context.Context) error {
+ s.refreshMu.Lock()
+ defer s.refreshMu.Unlock()
+
+ currentBiscuit := s.currentBiscuit()
+ if len(currentBiscuit) == 0 {
+ return errors.New("meshnet: no current biscuit to refresh")
+ }
+
+ var freshJWT string
+ if s.TokenSource != nil {
+ if tok, err := s.TokenSource(ctx); err != nil {
+ s.log().Warn("TokenSource failed during refresh; attempting session-backed refresh", "error", err)
+ } else {
+ freshJWT = strings.TrimSpace(tok)
+ }
+ } else if s.JWTPath != "" {
+ if raw, err := os.ReadFile(s.JWTPath); err == nil {
+ freshJWT = strings.TrimSpace(string(raw))
+ }
+ }
+
+ client := s.cpHTTPClient(controlPlaneTimeout)
+ refreshURL := s.cpURL + "/refresh"
+ b64Biscuit := base64.StdEncoding.EncodeToString(currentBiscuit)
+
+ resp, err := cpclient.DoWithChallenge(client, time.Now, func(ts int64) (*http.Request, error) {
+ sig, err := s.privKey.Sign(api.RefreshChallenge(s.peerID.String(), ts))
+ if err != nil {
+ return nil, fmt.Errorf("sign refresh challenge: %w", err)
+ }
+ req := &api.TokenRefreshRequest{
+ ChallengeSignature: sig,
+ ChallengeUnixMs: ts,
+ PeerId: s.peerID.String(),
+ Jwt: freshJWT,
+ }
+ reqData, err := proto.Marshal(req)
+ if err != nil {
+ return nil, err
+ }
+ httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, refreshURL, bytes.NewReader(reqData))
+ if err != nil {
+ return nil, err
+ }
+ httpReq.Header.Set("Content-Type", "application/x-protobuf")
+ httpReq.Header.Set("Authorization", "Bearer "+b64Biscuit)
+ return httpReq, nil
+ })
+ if err != nil {
+ return fmt.Errorf("POST /refresh: %w", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+
+ if resp.StatusCode != http.StatusOK {
+ body, _ := cpclient.ReadBody(resp.Body)
+ return fmt.Errorf("POST /refresh failed (%s): %s", resp.Status, strings.TrimSpace(string(body)))
+ }
+ respData, err := cpclient.ReadBody(resp.Body)
+ if err != nil {
+ return fmt.Errorf("read /refresh response: %w", err)
+ }
+ var refreshResp api.TokenRefreshResponse
+ if err := proto.Unmarshal(respData, &refreshResp); err != nil {
+ return fmt.Errorf("decode /refresh response: %w", err)
+ }
+ if refreshResp.GetErrorMessage() != "" {
+ return fmt.Errorf("refresh error: %s", refreshResp.GetErrorMessage())
+ }
+ if refreshResp.GetExpireTime() == nil {
+ return errors.New("refresh response missing expire_time")
+ }
+ if err := s.verifyOwnBiscuit(refreshResp.GetBiscuitToken()); err != nil {
+ return fmt.Errorf("refreshed biscuit rejected: %w", err)
+ }
+
+ s.keysMu.Lock()
+ s.issuedUnderKeys = s.publicKeysLocked()
+ s.keysMu.Unlock()
+
+ s.credMu.Lock()
+ s.biscuit = slices.Clone(refreshResp.GetBiscuitToken())
+ s.expireTime = refreshResp.GetExpireTime().AsTime()
+ s.credMu.Unlock()
+
+ if err := s.persistState(); err != nil {
+ return fmt.Errorf("persist refreshed state: %w", err)
+ }
+ s.readmitRouters(ctx)
+ return nil
+}
+
+func (s *Server) renewFromOIDCSession(ctx context.Context) (string, error) {
+ s.credMu.RLock()
+ sess := s.oidcSession
+ s.credMu.RUnlock()
+ if sess == nil || sess.GetIssuer() == "" || sess.GetClientId() == "" || sess.GetRefreshToken() == "" {
+ return "", errors.New("no OIDC refresh session")
+ }
+
+ issuer := strings.TrimSuffix(sess.GetIssuer(), "/")
+ if err := api.ValidateControlPlaneTransport(issuer, s.AllowInsecure); err != nil {
+ return "", err
+ }
+ httpClient := s.cpHTTPClient(15 * time.Second)
+ discReq, err := http.NewRequestWithContext(ctx, http.MethodGet, issuer+"/.well-known/openid-configuration", nil)
+ if err != nil {
+ return "", err
+ }
+ discResp, err := httpClient.Do(discReq)
+ if err != nil {
+ return "", err
+ }
+ defer func() { _ = discResp.Body.Close() }()
+ if discResp.StatusCode != http.StatusOK {
+ return "", fmt.Errorf("OIDC discovery returned %s", discResp.Status)
+ }
+ var doc struct {
+ TokenEndpoint string `json:"token_endpoint"`
+ }
+ if err := json.NewDecoder(io.LimitReader(discResp.Body, 1<<20)).Decode(&doc); err != nil || doc.TokenEndpoint == "" {
+ return "", fmt.Errorf("invalid OIDC discovery document: %w", err)
+ }
+
+ form := url.Values{
+ "grant_type": {"refresh_token"},
+ "client_id": {sess.GetClientId()},
+ "refresh_token": {sess.GetRefreshToken()},
+ }
+ tokReq, err := http.NewRequestWithContext(ctx, http.MethodPost, doc.TokenEndpoint, strings.NewReader(form.Encode()))
+ if err != nil {
+ return "", err
+ }
+ tokReq.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+ tokResp, err := httpClient.Do(tokReq)
+ if err != nil {
+ return "", err
+ }
+ defer func() { _ = tokResp.Body.Close() }()
+ if tokResp.StatusCode != http.StatusOK {
+ return "", fmt.Errorf("OIDC token refresh returned %s", tokResp.Status)
+ }
+ var tokOut struct {
+ IDToken string `json:"id_token"`
+ AccessToken string `json:"access_token"`
+ RefreshToken string `json:"refresh_token"`
+ }
+ if err := json.NewDecoder(io.LimitReader(tokResp.Body, 1<<20)).Decode(&tokOut); err != nil {
+ return "", err
+ }
+ if tokOut.RefreshToken != "" {
+ s.credMu.Lock()
+ if s.oidcSession != nil {
+ s.oidcSession.RefreshToken = tokOut.RefreshToken
+ }
+ s.credMu.Unlock()
+ }
+ if tokOut.IDToken != "" {
+ return tokOut.IDToken, nil
+ }
+ if tokOut.AccessToken != "" {
+ return tokOut.AccessToken, nil
+ }
+ return "", errors.New("OIDC token response contained neither id_token nor access_token")
+}
+
+func (s *Server) startRenewalLoop(ctx context.Context) {
+ go func() {
+ for {
+ renewAfter := defaultRenewalFallback
+ if exp := s.credentialExpireTime(); !exp.IsZero() {
+ d := time.Until(exp)
+ switch {
+ case d > renewalThreshold:
+ renewAfter = d - renewalBuffer
+ case d > 0:
+ renewAfter = max(d/2, 2*time.Second)
+ default:
+ renewAfter = 2 * time.Second
+ }
+ }
+
+ timer := time.NewTimer(renewAfter)
+ select {
+ case <-ctx.Done():
+ timer.Stop()
+ return
+ case <-timer.C:
+ }
+
+ if err := s.Refresh(ctx); err == nil {
+ s.log().Info("renewed mesh credential", "peer_id", s.peerID.String(), "expire_time", s.credentialExpireTime())
+ continue
+ } else {
+ s.log().Warn("proactive biscuit refresh failed; attempting token re-enrollment", "error", err)
+ }
+
+ if jwtStr, err := s.renewFromOIDCSession(ctx); err == nil && jwtStr != "" {
+ if regErr := s.enrollJWT(ctx, jwtStr); regErr == nil {
+ s.log().Info("renewed mesh credential via OIDC session", "peer_id", s.peerID.String())
+ continue
+ }
+ }
+ kind, tok, err := s.resolveJoinSecret(ctx)
+ if err == nil && kind == joinSecretJWT {
+ if regErr := s.enrollJWT(ctx, tok); regErr == nil {
+ s.log().Info("renewed mesh credential via JWT source", "peer_id", s.peerID.String())
+ continue
+ } else {
+ s.log().Error("JWT re-enrollment failed", "error", regErr)
+ }
+ }
+ }
+ }()
+}
+
+func (s *Server) verifyOwnBiscuit(token []byte) error {
+ if len(token) == 0 {
+ return errors.New("empty biscuit token")
+ }
+ trusted := s.trustedPublicKeys()
+ if len(trusted) == 0 {
+ return errors.New("no trusted control plane keys loaded")
+ }
+ _, key, err := identity.VerifyBiscuitAndGetKey(token, s.peerID, trusted, s.biscuitTimeout())
+ if err != nil {
+ return err
+ }
+ return identity.VerifyBiscuitRole(token, key, api.RoleNode, s.biscuitTimeout())
+}
+
+func (s *Server) verifySavedRole() error {
+ tok := s.currentBiscuit()
+ if len(tok) == 0 {
+ return errors.New("empty biscuit")
+ }
+ trusted := s.trustedPublicKeys()
+ if len(trusted) == 0 {
+ return errors.New("no trusted keys")
+ }
+ var lastErr error
+ for _, k := range trusted {
+ if err := identity.VerifyBiscuitRole(tok, k, api.RoleNode, s.biscuitTimeout()); err == nil {
+ return nil
+ } else {
+ lastErr = err
+ }
+ }
+ return lastErr
+}
+
+func (s *Server) currentBiscuit() []byte {
+ s.credMu.RLock()
+ defer s.credMu.RUnlock()
+ return slices.Clone(s.biscuit)
+}
+
+func (s *Server) credentialExpireTime() time.Time {
+ s.credMu.RLock()
+ defer s.credMu.RUnlock()
+ return s.expireTime
+}
+
+func (s *Server) trustedPublicKeys() []ed25519.PublicKey {
+ s.keysMu.RLock()
+ defer s.keysMu.RUnlock()
+ return s.publicKeysLocked()
+}
+
+func (s *Server) publicKeysLocked() []ed25519.PublicKey {
+ out := make([]ed25519.PublicKey, 0, len(s.trustedKeys))
+ for _, tk := range s.trustedKeys {
+ out = append(out, tk.key)
+ }
+ return out
+}
+
+func (s *Server) isTrustedKey(pub []byte) bool {
+ for _, k := range s.trustedPublicKeys() {
+ if k.Equal(ed25519.PublicKey(pub)) {
+ return true
+ }
+ }
+ return false
+}
+
+func (s *Server) addTrustedKey(key ed25519.PublicKey) {
+ s.keysMu.Lock()
+ for _, tk := range s.trustedKeys {
+ if bytes.Equal(tk.key, key) {
+ s.keysMu.Unlock()
+ return
+ }
+ }
+ s.trustedKeys = append(s.trustedKeys, trustedKey{key: slices.Clone(key), receivedAt: time.Now()})
+ s.keysMu.Unlock()
+ if err := s.persistState(); err != nil {
+ s.log().Warn("failed to persist updated trusted keys", "error", err)
+ }
+}
diff --git a/sdk/meshnet/statedir_test.go b/sdk/meshnet/statedir_test.go
new file mode 100644
index 00000000..d7a0c075
--- /dev/null
+++ b/sdk/meshnet/statedir_test.go
@@ -0,0 +1,616 @@
+// 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 meshnet
+
+import (
+ "bytes"
+ "context"
+ "crypto/ed25519"
+ "crypto/rand"
+ "encoding/base64"
+ "encoding/json"
+ "errors"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "github.com/eclipse-biscuit/biscuit-go/v2"
+ "github.com/google/agentmesh/api"
+ "github.com/libp2p/go-libp2p/core/crypto"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "google.golang.org/protobuf/proto"
+ "google.golang.org/protobuf/types/known/timestamppb"
+)
+
+func TestWriteAndReadStateDir(t *testing.T) {
+ priv, _, err := crypto.GenerateEd25519Key(rand.Reader)
+ if err != nil {
+ t.Fatalf("GenerateEd25519Key: %v", err)
+ }
+ privBytes, err := crypto.MarshalPrivateKey(priv)
+ if err != nil {
+ t.Fatalf("MarshalPrivateKey: %v", err)
+ }
+ cpPub, cpPriv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatalf("GenerateKey: %v", err)
+ }
+ pid, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+ tok := mintTestBiscuit(t, cpPriv, pid.String(), api.RoleNode, time.Now().Add(time.Hour))
+
+ recvAt := time.Date(2026, 11, 1, 10, 0, 0, 0, time.UTC)
+ expAt := time.Date(2026, 11, 1, 11, 0, 0, 0, time.UTC)
+ want := &api.MemberCredential{
+ ControlPlaneUrl: "https://bananas.sam-mesh.dev",
+ Biscuit: tok,
+ ExpireTime: timestamppb.New(expAt),
+ TrustedKeys: []*api.TrustedSigningKey{
+ {PublicKey: cpPub, ReceiveTime: timestamppb.New(recvAt)},
+ },
+ RouterAddresses: []string{"/ip4/127.0.0.1/tcp/4001/p2p/" + pid.String()},
+ OidcSession: &api.OIDCSession{
+ Issuer: "https://accounts.example.com",
+ ClientId: "meshnet-cli",
+ RefreshToken: "rt-initial",
+ },
+ IssuedUnderKeys: [][]byte{cpPub},
+ }
+
+ dir := filepath.Join(t.TempDir(), "state")
+ if err := WriteStateDir(dir, privBytes, want); err != nil {
+ t.Fatalf("WriteStateDir: %v", err)
+ }
+
+ dirInfo, err := os.Stat(dir)
+ if err != nil {
+ t.Fatalf("Stat(%s): %v", dir, err)
+ }
+ if perm := dirInfo.Mode().Perm(); perm != 0o700 {
+ t.Errorf("dir perm = %04o, want 0700", perm)
+ }
+ for _, name := range []string{StateDirIdentityFile, StateDirCredentialFile} {
+ fi, err := os.Stat(filepath.Join(dir, name))
+ if err != nil {
+ t.Fatalf("Stat(%s): %v", name, err)
+ }
+ if perm := fi.Mode().Perm(); perm != 0o600 {
+ t.Errorf("%s perm = %04o, want 0600", name, perm)
+ }
+ }
+
+ gotPriv, gotCred, err := ReadStateDir(dir)
+ if err != nil {
+ t.Fatalf("ReadStateDir: %v", err)
+ }
+ if !bytes.Equal(gotPriv, privBytes) {
+ t.Errorf("ReadStateDir privKey mismatch")
+ }
+ if !proto.Equal(gotCred, want) {
+ t.Errorf("ReadStateDir credential mismatch:\ngot: %v\nwant: %v", gotCred, want)
+ }
+
+ t.Run("rejects_invalid_private_key", func(t *testing.T) {
+ if err := WriteStateDir(t.TempDir(), []byte("not-a-key"), want); err == nil {
+ t.Fatal("WriteStateDir accepted invalid private key, want error")
+ }
+ badDir := t.TempDir()
+ if err := os.WriteFile(filepath.Join(badDir, StateDirIdentityFile), []byte("corrupt"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := ReadStateDir(badDir); err == nil {
+ t.Fatal("ReadStateDir accepted corrupt identity.key, want error")
+ }
+ })
+
+ t.Run("rejects_unknown_fields_in_credential_json", func(t *testing.T) {
+ badDir := t.TempDir()
+ if err := WriteStateDir(badDir, privBytes, want); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(badDir, StateDirCredentialFile), []byte(`{"control_plane_url":"https://example.com","unknown_field":true}`), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := ReadStateDir(badDir); err == nil {
+ t.Fatal("ReadStateDir accepted unknown field in credential.json, want error")
+ }
+ })
+}
+
+func TestEnrollmentAndRenewal(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+ defer cancel()
+
+ cp := newFakeControlPlaneHTTP(t)
+
+ t.Run("bootstrap_pending_then_approved", func(t *testing.T) {
+ cp.pendingBootstrapPolls.Store(1)
+ tokFile := filepath.Join(t.TempDir(), "bootstrap.token")
+ if err := os.WriteFile(tokFile, []byte("boot-secret\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ stateDir := t.TempDir()
+ s := &Server{
+ StateDir: stateDir,
+ ControlPlaneURL: cp.srv.URL,
+ BootstrapTokenPath: tokFile,
+ AllowInsecure: true,
+ }
+ if err := s.ensureCredential(ctx); err != nil {
+ t.Fatalf("ensureCredential: %v", err)
+ }
+ if len(s.currentBiscuit()) == 0 {
+ t.Fatal("currentBiscuit is empty after bootstrap enrollment")
+ }
+ _, cred, err := ReadStateDir(stateDir)
+ if err != nil {
+ t.Fatalf("ReadStateDir: %v", err)
+ }
+ if cred.GetControlPlaneUrl() != cp.srv.URL {
+ t.Errorf("ControlPlaneUrl = %q, want %q", cred.GetControlPlaneUrl(), cp.srv.URL)
+ }
+ if len(cred.GetTrustedKeys()) == 0 {
+ t.Error("TrustedKeys not persisted in credential.json")
+ }
+ })
+
+ t.Run("resume_cached_credential_and_offline_fallback", func(t *testing.T) {
+ stateDir := t.TempDir()
+ seed := &Server{
+ StateDir: stateDir,
+ ControlPlaneURL: cp.srv.URL,
+ BootstrapToken: "boot-secret",
+ AllowInsecure: true,
+ }
+ if err := seed.ensureCredential(ctx); err != nil {
+ t.Fatalf("seed ensureCredential: %v", err)
+ }
+ enrollsBefore := cp.bootstrapEnrolls.Load()
+ refreshesBefore := cp.refreshes.Load()
+
+ // 1. Online resume: >5m remaining and valid signing key skips both /refresh and /enroll.
+ online := &Server{
+ StateDir: stateDir,
+ AllowInsecure: true,
+ }
+ if err := online.ensureCredential(ctx); err != nil {
+ t.Fatalf("online resume ensureCredential: %v", err)
+ }
+ if cp.bootstrapEnrolls.Load() != enrollsBefore || cp.refreshes.Load() != refreshesBefore {
+ t.Errorf("online resume called enroll/refresh (%d/%d), want (%d/%d)",
+ cp.bootstrapEnrolls.Load(), cp.refreshes.Load(), enrollsBefore, refreshesBefore)
+ }
+
+ // 2. Offline control plane fallback: /keys and /refresh both unavailable, cached credential used.
+ cp.failKeys.Store(true)
+ cp.failRefresh.Store(true)
+ defer func() {
+ cp.failKeys.Store(false)
+ cp.failRefresh.Store(false)
+ }()
+
+ resumed := &Server{
+ StateDir: stateDir,
+ AllowInsecure: true,
+ }
+ if err := resumed.ensureCredential(ctx); err != nil {
+ t.Fatalf("resumed ensureCredential with offline CP: %v", err)
+ }
+ if cp.bootstrapEnrolls.Load() != enrollsBefore {
+ t.Errorf("bootstrapEnrolls = %d, want %d (must resume cached credential)", cp.bootstrapEnrolls.Load(), enrollsBefore)
+ }
+ if resumed.cpURL != cp.srv.URL {
+ t.Errorf("resumed.cpURL = %q, want %q", resumed.cpURL, cp.srv.URL)
+ }
+ })
+
+ t.Run("jwt_path_and_proactive_refresh", func(t *testing.T) {
+ jwtFile := filepath.Join(t.TempDir(), "id.jwt")
+ if err := os.WriteFile(jwtFile, []byte("jwt-initial\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ stateDir := t.TempDir()
+ s := &Server{
+ StateDir: stateDir,
+ ControlPlaneURL: cp.srv.URL,
+ JWTPath: jwtFile,
+ TokenSource: func(context.Context) (string, error) {
+ return "jwt-refreshed", nil
+ },
+ Labels: map[string]string{"env": "prod"},
+ AllowInsecure: true,
+ }
+ if err := s.ensureCredential(ctx); err != nil {
+ t.Fatalf("ensureCredential(JWT): %v", err)
+ }
+ firstBiscuit := append([]byte(nil), s.currentBiscuit()...)
+ refreshesBefore := cp.refreshes.Load()
+
+ if err := s.Refresh(ctx); err != nil {
+ t.Fatalf("Refresh: %v", err)
+ }
+ if cp.refreshes.Load() != refreshesBefore+1 {
+ t.Errorf("refreshes = %d, want %d", cp.refreshes.Load(), refreshesBefore+1)
+ }
+ if bytes.Equal(firstBiscuit, s.currentBiscuit()) {
+ t.Error("expected Refresh to update credential via POST /refresh")
+ }
+ })
+
+ t.Run("oidc_session_refresh_token_recovery", func(t *testing.T) {
+ priv, _, err := crypto.GenerateEd25519Key(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+ privBytes, err := crypto.MarshalPrivateKey(priv)
+ if err != nil {
+ t.Fatal(err)
+ }
+ pid, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatal(err)
+ }
+ cpPub, cpPriv := cp.currentKeys()
+ nearExpired := mintTestBiscuit(t, cpPriv, pid.String(), api.RoleNode, time.Now().Add(time.Minute))
+
+ // Reject direct /refresh so ensureCredential falls back to OIDC refresh_token -> /register.
+ cp.failRefresh.Store(true)
+ defer cp.failRefresh.Store(false)
+
+ stateDir := t.TempDir()
+ err = WriteStateDir(stateDir, privBytes, &api.MemberCredential{
+ ControlPlaneUrl: cp.srv.URL,
+ Biscuit: nearExpired,
+ ExpireTime: timestamppb.New(time.Now().Add(time.Minute)),
+ TrustedKeys: []*api.TrustedSigningKey{{PublicKey: cpPub, ReceiveTime: timestamppb.New(time.Now())}},
+ OidcSession: &api.OIDCSession{
+ Issuer: cp.srv.URL,
+ ClientId: "meshnet-test",
+ RefreshToken: "rt-old",
+ },
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ s := &Server{
+ StateDir: stateDir,
+ AllowInsecure: true,
+ }
+ if err := s.ensureCredential(ctx); err != nil {
+ t.Fatalf("ensureCredential via OIDC refresh_token: %v", err)
+ }
+ _, updated, err := ReadStateDir(stateDir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got := updated.GetOidcSession().GetRefreshToken(); got != "rt-rotated" {
+ t.Errorf("rotated refresh_token = %q, want %q", got, "rt-rotated")
+ }
+ })
+
+ t.Run("retired_signing_key_returns_ErrCredentialRetired", func(t *testing.T) {
+ stateDir := t.TempDir()
+ seed := &Server{
+ StateDir: stateDir,
+ ControlPlaneURL: cp.srv.URL,
+ BootstrapToken: "boot-secret",
+ AllowInsecure: true,
+ }
+ if err := seed.ensureCredential(ctx); err != nil {
+ t.Fatalf("seed ensureCredential: %v", err)
+ }
+
+ // Rotate control-plane key completely (dropping old key from KeysResponse).
+ cp.rotateKeyHard(t)
+
+ resumed := &Server{
+ StateDir: stateDir,
+ AllowInsecure: true,
+ }
+ err := resumed.ensureCredential(ctx)
+ if !errors.Is(err, ErrCredentialRetired) {
+ t.Fatalf("ensureCredential err = %v, want ErrCredentialRetired", err)
+ }
+ })
+
+ t.Run("rejects_non_loopback_plaintext_http_without_AllowInsecure", func(t *testing.T) {
+ s := &Server{
+ ControlPlaneURL: "http://198.51.100.10:8080",
+ BootstrapToken: "boot-secret",
+ AllowInsecure: false,
+ }
+ err := s.ensureCredential(ctx)
+ if !errors.Is(err, api.ErrInsecureControlPlaneURL) {
+ t.Fatalf("ensureCredential err = %v, want api.ErrInsecureControlPlaneURL", err)
+ }
+ })
+}
+
+type fakeControlPlaneHTTP struct {
+ mu sync.Mutex
+ cpPub ed25519.PublicKey
+ cpPriv ed25519.PrivateKey
+ routerAddrs []string
+ srv *httptest.Server
+ failKeys atomic.Bool
+ failRefresh atomic.Bool
+ pendingBootstrapPolls atomic.Int32
+ bootstrapEnrolls atomic.Int32
+ refreshes atomic.Int32
+}
+
+func newFakeControlPlaneHTTP(t *testing.T) *fakeControlPlaneHTTP {
+ t.Helper()
+ pub, priv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+ return newFakeControlPlaneHTTPWithKeys(t, pub, priv, nil)
+}
+
+func newFakeControlPlaneHTTPWithKeys(t *testing.T, pub ed25519.PublicKey, priv ed25519.PrivateKey, routerAddrs []string) *fakeControlPlaneHTTP {
+ t.Helper()
+ f := &fakeControlPlaneHTTP{cpPub: pub, cpPriv: priv, routerAddrs: routerAddrs}
+ mux := http.NewServeMux()
+ mux.HandleFunc("/keys", func(w http.ResponseWriter, _ *http.Request) {
+ if f.failKeys.Load() {
+ http.Error(w, "offline", http.StatusServiceUnavailable)
+ return
+ }
+ pubKey, privKey := f.currentKeys()
+ resp := &api.KeysResponse{PublicKeys: [][]byte{pubKey}}
+ if err := api.SignKeysResponse(resp, []ed25519.PrivateKey{privKey}, time.Now()); err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ writeProto(w, resp)
+ })
+ mux.HandleFunc("/info", func(w http.ResponseWriter, _ *http.Request) {
+ f.mu.Lock()
+ addrs := append([]string(nil), f.routerAddrs...)
+ f.mu.Unlock()
+ writeProto(w, &api.ControlPlaneInfoResponse{RouterAddresses: addrs})
+ })
+ mux.HandleFunc("/policies", func(w http.ResponseWriter, _ *http.Request) {
+ compiled, _ := api.BuildPolicyRules([]*api.PolicyRole{
+ {
+ Name: api.RoleNode,
+ AllowedTargets: []string{"*"},
+ AllowedServices: []string{"*"},
+ AllowedPublish: []string{"*"},
+ },
+ }, nil)
+ texts := make([]string, 0, len(compiled))
+ for _, r := range compiled {
+ texts = append(texts, r.Text)
+ }
+ writeProto(w, &api.PolicyConfigGetResponse{DatalogRules: texts})
+ })
+ mux.HandleFunc("/revocations", func(w http.ResponseWriter, _ *http.Request) {
+ writeProto(w, &api.RevocationsResponse{})
+ })
+ mux.HandleFunc("/enroll", func(w http.ResponseWriter, r *http.Request) {
+ f.bootstrapEnrolls.Add(1)
+ var req api.BootstrapEnrollRequest
+ if !readProto(w, r, &req) {
+ return
+ }
+ if req.GetBootstrapToken() != "boot-secret" {
+ http.Error(w, "bad token", http.StatusUnauthorized)
+ return
+ }
+ if f.pendingBootstrapPolls.Load() > 0 {
+ writeProto(w, &api.BootstrapEnrollResponse{
+ Status: api.EnrollmentStatus_ENROLLMENT_STATUS_PENDING,
+ PollIntervalSeconds: 1,
+ })
+ return
+ }
+ pubKey, privKey := f.currentKeys()
+ f.mu.Lock()
+ addrs := append([]string(nil), f.routerAddrs...)
+ f.mu.Unlock()
+ exp := time.Now().Add(time.Hour)
+ tok := mintTestBiscuit(t, privKey, req.GetPeerId(), api.RoleNode, exp)
+ writeProto(w, &api.BootstrapEnrollResponse{
+ Status: api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED,
+ BiscuitToken: tok,
+ ControlPlanePublicKey: pubKey,
+ ExpireTime: timestamppb.New(exp),
+ RouterAddresses: addrs,
+ })
+ })
+ mux.HandleFunc("/enroll/status", func(w http.ResponseWriter, r *http.Request) {
+ peerID := r.URL.Query().Get("peer_id")
+ if peerID == "" {
+ http.Error(w, "missing peer_id", http.StatusBadRequest)
+ return
+ }
+ if f.pendingBootstrapPolls.Add(-1) >= 1 {
+ writeProto(w, &api.BootstrapEnrollResponse{
+ Status: api.EnrollmentStatus_ENROLLMENT_STATUS_PENDING,
+ PollIntervalSeconds: 1,
+ })
+ return
+ }
+ pubKey, privKey := f.currentKeys()
+ f.mu.Lock()
+ addrs := append([]string(nil), f.routerAddrs...)
+ f.mu.Unlock()
+ exp := time.Now().Add(time.Hour)
+ tok := mintTestBiscuit(t, privKey, peerID, api.RoleNode, exp)
+ writeProto(w, &api.BootstrapEnrollResponse{
+ Status: api.EnrollmentStatus_ENROLLMENT_STATUS_APPROVED,
+ BiscuitToken: tok,
+ ControlPlanePublicKey: pubKey,
+ ExpireTime: timestamppb.New(exp),
+ RouterAddresses: addrs,
+ })
+ })
+ mux.HandleFunc("/register", func(w http.ResponseWriter, r *http.Request) {
+ var req api.EnrollRequest
+ if !readProto(w, r, &req) {
+ return
+ }
+ pubKey, privKey := f.currentKeys()
+ f.mu.Lock()
+ addrs := append([]string(nil), f.routerAddrs...)
+ f.mu.Unlock()
+ exp := time.Now().Add(time.Hour)
+ tok := mintTestBiscuit(t, privKey, req.GetPeerId(), api.RoleNode, exp)
+ writeProto(w, &api.EnrollResponse{
+ BiscuitToken: tok,
+ ControlPlanePublicKey: pubKey,
+ ExpireTime: timestamppb.New(exp),
+ RouterAddresses: addrs,
+ })
+ })
+ mux.HandleFunc("/refresh", func(w http.ResponseWriter, r *http.Request) {
+ if f.failRefresh.Load() {
+ http.Error(w, "refresh disabled", http.StatusUnauthorized)
+ return
+ }
+ f.refreshes.Add(1)
+ var req api.TokenRefreshRequest
+ if !readProto(w, r, &req) {
+ return
+ }
+ rawAuth := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
+ biscuitBytes, err := base64.StdEncoding.DecodeString(rawAuth)
+ if err != nil {
+ http.Error(w, "invalid bearer biscuit", http.StatusUnauthorized)
+ return
+ }
+ pubKey, privKey := f.currentKeys()
+ b, err := biscuit.Unmarshal(biscuitBytes)
+ if err != nil {
+ http.Error(w, "invalid biscuit", http.StatusUnauthorized)
+ return
+ }
+ if _, err := b.Authorizer(pubKey); err != nil {
+ http.Error(w, "untrusted biscuit", http.StatusUnauthorized)
+ return
+ }
+ exp := time.Now().Add(2 * time.Hour)
+ tok := mintTestBiscuit(t, privKey, req.GetPeerId(), api.RoleNode, exp)
+ writeProto(w, &api.TokenRefreshResponse{
+ BiscuitToken: tok,
+ ExpireTime: timestamppb.New(exp),
+ })
+ })
+ mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(map[string]string{
+ "token_endpoint": f.srv.URL + "/oidc/token",
+ })
+ })
+ mux.HandleFunc("/oidc/token", func(w http.ResponseWriter, r *http.Request) {
+ if err := r.ParseForm(); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ if r.FormValue("grant_type") != "refresh_token" || r.FormValue("refresh_token") != "rt-old" {
+ http.Error(w, "bad refresh_token", http.StatusUnauthorized)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(map[string]string{
+ "id_token": "oidc-refreshed-id-token",
+ "refresh_token": "rt-rotated",
+ })
+ })
+
+ f.srv = httptest.NewServer(mux)
+ t.Cleanup(f.srv.Close)
+ return f
+}
+
+func (f *fakeControlPlaneHTTP) currentKeys() (ed25519.PublicKey, ed25519.PrivateKey) {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ return f.cpPub, f.cpPriv
+}
+
+func (f *fakeControlPlaneHTTP) rotateKeyHard(t *testing.T) {
+ t.Helper()
+ pub, priv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+ f.mu.Lock()
+ f.cpPub = pub
+ f.cpPriv = priv
+ f.mu.Unlock()
+}
+
+func readProto(w http.ResponseWriter, r *http.Request, msg proto.Message) bool {
+ body, err := io.ReadAll(r.Body)
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return false
+ }
+ if err := proto.Unmarshal(body, msg); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return false
+ }
+ return true
+}
+
+func writeProto(w http.ResponseWriter, msg proto.Message) {
+ raw, err := proto.Marshal(msg)
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ w.Header().Set("Content-Type", "application/x-protobuf")
+ _, _ = w.Write(raw)
+}
+
+func mintTestBiscuit(t *testing.T, cpPriv ed25519.PrivateKey, peerID, role string, expiry time.Time) []byte {
+ t.Helper()
+ b := biscuit.NewBuilder(cpPriv)
+ for _, f := range []biscuit.Fact{
+ {Predicate: biscuit.Predicate{Name: api.FactNode, IDs: []biscuit.Term{biscuit.String(peerID)}}},
+ {Predicate: biscuit.Predicate{Name: api.FactClientPeerID, IDs: []biscuit.Term{biscuit.String(peerID)}}},
+ {Predicate: biscuit.Predicate{Name: api.FactRole, IDs: []biscuit.Term{biscuit.String(role)}}},
+ {Predicate: biscuit.Predicate{Name: api.FactEmail, IDs: []biscuit.Term{biscuit.String("[email protected]")}}},
+ {Predicate: biscuit.Predicate{Name: api.FactLabel, IDs: []biscuit.Term{biscuit.String("env"), biscuit.String("prod")}}},
+ {Predicate: biscuit.Predicate{Name: api.FactExpiration, IDs: []biscuit.Term{biscuit.Date(expiry)}}},
+ api.MarkerFact(api.FactTargetUnrestricted),
+ } {
+ if err := b.AddAuthorityFact(f); err != nil {
+ t.Fatalf("AddAuthorityFact: %v", err)
+ }
+ }
+ tok, err := b.Build()
+ if err != nil {
+ t.Fatalf("Build: %v", err)
+ }
+ out, err := tok.Serialize()
+ if err != nil {
+ t.Fatalf("Serialize: %v", err)
+ }
+ return out
+}
diff --git a/tests/integration/meshnet_test.go b/tests/integration/meshnet_test.go
new file mode 100644
index 00000000..72ceaaaf
--- /dev/null
+++ b/tests/integration/meshnet_test.go
@@ -0,0 +1,739 @@
+// 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 integration_test
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "iter"
+ "net/http"
+ "net/http/httptest"
+ "path/filepath"
+ "strings"
+ "sync"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "github.com/a2aproject/a2a-go/v2/a2a"
+ "github.com/a2aproject/a2a-go/v2/a2aclient"
+ "github.com/a2aproject/a2a-go/v2/a2aclient/agentcard"
+ "github.com/a2aproject/a2a-go/v2/a2asrv"
+ "github.com/google/agentmesh/api"
+ "github.com/google/agentmesh/internal/node"
+ "github.com/google/agentmesh/internal/standalone"
+ "github.com/google/agentmesh/sdk/meshnet"
+ "github.com/libp2p/go-libp2p/core/crypto"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+ "google.golang.org/protobuf/proto"
+)
+
+// TestMeshnetStateDirInterop verifies byte-for-byte compatibility between
+// agentmesh-node state export/import and sdk/meshnet's StateDir in both directions.
+func TestMeshnetStateDirInterop(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+
+ srv, err := standalone.New(standalone.Options{
+ BindAddress: "127.0.0.1:0",
+ DataDir: t.TempDir(),
+ })
+ if err != nil {
+ t.Fatalf("standalone.New: %v", err)
+ }
+ if err := srv.Start(ctx); err != nil {
+ t.Fatalf("standalone.Start: %v", err)
+ }
+ t.Cleanup(func() { _ = srv.Close() })
+
+ // 1. Enroll with agentmesh-node -> export StateDir -> resume in meshnet.Server.
+ nodeStoreDir := t.TempDir()
+ nodeStore, err := node.NewStore(nodeStoreDir)
+ if err != nil {
+ t.Fatalf("NewStore: %v", err)
+ }
+ priv := node.GetOrGenerateKey(nodeStore)
+ wantPeerID, err := peer.IDFromPrivateKey(priv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+ enrollNode, err := node.NewAgentMeshNode(node.Options{
+ PrivKey: priv,
+ Store: nodeStore,
+ ListenAddrs: []string{"/ip4/127.0.0.1/tcp/0"},
+ AllowLoopback: true,
+ RequiredRole: api.RoleNode,
+ })
+ if err != nil {
+ t.Fatalf("NewAgentMeshNode: %v", err)
+ }
+ if err := enrollNode.Start(ctx); err != nil {
+ t.Fatalf("enrollNode.Start: %v", err)
+ }
+ if err := enrollNode.EnrollBootstrap(ctx, srv.PublicURL(), srv.JoinToken()); err != nil {
+ _ = enrollNode.Teardown()
+ t.Fatalf("EnrollBootstrap: %v", err)
+ }
+ if err := nodeStore.SaveControlPlaneURL(srv.PublicURL()); err != nil {
+ t.Fatalf("SaveControlPlaneURL: %v", err)
+ }
+ _ = enrollNode.Teardown()
+
+ keyBytes, err := nodeStore.LoadKey()
+ if err != nil {
+ t.Fatalf("LoadKey: %v", err)
+ }
+ exportedCred, err := nodeStore.Credential()
+ if err != nil {
+ t.Fatalf("Credential: %v", err)
+ }
+ _ = nodeStore.Close()
+
+ exportedDir := filepath.Join(t.TempDir(), "from-node")
+ if err := node.WriteStateDir(exportedDir, keyBytes, exportedCred); err != nil {
+ t.Fatalf("node.WriteStateDir: %v", err)
+ }
+
+ gotKey, gotCred, err := meshnet.ReadStateDir(exportedDir)
+ if err != nil {
+ t.Fatalf("meshnet.ReadStateDir: %v", err)
+ }
+ if !bytes.Equal(gotKey, keyBytes) || !proto.Equal(gotCred, exportedCred) {
+ t.Fatalf("meshnet.ReadStateDir did not round-trip node.WriteStateDir")
+ }
+
+ resumed := &meshnet.Server{
+ StateDir: exportedDir,
+ ListenAddrs: []string{"/ip4/127.0.0.1/tcp/0"},
+ AllowInsecure: true,
+ }
+ st, err := resumed.Up(ctx)
+ if err != nil {
+ t.Fatalf("resumed.Up: %v", err)
+ }
+ t.Cleanup(func() { _ = resumed.Close() })
+ if st.PeerID != wantPeerID.String() {
+ t.Fatalf("resumed PeerID = %q, want %q", st.PeerID, wantPeerID.String())
+ }
+
+ // 2. Enroll fresh meshnet.Server -> read its StateDir via node.ReadStateDir & import into node.Store.
+ fromMeshnetDir := filepath.Join(t.TempDir(), "from-meshnet")
+ fresh := &meshnet.Server{
+ StateDir: fromMeshnetDir,
+ ControlPlaneURL: srv.PublicURL(),
+ BootstrapToken: srv.JoinToken(),
+ ListenAddrs: []string{"/ip4/127.0.0.1/tcp/0"},
+ AllowInsecure: true,
+ }
+ freshSt, err := fresh.Up(ctx)
+ if err != nil {
+ t.Fatalf("fresh.Up: %v", err)
+ }
+ _ = fresh.Close()
+
+ impKey, impCred, err := node.ReadStateDir(fromMeshnetDir)
+ if err != nil {
+ t.Fatalf("node.ReadStateDir(fromMeshnetDir): %v", err)
+ }
+ impPriv, err := crypto.UnmarshalPrivateKey(impKey)
+ if err != nil {
+ t.Fatalf("UnmarshalPrivateKey: %v", err)
+ }
+ impPID, err := peer.IDFromPrivateKey(impPriv)
+ if err != nil {
+ t.Fatalf("IDFromPrivateKey: %v", err)
+ }
+ if impPID.String() != freshSt.PeerID {
+ t.Fatalf("imported PeerID = %q, want %q", impPID.String(), freshSt.PeerID)
+ }
+
+ destStore, err := node.NewStore(t.TempDir())
+ if err != nil {
+ t.Fatalf("NewStore(dest): %v", err)
+ }
+ defer func() { _ = destStore.Close() }()
+ if err := destStore.SaveKey(impKey); err != nil {
+ t.Fatalf("SaveKey: %v", err)
+ }
+ if err := destStore.SetCredential(impCred); err != nil {
+ t.Fatalf("SetCredential: %v", err)
+ }
+}
+
+// TestMeshnetEndToEndIntegration exercises the complete embedded Go SDK surface
+// against a real standalone.Server + agentmesh-node:
+// - Private P2P A2A serving & calling (ListenA2A, Discover, HTTPClient, WhoIs, SSE)
+// - External HTTP Ingress in EDGE mode (anonymous card, OIDC /oauth/token, AttenuateToken TAR)
+// and PASSTHROUGH mode (app pair token + X-Mesh-* header sanitization)
+// - Policy-ceiling fallback when allowed_ingress denies public exposure
+// - Local MCPHandler progressive discovery (find_remote_tools -> describe_remote_tool -> call_remote_tool)
+// - Local InferenceHandler zero-secret OpenAI /v1/models + /v1/chat/completions + label floor
+func TestMeshnetEndToEndIntegration(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+
+ oidcURL, mintJWT := startCustomMockOIDC(t)
+
+ srv, err := standalone.New(standalone.Options{
+ BindAddress: "127.0.0.1:0",
+ DataDir: t.TempDir(),
+ OIDCIssuer: oidcURL,
+ AllowedAudiences: []string{"agentmesh-audience"},
+ })
+ if err != nil {
+ t.Fatalf("standalone.New: %v", err)
+ }
+ if err := srv.Start(ctx); err != nil {
+ t.Fatalf("standalone.Start: %v", err)
+ }
+ t.Cleanup(func() { _ = srv.Close() })
+
+ // Policy grants public ingress ONLY for a2a://coder and a2a://paired so that
+ // a2a://ceiling-blocked exercises the policy-ceiling fallback path.
+ postOperatorPolicy(t, ctx, srv.PublicURL(), srv.AdminToken(), &api.PolicyConfig{
+ Roles: []*api.PolicyRole{
+ {
+ Name: api.RoleRouter,
+ AllowedTargets: []string{"*"},
+ AllowedServices: []string{"*"},
+ },
+ {
+ Name: api.RoleNode,
+ AllowedTargets: []string{"*"},
+ AllowedServices: []string{"*"},
+ AllowedPublish: []string{"*"},
+ AllowedLabels: []string{"env=*"},
+ AllowedIngress: []*api.IngressGrant{
+ {
+ Services: []string{"a2a://coder"},
+ AllowedAuthModes: []api.IngressAuthMode{
+ api.IngressAuthMode_INGRESS_AUTH_MODE_EDGE,
+ },
+ },
+ {
+ Services: []string{"a2a://paired"},
+ AllowedAuthModes: []api.IngressAuthMode{
+ api.IngressAuthMode_INGRESS_AUTH_MODE_PASSTHROUGH,
+ },
+ },
+ },
+ },
+ {
+ Name: "external-caller",
+ AllowedTargets: []string{"*"},
+ AllowedServices: []string{"a2a://coder"},
+ },
+ },
+ Bindings: []*api.PolicyBinding{
+ {
+ Role: "external-caller",
+ Members: []string{"email:[email protected]", "email:[email protected]"},
+ },
+ },
+ })
+
+ // 1. Start an agentmesh-node hosting mcp://tools and inference://llm.
+ type echoArgs struct {
+ Message string `json:"message"`
+ }
+ mcpBackendSrv := mcp.NewServer(&mcp.Implementation{Name: "tools", Version: "1.0.0"}, nil)
+ mcp.AddTool(mcpBackendSrv, &mcp.Tool{
+ Name: "echo_arg",
+ Description: "Echoes a message back to the caller",
+ }, func(_ context.Context, _ *mcp.CallToolRequest, args echoArgs) (*mcp.CallToolResult, any, error) {
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: "echo:" + args.Message}},
+ }, nil, nil
+ })
+ mcpBackend := httptest.NewServer(mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return mcpBackendSrv }, nil))
+ t.Cleanup(mcpBackend.Close)
+
+ infMux := http.NewServeMux()
+ infMux.HandleFunc("/v1/models", func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"object":"list","data":[{"id":"mesh-qwen","object":"model"}]}`))
+ })
+ infMux.HandleFunc("/v1/chat/completions", func(w http.ResponseWriter, r *http.Request) {
+ var body struct {
+ Model string `json:"model"`
+ Stream bool `json:"stream"`
+ }
+ _ = json.NewDecoder(r.Body).Decode(&body)
+ if body.Stream {
+ w.Header().Set("Content-Type", "text/event-stream")
+ flusher, _ := w.(http.Flusher)
+ _, _ = fmt.Fprintf(w, "data: {\"id\":\"cmpl-1\",\"model\":%q,\"choices\":[{\"delta\":{\"content\":\"hi\"}}]}\n\n", body.Model)
+ if flusher != nil {
+ flusher.Flush()
+ }
+ _, _ = io.WriteString(w, "data: [DONE]\n\n")
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = fmt.Fprintf(w, `{"id":"cmpl-1","model":%q,"choices":[{"message":{"role":"assistant","content":"mesh-reply"}}]}`, body.Model)
+ })
+ infBackend := httptest.NewServer(infMux)
+ t.Cleanup(infBackend.Close)
+
+ providerNode := enrollAndStartRuntimeNode(
+ t,
+ ctx,
+ srv.PublicURL(),
+ srv.JoinToken(),
+ "",
+ nil,
+ node.ReachabilityAuto,
+ []string{"/ip4/127.0.0.1/tcp/0"},
+ []api.ServiceConfig{
+ {Type: "mcp", Name: "tools", Description: "Workspace tools", TargetURL: mcpBackend.URL},
+ {Type: "inference", Name: "llm", Description: "Mesh Qwen LLM", TargetURL: infBackend.URL},
+ },
+ )
+ providerPeerID := providerNode.Host.ID().String()
+
+ // 2. Start two embedded meshnet.Server instances (srvA = A2A provider, srvB = consumer).
+ srvA := &meshnet.Server{
+ StateDir: t.TempDir(),
+ ControlPlaneURL: srv.PublicURL(),
+ BootstrapToken: srv.JoinToken(),
+ Labels: map[string]string{"env": "prod"},
+ ListenAddrs: []string{"/ip4/127.0.0.1/tcp/0"},
+ AllowInsecure: true,
+ }
+ stA, err := srvA.Up(ctx)
+ if err != nil {
+ t.Fatalf("srvA.Up: %v", err)
+ }
+ t.Cleanup(func() { _ = srvA.Close() })
+
+ srvB := &meshnet.Server{
+ StateDir: t.TempDir(),
+ ControlPlaneURL: srv.PublicURL(),
+ BootstrapToken: srv.JoinToken(),
+ Labels: map[string]string{"env": "dev"},
+ ListenAddrs: []string{"/ip4/127.0.0.1/tcp/0"},
+ AllowInsecure: true,
+ }
+ stB, err := srvB.Up(ctx)
+ if err != nil {
+ t.Fatalf("srvB.Up: %v", err)
+ }
+ t.Cleanup(func() { _ = srvB.Close() })
+
+ // 3. Register A2A services on srvA:
+ // - coder (Public EDGE, allow carol + srvB node)
+ // - paired (Public PASSTHROUGH)
+ // - ceiling-blocked (Public EDGE requested, denied by allowed_ingress -> falls back to private-only)
+ coderEP, err := srvA.ListenA2A(ctx, meshnet.A2AOptions{
+ Name: "coder",
+ Description: "Embedded Go SDK coding agent",
+ Public: true,
+ IngressAuth: api.IngressAuthMode_INGRESS_AUTH_MODE_EDGE,
+ IngressAllow: []string{"email:[email protected]", "node:" + stB.PeerID},
+ })
+ if err != nil {
+ t.Fatalf("ListenA2A(coder): %v", err)
+ }
+ t.Cleanup(func() { _ = coderEP.Close() })
+ if coderEP.PublicURL == nil {
+ t.Fatalf("coderEP.PublicURL is nil, want %s/%s/a2a/coder", srv.IngressURL(), stA.PeerID)
+ }
+
+ var coderWhoIsMu sync.Mutex
+ var lastCoderWhoIs meshnet.CallerInfo
+
+ coderExec := a2asrv.AgentExecutorFunc(func(ctx context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
+ return func(yield func(a2a.Event, error) bool) {
+ if len(ec.Message.Parts) > 0 && ec.Message.Parts[0].Text() == "stream" {
+ if !yield(a2a.NewSubmittedTask(ec, ec.Message), nil) {
+ return
+ }
+ yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateCompleted, a2a.NewMessageForTask(a2a.MessageRoleAgent, ec, a2a.NewTextPart("stream-ok"))), nil)
+ return
+ }
+ yield(a2a.NewMessageForTask(a2a.MessageRoleAgent, ec, a2a.NewTextPart("meshnet-hello")), nil)
+ }
+ })
+ coderCard := &a2a.AgentCard{
+ Name: "coder",
+ Description: "Embedded Go SDK coding agent",
+ Version: "1.0.0",
+ Capabilities: a2a.AgentCapabilities{Streaming: true},
+ SupportedInterfaces: []*a2a.AgentInterface{
+ {URL: coderEP.PrivateURL.String() + "/invoke", ProtocolBinding: a2a.TransportProtocolJSONRPC, ProtocolVersion: "1.0"},
+ },
+ }
+ coderMux := http.NewServeMux()
+ coderMux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(coderCard))
+ coderMux.Handle("/invoke", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if info, ok := srvA.WhoIs(r.RemoteAddr); ok && info != nil {
+ coderWhoIsMu.Lock()
+ lastCoderWhoIs = *info
+ coderWhoIsMu.Unlock()
+ }
+ a2asrv.NewJSONRPCHandler(a2asrv.NewHandler(coderExec)).ServeHTTP(w, r)
+ }))
+ coderPrivHTTP := &http.Server{Handler: coderMux}
+ coderPubHTTP := &http.Server{Handler: coderMux}
+ go func() { _ = coderPrivHTTP.Serve(coderEP.PrivateListener) }()
+ go func() { _ = coderPubHTTP.Serve(coderEP.PublicListener) }()
+ t.Cleanup(func() {
+ _ = coderPrivHTTP.Close()
+ _ = coderPubHTTP.Close()
+ })
+
+ // PASSTHROUGH service on srvA.
+ pairedEP, err := srvA.ListenA2A(ctx, meshnet.A2AOptions{
+ Name: "paired",
+ Description: "Pair-token A2A service",
+ Public: true,
+ IngressAuth: api.IngressAuthMode_INGRESS_AUTH_MODE_PASSTHROUGH,
+ })
+ if err != nil {
+ t.Fatalf("ListenA2A(paired): %v", err)
+ }
+ t.Cleanup(func() { _ = pairedEP.Close() })
+ if pairedEP.PublicURL == nil {
+ t.Fatal("pairedEP.PublicURL is nil, want public URL")
+ }
+
+ var passthroughClean atomic.Bool
+ pairedExec := a2asrv.AgentExecutorFunc(func(_ context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
+ return func(yield func(a2a.Event, error) bool) {
+ yield(a2a.NewMessageForTask(a2a.MessageRoleAgent, ec, a2a.NewTextPart("paired-ok")), nil)
+ }
+ })
+ pairedCard := &a2a.AgentCard{
+ Name: "paired",
+ Description: "Pair-token A2A service",
+ Version: "1.0.0",
+ SupportedInterfaces: []*a2a.AgentInterface{
+ {URL: pairedEP.PublicURL.String() + "/invoke", ProtocolBinding: a2a.TransportProtocolJSONRPC, ProtocolVersion: "1.0"},
+ },
+ }
+ pairedMux := http.NewServeMux()
+ pairedMux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(pairedCard))
+ pairedMux.Handle("/invoke", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Header.Get(api.HeaderMeshPrincipal) == "" && r.Header.Get(api.HeaderMeshIngress) == api.IngressAuthModeStringPassthrough {
+ passthroughClean.Store(true)
+ }
+ if r.Header.Get("Authorization") != "Bearer pair-secret-123" {
+ http.Error(w, "unauthorized", http.StatusUnauthorized)
+ return
+ }
+ a2asrv.NewJSONRPCHandler(a2asrv.NewHandler(pairedExec)).ServeHTTP(w, r)
+ }))
+ pairedPubHTTP := &http.Server{Handler: pairedMux}
+ go func() { _ = pairedPubHTTP.Serve(pairedEP.PublicListener) }()
+ t.Cleanup(func() { _ = pairedPubHTTP.Close() })
+
+ // Policy-ceiling fallback service on srvA: Public=true requested, hub denies ingress,
+ // so PublicURL is nil while PrivateListener continues serving internal mesh peers.
+ blockedEP, err := srvA.ListenA2A(ctx, meshnet.A2AOptions{
+ Name: "ceiling-blocked",
+ Description: "Policy ceiling fallback service",
+ Public: true,
+ IngressAuth: api.IngressAuthMode_INGRESS_AUTH_MODE_EDGE,
+ })
+ if err != nil {
+ t.Fatalf("ListenA2A(ceiling-blocked): %v", err)
+ }
+ t.Cleanup(func() { _ = blockedEP.Close() })
+ if blockedEP.PublicURL != nil {
+ t.Fatalf("blockedEP.PublicURL = %v, want nil when policy ceiling denies ingress", blockedEP.PublicURL)
+ }
+ blockedPrivHTTP := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write([]byte("private-still-works"))
+ })}
+ go func() { _ = blockedPrivHTTP.Serve(blockedEP.PrivateListener) }()
+ t.Cleanup(func() { _ = blockedPrivHTTP.Close() })
+
+ // 4. Verify Private P2P A2A from srvB -> srvA (Discover + AgentCard + SendMessage + SSE + WhoIs).
+ var foundCoder string
+ deadline := time.Now().Add(5 * time.Second)
+ for {
+ providers, dErr := srvB.Discover(ctx, api.ServiceType_SERVICE_TYPE_A2A, "coder")
+ if dErr == nil && len(providers) > 0 {
+ foundCoder = providers[0].GetLocalProxyUrl()
+ break
+ }
+ if time.Now().After(deadline) {
+ t.Fatalf("srvB.Discover(coder) timed out; last err=%v", dErr)
+ }
+ time.Sleep(25 * time.Millisecond)
+ }
+ if foundCoder != coderEP.PrivateURL.String() {
+ t.Fatalf("discovered URL = %q, want %q", foundCoder, coderEP.PrivateURL.String())
+ }
+
+ privCard, err := agentcard.NewResolver(srvB.HTTPClient()).Resolve(ctx, foundCoder)
+ if err != nil {
+ t.Fatalf("Resolve private coder card: %v", err)
+ }
+ privA2AClient, err := a2aclient.NewFromCard(ctx, privCard, a2aclient.WithJSONRPCTransport(srvB.HTTPClient()))
+ if err != nil {
+ t.Fatalf("a2aclient.NewFromCard(private): %v", err)
+ }
+ privRes, err := privA2AClient.SendMessage(ctx, &a2a.SendMessageRequest{
+ Message: a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("hello")),
+ })
+ if err != nil {
+ t.Fatalf("private SendMessage: %v", err)
+ }
+ if msg, ok := privRes.(*a2a.Message); !ok || len(msg.Parts) == 0 || msg.Parts[0].Text() != "meshnet-hello" {
+ t.Fatalf("private SendMessage reply = %#v, want meshnet-hello", privRes)
+ }
+ coderWhoIsMu.Lock()
+ gotPrivWhoIs := lastCoderWhoIs
+ coderWhoIsMu.Unlock()
+ if gotPrivWhoIs.PeerID != stB.PeerID || gotPrivWhoIs.Labels["env"] != "dev" {
+ t.Fatalf("private WhoIs = %+v, want PeerID=%s env=dev", gotPrivWhoIs, stB.PeerID)
+ }
+
+ // Verify private fallback on ceiling-blocked service works while /ingress returns 404.
+ privBlockedResp, err := srvB.HTTPClient().Get(blockedEP.PrivateURL.String() + "/ping")
+ if err != nil {
+ t.Fatalf("private GET ceiling-blocked: %v", err)
+ }
+ privBlockedBody, _ := io.ReadAll(privBlockedResp.Body)
+ _ = privBlockedResp.Body.Close()
+ if privBlockedResp.StatusCode != http.StatusOK || string(privBlockedBody) != "private-still-works" {
+ t.Fatalf("private ceiling-blocked = %d %q, want 200 private-still-works", privBlockedResp.StatusCode, privBlockedBody)
+ }
+
+ extHTTP := &http.Client{Timeout: 5 * time.Second}
+ pubBlockedResp, err := extHTTP.Get(fmt.Sprintf("%s/%s/a2a/ceiling-blocked/.well-known/agent-card.json", srv.IngressURL(), stA.PeerID))
+ if err != nil {
+ t.Fatalf("GET public ceiling-blocked: %v", err)
+ }
+ _ = pubBlockedResp.Body.Close()
+ if pubBlockedResp.StatusCode != http.StatusNotFound {
+ t.Fatalf("public ceiling-blocked = %d, want 404", pubBlockedResp.StatusCode)
+ }
+
+ // 5. Verify Public External Ingress (EDGE + OIDC /oauth/token + AttenuateToken TAR + PASSTHROUGH).
+ pubCard, err := agentcard.NewResolver(extHTTP).Resolve(ctx, coderEP.PublicURL.String())
+ if err != nil {
+ t.Fatalf("Resolve public coder card: %v", err)
+ }
+ if len(pubCard.SupportedInterfaces) != 1 || pubCard.SupportedInterfaces[0].URL != coderEP.PublicURL.String()+"/invoke" {
+ t.Fatalf("public SupportedInterfaces = %+v, want %s/invoke", pubCard.SupportedInterfaces, coderEP.PublicURL.String())
+ }
+
+ // 5a. External OIDC user allowed by IngressAllow (SendMessage + SSE SendStreamingMessage).
+ carolJWT := mintJWT(map[string]any{"sub": "carol-sub", "email": "[email protected]"})
+ carolBiscuit := exchangeJWTForBiscuit(t, srv.PublicURL(), carolJWT, "", false)
+ pubAllowed, err := a2aclient.NewFromCard(ctx, pubCard, a2aclient.WithJSONRPCTransport(bearerClient(carolBiscuit, nil)))
+ if err != nil {
+ t.Fatalf("NewFromCard(public carol): %v", err)
+ }
+ var gotSSE bool
+ for ev, sErr := range pubAllowed.SendStreamingMessage(ctx, &a2a.SendMessageRequest{
+ Message: a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("stream")),
+ }) {
+ if sErr != nil {
+ t.Fatalf("SendStreamingMessage: %v", sErr)
+ }
+ if upd, ok := ev.(*a2a.TaskStatusUpdateEvent); ok && upd.Status.State == a2a.TaskStateCompleted {
+ gotSSE = true
+ }
+ }
+ if !gotSSE {
+ t.Fatal("did not receive completed TaskStatusUpdateEvent over public SSE")
+ }
+ coderWhoIsMu.Lock()
+ gotPubWhoIs := lastCoderWhoIs
+ coderWhoIsMu.Unlock()
+ if gotPubWhoIs.Principal != "[email protected]" {
+ t.Fatalf("public WhoIs Principal = %q, want [email protected]", gotPubWhoIs.Principal)
+ }
+
+ // 5b. External OIDC user excluded by IngressAllow gets denied.
+ bobJWT := mintJWT(map[string]any{"sub": "bob-sub", "email": "[email protected]"})
+ bobBiscuit := exchangeJWTForBiscuit(t, srv.PublicURL(), bobJWT, "", false)
+ pubDenied, err := a2aclient.NewFromCard(ctx, pubCard, a2aclient.WithJSONRPCTransport(bearerClient(bobBiscuit, nil)))
+ if err != nil {
+ t.Fatalf("NewFromCard(public bob): %v", err)
+ }
+ if _, err := pubDenied.SendMessage(ctx, &a2a.SendMessageRequest{
+ Message: a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("hi")),
+ }); err == nil {
+ t.Fatal("excluded external user succeeded on coder, want error")
+ }
+
+ // 5c. Task-scoped Biscuit minted offline via srvB.AttenuateToken(..., seal=true) surfaces Task in WhoIs.
+ tarToken, _, err := srvB.AttenuateToken(&api.TaskAuthorizationRule{
+ Name: "audit-pr-99",
+ Rules: []*api.TaskRule{
+ {
+ AllowedServices: []string{"a2a://coder"},
+ Operation: &api.TaskOperation{AllowedMethods: []string{"POST"}},
+ },
+ },
+ }, 2*time.Minute, true)
+ if err != nil {
+ t.Fatalf("srvB.AttenuateToken: %v", err)
+ }
+ pubTARClient, err := a2aclient.NewFromCard(ctx, pubCard, a2aclient.WithJSONRPCTransport(bearerClient(tarToken, nil)))
+ if err != nil {
+ t.Fatalf("NewFromCard(TAR): %v", err)
+ }
+ if _, err := pubTARClient.SendMessage(ctx, &a2a.SendMessageRequest{
+ Message: a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("hi")),
+ }); err != nil {
+ t.Fatalf("SendMessage(TAR): %v", err)
+ }
+ coderWhoIsMu.Lock()
+ gotTARWhoIs := lastCoderWhoIs
+ coderWhoIsMu.Unlock()
+ if gotTARWhoIs.Task != "audit-pr-99" {
+ t.Fatalf("TAR WhoIs Task = %q, want audit-pr-99", gotTARWhoIs.Task)
+ }
+
+ // 5d. PASSTHROUGH service preserves upstream Bearer pair token and strips spoofed X-Mesh-*.
+ pubPairedCard, err := agentcard.NewResolver(extHTTP).Resolve(ctx, pairedEP.PublicURL.String())
+ if err != nil {
+ t.Fatalf("Resolve public paired card: %v", err)
+ }
+ pairedClient, err := a2aclient.NewFromCard(ctx, pubPairedCard, a2aclient.WithJSONRPCTransport(
+ bearerClient("pair-secret-123", map[string]string{api.HeaderMeshPrincipal: "spoofed-admin"}),
+ ))
+ if err != nil {
+ t.Fatalf("NewFromCard(paired): %v", err)
+ }
+ if _, err := pairedClient.SendMessage(ctx, &a2a.SendMessageRequest{
+ Message: a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("hi")),
+ }); err != nil {
+ t.Fatalf("SendMessage(paired): %v", err)
+ }
+ if !passthroughClean.Load() {
+ t.Fatal("PASSTHROUGH backend saw spoofed X-Mesh-Principal or missed X-Mesh-Ingress=passthrough")
+ }
+
+ // 6. Verify srvB.MCPHandler() 3-step progressive remote tool discovery & invocation against agentmesh-node.
+ localMCP := httptest.NewServer(srvB.MCPHandler())
+ t.Cleanup(localMCP.Close)
+
+ mcpCli := mcp.NewClient(&mcp.Implementation{Name: "agent-caller", Version: "1.0.0"}, nil)
+ mcpSess, err := mcpCli.Connect(ctx, &mcp.StreamableClientTransport{Endpoint: localMCP.URL + "/mcp"}, nil)
+ if err != nil {
+ t.Fatalf("Connect local MCPHandler: %v", err)
+ }
+ t.Cleanup(func() { _ = mcpSess.Close() })
+
+ var foundToolsText string
+ deadline = time.Now().Add(5 * time.Second)
+ for {
+ findRes, fErr := mcpSess.CallTool(ctx, &mcp.CallToolParams{
+ Name: "find_remote_tools",
+ Arguments: map[string]any{"tool_name": "echo_arg"},
+ })
+ if fErr == nil && len(findRes.Content) > 0 {
+ txt := findRes.Content[0].(*mcp.TextContent).Text
+ foundToolsText = txt
+ if !findRes.IsError && strings.Contains(txt, "mcp://tools/echo_arg") {
+ break
+ }
+ }
+ if time.Now().After(deadline) {
+ t.Fatalf("find_remote_tools did not discover mcp://tools/echo_arg in time; last=%q err=%v", foundToolsText, fErr)
+ }
+ time.Sleep(50 * time.Millisecond)
+ }
+
+ descRes, err := mcpSess.CallTool(ctx, &mcp.CallToolParams{
+ Name: "describe_remote_tool",
+ Arguments: map[string]any{
+ "peer_id": providerPeerID,
+ "tool_name": "mcp://tools/echo_arg",
+ },
+ })
+ if err != nil || descRes.IsError {
+ t.Fatalf("describe_remote_tool: err=%v res=%+v", err, descRes)
+ }
+ if !strings.Contains(descRes.Content[0].(*mcp.TextContent).Text, "message") {
+ t.Fatalf("describe_remote_tool schema missing 'message': %s", descRes.Content[0].(*mcp.TextContent).Text)
+ }
+
+ callRes, err := mcpSess.CallTool(ctx, &mcp.CallToolParams{
+ Name: "call_remote_tool",
+ Arguments: map[string]any{
+ "peer_id": providerPeerID,
+ "tool_name": "mcp://tools/echo_arg",
+ "arguments": map[string]any{"message": "from-meshnet"},
+ },
+ })
+ if err != nil || callRes.IsError {
+ t.Fatalf("call_remote_tool: err=%v res=%+v", err, callRes)
+ }
+ if got := callRes.Content[0].(*mcp.TextContent).Text; !strings.Contains(got, "echo:from-meshnet") {
+ t.Fatalf("call_remote_tool output = %q, want echo:from-meshnet", got)
+ }
+
+ // 7. Verify srvB.InferenceHandler() zero-secret OpenAI /v1/models + /v1/chat/completions + label check.
+ localInf := httptest.NewServer(srvB.InferenceHandler())
+ t.Cleanup(localInf.Close)
+
+ modelsResp, err := extHTTP.Get(localInf.URL + "/v1/models")
+ if err != nil {
+ t.Fatalf("GET /v1/models: %v", err)
+ }
+ modelsBody, _ := io.ReadAll(modelsResp.Body)
+ _ = modelsResp.Body.Close()
+ if modelsResp.StatusCode != http.StatusOK || !strings.Contains(string(modelsBody), "mesh-qwen") {
+ t.Fatalf("GET /v1/models = %d %s, want mesh-qwen", modelsResp.StatusCode, modelsBody)
+ }
+
+ chatResp, err := extHTTP.Post(localInf.URL+"/v1/chat/completions", "application/json",
+ strings.NewReader(`{"model":"mesh-qwen","messages":[{"role":"user","content":"ping"}]}`))
+ if err != nil {
+ t.Fatalf("POST /v1/chat/completions: %v", err)
+ }
+ chatBody, _ := io.ReadAll(chatResp.Body)
+ _ = chatResp.Body.Close()
+ if chatResp.StatusCode != http.StatusOK || !strings.Contains(string(chatBody), "mesh-reply") {
+ t.Fatalf("POST /v1/chat/completions = %d %s, want mesh-reply", chatResp.StatusCode, chatBody)
+ }
+
+ streamChatResp, err := extHTTP.Post(localInf.URL+"/v1/chat/completions", "application/json",
+ strings.NewReader(`{"model":"mesh-qwen","stream":true,"messages":[{"role":"user","content":"ping"}]}`))
+ if err != nil {
+ t.Fatalf("POST streaming /v1/chat/completions: %v", err)
+ }
+ streamChatBody, _ := io.ReadAll(streamChatResp.Body)
+ _ = streamChatResp.Body.Close()
+ if streamChatResp.StatusCode != http.StatusOK || !strings.Contains(string(streamChatBody), "[DONE]") {
+ t.Fatalf("POST streaming /v1/chat/completions = %d %s, want SSE [DONE]", streamChatResp.StatusCode, streamChatBody)
+ }
+
+ badInfReq, _ := http.NewRequestWithContext(ctx, http.MethodPost, localInf.URL+"/v1/chat/completions",
+ strings.NewReader(`{"model":"mesh-qwen","messages":[{"role":"user","content":"ping"}]}`))
+ badInfReq.Header.Set("Content-Type", "application/json")
+ badInfReq.Header.Set(api.HeaderMeshRequiredLabels, "tier=missing")
+ badInfResp, err := extHTTP.Do(badInfReq)
+ if err != nil {
+ t.Fatalf("POST /v1/chat/completions with unmet label: %v", err)
+ }
+ badInfBody, _ := io.ReadAll(badInfResp.Body)
+ _ = badInfResp.Body.Close()
+ if badInfResp.StatusCode != http.StatusServiceUnavailable {
+ t.Fatalf("unmet required label on inference = %d %s, want 503", badInfResp.StatusCode, badInfBody)
+ }
+}