Skip to content

Agent Mesh

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.md
index 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.md
index 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 and
refuses 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 passed
the 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. |