Skip to content

Agent Mesh

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.go
index 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.go
index 8772e406..f8c3fba2 100644
--- a/cmd/sam-node/gate.go
+++ b/cmd/sam-node/gate.go
@@ -16,7 +16,6 @@ package main
import (
"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.go
index 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 fail
diff --git a/cmd/sam-node/sidecar.go b/cmd/sam-node/sidecar.go
index 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.md
index 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.
+
+