Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: a router serves nothing before the handshake
Antonio Ojea5943f4d76690
diff --git a/site/content/docs/contributing/security-architecture.md b/site/content/docs/contributing/security-architecture.mdindex 29f818d7..244e50d1 100644--- a/site/content/docs/contributing/security-architecture.md+++ b/site/content/docs/contributing/security-architecture.md@@ -594,3 +594,14 @@ response directly).members on charset grounds and quotes wildcard string literals with`strconv.Quote` before rendering `.starts_with(...)` or `.ends_with(...)`Datalog rules.+7. Nothing interacts with the mesh unauthenticated. A router or a member+ serves a mesh protocol (the DHT, gossip, the relay, the data plane) only to+ a peer that completed the credential handshake on that connection and whose+ credential has not lapsed. The protocols open to a peer before that are the+ ones the handshake needs: the transport security handshake, identify and+ `/mesh/auth`. The DHT and gossipsub are built on a host wrapper that holds a+ stream until its peer is authenticated and resets it when the connection+ closes first, counted in `*_streams_refused_total{scope="unauthenticated"}`;+ a router's routing table admits authenticated peer routers only. A+ directory lookup and a gossip subscription are mesh data, so this covers+ reads as much as writes.diff --git a/site/content/docs/reference/router.md b/site/content/docs/reference/router.mdindex aaa5342b..fadaed75 100644--- a/site/content/docs/reference/router.md+++ b/site/content/docs/reference/router.md@@ -64,6 +64,13 @@ replica count.router on `/info` while the lease is live.4. Runs the mutual credential handshake on every inbound connection andrefuses peers whose credential does not verify and peers on the ban list.+ Until a peer passes it, the router serves it nothing but the handshake:+ a DHT or gossip stream it opens waits, unread, and is served once the+ peer is authenticated, or reset when the connection closes at+ `--auth-deadline` first. A member's streams open on connect, a moment+ before its handshake completes, which is why they wait instead of being+ refused outright. The routing table admits authenticated peer routers and+ nothing else, and the router queries no one else either.5. Refreshes its own credential before it expires, like a node.6. Every 5 seconds, compares the members it holds, the peers that passedthe handshake, with `--high-watermark`. At the mark it picks members at@@ -120,7 +127,7 @@ The metrics address exposes, next to the Go runtime metrics:| `agentmesh_router_goaway_sent_total{reason,result}` | Members sent away, by reason (`DRAINING`, `OVERLOADED`) and outcome: `ok` when the member took the message, `unsupported` when it does not speak the protocol and was closed instead, `failed` when the stream broke. A rising `OVERLOADED` count on a router that is not draining is a fleet that has outgrown its routers. || `agentmesh_router_unauthenticated_connections_closed_total` | Connections closed at `--auth-deadline` without a handshake. Members handshake with every router they connect to, so a steady rate is members running a node release that predates that, and a burst is a scanner. || `agentmesh_router_inbound_connections_refused_total` | Inbound connections refused by the per-address cap. |-| `agentmesh_router_streams_refused_total{scope,protocol}` | Streams the resource manager refused, by scope and protocol or service. A count on `/mesh/kad/1.0.0` or a `/meshsub/*` protocol is members the router keeps out of discovery; see the scalability guide. |+| `agentmesh_router_streams_refused_total{scope,protocol}` | Streams refused, by scope and protocol or service. `scope="unauthenticated"` is a stream from a peer that never passed the handshake, reset when its connection closed; a steady rate is a scanner, or a member whose handshake fails. The other scopes are the resource manager's: a count on `/mesh/kad/1.0.0` or a `/meshsub/*` protocol there is members the router keeps out of discovery; see the scalability guide. || `agentmesh_router_busiest_connection_streams{transport}` | The most streams any one connection carries. The connection to a service the router relays for holds one stream per relayed caller, and QUIC admits 256 per connection; see the scalability guide. || `libp2p_relaysvc_*` | The relay service's own counters: `reservations_total{type}` and `connections_total{type}` (`opened`, `closed`, `renewed`), requests by response status, rejections and bytes relayed. The difference between `opened` and `closed` is the number in use; read it against `agentmesh_router_relay_limit` to see how close the relay is to its budget. |