Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
doc, cmd: document ingress auth pipeline and cleanup local node auth warning
Antonio Ojea41ba662cdfee
diff --git a/cmd/mcp-client/main.go b/cmd/mcp-client/main.goindex 90dfd3b2..a78a342a 100644--- a/cmd/mcp-client/main.go+++ b/cmd/mcp-client/main.go@@ -157,9 +157,22 @@ func main() {},}}- session, err := client.Connect(ctx, mcpTransport, nil)+ var session *mcp.ClientSession+ var err error+ for attempt := 1; attempt <= 5; attempt++ {+ session, err = client.Connect(ctx, mcpTransport, nil)+ if err == nil {+ break+ }+ log.Printf("Connection attempt %d failed: %v. Retrying in 500ms...", attempt, err)+ select {+ case <-ctx.Done():+ log.Fatalf("Context cancelled during connection: %v", ctx.Err())+ case <-time.After(500 * time.Millisecond):+ }+ }if err != nil {- log.Fatalf("Failed to connect: %v", err)+ log.Fatalf("Failed to connect after 5 attempts: %v", err)}defer func() {if err := session.Close(); err != nil {diff --git a/cmd/sam-node/gate.go b/cmd/sam-node/gate.goindex 8772e406..f8c3fba2 100644--- a/cmd/sam-node/gate.go+++ b/cmd/sam-node/gate.go@@ -16,7 +16,6 @@ package mainimport ("context"- "fmt""github.com/libp2p/go-libp2p/core/connmgr""github.com/libp2p/go-libp2p/core/control"@@ -40,10 +39,18 @@ type nodeConnGate struct {// InterceptPeerDial controls who we are allowed to call (Outbound)func (g *nodeConnGate) InterceptPeerDial(p peer.ID) (allow bool) {+ logger.Debugf("[Gater] InterceptPeerDial for %s", p)if g.node.revokedPeers.Contains(p.String()) {+ logger.Infof("[Gater] InterceptPeerDial denying %s: in revoked cache", p)return false}- return !g.node.Store.IsBanned(p)+ banned := g.node.Store.IsBanned(p)+ if banned {+ logger.Infof("[Gater] InterceptPeerDial denying %s: banned in store", p)+ return false+ }+ logger.Debugf("[Gater] InterceptPeerDial allowing %s", p)+ return true}// InterceptAddrDial ensures we only dial specific approved networks@@ -58,16 +65,16 @@ func (g *nodeConnGate) InterceptAccept(n network.ConnMultiaddrs) (allow bool) {// InterceptSecured is called after TLS handshake. This is our Layer 2 Check.func (g *nodeConnGate) InterceptSecured(dir network.Direction, p peer.ID, n network.ConnMultiaddrs) (allow bool) {+ logger.Debugf("[Gater] InterceptSecured for %s (dir: %v)", p, dir)if g.node.revokedPeers.Contains(p.String()) {- fmt.Printf("[Layer 2] Dropping connection: Peer %s is in revoked cache\n", p)+ logger.Infof("[Gater] InterceptSecured denying %s: in revoked cache", p)return false}if g.node.Store.IsBanned(p) {- fmt.Printf("[Layer 2] Dropping connection: Peer %s is explicitly BANNED\n", p)+ logger.Infof("[Gater] InterceptSecured denying %s: banned in store", p)return false}-- // Allow the TLS pipe to stay open. Layer 3 & 4 will handle the rest.+ logger.Debugf("[Gater] InterceptSecured allowing %s", p)return true}diff --git a/cmd/sam-node/middleware.go b/cmd/sam-node/middleware.goindex 59adeab1..710afbff 100644--- a/cmd/sam-node/middleware.go+++ b/cmd/sam-node/middleware.go@@ -254,6 +254,7 @@ func (n *SamNode) injectIdentityFacts(authorizer biscuit.Authorizer, pubKey ed25}// We must Authorize() to evaluate the token's facts into the world+ auth.AddPolicy(api.AllowIfTruePolicy)if err := auth.Authorize(); err != nil {logger.Warnf("Failed to authorize our own identity token: %v", err)// we continue anyway, as we just want the facts, but ideally it shouldn't faildiff --git a/cmd/sam-node/sidecar.go b/cmd/sam-node/sidecar.goindex 27a7820e..1246e0ed 100644--- a/cmd/sam-node/sidecar.go+++ b/cmd/sam-node/sidecar.go@@ -178,6 +178,7 @@ func handleReadyz(w http.ResponseWriter, r *http.Request) {func withMeshConnection(node *SamNode, next http.Handler) http.Handler {return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {if node != nil && !node.IsConnected() {+ logger.Warnf("[SidecarAuth] Request %s %s rejected: node not connected to mesh", r.Method, r.URL.Path)http.Error(w, "Service Unavailable: Not connected to the mesh", http.StatusServiceUnavailable)return}@@ -187,6 +188,7 @@ func withMeshConnection(node *SamNode, next http.Handler) http.Handler {func withAuth(token string, next http.Handler) http.Handler {return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ logger.Debugf("[SidecarAuth] Incoming request: %s %s from %s", r.Method, r.URL.Path, r.RemoteAddr)if token == "" {// If token is empty, we assume mTLS is handling authentication.// startSidecarServer enforces that token is present if mTLS is not used.@@ -196,6 +198,7 @@ func withAuth(token string, next http.Handler) http.Handler {authHeader := r.Header.Get("Authorization")if authHeader == "" {+ logger.Warnf("[SidecarAuth] Request %s %s rejected: missing Authorization header", r.Method, r.URL.Path)http.Error(w, "Unauthorized", http.StatusUnauthorized)return}diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.mdindex 179c83bd..5162c2d9 100644--- a/site/content/docs/development/policy.md+++ b/site/content/docs/development/policy.md@@ -143,3 +143,50 @@ allow if service("system", "sam.catalog");> [!IMPORTANT]> Without this baseline rule (or if a custom local attenuation policy explicitly blocks it), remote nodes will not be able to retrieve this node's tool catalog. As a result, agents across the mesh will fail to discover or call any of this node's tools.+## 5. Ingress Authorization Pipeline (Execution Flow)++When a node receives an incoming connection request (via P2P HTTP Ingress or wrapped protocol streams like MCP/Inference), it performs a multi-stage verification pipeline.++### 5.1 Pipeline Stages++```mermaid+graph TD+ A[Incoming Connection] --> B(Stage 1: Connection Gating)+ B -->|Banned/Revoked| C[Drop Connection]+ B -->|Allowed| D(Stage 2: Biscuit Token Verification)+ D --> E[Run 1: Authorize Node's Own Identity Token]+ E --> F[Query & Inject Destination Target Facts]+ F --> G[Run 2: Authorize Caller's Request Token]+ G -->|Success| H[Proxy to Downstream Service]+ G -->|Denied| I[Return 403 Forbidden / Reject Auth Frame]+```++1. **Stage 1: Connection Gating (Layer 2)**+ - Performed immediately at the connection manager level (`gate.go`).+ - Checks the remote peer ID against local blacklist (`Store.IsBanned`) and revocation caches (`revokedPeers`).+ - Does not parse Biscuit tokens. Connection is dropped early if matched.++2. **Stage 2: Biscuit Token Verification (Layer 3/4)**+ - Handled inside node middleware (`middleware.go`).+ - Performs exactly **two Biscuit authorizer execution runs** to process authorization:++#### Run 1: Destination Identity Fact Evaluation+- **Target**: The node's **own identity token** (issued by the Hub during enrollment).+- **Purpose**: We must mathematically evaluate the node's own OIDC group/user claims and node ID to produce `target_fact(...)` datalog assertions (e.g. `target_fact("group", "backend-nodes")`). These facts represent *who we are*.+- **Mechanism**:+ 1. We create an authorizer for our own token signed by the Hub's public key.+ 2. We add a baseline `allow if true` policy. This policy is required by Biscuit so that the authorizer can execute (since the token itself holds only identity facts and has no operation-level authorization policies).+ 3. We execute `Authorize()` to verify our token signature and validate internal checks (such as expiration).+ 4. We query `api.TargetFactRules` against this authorizer to extract target facts.+ 5. We inject these extracted `target_fact` assertions into the main request authorizer.++#### Run 2: Caller Request Authorization+- **Target**: The caller's **request token** (the Biscuit token presented in the request's `X-Sam-Biscuit` header or `AuthFrame`).+- **Purpose**: Verifies that the caller has been granted access by the Hub to the requested target service, checks for replay protection, and evaluates local attenuation constraints.+- **Mechanism**:+ 1. We create an authorizer for the caller's token using the Hub's public key.+ 2. We inject the target matching facts derived from Run 1.+ 3. We add baseline rules (e.g. peer ID matching connection ID check, system catalog access policies) and local attenuation configurations (`sam-node-config.yaml`).+ 4. We execute `Authorize()` to check all signatures, checks, and policies. If successful, the request is forwarded to the underlying service.++