Skip to content

Agent Mesh

15.0 KB
Raw Blame
// 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 node

import (
	"crypto/ed25519"
	"errors"
	"fmt"
	"runtime/debug"
	"sync/atomic"
	"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"
)

// RequestContext carries the security metadata for a specific stream request
type RequestContext struct {
	PeerID   peer.ID
	User     string
	Group    string
	Protocol string
	Target   string

	// HTTP is set when the node handles the request as HTTP: the method as
	// received and the path as the backend sees it. Injected as method() and
	// path() facts, taken from the wire and never from the caller's token. A
	// tunnel the node opens without terminating HTTP carries Method "CONNECT"
	// and an empty Path. Nil on a stream that carries no HTTP request.
	HTTP *HTTPRequestFacts

	// Egress is set on a request for an egress destination: the hostname and
	// port the node connects to, injected as host() and port() facts.
	Egress *EgressFacts

	// Local marks a request this node makes for one of its own clients over the
	// local API, for a destination it serves itself. The caller is then this
	// node, evaluated on its own credential, and the target check is satisfied
	// because a node is always allowed to reach itself. Never set from the wire.
	Local bool

	// MCPTool is set when evaluating a specific MCP tools/call invocation.
	MCPTool string

	// AllowMCPStreamInit is set when an MCP request is a session handshake or
	// discovery method (initialize, ping, tools/list).
	AllowMCPStreamInit bool

	// TaskRules holds the verified TaskAuthorizationRule chain extracted from
	// the caller's Biscuit during stream authentication so downstream stream
	// handlers (such as MCP pass-through) can enforce tool-level constraints.
	TaskRules []*api.TaskAuthorizationRule
}

// HTTPRequestFacts is what an HTTP request contributes to policy.
type HTTPRequestFacts struct {
	Method string
	Path   string
}

// EgressFacts is the destination of an egress request.
type EgressFacts struct {
	Host string
	Port int
}

// recoverStreamHandler isolates a panic while processing untrusted peer bytes
// to the single stream, resetting it instead of crashing the whole node.
func recoverStreamHandler(name string, next network.StreamHandler) network.StreamHandler {
	return func(s network.Stream) {
		defer func() {
			if r := recover(); r != nil {
				logger.Errorf("[%s] panic recovered from peer %s: %v\n%s", name, s.Conn().RemotePeer(), r, debug.Stack())
				_ = s.Reset()
			}
		}()
		next(s)
	}
}

// trackingStream wraps a network.Stream to count bytes read and written.
type trackingStream struct {
	network.Stream
	bytesRead    atomic.Int64
	bytesWritten atomic.Int64
}

func (t *trackingStream) Read(p []byte) (n int, err error) {
	n, err = t.Stream.Read(p)
	t.bytesRead.Add(int64(n))
	return n, err
}
func (t *trackingStream) Write(p []byte) (n int, err error) {
	n, err = t.Stream.Write(p)
	t.bytesWritten.Add(int64(n))
	return n, err
}

// WithBiscuitAuth enforces a Protobuf handshake on a stream before calling the next handler.
func (n *AgentMeshNode) WithBiscuitAuth(next func(network.Stream, RequestContext)) network.StreamHandler {
	return func(s network.Stream) {
		ts := &trackingStream{Stream: s}
		remotePeer := s.Conn().RemotePeer()
		var reqCtx RequestContext

		defer func() {
			target := reqCtx.Target
			if target == "" {
				target = "unauthenticated_or_failed"
			}
			logger.Infow("Stream Accounting",
				"peer_id", remotePeer.String(),
				"target", truncateForLog(target),
				"protocol", reqCtx.Protocol,
				"bytes_read", ts.bytesRead.Load(),
				"bytes_written", ts.bytesWritten.Load(),
			)
			if err := ts.Close(); err != nil {
				logger.Debugf("[Auth] Failed to close stream: %v", err)
			}
		}()

		if !n.rateLimiter.Allow(remotePeer.String()) {
			logger.Warnf("[Auth] Rate limit exceeded for %s, dropping connection", remotePeer)
			_ = ts.Reset()
			return
		}

		// The peer is not authorized yet: it gets the handshake budget to
		// produce its frame, not an open-ended hold on this goroutine.
		if err := ts.SetReadDeadline(time.Now().Add(authHandshakeTimeout)); err != nil {
			logger.Debugf("[Auth] Failed to set auth frame deadline for %s: %v", remotePeer, err)
		}

		// Read AuthFrame
		reader := msgio.NewVarintReaderSize(ts, 1024*64)
		msg, err := reader.ReadMsg()
		if err != nil {
			logger.Errorf("[Auth] Failed to read auth frame from %s: %v", remotePeer, err)
			return
		}
		defer reader.ReleaseMsg(msg)

		var authFrame api.AuthFrame
		if err := proto.Unmarshal(msg, &authFrame); err != nil {
			logger.Warnf("[Auth] Invalid auth frame from %s", remotePeer)
			return
		}

		reqCtx = RequestContext{
			PeerID:   remotePeer,
			User:     "", // Not used in Authorize
			Protocol: string(ts.Protocol()),
			Target:   authFrame.TargetService,
		}

		writer := msgio.NewVarintWriter(ts)

		taskRules, err := n.verifyBiscuitTokenWithRules(authFrame.Biscuit, reqCtx)
		if err != nil {
			logger.Warnf("[Auth] AuthZ Denied %s: %v", remotePeer, err)
			resp := &api.AuthResponse{Success: false, Error: err.Error()}
			respBytes, _ := proto.Marshal(resp)
			_ = writer.WriteMsg(respBytes)
			return
		}
		reqCtx.TaskRules = taskRules

		// Valid. Mutual auth: return our control-plane-minted identity so the
		// caller can verify this node's attested facts (e.g. region) before
		// sending request data.
		resp := &api.AuthResponse{Success: true, Biscuit: n.GetIdentity()}
		respBytes, _ := proto.Marshal(resp)
		if err := writer.WriteMsg(respBytes); err != nil {
			logger.Errorf("[Auth] Failed to write ACK to %s: %v", remotePeer, err)
			return
		}

		// Authorized: the session itself is long-lived, so the pre-auth
		// deadline comes off.
		if err := ts.SetReadDeadline(time.Time{}); err != nil {
			logger.Debugf("[Auth] Failed to clear auth frame deadline for %s: %v", remotePeer, err)
		}

		next(ts, reqCtx)
	}
}

// VerifyBiscuitToken checks revocation, cache, and evaluates the token against trusted keys and local policies.
func (n *AgentMeshNode) VerifyBiscuitToken(biscuitBytes []byte, reqCtx RequestContext) error {
	_, err := n.verifyBiscuitTokenWithRules(biscuitBytes, reqCtx)
	return err
}

func (n *AgentMeshNode) verifyBiscuitTokenWithRules(biscuitBytes []byte, reqCtx RequestContext) ([]*api.TaskAuthorizationRule, error) {
	remotePeer := reqCtx.PeerID

	// Check revocation cache
	if n.revokedPeers != nil {
		if _, isRevoked := n.revokedPeers.Get(remotePeer.String()); isRevoked {
			logger.Warnf("[Auth] Peer %s is revoked", remotePeer)
			return nil, fmt.Errorf("peer is revoked")
		}
	}

	n.keysMu.RLock()
	keys := n.trustedKeys
	n.keysMu.RUnlock()

	var authorized bool
	var taskRules []*api.TaskAuthorizationRule
	var lastErr error
	for _, pubKey := range keys {
		logger.Infof("[Auth] Trying key: %x", pubKey.Key)
		if rules, err := n.authorizeWithRules(biscuitBytes, reqCtx, pubKey.Key); err == nil {
			authorized = true
			taskRules = rules
			break
		} else {
			lastErr = err
			if !errors.Is(err, biscuit.ErrInvalidSignature) {
				break
			}
		}
	}

	if !authorized {
		if lastErr != nil {
			return nil, lastErr
		}
		return nil, fmt.Errorf("authorization failed")
	}

	return taskRules, nil
}

func (n *AgentMeshNode) Authorize(rawToken []byte, req RequestContext, pubKey ed25519.PublicKey) error {
	_, err := n.authorizeWithRules(rawToken, req, pubKey)
	return err
}

func (n *AgentMeshNode) authorizeWithRules(rawToken []byte, req RequestContext, pubKey ed25519.PublicKey) ([]*api.TaskAuthorizationRule, error) {
	if len(pubKey) != ed25519.PublicKeySize {
		return nil, fmt.Errorf("invalid public key size: %d", len(pubKey))
	}
	b, taskRules, err := identity.UnmarshalInbound(rawToken)
	if err != nil {
		return nil, fmt.Errorf("invalid biscuit: %w", err)
	}
	if n.IsBiscuitRevoked(b) {
		logger.Infow("Audit Traceability", append(req.auditFields(), "decision", "deny", "reason", "biscuit is revoked")...)
		return nil, fmt.Errorf("biscuit is revoked")
	}

	authorizer, err := b.Authorizer(pubKey, identity.AuthorizerOptions(n.BiscuitTimeout)...)
	if err != nil {
		return nil, err
	}

	if err := identity.RequireAuthorityRequestBinding(b, req.PeerID); err != nil {
		return nil, err
	}

	// The request as every enforcement point describes it: the service it
	// names, or the connection protocol in the system namespace when it
	// names none; the HTTP line and egress destination when present; and
	// the connection peer, which binds client_peer_id to this stream.
	meshReq := identity.MeshRequest{
		ConnectionPeer:     req.PeerID,
		Unrestricted:       req.Local,
		MCPTool:            req.MCPTool,
		AllowMCPStreamInit: req.AllowMCPStreamInit || (req.HTTP == nil && req.MCPTool == "" && req.Protocol == string(api.MCPProtocolID)),
	}
	if req.Target == "" {
		meshReq.ServiceType = api.SystemNamespace
		meshReq.ServiceName = req.Protocol
	} else {
		meshReq.ServiceType, meshReq.ServiceName = api.ParseServiceTarget(req.Target)
	}
	if req.HTTP != nil {
		meshReq.HasHTTP = true
		meshReq.Method = req.HTTP.Method
		meshReq.Path = req.HTTP.Path
	}
	if req.Egress != nil {
		meshReq.HasEgress = true
		meshReq.EgressHost = req.Egress.Host
		meshReq.EgressPort = int64(req.Egress.Port)
	}

	pol, err := n.meshPolicy()
	if err != nil {
		return nil, err
	}
	if err := identity.AuthorizeMeshRequest(authorizer, meshReq, pol); err != nil {
		logger.Infow("Audit Traceability", append(req.auditFields(), "decision", "deny", "reason", err.Error())...)
		logger.Debugf("Authorizer failure: %v, token: %s", err, b.String())
		logger.Debugf("Authorizer state: %s", authorizer.PrintWorld())
		return nil, err
	}

	if len(taskRules) > 0 {
		if err := api.EvaluateTaskRules(taskRules, meshReq.TaskRequest(), time.Now()); err != nil {
			logger.Infow("Audit Traceability", append(req.auditFields(), "decision", "deny", "reason", err.Error())...)
			return nil, err
		}
	}

	var userStr, emailStr, roleStr, actorNodeStr string

	if facts, _ := authorizer.Query(biscuit.Rule{
		Head: biscuit.Predicate{Name: "get_user", IDs: []biscuit.Term{biscuit.Variable("u")}},
		Body: []biscuit.Predicate{{Name: api.FactUser, IDs: []biscuit.Term{biscuit.Variable("u")}}},
	}); len(facts) > 0 && len(facts[0].IDs) > 0 {
		if s, ok := facts[0].IDs[0].(biscuit.String); ok {
			userStr = string(s)
		}
	}

	if facts, _ := authorizer.Query(biscuit.Rule{
		Head: biscuit.Predicate{Name: "get_email", IDs: []biscuit.Term{biscuit.Variable("e")}},
		Body: []biscuit.Predicate{{Name: api.FactEmail, IDs: []biscuit.Term{biscuit.Variable("e")}}},
	}); len(facts) > 0 && len(facts[0].IDs) > 0 {
		if s, ok := facts[0].IDs[0].(biscuit.String); ok {
			emailStr = string(s)
		}
	}

	if facts, _ := authorizer.Query(biscuit.Rule{
		Head: biscuit.Predicate{Name: "get_role", IDs: []biscuit.Term{biscuit.Variable("r")}},
		Body: []biscuit.Predicate{{Name: api.FactRole, IDs: []biscuit.Term{biscuit.Variable("r")}}},
	}); len(facts) > 0 && len(facts[0].IDs) > 0 {
		if s, ok := facts[0].IDs[0].(biscuit.String); ok {
			roleStr = string(s)
		}
	}

	if facts, _ := authorizer.Query(biscuit.Rule{
		Head: biscuit.Predicate{Name: "get_actor_node", IDs: []biscuit.Term{biscuit.Variable("a")}},
		Body: []biscuit.Predicate{{Name: api.FactActorNode, IDs: []biscuit.Term{biscuit.Variable("a")}}},
	}); len(facts) > 0 && len(facts[0].IDs) > 0 {
		if s, ok := facts[0].IDs[0].(biscuit.String); ok {
			actorNodeStr = string(s)
		}
	}

	auditFields := append(req.auditFields(),
		"decision", "allow",
		"user", userStr,
		"email", emailStr,
		"role", roleStr,
	)
	if actorNodeStr != "" {
		if n.revokedPeers != nil {
			if actorPID, pErr := peer.Decode(actorNodeStr); pErr == nil {
				if _, isRevoked := n.revokedPeers.Get(actorPID.String()); isRevoked {
					logger.Infow("Audit Traceability", append(req.auditFields(), "decision", "deny", "reason", "actor_node is revoked")...)
					return nil, fmt.Errorf("actor_node %s is revoked", actorPID.String())
				}
			}
		}
		auditFields = append(auditFields, "actor_node", actorNodeStr)
	}
	if len(taskRules) > 0 {
		auditFields = append(auditFields, "task", taskRules[len(taskRules)-1].GetName())
	}
	logger.Infow("Audit Traceability", auditFields...)

	return taskRules, nil
}

// auditFields is what every authorization decision logs about the request:
// who asked, for what, and the request facts policy saw. One line per
// decision, allow or deny, is the audit trail of the PEP.
func (req RequestContext) auditFields() []any {
	fields := []any{
		"peer_id", req.PeerID.String(),
		"target", req.Target,
		"protocol", req.Protocol,
	}
	if req.HTTP != nil {
		fields = append(fields, "method", req.HTTP.Method, "path", req.HTTP.Path)
	}
	if req.Egress != nil {
		fields = append(fields, "host", req.Egress.Host, "port", req.Egress.Port)
	}
	if req.MCPTool != "" {
		fields = append(fields, "mcp_tool", req.MCPTool)
	}
	return fields
}

// meshPolicy is what this node adds to every authorization it performs,
// on whichever path the request arrived: the target facts of its own
// credential, its local attenuation from agentmesh-node.yaml, and the mesh
// policy rules it last synced. Both the in-mesh verifier
// (verifyBiscuitTokenWithRules) and the external ingress handler build their
// authorizer from this one value, so neither can drift from the other.
func (n *AgentMeshNode) meshPolicy() (identity.MeshPolicy, error) {
	targetFacts, err := n.ownTargetFacts()
	if err != nil {
		return identity.MeshPolicy{}, err
	}
	n.MeshPolicyMu.RLock()
	meshRules := n.MeshPolicyRules
	n.MeshPolicyMu.RUnlock()

	pol := identity.MeshPolicy{TargetFacts: targetFacts, MeshRules: meshRules}
	if n.nodeConfig != nil {
		pol.LocalPolicies = n.nodeConfig.Policies
		pol.LocalChecks = n.nodeConfig.Checks
		pol.LocalRules = n.nodeConfig.Rules
	}
	return pol, nil
}

// ownTargetFacts queries this node's own credential for the target_fact()
// facts a caller's target grants are matched against. A node without an
// identity yet contributes none: BaselineTargetCheck then admits only a
// caller whose grant is unrestricted.
func (n *AgentMeshNode) ownTargetFacts() ([]biscuit.Fact, error) {
	ourIdentity := n.GetIdentity()
	if len(ourIdentity) == 0 {
		logger.Debugf("[Auth] Node identity is missing, no target facts to match against")
		return nil, nil
	}
	ourB, err := biscuit.Unmarshal(ourIdentity)
	if err != nil {
		return nil, fmt.Errorf("failed to unmarshal node identity: %w", err)
	}
	facts, err := identity.TargetFactsFromBiscuit(ourB, n.trustedPublicKeys(), n.BiscuitTimeout)
	if err != nil {
		return nil, fmt.Errorf("failed to inject target facts: %w", err)
	}
	return facts, nil
}